408 lines
10 KiB
Markdown
408 lines
10 KiB
Markdown
# Badger 2040 <!-- omit in toc -->
|
|
|
|
Badger 2040 is an RP2040 powered E Ink badge.
|
|
|
|
- [Summary](#summary)
|
|
- [Getting Started](#getting-started)
|
|
- [Update Speed](#update-speed)
|
|
- [Buttons](#buttons)
|
|
- [Other Functions](#other-functions)
|
|
- [Other Constants](#other-constants)
|
|
- [Screen Size](#screen-size)
|
|
- [E Ink Pins](#e-ink-pins)
|
|
- [Power Pins](#power-pins)
|
|
- [Activity LED Pin](#activity-led-pin)
|
|
- [Function Reference](#function-reference)
|
|
- [Basic Drawing Settings](#basic-drawing-settings)
|
|
- [Pen Colour](#pen-colour)
|
|
- [Pen Thickness](#pen-thickness)
|
|
- [Text](#text)
|
|
- [Draw Text](#draw-text)
|
|
- [Measure Text](#measure-text)
|
|
- [Change Font](#change-font)
|
|
- [Lines, Pixels & Rectangles](#lines-pixels--rectangles)
|
|
- [Pixel](#pixel)
|
|
- [Line](#line)
|
|
- [Rectangle](#rectangle)
|
|
- [Images](#images)
|
|
- [Converting Images](#converting-images)
|
|
- [Image](#image)
|
|
- [Icon](#icon)
|
|
- [Updating The Display](#updating-the-display)
|
|
- [Update](#update)
|
|
- [Clear](#clear)
|
|
- [Partial Update](#partial-update)
|
|
- [Invert (aka Dark Mode)](#invert-aka-dark-mode)
|
|
- [Update Speed](#update-speed-1)
|
|
- [LED](#led)
|
|
|
|
# Summary
|
|
|
|
## Getting Started
|
|
|
|
To start coding your Badger 2040, you will need to add the following lines of code to the start of your code file.
|
|
```python
|
|
import badger2040
|
|
badger = badger2040.Badger2040()
|
|
```
|
|
This will create a `Badger2040` class called `badger` that will be used in the rest of the examples going forward.
|
|
|
|
## Update Speed
|
|
|
|
The E Ink display on Badger 2040 supports several update speeds. These can be set using `update_speed(speed)` where `speed` is a value from `0` to `3`. For convenience these speeds have been given the following constants:
|
|
|
|
* `UPDATE_NORMAL` = `0`
|
|
* `UPDATE_MEDIUM` = `1`
|
|
* `UPDATE_FAST` = `2`
|
|
* `UPDATE_TURBO` = `3`
|
|
|
|
## Buttons
|
|
|
|
Badger 2040 features five buttons on its front, labelled A, B, C, ↑ (up), ↓ (down), and 1 button on the rear labelled BOOT/USR. These can be read using the `pressed(button)` function, which accepts the button's pin number. For convenience, each button can be referred to using these constants:
|
|
|
|
* `BUTTON_A` = `12`
|
|
* `BUTTON_B` = `13`
|
|
* `BUTTON_C` = `14`
|
|
* `BUTTON_UP` = `15`
|
|
* `BUTTON_DOWN` = `11`
|
|
* `BUTTON_USER` = `23`
|
|
|
|
Note, due to the BOOT/USR button performing both BOOT and USER functions, the output of reading it with `pressed()` will be inverted from the others.
|
|
|
|
## Other Functions
|
|
|
|
Below is a list of other functions that have been made available, to help with the creation of more advanced programs.
|
|
|
|
```python
|
|
pen(color)
|
|
thickness(thickness)
|
|
|
|
pixel(x, y)
|
|
line(x1, y1, x2, y2)
|
|
rectangle(x, y, w, h)
|
|
|
|
text(message, x, y, scale=1.0, rotation=0.0)
|
|
glyph(char, x, y, scale=1.0, rotation=0.0)
|
|
measure_text(message, scale=1.0)
|
|
measure_glyph(char, scale=1.0)
|
|
font(font)
|
|
|
|
led(brightness)
|
|
|
|
image(data, w=296, h=128, x=0, y=0)
|
|
icon(data, icon_index, sheet_size, icon_size)
|
|
|
|
clear()
|
|
update()
|
|
partial_update(x, y, w, h)
|
|
update_speed(speed)
|
|
invert(inverted)
|
|
```
|
|
|
|
## Other Constants
|
|
|
|
Below is a list of other constants that have been made available, to help with the creation of more advanced programs.
|
|
|
|
### Screen Size
|
|
* `WIDTH` = `296`
|
|
* `HEIGHT` = `128`
|
|
|
|
### E Ink Pins
|
|
* `PIN_CS` = `17`
|
|
* `PIN_CLK` = `18`
|
|
* `PIN_MOSI` = `19`
|
|
* `PIN_DC` = `20`
|
|
* `PIN_RESET` = `21`
|
|
* `PIN_BUSY` = `26`
|
|
|
|
### Power Pins
|
|
* `PIN_VBUS_DETECT` = `24`
|
|
* `PIN_VREF_POWER` = `27`
|
|
* `PIN_1V2_REF` = `28`
|
|
* `PIN_BATTERY` = `29`
|
|
* `PIN_ENABLE_3V3` = `10`
|
|
|
|
### Activity LED Pin
|
|
* `PIN_LED` = `25`
|
|
|
|
# Function Reference
|
|
|
|
## Basic Drawing Settings
|
|
|
|
### Pen Colour
|
|
|
|
There are 16 pen colours - or "shades of grey" - to choose, from 0 (black) to 15 (white).
|
|
|
|
Since Badger2040 cannot display colours other than black and white, any value from 1 to 14 will apply dithering when drawn, to simulate a shade of grey.
|
|
|
|
```python
|
|
pen(
|
|
colour # int: colour from 0 to 15
|
|
)
|
|
```
|
|
|
|
### Pen Thickness
|
|
|
|
Thickness governs how thick a line should be and affects lines and text making them thicker or bolder respectively:
|
|
|
|
```python
|
|
thickness(
|
|
value # int: thickness in pixels
|
|
)
|
|
```
|
|
|
|
## Text
|
|
|
|
### Draw Text
|
|
|
|
To draw text in your selected font:
|
|
|
|
```python
|
|
text(
|
|
text, # string: the text to draw
|
|
x, # int: x coordinate for the left middle of the text
|
|
y, # int: y coordinate for the left middle of the text
|
|
scale=1.0, # float: size of the text
|
|
rotation=0.0 # float: rotation of the text in degrees
|
|
)
|
|
```
|
|
|
|
Text uses the "thickness" value, too, and a larger thickness value will give you bold text.
|
|
|
|
### Measure Text
|
|
|
|
Sometimes it's useful to know how big a particular bit of text will be on the screen. You can measure it like so:
|
|
|
|
```python
|
|
measure_text(
|
|
text, # string: the text to measure
|
|
scale # float: size of the text
|
|
)
|
|
```
|
|
|
|
### Change Font
|
|
|
|
There are five fonts to pick from:
|
|
|
|
* "sans"
|
|
* "gothic"
|
|
* "cursive"
|
|
* "serif"
|
|
* "serif_italic"
|
|
|
|
```python
|
|
font(
|
|
font # string: one of the fonts listed above
|
|
)
|
|
```
|
|
|
|
## Lines, Pixels & Rectangles
|
|
|
|
The basic building blocks of any Badger2040 interface are lines and rectangles.
|
|
|
|
### Pixel
|
|
|
|
Single pixels are always drawn in your pen colour, and with the thickness set by `thickness`.
|
|
|
|
Be wary that colours other than 0 and 15 can result in your pixel being dithered, and invisible! Badger2040 cannot draw just *one* grey pixel, sorry.
|
|
|
|
```python
|
|
pixel(
|
|
x, # int: x coordinate of pixel to draw
|
|
y # int: y coordinate of pixel to draw
|
|
)
|
|
```
|
|
|
|
### Line
|
|
|
|
Lines are always drawn in your pen colour, and with the line thickness set by `thickness`.
|
|
|
|
```python
|
|
line(
|
|
x1, # int: x coordinate of starting point
|
|
y1, # int: y coordinate of starting point
|
|
x2, # int: x coordinate of ending point
|
|
y2, # int: y coordinate of ending point
|
|
)
|
|
```
|
|
|
|
### Rectangle
|
|
|
|
Rectangles are always drawn in your pen colour.
|
|
|
|
They are the best way to see the dithering effects of different pens since anything from 1 to 14 (ie: not full black or white) is dithered.
|
|
|
|
```python
|
|
rectangle(
|
|
x, # int: x coordinate of the rectangle's top left corner
|
|
y, # int: y coordinate of the rectangle's top left corner
|
|
w, # int: width of rectangle
|
|
h # int: height of rectangle
|
|
)
|
|
```
|
|
|
|
## Images
|
|
|
|
Must be a multiple of 8 pixels wide (because reasons).
|
|
|
|
You will normally be using a `bytearray` as your source of data.
|
|
|
|
To load an image you must first allocate a `bytearray` big enough to store it. The formula is `WIDTH * HEIGHT / 8` since there are eight image pixels in every byte (one bit per pixels indicating either 1 black or 0 white):
|
|
|
|
```python
|
|
my_image = bytearray(int(296 * 128 / 8))
|
|
```
|
|
|
|
You can then open your file and read it into your `bytearray`:
|
|
|
|
```python
|
|
open("my_image.bin", "r").readinto(my_image)
|
|
```
|
|
|
|
And finally display it:
|
|
|
|
```python
|
|
screen = badger2040.Badger2040()
|
|
screen.image(my_image)
|
|
screen.update()
|
|
```
|
|
|
|
### Converting Images
|
|
|
|
We've supplied a script - `convert.py` - which will help you get your images converted.
|
|
|
|
Ideally you should pick something already 296x128 pixels or smaller, and in monochrome, but it will dither and convert images for you.
|
|
|
|
Find it in [/examples/badger2040/image_converter](/examples/badger2040/image_converter).
|
|
|
|
To convert an oversized image use:
|
|
|
|
```bash
|
|
python3 convert.py --resize --binary my_image.png
|
|
```
|
|
|
|
This will output `my_image.bin`, which you can save to your Badger 2040 via Thonny and display with the code above.
|
|
|
|
For smaller images such as icons you can omit the `--resize` flag:
|
|
|
|
```bash
|
|
python3 convert.py --binary my_icon.png
|
|
```
|
|
|
|
In all cases your images should be a multiple of 8 pixels wide.
|
|
|
|
### Image
|
|
|
|
```python
|
|
image(
|
|
data, # bytearray: raw image data 1bpp
|
|
w=296, # int: width in pixels
|
|
h=128, # int: height in pixels
|
|
x=0, # int: destination x
|
|
y=0, # int: destination y
|
|
)
|
|
```
|
|
|
|
When displaying a full-sized (296x128 pixel) image you can supply only the raw data, eg:
|
|
|
|
```python
|
|
image(data)
|
|
```
|
|
|
|
### Icon
|
|
|
|
Copies a portion from an icon sheet onto the screen at x/y.
|
|
|
|
Icons must be square- equal width/height- and sized in multiples of 8 pixels.
|
|
|
|
IE: 8x8, 16x16, 24x24, 32x32, 64x64
|
|
|
|
```python
|
|
icon(
|
|
data, # bytearray: raw image data 1bpp
|
|
icon_index, # int: location of the icon in the sheet, left-most is 0, etc
|
|
sheet_size, # int: width of the icon sheet in pixels
|
|
icon_size, # int: icon width/height in pixels (multiple of 8)
|
|
dx, # int: destination x
|
|
dy, # int: destination y
|
|
)
|
|
```
|
|
|
|
## Updating The Display
|
|
|
|
### Update
|
|
|
|
Starts a full update of the screen. Will block until the update has finished.
|
|
|
|
Update takes no parameters, but the update time will vary depending on which `update_speed` you've selected.
|
|
|
|
```python
|
|
update()
|
|
```
|
|
|
|
### Clear
|
|
|
|
Before drawing again it can be useful to `clear` your display.
|
|
|
|
`clear` fills the drawing buffer with the pen colour, giving you a clean slate:
|
|
|
|
```python
|
|
clear()
|
|
```
|
|
|
|
### Partial Update
|
|
|
|
Starts a partial update of the screen. Will block until the update has finished.
|
|
|
|
A partial update allows you to update a portion of the screen rather than the whole thing.
|
|
|
|
That portion *must* be a multiple of 8 pixels tall, but can be any number of pixels wide.
|
|
|
|
```python
|
|
partial_update(
|
|
x, # int: x coordinate of the update region
|
|
y, # int: y coordinate of the update region (must be a multiple of 8)
|
|
w, # int: width of the update region
|
|
h # int: height of the update region (must be a multiple of 8)
|
|
)
|
|
```
|
|
|
|
### Invert (aka Dark Mode)
|
|
|
|
Badger 2040 can invert all your display data for a quick and easy dark mode:
|
|
|
|
```python
|
|
invert(
|
|
inverted # bool: True to invert, False to... not invert!
|
|
)
|
|
```
|
|
|
|
### Update Speed
|
|
|
|
Badger 2040 is capable of updating the display at multiple different speeds.
|
|
|
|
These offer a tradeoff between the quality of the final image and the speed of the update.
|
|
|
|
There are currently four constants naming the different update speeds from 0 to 3:
|
|
|
|
* `UPDATE_NORMAL` - a normal update, great for display the first screen of your application and ensuring good contrast and no ghosting
|
|
* `UPDATE_MEDIUM` - a good balance of speed and clarity, you probably want this most of the time
|
|
* `UPDATE_FAST` - a fast update, good for stepping through screens such as the pages of a book or the launcher
|
|
* `UPDATE_TURBO` - a super fast update, prone to ghosting, great for making minor changes such as moving a cursor through a menu
|
|
|
|
```python
|
|
update_speed(
|
|
speed # int: one of the update constants
|
|
)
|
|
```
|
|
|
|
## LED
|
|
|
|
The white indicator LED can be controlled, with brightness ranging from 0 (off) to 255:
|
|
|
|
```python
|
|
led(
|
|
brightness # int: 0 (off) to 255 (full)
|
|
)
|
|
```
|