# 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:

```sh
benchlink flash --uart loader.uf2 xous.uf2 apps.uf2
benchlink console
```

Send a line to the shell while another terminal reads:

```sh
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

```text
> 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](/wiki/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.