Files
microduck/docs/robot/install-dev.md
Pierre Rouanet b64def7b73 updaterd: automatic rollback is off unless asked for
`[update_gate] auto_rollback` in robotd.toml, default false, a row in
`robotctl configure`. It gates every path that reverts without being
asked:

- the health gate after `update apply`, `select` and `rollback`;
- the boot counter on a trial that never confirmed;
- `robot-boot-check` handing over to `robot-rescue`.

Off, the gate still runs and decides. A release that fails stays live,
reported `Stuck` with `robotctl update rollback <component>` in the
reason; the trial is cleared, and the journal entry is aborted rather
than rolled back, so `known_bad` does not blacklist it. The boot check
names the failed units and the manual `robot-rescue --reboot`, and exits
2. `--dry-run` is unchanged, since the OS slot gate reads it.

Releases now reach robots as tested Yocto images, and a separate daemon
update is the dev-board case, where an unasked revert replacing the
code under whoever holds the robot does more damage than it prevents.
A soft deprecation: the code stays, tested, one setting away.

`updaterd` reads the key from `robotd_config` (new, defaults to
/etc/robot/robotd.toml), both layers, at the moment of deciding, like
`allow_community` and the board. Test fixtures turn it on where they
test what a revert does.

Assisted-by: Claude:claude-opus-5-5
2026-11-04 12:38:25 +01:00

13 KiB

Installing on a dev board

Getting a board from nothing to a robot you can push branches to.

A dev board trusts the team dev key, so it will install anything anyone on the team builds. A customer robot is set up differently and deliberately refuses those builds — everything here assumes a dev board, never a customer robot.

Nothing is relaxed for a dev build: same signature and hash verification, same health gate, same rollback setting. The only difference is which key signed it, and that is what keeps these builds off customer robots — every updaterd carries the dev key, and uses it only on a robot that has been made a dev board (below).

Flash the board

Use the Armbian imager. Pick Radxa Zero 3, then Armbian 26.2.1 Minimal.

Before writing, fill in the imager's profile — wifi network and password, and the username and password you want. Doing it there saves a serial console later: the board joins your network on first boot and is reachable over ssh straight away.

Then add your ssh key, so provisioning can reconnect after it reboots the board:

ssh-copy-id microduck@192.168.1.42

What you need

  • The board's IP address. mDNS on this image is unreliable, so a .local name resolves when it feels like it. duckctl ip asks the robot over Bluetooth, which needs no network of your own and no DHCP lease to read; your router's lease table is the fallback if the board is not advertising yet.
  • ssh key access, from the step above. Provisioning reboots the board and reconnects by itself, and a password prompt cannot survive that.
  • A GitHub token, while this repository is private: its release assets are unreachable without one. Once it is public the token is optional and buys only a higher API rate limit (docs/design/updater-design.md §6.1).
  • A clone of this repo. The dev key it needs is committed at deploy/dev-key/team.dev.pub, so there is nothing to ask anyone for.

Install

From a clone on your own machine, two commands:

export DUCK_TOKEN=github_pat_replace_with_your_token
./scripts/provision-board.sh --pause-btd-on-pair --name <MY_COOL_ROBOT_NAME> microduck@192.168.1.42

That sends your dev key, starts provisioning, waits out the reboot, streams the log, and ends on robotctl health.

Why --pause-btd-on-pair is in that command

On the aic8800 radio a pad cannot form a new bond while btd is advertising. That flag leaves a marker so robotctl pad pair stops btd and power-cycles the adapter for the pairing window, then starts it again. An existing bond is unaffected — a bonded pad connects and drives with the whole stack up — so the cost is one daemon being down for the length of a pairing.

It is the default here because a board that needed it and was provisioned without it presents as a gamepad that will not pair, and every plausible cause you chase first is somewhere else.

The three configurations, and how to tell which you have

There are two independent faults, so there are two flags. Pair a pad and read the failure, then pick:

