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 EInk 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:
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.
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`
### EInk 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 298x128 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 Badger2040 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=298, # 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)
