![]() |
||
---|---|---|
.. | ||
README.md | ||
badger2040.c | ||
badger2040.cpp | ||
badger2040.h | ||
badgerinit.S | ||
micropython.cmake |
README.md
Badger 2040
Badger 2040 is an RP2040 powered E Ink badge.
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.
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
System speed
The system clock speed of the RP2040 can be controlled, allowing power to be saved if on battery, or faster computations to be performed. Use badger2040.system_speed(speed)
where speed
is one of the following constants:
SYSTEM_VERY_SLOW
=0
4 MHz if on battery, 48 MHz if connected to USBSYSTEM_SLOW
=1
12 MHz if on battery, 48 MHz if connected to USBSYSTEM_NORMAL
=2
48 MHzSYSTEM_FAST
=3
133 MHzSYSTEM_TURBO
=4
250 MHz
On USB, the system will not run slower than 48MHz, as that is the minimum clock speed required to keep the USB connection stable.
It is best to set the clock speed as the first thing in your program, and you must not change it after initializing any drivers for any I2C hardware connected to the qwiic port. To allow you to set the speed at the top of your program, this method is on the badger2040
module, rather than the badger
instance, although we have made sure that it is safe to call it after creating a badger
instance.
Note that SYSTEM_TURBO
overclocks the RP2040 to 250MHz, and applies a small over voltage to ensure this is stable. We've found that every RP2040 we've tested is happy to run at this speed without any issues.
Other Functions
Below is a list of other functions that have been made available, to help with the creation of more advanced programs.
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)
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.
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:
thickness(
value # int: thickness in pixels
)
Text
Draw Text
To draw text in your selected font:
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:
measure_text(
text, # string: the text to measure
scale # float: size of the text
)
Change Font
There are five vector fonts to pick from:
- "sans"
- "gothic"
- "cursive"
- "serif"
- "serif_italic"
There are also three bitmap fonts, useful for smaller text and retro goodness. They should handle characters like £, ° and accented characters more gracefully.
- "bitmap6"
- "bitmap8"
- "bitmap14_outline"
When working with bitmap fonts, note that scale
must be an integer >= 1, and text is orientated from its top left corner.
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.
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
.
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.
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):
my_image = bytearray(int(296 * 128 / 8))
You can then open your file and read it into your bytearray
:
open("my_image.bin", "r").readinto(my_image)
And finally display it:
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.
To convert an oversized image use:
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:
python3 convert.py --binary my_icon.png
In all cases your images should be a multiple of 8 pixels wide.
Image
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:
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
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.
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:
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.
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:
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 ghostingUPDATE_MEDIUM
- a good balance of speed and clarity, you probably want this most of the timeUPDATE_FAST
- a fast update, good for stepping through screens such as the pages of a book or the launcherUPDATE_TURBO
- a super fast update, prone to ghosting, great for making minor changes such as moving a cursor through a menu
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:
led(
brightness # int: 0 (off) to 255 (full)
)