what you see what the board wants
the pad bonds and drives nothing — provision with no flag
the pad will not bond; the last SMP step never completes --pause-btd-on-pair
the pad will not bond even with btd paused --weird-ble (implies the pause, and adds Privacy = device)
the pad bonds, then flaps — PIN or Key Missing (0x06), no input device --weird-ble is wrong for this board: drop it, keep the pause

That last row is the one to watch for. Privacy = device on a board that only needed the pause produces a bond that immediately stops working, which is harder to diagnose than a pad that plainly will not pair — measured on 50:37:CD:16:1D:90, where off plus the pause bonds and holds while device flaps 46 times in 45 seconds. --weird-ble is therefore not the default any more.

To move a board from --weird-ble to the pause alone, keeping the marker:

sudo sed -i 's/^Privacy = device/Privacy = off/' /etc/bluetooth/main.conf && sudo reboot

To go the other way, with the copy of the script provisioning leaves on the board:

sudo DUCK_WEIRD_BLE=1 /usr/local/sbin/robot-setup-board && sudo reboot

And to check a board needs neither, drop both and pair a pad:

sudo rm /var/lib/robot/weird-ble
sudo sed -i '/^Privacy = /d' /etc/bluetooth/main.conf && sudo reboot

Re-pair after any change to Privacy: it changes the address the stored keys were derived against, so existing bonds stop matching and flap with PIN or Key Missing until they are re-made.

All of this is a workaround for the aic8800 radio, not a property of the design; it goes when the radio does. pair-a-gamepad.md has the detail.

It is a viewer, not the thing doing the work — provisioning installs a systemd unit that resumes at boot, so the board finishes whether or not you are still watching. Ctrl-C costs you nothing, and you can pick the log back up:

ssh -t microduck@192.168.1.42 'sudo tail -f /var/lib/robot/provision.log'

--ref BRANCH provisions from a branch: its scripts run the bring-up, and its build of the daemon is installed on top. golden stays the stable release — it is the boot recovery net's fallback, and a branch build as golden would give a broken branch a broken fallback — while current is the branch.

Provisioning fails if that build cannot be installed, or if it is installed and then rolled back by the health gate. A dev board quietly running the stable release when a branch was asked for is the worst failure to debug: everything looks installed and the code under test is not there. Give CI its minute or two before provisioning, and check with gh run list --branch BRANCH if it stops. --name is applied before the branch build, so a board that fails here still has its name.

Other useful flags: --name Ducky names the robot instead of leaving it the duck-7f3a it derives from its own serial (robotctl system set-name changes it later, so this only saves a command), --local sends this clone's provision.sh instead of fetching it (which is how to test a change to the provisioning scripts without merging first), and --no-dev-key makes a board that only takes releases.

Check it worked

robotctl health

The board only counts as a dev board if the key really installed, and that is a thing you can check rather than a thing you have to remember:

grep -c 'DEV BOARD' /var/lib/robot/provision.log

1 means yes. 0 means the key did not land, and --ref will be refused later with an error that reads like a corrupt release. That is the failure this check exists to catch early.

Then the real test — put a branch on it:

sudo robotctl update apply --ref main daemon

When ssh refuses to connect after a reflash

Reflashing regenerates the board's host keys, so the address you used last time now presents a different one. StrictHostKeyChecking=accept-new does not cover it: the host is not new, its key is. The raw ssh error for this is a wall of text about a possible attack.

./scripts/provision-board.sh microduck@192.168.1.42 --forget-host-key

This matters more than it sounds, because DHCP leases get reused — the address that was one board last week is a different board today, with a different key.

When the board comes back at a different address

The wifi cutover in the middle of provisioning can leave the board on a different lease than the one you gave. provision-board.sh goes looking: while it waits for ssh it also asks the robot over Bluetooth what address it ended up with, and adopts the answer.

  bluetooth: the robot reports 192.168.1.57, and 192.168.1.42 was its old lease.

Nothing to do — the rest of the run is addressed there.

