Commands
Reference for the benchlink CLI and the text protocol of the board's control port.
Two ways to drive the board
The benchlink command covers the usual jobs: status, reset, bootloader, flashing, console.
The control port takes plain text commands, one per line. Use it from a script or a terminal program when you want a single line change and nothing else.
Both talk to the same firmware. Every CLI command that touches a line is built from the control-port commands below.
Finding the board
benchlink finds the one bench link plugged in by its USB ids, 1209:0002. With several bench links connected, name the ports:
| Option | What it names |
|---|---|
--control <port> |
the control port, for example /dev/ttyACM1, /dev/cu.usbmodem1103 or COM4 |
--console <port> |
the console port, the Dabao’s UART, for example /dev/ttyACM0 |
Both options work with every command.
CLI reference
| Command | What it does |
|---|---|
benchlink ports |
prints the two ports, for a terminal program of your own |
benchlink status |
the firmware version, the three lines, the Dabao’s 3.3 V rail |
benchlink reset [--ms 50] |
pulls RUN low for a moment |
benchlink prog hold |
holds PROG (PC13) until release |
benchlink prog release |
releases PROG |
benchlink prog pulse [--ms 200] |
holds PROG for a moment |
benchlink power off |
switches the Dabao’s regulators off, until power on |
benchlink power on |
switches them on and waits for the 3.3 V rail |
benchlink power cycle [--ms 1000] |
off, then on; waits for the 3.3 V rail |
benchlink boot1 |
into the bootloader: PROG held across a reset and for a second after it |
benchlink boot1 --via power |
the same by switching the Dabao off and on, for a board with boot-wait enabled |
benchlink flash <file.uf2>... |
into boot1, copies the images onto its volume in the order given, presses PROG to start them |
benchlink flash --uart <file.uf2>... |
the same through the console UART, for a Dabao whose USB carries no data |
benchlink console [--log file] |
prints the console, each line with its time, until Ctrl-C |
benchlink send <line> |
sends one line to the Dabao’s console |
benchlink gap [us] |
prints or sets the pause after every byte sent to the console, 0 to 10,000 µs |
Pulse and cycle lengths are 1 to 10,000 ms.
Options of flash
| Option | With | What it does |
|---|---|---|
--via prog or --via power |
both | how to get into boot1, as for benchlink boot1; prog is the default |
--volume <path> |
the volume | where the BAOCHIP volume is mounted, if it is not found under /Volumes, /media or /run/media |
--uart |
flash through the console UART | |
--gap-us <us> |
--uart |
the pause between bytes while blocks are sent; 50 unless given |
--all |
--uart |
sends every image, whatever the record of earlier flashes says |
--state-dir <dir> |
both | where the records are kept; by default benchlink under $XDG_STATE_HOME, or under ~/.local/state |
flash over the volume deletes every board’s record, because the volume does not say which board it belongs to. So does flash --uart on a board whose audit gives no serial number; that board gets every image.
flash --uart reads the console port itself. Stop benchlink console first; while it runs, flash --uart is refused.
Examples
Flash a Xous release and read its first boot:
benchlink flash --uart loader.uf2 xous.uf2 apps.uf2
benchlink console
Send a line to the shell while another terminal reads:
benchlink console # terminal 1
benchlink send "ver xous" # terminal 2
send and console can run at the same time on macOS and Linux. A second benchlink console on the same port is refused: two readers would each get only part of the output.
send writes the whole line at once. The bench link leaves the gap pause after each byte on its way to the Dabao.
Control port protocol
Open the control port at any rate. Send one command per line. Each command gets one line back:
| Answer | Meaning |
|---|---|
ok |
done |
ok <detail> |
done, with a value |
err <reason> |
not done, and why |
Commands
| Command | Effect | Answer |
|---|---|---|
version |
the firmware version | ok benchlink <version> |
status |
the state of the lines and the 3.3 V rail | ok run=... prog=... power=... target=...mV dropped=... |
run hold |
holds the Dabao in reset | ok |
run release |
releases reset | ok |
run pulse <ms> |
holds reset for <ms>, then releases |
ok, at once |
prog hold |
holds PC13, as a pressed PROG button |
ok |
prog release |
releases PC13 |
ok |
prog pulse <ms> |
holds PC13 for <ms>, then releases |
ok, at once |
power off |
pulls ON low: both of the Dabao’s regulators stop |
ok |
power on |
releases ON |
ok |
power cycle <ms> |
off for <ms>, then on |
ok, at once |
gap |
prints the pause after every byte sent to the console | ok <us> |
gap <us> |
sets that pause, 0 to 10,000 µs | ok |
Rules
- A pulse or a cycle is answered at once and ends by itself, after 1 to 10,000 ms.
hold,release,offandoncancel a pulse in progress on their line.- Held
RUNis reset. HeldPC13is PROG pressed, and the Dabao’s USB data lines are disconnected for as long. targetis the Dabao’s 3.3 V rail as the board measures it. From 2,500 mV up, the Dabao counts as powered.droppedcounts console bytes lost because the 32 KiB buffer was full.- The pause set by
gapis 1,000 µs after the firmware starts.
Example session
> version
ok benchlink <version>
> prog hold
ok
> run pulse 50
ok
> prog release
ok
> status
ok run=released prog=released power=on target=3312mV dropped=0
The console port
The console port is the Dabao’s console UART, PB14 out of the Dabao and PB13 into it, at 1,000,000 baud 8N1. Open it at any rate; the firmware runs the UART at 1 Mbaud regardless. See Firmware for what it does with the data.
boot1’s console takes commands on this UART with no authentication, destructive ones included. Treat access to the console port as access to the board.