# Getting started

Plug in the bench link, install the CLI, seat a Dabao and flash it with one cable.

## What you need

- The bench link board.
- One USB-C cable from the board to your computer.
- A Dabao (Baochip-1x) board.
- Rust on the computer, to build the `benchlink` command: from the repository's Nix dev shell, or from rustup.

> [!WARNING]
> The bench link is not a debugger. The chip's JTAG port is fused out, so no adapter can single-step it.

## Plug in the board

Plug the bench link into the computer with nothing on the Dabao site.

The `PWR` LED lights. The `D3V3` LED stays dark, because no Dabao is powered yet.

The computer sees one USB device, `1209:0002`, with the product string `benchlink`. It has two serial ports:

| Port | What it is |
|---|---|
| Console port (USB interface 0) | the Dabao's console UART |
| Control port (USB interface 2) | text commands for the board, one line in, one line out |

You do not need to know the port names. The CLI finds the one bench link that is plugged in. To see them, run `benchlink ports`.

## Install the CLI

Get the tools first, in one of two ways:

- With [Nix](https://nixos.org/) and [direnv](https://direnv.net/), run `direnv allow` once in the checkout. Each time you enter it, you get a shell with Rust and `just`. Without direnv, `nix develop` opens the same shell.
- Without Nix, install Rust from [rustup](https://rustup.rs/). The repository's `rust-toolchain.toml` picks the toolchain. `just` is optional.

Then, from the checkout:

```sh
just install        # without just: cargo install --path apps/benchlink
```

Check that the command talks to the board:

```sh
benchlink ports
benchlink status
```

## Put a Dabao on the site

Unplug the bench link first.

The site comes in one of two builds:

| Build | How the Dabao sits |
|---|---|
| Spring probes | a bare Dabao, held down on 32 probes by a cradle on the four cradle holes |
| Sockets | a Dabao with pin headers, plugged into two 1x16 sockets |

The Dabao's USB-C end goes to the notch in the board's edge, where `USB` and an arrow are printed. A Dabao with headers also fits turned by 180 degrees. That puts its 5 V pin on a GPIO line, so check the direction before you power it.

The notch leaves the Dabao's own USB-C receptacle free. You do not need a second cable. See [When the Dabao has its own cable](#when-the-dabao-has-its-own-cable) for when you might want one.

## First status

Plug the bench link back in. The board powers the Dabao from the same cable, through a current-limited 5 V feed into the Dabao's `VSYS` pin. See [The board](/wiki/hardware) for how the feed limits the current.

Then ask for the status:

```sh
benchlink status
```

The control port answers in one line, for example:

```text
ok run=released prog=released power=on target=3312mV dropped=0
```

| Field | Meaning |
|---|---|
| `run` | the Dabao's reset line, `held` or `released` |
| `prog` | the Dabao's PROG line (`PC13`), `held` or `released` |
| `power` | the Dabao's `ON` pin: `on` or `off` |
| `target` | the Dabao's 3.3 V rail in millivolts; 2,500 mV or more counts as powered |
| `dropped` | console bytes lost because nobody read them in time |

A seated, powered Dabao shows `target` close to 3,300 mV, and the `D3V3` LED is lit. If the reading is not steady at 3.3 V a moment after power-up, unplug and reseat the Dabao.

## Read the console

```sh
benchlink console
```

This prints the Dabao's console, each line with the seconds since the command started, until Ctrl-C. Add `--log file` to also append it to a file.

Anything the Dabao printed before you opened the port is kept and shown first. Reset the board to see a whole boot from the first line:

```sh
benchlink reset
```

To type into the Dabao's console, send one line at a time from a second terminal:

```sh
benchlink send audit
```

`send` and `console` can run at the same time on macOS and Linux: one writes, the other reads. A second `benchlink console` on the same port is refused, because two readers would each get only part of the output. A terminal program on the console port is such a second reader, and nothing refuses it, so type lines with `send` rather than in a terminal program while `console` runs. See [Commands](/wiki/commands) for `send` and `gap`.

## First flash and boot log

With one cable, the Dabao's USB carries no data. The bootloader `boot1` then keeps its console on the UART, and images go through it:

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

`flash --uart` does the whole job:

1. Checks that every file is a UF2 image before it touches the board.
2. Gets the Dabao into `boot1` with PROG held across a reset.
3. Waits until `boot1` is ready for input.
4. Sends each image one block per line, each block confirmed by `boot1`.
5. Presses PROG to start the new image.

`flash --uart` reads the console itself, so stop `benchlink console` before you run it. Start it again afterwards. The boot log of the new image is kept until it opens the port.

The next time, an image that is already on the board is not sent again. After most builds only `apps.uf2` goes. Use `--all` to send every image, for example after the board was flashed from another computer. [Commands](/wiki/commands) has every flag of `flash --uart`.

## When the Dabao has its own cable

You can plug a cable into the Dabao's own USB-C receptacle through the notch. Use this for the application's USB link, or to flash over the `BAOCHIP` volume:

```sh
benchlink flash loader.uf2 xous.uf2 apps.uf2
```

This copies the images onto the volume `boot1` mounts, in the order given, then presses PROG.

Once that cable carries data, `boot1` moves its console to the Dabao's own USB serial port. Lines sent on the bench link's console then get no answer. Use `flash --uart` only while the Dabao's cable carries no data. A cable to a charger has no data lines, so with the Dabao on a charger `boot1` keeps its console on the UART and `flash --uart` and `send` work as with one cable.

## Next steps

- [Commands](/wiki/commands): every `benchlink` command and the raw control-port protocol.
- [Firmware](/wiki/firmware): what the board's firmware does for you.
- [Build your own with a Pico 2](/wiki/diy-pico).