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, off and on cancel a pulse in progress on their line.
  • Held RUN is reset. Held PC13 is PROG pressed, and the Dabao’s USB data lines are disconnected for as long.
  • target is the Dabao’s 3.3 V rail as the board measures it. From 2,500 mV up, the Dabao counts as powered.
  • dropped counts console bytes lost because the 32 KiB buffer was full.
  • The pause set by gap is 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.