Three things stop it working, and it says which:

  • It needs cargo and this clone, because duckctl is an example rather than an installed binary.
  • It can only ask once btd is running, which on a board being provisioned for the first time is a few minutes into phase 2.
  • The robot reports its wifi address, so a board you reach over ethernet is not covered.

--no-ble turns it off. A robot that has been given its own pairing PIN needs it in DUCK_PIN.

Making an existing board take dev builds

For a board flashed with an image, provisioned some other way, or set up with --no-dev-key. On the board:

sudo robotctl configure --allow-dev-daemon on

That is the whole step. updaterd carries the team dev key built in, so there is no key to copy, and this switch — kept under /var/lib/robot, so an OS update does not undo it — tells it to use that key. It restarts updaterd. Then:

sudo robotctl update apply --ref main daemon

Swap main for any branch to get what CI last built for it. From here on, don't run robotctl update apply daemon without --ref or --version: it installs the latest stable release, which on a dev board is usually a downgrade.

sudo robotctl configure --allow-dev-daemon off makes it a robot that only takes releases again. The same switch is the first row of the sudo robotctl configure editor, allow_dev_daemon under [dev board]: SPACE toggles it, and saving offers the updaterd restart.

The switch needs an updaterd that knows about it — a release from after it was added. On a board running an older one, sudo robotctl update apply daemon first, then the switch.

The token, by hand

scripts/install.sh writes this for you when given DUCK_TOKEN. These steps are for a board provisioned some other way — and they are only needed while this repository is private, or on a board that fetches often enough to want the higher rate limit a token buys.

updaterd reads GITHUB_TOKEN from its own environment, so exporting it in your shell does not reach the daemon — it needs a systemd drop-in.

sudo mkdir -p /etc/systemd/system/updaterd.service.d

Substitute your own token in the next block — it is the only placeholder here:

sudo tee /etc/systemd/system/updaterd.service.d/token.conf > /dev/null <<'EOF'
[Service]
Environment=GITHUB_TOKEN=ghp_replace_with_your_token
EOF

A drop-in is world-readable by default, and this one holds a credential:

sudo chmod 600 /etc/systemd/system/updaterd.service.d/token.conf
sudo systemctl daemon-reload
sudo systemctl restart updaterd

A token on a developer's board is fine. A token on a customer robot is not — a fleet-wide credential in an image cannot be rotated without reflashing — which is why the answer is a public repository rather than a shipped token (docs/design/updater-design.md §6.1). A board with no token can still install from a local directory or a dev push.

Installing without a network

On a board that already has a release, install a local directory the ordinary way — through the daemon, with the health gate:

sudo robotctl update apply daemon --from /media/usb/release

That is also what scripts/dev-push.sh ends with; dev-push.md is the laptop-to-board path.

The rest of this section is the bare-board case: a factory or offline install, before there is a daemon to ask. It is updaterd rather than robotctl for that reason, and updaterd is deliberately not on PATH:

sudo /opt/robot/daemon/current/bin/updaterd install --from /media/usb/release

The directory holds what a release is: <version>.manifest.json, its .minisig, the artifact and the artifact's .minisig. Signatures, hashes and compatibility are checked exactly as they are for a download — --from changes where the bytes come from, not what is trusted.

That command refuses to run once a release is live, because it forces on_apply and the health gate off, and doing that to a working robot would silently disable auto-rollback. One situation needs it anyway, and robotctl update apply cannot help with it — a board whose installed updaterd is too old to accept the release that fixes being too old. It rolls the new release back every time, and the binary running that gate is the one being replaced. Stop the robot and say so explicitly:

sudo systemctl stop robotd
sudo /opt/robot/daemon/current/bin/updaterd install --from /media/usb/release --force

--force is itself refused while robotd is still answering, since the objection is about a working robot losing its safety net. It gives up auto-rollback for that one install and nothing else — signatures, hashes and compatibility are still checked, and sudo robotctl update rollback daemon is the recovery path if the release misbehaves.

Going deeper

deploy/README.md is the reference for what all of this actually does: the trust chain, what ends up where, the other ways in (on the board without a clone, by hand step by step), where logs go and what survives a reboot.