pimoroni-pico/micropython/modules/badger2040/README.md

Badger 2040

Badger 2040 is an RP2040 powered E Ink badge.

• Summary
  • Getting Started
  • Update Speed
  • Buttons
  • Other Functions
  • Other Constants
    • Screen Size
    • E Ink Pins
    • Power Pins
    • Activity LED Pin
• Function Reference
  • Basic Drawing Settings
    • Pen Colour
    • Pen Thickness
  • Text
    • Draw Text
    • Measure Text
    • Change Font
  • Lines, Pixels & Rectangles
    • Pixel
    • Line
    • Rectangle
  • Images
    • Converting Images
    • Image
    • Icon
  • Updating The Display
    • Update
    • Clear
    • Partial Update
    • Invert (aka Dark Mode)
    • Update Speed
  • 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.

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 USB
• SYSTEM_SLOW = 1 12 MHz if on battery, 48 MHz if connected to USB
• SYSTEM_NORMAL = 2 48 MHz
• SYSTEM_FAST = 3 133 MHz
• SYSTEM_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.

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 fonts to pick from:

• "sans"
• "gothic"
• "cursive"
• "serif"
• "serif_italic"

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 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

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)
)