Serial command reference#

The board’s configuration channel is a plain text serial port. The config app, the Python library or a serial terminal such as PuTTY can drive it.

You send one command per line, ending in a newline.
The board answers with one JSON object per line.
Every command produces exactly one final line, either {"ok":true,...} or {"ok":false,"err":"..."}.
The board may send event lines at any time, marked with "ev". One can arrive between a command and its reply.

Baud rate is ignored; any setting works.

Enter must send a newline, not a carriage return. PuTTY’s default sends CR, which this channel ignores: commands appear to be accepted and nothing happens. Set it to send LF, or use bbctl.

The commands#

Command	What it does
`hello`	Identify the board: firmware, serial, tile count, USB personality
`tiles`	Every tile the board knows about
`stats`	Uptime, poll cycle time, fault state, power budget
`usb frc` \| `usb xinput`	Set the USB personality, applied at the next reset
`pixel on` \| `pixel off`	Flash the main module’s light white on every button press. On by default; `save` keeps the setting
`bind <btn>`	Wait for a key press and bind it to that button
`bind <btn> add`	Same, but add to the button’s group instead of replacing
`bind cancel`	Stop waiting
`unbind <btn>`	Remove every key from a button
`unbind <btn> <addr> <key>`	Remove one key from a group
`bind axis <n>`	Bind axis 1–4 to the next encoder turned
`unbind axis <n>`	Remove it
`enc zero [<n>]`	Zero one encoder axis, or all of them
`map get`	The whole configuration as JSON
`map set <json>`	Replace it
`save`	Write configuration to flash and verify it
`led <btn> <rgb> [fx] [press]`	Live colour for a logical button
`led tile <addr> <led> <rgb> [fx]`	Live colour by tile and LED number
`led all <rgb>`	Every LED. `led all off` is the panic button
`led reset`	Discard the live layer; back to saved defaults
`power budget <mA>`	Set the LED power budget
`test walk [ms]`	Press buttons 1→32 in turn, with no tile involved
`test hold <btn>`	Hold one button
`test all`	Every button at once
`test off`	Stop
`disp <addr> …`	Write text, a bar or a picture to a display tile
`disp <addr> slot <n> …`	Store, show, erase, check (`info`) or read back (`read`) one of the tile’s saved pictures
`replace <old> <new>`	Move a tile’s bindings to another address by hand
`reset`	Reboot
`reset factory`	Erase the configuration and reboot
`boot`	Reboot into the USB bootloader for a firmware update

rgb is six hex digits or off. fx is solid, blink, fast or breathe. Addresses are 1–31, logical buttons 1–32, keys count from 0.

Events#

Event	When
`tile`	A tile went online, was lost, was assigned an address, or entered its bootloader
`fault`	The fault indicator changed, with the reason
`key`	A key was pressed — only while waiting for a binding
`enc`	An encoder was turned — only while waiting for a binding
`progress`	During a tile firmware update
`player`	The FTC Driver Station assigned this board a player number
`rumble`	A rumble packet arrived, with the legend code it decodes to — FTC mode only

A client that only wants request and response can ignore every line containing "ev".

A worked example#

> hello
< {"ok":true,"product":"Button Board","fw":"0.1.0","proto":1,"tiles":3,"mode":"run","usb":"frc"}
> bind 7
< {"ev":"key","addr":1,"key":4}
< {"ok":true,"btn":7,"addr":1,"key":4,"sources":1}
> led 7 FF8800 blink
< {"ok":true}
> save
< {"ok":true,"saved":true}

bbctl#

tools/bbctl.py in the repository is a console for this channel. It sends the right newline endings, holds the port open so test mode survives, and reads past event lines to the reply.

python3 tools/bbctl.py                          # interactive console
python3 tools/bbctl.py hello stats               # run and exit
python3 tools/bbctl.py -p COM7 "test walk 250"   # explicit port