Python API summary#

Everything here is a method on Board. Each one sends a command and returns the board’s reply as a dictionary, or raises.

Connecting#

Call	What it does
`Board.open(port=None)`	Open the board, auto-detecting the port
`board.close()`	Close it. Also happens on leaving a `with` block
`MockBoard()`	An in-process board, no hardware

Identity and state#

Call	Returns
`board.hello()`	Product, firmware version, serial, tile count, USB personality
`board.tiles()`	A list, one entry per tile: kind, firmware, state, keys currently down
`board.tile(addr)`	One tile’s entry, or `None`
`board.stats()`	Uptime, poll cycle time, fault state, LED power budget

LEDs#

Call	What it does
`board.led(btn, colour, fx=None, press=None)`	Set a logical button’s colour
`board.led_tile(addr, index, colour, fx=None)`	Set one LED by tile and position
`board.led_all(colour)`	Every LED on every tile
`board.led_reset()`	Back to the saved defaults
`board.led_layer()`	A diffing writer — see Your first script

colour takes a name, "#RRGGBB", "RRGGBB", an (r, g, b) triple, an int, or None for off. fx is "solid", "blink", "fast" or "breathe". press turns the white press-flash on or off for that button.

LedLayer#

Call	What it does
`layer.set(btn, colour, fx, press)`	Stage a colour
`layer.set_tile(addr, index, colour, fx)`	Stage a colour by tile and position
`layer.flush()`	Send what changed; returns how many commands went out
`layer.all(colour)` / `layer.reset()`	Send immediately and reset the diff
`layer.forget()`	Force the next `flush()` to resend everything

Bindings#

Call	What it does
`board.bind(btn, add=False)`	Wait for a key press and bind it. `add=True` joins a group
`board.bind_cancel()`	Stop waiting
`board.unbind(btn)`	Remove every key from a button
`board.unbind(btn, addr, key)`	Remove one key from a group
`board.map_get()` / `board.map_set(m)`	The whole configuration as a dictionary
`board.save()`	Write it to flash

bind() blocks until someone presses a key, up to 30 seconds.

Encoders#

Call	What it does
`board.bind_axis(n)`	Bind axis 1–4 to the next encoder turned
`board.unbind_axis(n)`	Remove it
`board.enc_zero(n=None)`	Zero one axis, or all of them

Display tiles#

Call	What it does
`board.screen(addr)`	A row-diffing writer for a display tile
`screen.text(row, s)` / `screen.bar(row, col, width, value)`	Stage a row
`screen.flush()`	Send changed rows and commit them together
`screen.clear()`	Blank the panel
`board.disp_store_image(addr, slot, file)`	Encode an image for the tile and store it in a slot
`board.disp_slot_show(addr, slot)`	Show a stored picture: one frame
`board.disp_slot_info(addr, slot)`	What a slot holds: `None`, or its `fmt`, `attr`, `len` and `crc`
`board.disp_slot_read(addr, slot)`	Read a stored picture back, checked against its CRC; seconds for a colour picture

Display tiles differ in size: disp1 is 21 columns × 4 rows, disp2 13 × 8 and screenkey1 10 × 8. Take the geometry from screen.cols / screen.rows, which come from the tile’s own descriptor, rather than hard-coding it. MockBoard() includes display tiles to develop against; MockBoard(display=False) behaves like firmware without display support, which answers unknown.

The board itself#

Call	What it does
`board.usb("frc")` / `board.usb("xinput")`	Set the USB personality; takes effect at the next reset
`board.power_budget(mA)`	Set the LED power budget
`board.test("walk", 250)` / `board.test("off")`	Report button presses with no tile involved
`board.reset()` / `board.reset(factory=True)`	Reboot, optionally erasing the configuration

Events#

The board reports events such as a tile lost, a fault raised, or a key pressed during binding.

def on_tile(ev):
    print(ev["addr"], ev["state"])      # 3 lost

unsubscribe = board.on("tile", on_tile)

Names are tile, fault, key, enc, progress and player; "*" receives all of them.

Callbacks run on the library’s reader thread. Do not call board methods from inside one: the call blocks until it times out. Put the event on a queue and handle it in your loop.

Errors#

Exception	When
`CommandError`	The board refused the command. `.err` is the reason code
`Timeout`	No reply in time
`NotConnected`	The port is closed or the cable went away
`NoBoardFound`	Auto-detection could not identify a board
`BoardError`	Base class for all of the above