# Firmware

What the firmware on the bench link does, and what it saves you compared with a USB-UART adapter and a hand on the buttons.

## The problem it solves

The Dabao's own USB console goes away at every reset and at every change of boot stage. Its boot log is on a UART at 1,000,000 baud, which not every adapter can do. Getting into its bootloader, `boot1`, takes a hand on the buttons.

The firmware on the bench link takes these out of the loop. A script or an agent can reset the Dabao, get it into `boot1`, power-cycle it, flash it and read its log from the first byte.

| Task | USB-UART adapter and buttons | Bench link |
|---|---|---|
| Keep the console open across a reset | the Dabao's USB port disappears | the console port stays |
| Read the first lines of a boot | lost unless a terminal is already open | kept and replayed to the next opener |
| Run at 1 Mbaud | depends on the adapter and the terminal | fixed, whatever the host asks |
| Send a line to `boot1` | part of a fast line is lost | paced, byte by byte |
| Enter the bootloader | hold PROG, press reset | `benchlink boot1` |
| Flash without the Dabao's USB | not possible | `benchlink flash --uart` |
| Power-cycle | unplug the cable | `benchlink power cycle` |
| Know the supply | a separate meter | the 3.3 V rail in `benchlink status` |

## The console port

**It survives resets and power loss.** The console port belongs to the bench link, not to the Dabao. It stays when the Dabao resets, changes boot stage or loses power.

**Nothing is lost while it is closed.** What the Dabao prints while no program has the port open is kept, up to 32 KiB, and delivered to the next program that opens it. Beyond that, new output is dropped and counted as `dropped=` in the status.

**Fixed 1 Mbaud.** The firmware runs the Dabao's UART at 1,000,000 baud 8N1 whatever rate the host asks for. Any terminal program works at any setting.

**Paced sending.** The Dabao drops part of a line that arrives in one piece. The firmware leaves a pause after every byte: 1 ms by default, 0 to 10,000 µs with `gap`.

**Nothing into an unpowered Dabao.** While the Dabao's 3.3 V rail reads below 2,500 mV, the firmware lets its console output float and drops what the host sends, so no pin feeds the Dabao through its pad.

## Flashing over the UART

`benchlink flash --uart` writes images with `boot1`'s `uf2` command. It needs no USB data on the Dabao, so it works with the single cable.

- **It waits for `boot1`.** After entry, `boot1` takes no input for about 1.3 s, until it prints `USB device ready`. The tool waits for that line.
- **One block per line, confirmed.** `boot1` confirms each block before the next goes. An unconfirmed block is sent again, up to three times in all; then the flash stops.
- **Fuller blocks.** A UF2 file carries 256 bytes per block; `boot1` accepts up to 476. The tool repacks to 448 bytes per line, so 4 lines do the work of 7.
- **A shorter pause for the blocks only.** 50 µs (`--gap-us`) during the flash; 1 ms again after the last block.
- **Images already on the board are skipped.** After most builds only `apps.uf2` is new, and only that file goes.

The three images of a Xous release, 2.9 MB, take about 123 s at 50 µs, and 3 s when none has changed. Over the USB volume they take 16 s.

`flash --uart` reads the console itself, so a running `benchlink console` makes it refuse to start.

`boot1` cannot read the chip back, so the skip rests on a record on the computer: per Dabao, named by its `audit` serial number, the address range and a 64-bit FNV-1a fingerprint of every image written in full. An image leaves the record before its first block and returns after its last, so a flash that stops halfway claims nothing. An image that overwrites another removes that one. `flash` over the volume clears every record, and so does a board whose `audit` gives no serial number.

After a write by another tool or computer, give `--all` once. The fingerprint is not a security check. The Dabao checks the signatures of what it starts.

## Lines that never disturb the Dabao

The firmware starts with `RUN`, `PC13` and `ON` released. An unplugged bench link, or one in its own bootloader, leaves them released too. To the Dabao, an idle adapter looks like no adapter, and its own buttons keep working.

The circuit backs this up. `RUN`, `PC13` and `ON` are only ever pulled low, each through an N-MOSFET. No processor pin reaches a Dabao pin at less than 33 kΩ, except through a gate. The console line into the Dabao idles high even while the bench link is off.

## Power and measurement

The firmware switches the Dabao off by pulling `ON` low, which stops both of its regulators. `power cycle` releases it after the given time. `benchlink power on` and `benchlink power cycle` then wait for the 3.3 V rail, not for a fixed time.

The firmware reads the Dabao's 3.3 V rail every 5 ms (`target=` in the status). From 2,500 mV up, the Dabao counts as powered.

### Not in the firmware yet

The board also has a current-limited 5 V feed into the Dabao's `VSYS`, a current monitor on that feed, two more voltage readings and two marker inputs. See [The board](/wiki/hardware). The firmware does not drive them yet, and the control port has no command for the feed.

## One-line answers

Every control-port command gets exactly one line back: `ok`, `ok <detail>` or `err <reason>`. A script or an agent sends a command and reads one line, with no prompt or menu to parse. See [Commands](/wiki/commands).

## Updating the firmware

Hold the board's `BOOT` button while plugging it in. It shows up as a volume named `RP2350`. Copy the firmware's UF2 file onto it; the board restarts into it.