The board's kernel has no hid-nintendo, so a Switch pad runs on hid-generic
in its simple HID mode and nothing on the robot knew its battery. Every
subcommand reply carries it, though: byte 2 of an 0x21 report.
- padd asks the connected Nintendo pad on its hidraw node once a minute
(subcommand 0x50, which changes nothing), and writes the level and the
charging bit to /run/padd/pad-battery.json. With hid-nintendo present it
reads that driver's power_supply instead and sends nothing.
- configd adds it to the connected pad in pad.status, while fresh (5 min).
It cannot ask the pad itself: PrivateDevices leaves no hidraw in its /dev.
- robotctl pad status and robotctl monitor's pad title show it.
- A udev rule gives padd the Nintendo pads' hidraw (group padd, 0660),
installed by hooks/postinstall on every update; xtask checks it is packaged.
API v65: Pad.battery, optional.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The October brain, brought up to main. Beyond the conflicts:
- The pad's handoff (silent until touched, lets go after pad_idle_s) is
now pad_map::engage, since main moved padd's mapping into pad-map. A pad
nobody was touching going away no longer sits the robot down: the brain
was driving, not the pad.
- autod walks at the pad's [pad_drive] full stick rather than the removed
robotd_params::drive constants.
- [map]'s template values are commented out like [laser] and [soccer]:
they never shipped live, so they do not belong in EVER_SHIPPED.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
robotd/emotions/ holds the 13 emotions from microduck_emotions (431c73d),
cut by scripts/vendor-emotions.py, and every packaging site includes them as
emotions/ (xtask --include now takes a directory). robotd loads the shipped
set from the release, then [emotions] dir on top: a file there adds one or
replaces the shipped one of the same name. A robot installed or updated to
this build has them with nothing to copy. The simulator reads the
checkout's set.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit f6822d9894)
main took API v42–v44 for the vet book, so map.* moves to v45. netpadd
joins mapd in the release units, the restart order and configd's MANAGED
list (now ten); the Call variant count is 77 with both sides' routes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mapd subscribes to robot.state and tof.frame like any client, feeds the maploc
mapper on its own thread, keeps the map in /var/lib/mapd/map.json across
reboots, and answers map.status, map.stream, map.grid and map.wipe on
/run/mapd/map.sock. It commands nothing: the robot walks without it, and the
head moves by robotd's own idle glances.
The map file is replaced atomically, saved every autosave_s, when the pose has
moved 30 cm and on shutdown; a file it cannot read is set aside as
map.json.bad-<secs>, never overwritten.
[map] in robotd.toml (on by default); robotctl map / map show / map wipe;
routed over WebRTC by mediad, refused over BLE. Packaged in both release
workflows and dev-push, named in install.sh, configd's unit list and
updater.toml. docs/design/mapping-design.md owns the mechanism.
Checked end to end against a recorded living-room session served over real
sockets: same 21 stops as the offline replay, saved on SIGTERM, and after a
restart relocalized within four stops onto the first run's nodes (2-3 cm).
Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
A policy keeps stepping when the duck is lifted, so a robot picked up mid-walk
thrashes in the hand until somebody presses Start. `[pickup] enabled = true`
runs a small classifier over the last second of what the loop already reads
(gyro, gravity, joint positions/velocities, last commanded target) and pauses
the walking/standing networks while a hand carries the robot: the legs ramp to
the walking policy's own standing stance at the policy gain, and the policy
takes the robot back ~0.2 s after it is set down on its feet.
- duck_control::pickup: feature row, 1 s window, ONNX detector, hysteresis
latch and pause pose -- the contract with the training code in microduck_rl
(pickup_detector branch); model vendored at duck-control/models and packaged
at all three release sites, with a tripwire test
- robotd/src/pickup.rs: the loop's side; watches only walk/stand in walk mode,
any other owner (skill, sit, limp-fall, disable, shutdown) ends a pause, a
failing detector lets go; off means nothing is loaded or run
- robotd-params [pickup]: enabled (feature switch in robotctl configure,
restarts robotd), model, pause/resume thresholds (validated as a band)
- docs: robotd-design.md 2.4.2, cheatsheet "Picking the robot up"
Trained in simulation only. Closed loop in the RL sim: pick-ups detected 100 %
(median 0.20 s), set-downs resumed median 0.18 s, under ~1 false pause per hour
of walking. End to end against duck-body (robotd --sim, velstand, a scripted
hand): three pick-ups paused in 0.22-0.28 s, three set-downs resumed in
0.20-0.24 s, no false pause while walking, standing or turning.
Assisted-by: Claude:claude-opus-5-5
The image's account is `microduck`, not `radxa`. `duckctl ssh`/`scp`
and `dev-push.sh` fall back to it when neither `--user` nor
`DUCK_BOARD_USER` is set, and every doc example follows.
Assisted-by: Claude:claude-opus-5-5
The bench script becomes a daemon that ships in the release. nfcd owns the
CLRC663 reader on /dev/ttyACM0, a Rust port of winnie's ntag663 cut down to
selecting a tag and reading its NDEF, and polls it at 5 Hz. On a tag's
arrival it takes the first Bluetooth address in the records: a pad already
connected means nothing happens, otherwise configd pairs that one
(pad.pair) and robotd quacks (robot.sound). One attempt per touch.
No reader is the ordinary case — one log line and a retry every 30 s, so
plugging one in is all it takes. Unprivileged: dialout for the port, robot
for the sockets, and configd names it in --allow-user since pad.pair is
mutating.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mediad reads its model from /opt/robot/detector/current rather than from
inside the release. The release's postinstall hook seeds that directory
from a pin in [workspace.metadata.detector] (pollen-robotics/
microduck-duck-detector@duck-v1) with scripts/seed-detector.sh, which is
seed-policies.sh with a fixed file list and the same rules: a floor not a
ceiling, nothing partial goes live, never touch a set it did not install.
`robotctl detect check` and `sudo robotctl detect update [--version]`
are `policy check`/`update` against the other root — new updaterd calls
detector.check / detector.install (API v28), sharing the policy set's
types, provenance record and install path. An install restarts mediad,
which is where the model is loaded, and reports whether that took.
The 14 MB of vendored weights leave the repository and the three
packaging sites; xtask holds the pin, the file list (script, updater,
robotd-params) and the packaging together.
The model repo shares its name with the dataset repo. The robot only
addresses the model (resolve/ without a datasets/ prefix, api/models/),
which is written down where the URLs are built.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Every boot of the Armbian image runs /usr/lib/armbian/armbian-apt-updates from an
`@reboot` line in /etc/cron.d/armbian-updates: a simulated `apt-get upgrade -s -qq`
that pins one core for several seconds while robotd is starting, to produce an update
count that only the stock login banner reads. The robot updates through updaterd, so
nothing on it reads that number.
scripts/setup-quiet-boot.sh empties that cron file (kept as a file so the package that
owns it does not put its lines back) and masks apt-daily.timer and apt-daily-upgrade.timer,
the other unattended apt work a board does — including, on the Ubuntu-based images,
unattended package upgrades nobody asked for. `apt-get` by hand is untouched.
Run by install.sh and by hooks/postinstall, so every board already in the field gets it at
its next update (updater-design.md §9.1); packaged by both workflows and dev-push.sh, which
the xtask guards insisted on. board-test.sh asserts the cron file is emptied and both timers
masked, from install.sh and from the hook alone.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The set is on the Hub at pollen-robotics/microduck-policies, so the copies here
have nothing left to do. Verified before deleting: the real fetch pulls all nine
files and every one is byte-identical to what was vendored.
Gone with them: the nine --include lines at each of the three packaging sites,
and every_policy_in_the_repo_is_packaged, which existed to keep those three
lists honest against this directory and now guards nothing. The transitional
fallback goes too — seed-policies.sh no longer takes a release directory,
because there is no longer a release copy to fall back on.
A board that cannot reach the Hub on a first install therefore has no gait, and
that is the accepted shape rather than an oversight: robotd holds its pose and
reports degraded, so the update gate passes and nothing rolls back, and the next
update fetches. It is the bargain setup-board.sh already makes for ONNX Runtime
and setup-gstreamer.sh for the plugins — a board needs a network once. What the
seeder must never do is *fail*, since a non-zero exit from the post-install hook
would roll back a release over a network problem that had nothing to do with it;
every error path exits zero and says so on stderr.
The provenance table moves to policy-channel-design.md §10 rather than being
deleted with the README. It records which upstream training run each role name
points at — including the roller_crouch typo fix — and that mapping is not
recoverable from the file names on the Hub, so this repository was about to be
the only place it had ever been written down and then not be.
The pin is still v1 and the tag does not exist yet, so boards keep whatever they
have and the fetch starts working the moment it is created.
Assisted-by: Claude:claude-opus-5[1m]
robotd read its policies out of /opt/robot/daemon/current/policies, which is
what made a gait retrain need a daemon release and a daemon fix re-ship six
megabytes of unchanged weights. It now reads /opt/robot/policies/current, and
that is the whole point: one runtime source for a policy, whoever put it there,
with no precedence rule between a release copy and anything else to get wrong
later.
Nothing publishes a policy bundle yet, so until something does the release is
what fills that directory. scripts/seed-policies.sh — run by hooks/postinstall
on every update and by install.sh on a fresh board, which between them are every
way policies reach a robot today — copies the .onnx files the release still
carries into releases/seed-<version>/ and points `current` at it, in the same
releases/ + symlink layout the updater already swaps.
One rule makes that a bootstrap rather than a second home: it never touches a
set it did not install. A `current` pointing anywhere but a seed-* directory
means something else put policies there, and the release stops overwriting them
for good. The handover therefore needs no flag and nothing to remember — whatever
ends up publishing bundles just installs one, and the seeding is over. A newer
seed does replace an older one, because while the release is the only source of
policies a daemon update is still how a retrained gait reaches a board; a seeder
that only ever filled an empty directory would freeze every board on whatever
first seeded it.
Two bugs found by testing the seeder rather than reasoning about it. The
`current` symlink was written with an absolute target, which resolves against
the wrong directory the moment the root is not the one it was written with — it
is now relative to its own directory, the way the updater writes it. And the
"is this ours" test was matching the absolute form, so with the fix it would
have stopped recognising its own seeds and never replaced one.
hooks/postinstall was not in the shellcheck list while being the one file that
runs on every board on every update — the argument that comment opens with,
applied to itself. It and seed-policies.sh are now linted.
What is NOT here, and why: the policies component on the Hub. Every artifact the
component path installs is signature-verified, unconditionally, by the same code
that installs daemon binaries — so an official set delivered that way has to be
signed, which is a decision about the engine rather than about policies and is
not one to take while nothing is published. Recorded as the open question in
policy-channel-design.md §13; the seeding holds until it is answered, and
policies/ stays in the repo because the seeding is what reads it.
Assisted-by: Claude:claude-opus-5[1m]
`install.sh` wrote three files nothing else writes: the `robotctl` completions, the motd
banner, and the `/etc/profile.d` snippet putting the robot's name in the prompt. It runs
once, on a board being set up, and it is not in the artifact — so no hook could run it
even if one tried. The board this was found on has been taking updates since 19 August
with the banner and the completions from that day and no prompt snippet at all, because
the prompt landed on the 26th and boards do not get provisioned twice.
`scripts/setup-login.sh` is those three functions, moved whole. `install.sh` runs it out
of the installed release — the copy a signature was checked against, like the sysusers
files — and `hooks/postinstall` runs it on every update, which is the caller that matters:
it is what puts a file on a board provisioned before that file was written. Idempotent by
construction, since each step rewrites its own file, and never fatal, because a shell
prompt is not worth rolling an update back for.
Moving them fixed an unrelated wart on the way: the comment explaining why the completions
are a loader rather than a snapshot had drifted forty lines from `install_completions` and
sat above the banner instead.
**And the test, which is the point.** §9.1 has now been broken four times and the fourth
happened the day before the rule was written down, so a fifth was a matter of time.
`every_install_sh_step_reaches_an_updated_board` reads `install.sh`'s call sites and fails
unless each one is either performed by a hook too or written down, with a reason, as
something only a fresh install does; its second half fails if `install.sh` runs a
`setup-*.sh` out of the release that no hook names. Both halves were confirmed to fail by
breaking them. It is a forcing function and not a proof — the escape hatch is a line in a
table — but every one of the four would have had to argue for that line.
`board-test.sh` deletes the three files before the postinstall-alone run and asserts the
hook puts them back, and drives the prompt snippet rather than only checking it exists:
it cannot edit PS1 directly, so it hooks PROMPT_COMMAND and rewrites PS1 at the first
prompt, and that indirection is the half that silently does nothing when it is wrong.
One gap stays open and is now named where the accounting is: `hooks/postinstall` installs
units but not the journald drop-in and not the `robotctl` symlink. That asymmetry is
deliberate and `board-test.sh` pins it, so it is not changed here.
Assisted-by: Claude:claude-opus-5
`robotctl configure` turns it on, `robotctl update` delivers it, and the
console draws boxes on the video.
**mediad runs it**, on the raw branch of the tee that has existed for
perception since the pipeline was written. Its own thread, because inference
is 60 ms of blocking work and the runtime here serves WebRTC signalling;
paced at 2 Hz, because flat out this takes the board to 95 °C and the CPU
throttles to 408 MHz — a robot that walks badly to see well. The camera's
mount rotation is folded into the resampling it already does, so upright
pixels cost nothing: rotating in the pipeline is what the commit before
this one was about.
**A list of models, not a choice.** The `.rknn` is preferred and the `.onnx`
is the fallback, tried in order: whether the NPU works is not something a
config file can know, and a board whose NPU is disabled in its device tree —
which is how Armbian ships this one — should still see, on the CPU, rather
than log one warning and do nothing for ever.
**`[detect]` lives in robotd.toml** even though `mediad` reads it, because
that is the file `robotctl configure` edits and a robot has one place for
its settings. Which meant teaching configure that a section can belong to
another daemon: `[detect]` restarts `mediad`, everything else `robotd`. That
uncovered a bug of its own — `save()` clears the pending map and the restart
decision is made after the editor closes, so it restarted *nothing*, ever;
the model now records what it wrote and a test pins it.
**The console** draws boxes on an SVG whose viewBox is the upright frame's
own pixels, in the same grid cell as the video. The wrapper is already the
upright space, so the boxes need to know nothing about the mount rotation
and neither does drag-to-look. Boxes expire after 2.5 s: at 2 Hz a longer
silence means the detector stopped, and the alternative is the last duck
painted on screen for ever, which looks exactly like a duck still standing
there.
Two things the boxes will not tell you, both measured. The score is one bit:
the head emits box coordinates (0..320) and scores (0..1) in one tensor
under one INT8 scale, so the scale is set by the coordinates and every real
detection reads exactly one step — two distinct values in the whole channel.
The label says "duck" and no number for that reason. And box edges land on
that same ~1.3 px grid at 320², about 5 px at full resolution. Splitting the
head before the concat is the fix when confidences start to matter.
Also: mediad needed the `render` group. The NPU is a DRM device
(/dev/dri/renderD129, root:render 660) and without it `rknn_init` returns a
number that says nothing about permissions.
Each was found by the docs audit (#154) and written down there rather than
fixed, because a docs change is not the place for code.
**`cargo test --workspace` now works on a Mac.** `vendor/platform.c` reaches
the bus through `linux/i2c.h`, so `build.rs` compiles it only when the *target*
is Linux — read from `CARGO_CFG_TARGET_OS`, since a build script is compiled
for the host and `cfg!` there would answer for the laptop. The driver's calls
go with it, and off a board `Sensor` is uninhabited: `open` is the only
constructor and it always fails, so the compiler discharges every other method
instead of leaving a body that could one day invent a frame. `tofd` still
builds, `tofd --fake` still serves, and 942 tests pass with nothing excluded.
**`install.sh` stops reporting `tofd` as a daemon it forgot.** The hook enables
every unit with an `[Install]` section a step earlier, so the warning was noise
on every fresh install. Named as known, with no `enable_unit` of its own:
nothing depends on it, so there is no ordering to have an opinion about.
**`dev-push.sh` checks all seven daemons**, not six — and the comment saying
five, restarted in a set of three, was two daemons out of date.
That last one could not work on its own, and finding out why turned up two
faults rather than one:
- **`tofd` published no identity.** Six daemons call `log_startup_identity!`;
`tofd` had a hand-rolled `warn!` that logged a version and wrote no
`/run/tofd/identity.json`. That macro exists because `padd` was once the one
daemon whose journal could not say which build was running — and its own doc
comment predicts this: "a shared definition makes the next daemon's omission
a missing call rather than a missing idea". `tofd` was the next daemon.
- **`configd::units::MANAGED` was still five units.** `mediad` and `tofd`
shipped units two releases ago. So the `units` block of `robotctl health` —
the one a person reads after an update to find which daemon is still on the
old release — could not report either of them at all. Same defect as the
restart set in `restart-order.md` that #154 fixed, one file over.
Docs follow the code: the macOS caveat in CONTRIBUTING, the `tofd` note in
`restart-order.md` §6, and `dev-push.md`, which claimed `robotctl version`
could answer for `tofd` — it could not, for both reasons above.
Verified: `cargo test --workspace` 942 passing on macOS with no exclusions,
`cargo board -p tof --bins` still cross-compiles the driver for the board,
clippy clean for what this touches, `shellcheck -S warning` clean on both
scripts.
Assisted-by: Claude:claude-opus-5[1m]
The camera works and has no auto exposure, no white balance and no
denoise, because nothing converges the ISP: mediad pins one exposure at
startup and that is the picture, green and noisy, for every lighting
condition afterwards. The prototype solved this with Rockchip's rkaiq
engine, and it is still the only 3A on this platform — libcamera's IPA
drives mainline rkisp1, and mainline would cost us the hardware encoder
mediad depends on.
So scripts/setup-rkaiq.sh, a sibling of setup-gstreamer.sh with the same
contract: never prompt, never fatal, leave a copy at
/usr/local/sbin/robot-setup-rkaiq, and run from both provisioning (on by
default, --no-rkaiq to skip) and the pre-install hook, so a board
provisioned before this existed gets it from an ordinary update.
**One thing is deliberately not ported: the AE disable.** The prototype
zeroed ae_calib CommCtrl.Enable because its runtime owned exposure — a
software AE loop over decoded MJPEG, and pinned values in laser mode
that rkaiq clobbered into a black image. Neither reason survives here,
and auto exposure is the thing that is missing, so the engine owns it.
These being the same physical boards, a file left at 0 by that script is
the likeliest way to install an engine and still have no auto exposure,
so the script sets it back to 1 rather than trusting what is on disk.
Carried over intact: the LD_PRELOAD ioctl shim, without which the engine
segfaults on this kernel (the deb was built against different headers,
so the module-info ioctl number disagrees by a struct size), and the
sensor-mode pin before the engine starts — it reads the sensor
resolution once and programs the ISP with it, so the IMX219's 3280x2464
boot mode against mediad's 1920x1080 capture is CIF_ISP_PIC_SIZE_ERROR
and no frames at all.
Tested off-board, since none of this can be: the IQ patch against a
synthetic CRLF tuning file (renames applied once, idempotent, AE flipped
back on, line endings intact), the generated pin script against a
media-ctl topology stub (it emits exactly the call mediad's
pin_sensor_mode makes, and exits 0 on a camera-less board so it cannot
block boot), --help, and the shim's compile. A new xtask test packages
the shim beside the script that compiles it — which caught a third
packaging site, dev-push.sh, that the hook guard alone would have
missed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
`setup-gstreamer.sh` has said so since it was written — "the download happens during provisioning
and, later, from the updater's preinstall hook, which runs with a cleared environment and no token",
which is why the plugins repository is public. The hook half was never written, so a board
provisioned before that script existed needed a command somebody remembered, and a board whose
plugins predate the version this release was built against failed with a missing element in a log.
The hook runs the release's own copy of the script rather than a second implementation of it. That
script owns the pinned plugins version, the Debian package list, the Rockchip MPP and RGA debs, the
udev rule for `/dev/mpp_service` and the encoder report — six things that would otherwise exist twice
and drift, which is the class of bug this repo keeps writing down. It is idempotent by design, so a
provisioned board pays a stamp comparison and two `dpkg -s` calls.
**Never fatal**, and that is the difference from the ONNX Runtime step above it. A release that
cannot load a policy is a robot that cannot stand, so that one aborts the update with the old release
still live. A board with no camera stack loses `mediad` and still walks, pairs and updates — refusing
the update over it would mean a board that cannot be fixed by the mechanism that fixes boards.
**The pre-install hook gets ten minutes instead of two.** It is the hook that installs what the
release needs and the board may not have, and on a board that has never had the media stack that is
around 100 MB of apt over whatever wifi the robot is on. It can afford the minutes precisely because
nothing has been swapped yet: the old release is still live and serving, so a long pre-install is a
slow update rather than a robot in an unclear state. The post-install hook keeps its two minutes,
where the same wait would sit between the swap and the restart.
Packaged at all three sites, with an xtask tripwire — `every_script_the_hooks_run_is_packaged` — for
the failure this would otherwise have: a script referenced and not packaged makes the step a no-op
that says so in a log nobody reads, on exactly the boards it exists for.
Assisted-by: Claude:claude-opus-5[1m]
It shipped without one so that a board could carry the binary without running it, "until it has
proven itself over a few boots". It has run, and the gate had turned into a permanent manual step:
`hooks/postinstall` skips `enable --now` on a unit with no `[Install]`, `units_shipped` skips it when
an apply restarts daemons, and `install.sh` warned that it did not know where the unit belonged. So
every push ended with somebody typing `systemctl restart mediad`, and every board provisioned in the
meantime accumulated a bring-up step nobody remembers.
One rule does all of it — a unit with an `[Install]` section is enabled on install and restarted on
apply — so this is the section, and the removal of everything that stood in for its absence:
- `install.sh` starts `mediad` after the daemons it forwards to, allowed to fail like `btd` and
`padd`, with the GStreamer command in the warning.
- `dev-push.sh` loses the `deferred` list, the `[--] nothing restarts it` branch and the exit-3 path
that existed so the closing line would not contradict them. A stale `mediad` is now a `[FAIL]`
like any other daemon, because now it is one.
- `deploy/updater.toml`, `updater.example.toml` and `updater-design.md` stop saying `mediad` joins
the restart list when it exists. It needs no entry at all: the set is derived from the units the
release ships, and `units` is only for units it does not.
- `robotctl`'s camera line and `monitor`'s caption still omit themselves when `mediad` published
nothing, which is still right — but the reason is a board with no camera, not a daemon that ships
disabled.
**Two ways this can now fail on a robot nobody is watching**, both reported by `robotctl health` as a
unit that is not running, neither touching the control loop, BLE, the pad or an update:
- a board provisioned before `setup-gstreamer.sh` existed has no plugins, so the pipeline cannot
start and `Restart=always` retries every five seconds. `sudo /usr/local/sbin/robot-setup-gstreamer`
fixes it. Provisioning has installed the stack by default since before `mediad` shipped, so this is
only boards older than that.
- a board with no camera, because `ExecStart` carries `--camera`. The unit's own drop-in is the fix.
And one behaviour change on every robot: an update now restarts `mediad`, which drops a live WebRTC
session. `remote-webrtc.md` §8 already describes the gate that will hold an update while a session is
active; nothing sets that flag yet.
Assisted-by: Claude:claude-opus-5[1m]
`duck-btctl` was an example of `btd`, and both halves of that stop fitting.
`mediad` gives a robot a second transport, and the two reach different method
sets by design — `robot.move` is refused over BLE and permitted over WebRTC,
`net.connect` the other way round — so a tool named after one radio teaches
everyone that it is the way in, at the moment it stops being the only one.
Its own crate, because a transport-agnostic client cannot be an example of the
BLE daemon: it would need btleplug and a WebSocket client, and only one of those
belongs to `btd`. The guarantee the example arrangement bought — btleplug never
in a release — survives as something stated rather than incidental: nothing on
the robot depends on `duckctl`. `advwatch` comes too; it is a scanner, and
scanners run on laptops.
`default-members` is what keeps it off the board. `cargo board --bins` builds
every default member for aarch64, and cross-compiling a Bluetooth stack for a
board that must never see one is both wasted and wrong. One list, rather than
naming binaries at each of the two `--bins` call sites.
No shim: `duck-btctl` is gone rather than aliased. `docs/project/` keeps
saying it, because those are records of a moment and a tool did not have this
name when they were written — their links are repointed, their prose is not.
Assisted-by: Claude:claude-opus-5
The check printed
[--] mediad is still on the previous release; nothing restarts it
==> every daemon on <board> is running <version>
which contradicts itself two lines apart. Making mediad's staleness non-fatal was right; leaving
the closing line to say "every daemon" was not.
The remote half now exits 3 when it deferred something, and the closing line says "apart from the
daemon marked [--] above" instead. No second ssh and no temp file to carry the name: it is already
on the line above, so the exit code is all the caller needs.
Assisted-by: Claude:claude-opus-5[1m]
Adding mediad to the post-push check made it fail every push. Nothing restarts mediad: it ships
with no [Install] section and updaterd does not manage it, so after a push it keeps running the
release it was started with until someone restarts it by hand.
So `stale` is the correct state for it rather than a fault, and the check now says so and prints the
command instead of the three-line "a fix that did not work" block.
Assisted-by: Claude:claude-opus-5[1m]
Every wrong turn in the camera bring-up came from inferring the delivered frame rate: from rkvenc
interrupt counts, which measure what the *encoder* did; from "lost frames detected" warnings, which
count sequence gaps and go quiet when the source merely runs slow; or from timing gst-launch, which
is a different pipeline. The tee's raw branch sees every frame, so it counts them.
Quiet when healthy: the first ten-second window is reported and after that only a crossing of the
90% threshold, in either direction. Six lines a minute forever gets grepped out, and then it may as
well not be logged at all.
dev-push's post-check now includes mediad. It reports [--] rather than failing when nothing is
published, which is correct here: mediad ships with no [Install] section, so being stopped is its
normal state until it has survived a few boots.
Assisted-by: Claude:claude-opus-5[1m]
It used to `scp` libudev.so.1 from the robot and hand-write a `.pc` beside it,
which worked because libudev-sys asks for no particular version and the linker
records the SONAME rather than the filename. GStreamer ends that: `mediad` needs
seven pkg-config modules with real Cflags and Requires, and hand-writing those
is not a thing to do.
Two things got better rather than merely different. The sysroot comes from
Debian trixie — the same archive the board installs from — so versions match by
construction instead of by having copied one file off one board. And **building
no longer needs a reachable board at all**: the old path exited with "no
libudev.so.1 on $BOARD", so the board you wanted to set up was the board you
needed in order to build, which is the wrong way round. Its own comment noted
`--docker` as the way out of that; there is no longer anything to get out of.
The one fact worth keeping from the old block is kept: libudev-sys probes for
udev_hwdb_new by linking with the *host* toolchain, which fails on a Mac and
leaves its hwdb cfg off. gilrs calls nothing under that cfg.
Assisted-by: Claude:claude-opus-5[1m] shellcheck
Two tripwires fired, both correctly, and the fix for each is the thing they
were pointing at.
`every_sysusers_file_in_the_repo_is_packaged` caught a sysusers file in the tree
that no packaging site installs — "the account it creates will not exist and the
unit naming it will not start". The tension it exposed is real: I did not want
to ship mediad, because postinstall enables every unit that ships, and a daemon
that has never run would restart-loop on every robot in the field.
`[Install]` is the switch, and the repo already had the precedent: postinstall
skips a unit with no `[Install]` section and says so, which is how the boot
recovery net's oneshot ships. So mediad ships — binary, unit, account — and
starts only when somebody runs `systemctl enable --now mediad`. The unit carries
the three lines to add when it has run somewhere, and why they are absent.
`every_binary_a_packaged_unit_execs_is_staged` then caught dev-push.sh packaging
the unit without staging the binary, which would have been 203/EXEC on a board.
Both tests earned their keep.
The other failure was mine: dev.yml and _build-release.yml have their own
cross-build steps, and I had wired the sysroot into ci.yml alone — so they still
pointed pkg-config at Ubuntu multiarch and died in glib-sys. Fixed by replacing
multiarch with the sysroot in all three rather than adding the sysroot beside
it: PKG_CONFIG_LIBDIR replaces the search path while PKG_CONFIG_PATH prepends to
it, so keeping both would have mixed Ubuntu's libudev with Debian's GStreamer,
and only one of those matches the robot.
That makes scripts/ci-cross-deps.sh dead, so it goes, and the prose that quoted
it now names what replaced it. Deleting it is safe to do here rather than later
because ci.yml's board job has already gone green with the sysroot — the step
works, unpacks in about ten seconds, and caches on the hash of the script that
owns the package list.
Assisted-by: Claude:claude-opus-5[1m] shellcheck
The previous commit built the daemon but nothing carried it: both the
binary and the unit are explicit lists, so the release had neither and
`systemctl status tofd` found no unit. Now:
- All three packaging sites stage the `tofd` binary and `--include`
tofd.service + its sysusers conf. postinstall enables and starts
every packaged unit, so an `update apply` brings tofd up by itself;
the xtask tripwires enforce the three lists staying in step.
- install.sh names tofd.service in the two hardcoded stop lists (the
install path itself reads the release directory, so it needed
nothing).
- setup-board.sh gains configure_tof(): the /dev/i2c-pihat udev rule,
so the bus has a stable name across a kernel or overlay renumber.
The bus, overlay and vendor kernel were already done by the audio
section — the sensor shares the codec's i2c3 — and i2c-tools moves
into that package list, since its postinst is what creates the `i2c`
group tofd joins (and i2cdetect is the first thing anyone runs when
a device on that bus goes quiet).
- architecture.md records tofd in the service table with why it is not
in robotd (firmware upload, shared bus, mostly-absent sensor) and
why it is not mediad's (a sensor on a bus, not a media pipeline).
The cheatsheet documents the panel, the three absence states, and
that stopping it is safe.
Verified: monitor survives tofd being SIGTERMed and recovers when it
returns, with no panic and a sentence saying which of the three
situations it is in — nothing depends on the unit, and robotd has no
reference to it at all.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Migration step: the prototype's audio stack, with its two satellite
repos absorbed as workspace crates and the Python removed entirely.
sounds/ is microduck_sounds rewritten in Rust: the seedable synth
(personality, recipes, variants) plus a CLI whose ensure-bank replaces
generate_sounds.sh — no venv, no numpy, no ffmpeg. It renders at
48 kHz natively (the resample step existed only because the synth was
22.05 kHz and the Radxa's I2S tree is 48k-family), with the two
rate-tuned constants rescaled to keep their time-domain character. The
RNG is a vendored xoshiro256++ with a pinned-stream test, because the
generator IS the voice: every robot re-rolls once (bank v5, the same
event as a synth retune), then stays itself forever. The seed
derivation (SoC serial -> sha256 -> u32) is unchanged, so each robot
keeps its personality traits' provenance. The parrot experiment stays
unported.
pet-detect/ is microduck_pet_detect plus the prototype's pet_worker:
mel extractor, streaming detector, the arecord worker and the ambient
sound sentry, the pet-detect/pet-features binaries, the vendored model
(shipped as models/pet_detect.onnx) and the training script — which
extracts features through the Rust binary, so train/infer parity
crosses the port intact.
robotd owns playback (root already, and the codec PCM is single-
client): greet as the loop comes up, goodbye peck on shutdown, coo on
petting (walk mode, per the prototype's launch lines), and the new
robot.sound call (v10) for the rest. padd's triggers do what the
prototype's did — RT quacks on its rising edge, LT rides the wheee,
streamed start->loop->end into one aplay with the writer paced 250 ms
ahead. The hold is a per-tick notification that decays, so a client
that dies mid-ride leaves a ride that lands. robotctl quack replaces
the quack binary, over the socket — so it also works from a laptop on
a forwarded socket, which is when you actually need to know which duck
you are talking to.
Found by the fake-bus torture test: robotd restores SIGPIPE's default
disposition at startup, so a write into a dead aplay killed the whole
daemon — the wheee writer thread now blocks SIGPIPE and gets EPIPE
like it expects.
Provisioning: setup-board.sh gains configure_audio() — alsa-utils +
DKMS toolchain, the Armbian vendor kernel (+headers), the i2c3 +
codec/I2S overlays compiled from deploy/audio/, the aic3x DKMS module
(the vendor kernel does not build SND_SOC_AIC3X), and the mixer-init
service ordered Before=robotd. The voice bank is NOT provisioned
there: every release install renders it via postinstall (sounds
ensure-bank, idempotent by seed+version marker). Packaging ships the
three new binaries and the model at all three sites, with a tripwire
for the model like the policies have.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The --include list exists in three copies: dev.yml (what --ref <branch>
installs), _build-release.yml, and dev-push.sh. The skills branch added
its six policies to the last two and missed the first — so the branch
build shipped two networks of eight, robotd failed its health gate on
the first missing file, and the board rolled the release back.
All three lists now carry the full policies/ directory, and a new xtask
tripwire (every_policy_in_the_repo_is_packaged) fails the build when a
vendored .onnx is missing from any site — the same guard the units and
hooks already had.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Both sides had claimed API v8 — main's v8 is pad.input, so the skill
intents (robot.do/pose/mouth/shutdown/mode) move to v9. In padd, the
merge keeps main's per-tick tap.watch alongside this branch's
Drive/Head/BodyPose modes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
`provision-board.sh` never forwarded `DUCK_NAME`, so the only way to name a
board while provisioning it was to run `provision.sh` on the board by hand.
Through the wrapper the name silently did nothing, and the fix for that was
either forwarding one more environment variable or making the name what it
actually is: one decision per board, typed at the keyboard.
So `--name NAME` on both, and `DUCK_NAME` is gone. The other knobs are
environment variables because they are passed on — `install.sh` reads the same
names, so a pinned tag is one decision for a whole bring-up — while a name goes
no further than `robotctl system set-name` at the end of phase 2. It is also the
only one that is per-board rather than per-session, and an exported name is
exactly the kind of thing that is still set when the next board is provisioned.
The state file that carries the name across the reboot is now written quoted.
It is read by sourcing it, and a name is free text: `DUCK_NAME=Ducky Two` came
back as an assignment plus an attempt to run `Two`, which under `set -eu` ended
phase 2 on its first line — so naming a robot after two words broke
provisioning rather than just the name. Every value is quoted, not only the
name, and the two keys that are not environment knobs are `PROVISION_*` so that
sourcing the file cannot set something an operator could also have exported.
The name is escaped again on the way over ssh, which hands the command to a
second shell.
Assisted-by: Claude:claude-opus-5[1m] shellcheck
`DUCK_BOARD=radxa@192.168.1.42` is the one setting about a board that cannot be
kept in a shell profile: a reflash, a router reboot or a different network hands
it a new lease, and mDNS on this image is unreliable enough that a `.local` name
is not the answer either. The way that reads is a push that hangs until ssh
times out, followed by finding the address again by hand.
A name does not move. `--name`, or `DUCK_ROBOT` — the same variable `duck-btctl`
already defaults `--name` to, so one exported name serves both tools — and the
address comes from the robot itself over BLE, which is the one channel that
works precisely when the network does not.
Cached in `~/.cache/duck/boards`, and re-resolved only when ssh cannot reach the
cached address. BLE discovery costs ten to twenty seconds and this script exists
to be quick, so the steady state is one ssh probe and the moved-board case pays
one scan before going back to being quick.
Each failure is a different next move, so each says which one it was: a robot
that is not advertising, one that answered but is on no network — joinable over
the same radio, no ssh needed — and one that refused `net.status`, which is a
PIN rather than an address. Re-resolving to the address ssh just failed on says
so too, because the address is then not the problem and a reflashed board with
new host keys looks identical until somebody says it.
An address still wins over a name and skips the radio entirely, so nothing that
worked before changes. `DUCK_BOARD_USER` is for a board whose ssh user is not
`radxa`.
Assisted-by: Claude:claude-opus-5
`updaterd.service` sets `PrivateTmp=yes`, which gives the unit its own
`/tmp` *and* its own `/var/tmp`. `scripts/dev-push.sh` copied the release
to `/var/tmp/duck-sideload`, so the files landed in the pair the shell
sees and the daemon read the pair the namespace gave it. Every push
failed at
error: network error: no manifest for version 0.5.1-dev.local.… in
/var/tmp/duck-sideload
against a directory whose `ls` lists that exact manifest, its signature
and the artifact — a sentence with nothing in it to act on, which is why
it cost an afternoon rather than a minute. The tests never caught it:
they point `LocalDir` at a fixture root, where no namespace applies.
Three changes, one per way this could recur:
- The push now sideloads from the board user's home, resolved on the
board. It keeps the property `/var/tmp` was chosen for — writable by
the ssh user, so no sudo to copy into it — and is outside the unit's
namespace.
- Preflight gains `Check::SideloadDir`: a `--from` directory this process
cannot see fails before any lookup, and when the path is under `/tmp`
or `/var/tmp` the failure names `PrivateTmp=yes` and says where to put
the release instead. A board that does not privatise `/var/tmp` passes
it without noticing it exists, and `updaterd install --from` — which
runs as a CLI, outside the namespace — is unaffected.
- `xtask/tests/sideload.rs` holds the two files against each other: the
script may not name a path the unit hides, and while it sideloads from
a home directory the unit may not set `ProtectHome=`. Neither file can
check that alone, and a third test fails if both halves stop applying
so the file cannot go quietly vacuous.
Assisted-by: Claude:claude-opus-5[1m]
The first migration step: everything between the sticks and the servos
that the prototype had and the daemon did not, minus what is deprecated
(jump, roulade, fold, the non-alpha variants).
Skills, scheduled in robotd with the prototype's priority chain
(kick > ground pick > sit/rise > stand > walk), each its own network on
the shared 61-D observation:
- ground pick (phase-encoded command, ends at 70% of the cycle)
- ball kick left/right (0.5 s window, all-zero command, standing tuning)
- sit <-> stand via the sitstand posture flag (sit at full gain, rise at
standing gain for 1 s, then back to velstand)
- body-pose mode (robot.pose: z/roll/pitch into the obs body block)
- shutdown sit (robot.shutdown / Select 2 s: sit 4 s, torque off,
systemctl poweroff) and battery-empty auto-shutdown at 6.6 V EMA
- seated-boot detection (mean leg deviation > 0.30 rad: rise via the
sitstand network instead of the linear home ramp)
- roller mode ([policy] mode = "roller": roller nets, crouch on the
ground-pick slot, no standing, the preset tuning; padd asks
robot.mode and shapes its sticks to match)
Control-loop features carried with them:
- command smoothing (cmd_alpha/head_alpha 0.2, robot-side so every
client gets the same feel)
- voltage-adaptive action scaling (off by default, as the prototype)
- asymmetric forward/backward speed caps in padd
- mouth control (robot.mouth from the triggers, -5deg..30deg)
- fall recovery ([safety] fall_recover: limp 0.3 s, stand-up network
until solidly upright 1 s; the one sanctioned drive-while-fallen path,
marked inside Safety itself)
- IMU warm-start gate: the policy will not start on an unconverged
orientation filter
Defaults now match the prototype's CURRENT alpha configuration — its
built-in defaults, which its installer passes no flags to override:
action_scale 0.9 (was 0.7), standing_gain_ratio 0.8 (was 0.6), head/leg
low-pass ON at 0.5/0.7 (the values the policies are trained with; they
were off). The vendored policies are re-synced to the runtime's current
symlinks (walking_rough, stand_body_control) plus the six new networks,
all verified obs[1,61] -> actions[1,14], from apirrone/microduck_runtime
@ 5f3b314.
padd adopts the prototype's full button map (Start/Y/B/A/LB/RB/DPad-Down/
triggers/Select-hold). API_VERSION bumps to 8 for robot.do, robot.pose,
robot.mouth, robot.shutdown and robot.mode — boards need one
dev-push --bootstrap to cross it.
Verified end to end against real ONNX inference on a fake bus: every
skill transition, the per-state gains (200/160), the mouth endpoints,
body-pose forcing the standing net, roller-mode loading and refusals,
and the deadman still engaging when intents stop.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
`dev-push.sh` ended at "is live". That means the swap happened and the health gate
passed; it does not mean the five daemons are running the release that was swapped
in, and the gap between those two is where an afternoon goes — four wifi fixes were
once verified as broken against a `configd` that had never restarted.
So it now asks. Each daemon publishes its identity at startup, naming the release
directory it was launched from, so this is a file read rather than a question — which
matters for `btd`, the one daemon that serves no socket and therefore cannot be asked
anything else.
Three things are compared, not one. Every daemon against the board's `current`; and
`current` against the version this push built, because five daemons agreeing on the
release this push was meant to replace would otherwise read as success. `robotd`,
`configd` and `padd` must match at once — they restart before the reply, so a
mismatch there is a fault rather than a race. `updaterd` and `btd` are polled for up
to 30s, because they restart five seconds after it.
Polled rather than slept: a fixed sleep is either a wrong answer or a slow one, and
the interesting case is a restart that never happens, which no length of sleep
improves.
Two deliberate non-failures. A daemon that published nothing is reported, not failed:
systemd removes the runtime directory when a unit stops, so it is also what a
disabled `padd` looks like. And `robotctl health` only has to answer — a bench board
with no servo power reports degraded, which is a fact about the bench.
This is item 3 of the plan in install-path-gap.md, and it lands in `dev-push.sh`
rather than as a scenario script run before a promotion. The mechanism it observes is
systemd's — the transient timer, the RuntimeDirectory holding each identity, the
five-second delay — so no container can stand in for it, and a check that runs every
time beats one somebody has to remember.
Exercised against a fake board tree while writing: a stale unit fails and names
itself, all five current passes, a `current` that is not what was pushed fails
immediately, and the poll gives up rather than spinning.
Assisted-by: Claude:claude-opus-5
Five conflicts, and one of them was not textual.
`ci.yml`: the lint list gained `robot-rescue` on main and `dev-push.sh` here. Both.
`API_VERSION`: main rewrote this comment to state the rule — a bump promises nothing
in either direction, and `updaterd` refuses on an exact `!=` deliberately rather
than pending (#77). That rule stands as written; the bump to 7 becomes an instance of
it, so `from_dir`'s reason is recorded under it rather than as a competing paragraph.
`xtask`: two changes to the same assertion, both wanted. Main skips a unit that execs
out of the *base* — the boot recovery net does, so that a broken release cannot break
its own rescue. This branch reads staged names by basename rather than matching a
literal `release/<exec> staged/`, because `dev-push.sh` builds in one of two
directories depending on the toolchain and names the source through a variable. Kept
the skip, then the basename parse.
`artifact.rs`: main's test name over this branch's `PACKAGING_SITES`, and the one
remaining `PACKAGING_WORKFLOWS` — in the recovery-net test main added — retargeted at
the renamed constant. It did not compile otherwise.
The substantive one: **`dev-push.sh` never got the four recovery-net `--include`
lines** that #74 added to both workflows, so a laptop build shipped a release with no
`robot-rescue`, no `robot-boot-check` and neither of its units. Silent until a board
needed the recovery it did not have. That is exactly what renaming the constant to
`PACKAGING_SITES` is for, and with the last usage retargeted the test says so; the
three lists are now identical.
Workspace suite, clippy, fmt and both shell lint steps green.
Assisted-by: Claude:claude-opus-5
`scripts/dev-push.sh --docker` builds inside `rust:1-bookworm` with libudev
installed, instead of cross-compiling with zigbuild. On an arm64 host the target
is the host, so there is nothing to cross: no `zig`, no `cargo-zigbuild`, and no
`libudev.so.1` copied off a board — which also makes it the path that works
before you have a board at all. Measured here: 1m30s cold for the whole
workspace, native on Apple Silicon.
Bookworm rather than Trixie for the reason `board-test.sh` gives: build against
an older glibc than any userland we might ship. Its 2.36 is below Trixie's 2.41,
and the binaries that come out need at most GLIBC_2.34, so they load on the board
we ship and on an older image. That is what the `.2.31` pin buys on the zig path.
Its own target directory. The two modes produce the same triple through different
toolchains and linkers, and cargo's fingerprints do not capture all of that, so
sharing one directory risks it deciding a binary from the other environment is up
to date. The cost is disk and one full rebuild when switching, which is why zig
stays the default: it is faster day to day and is what CI uses.
The staging block now names its source through `$BIN` instead of a literal path,
since the directory is the one thing that differs between modes. That cost
`every_binary_a_packaged_unit_execs_is_staged` its `"release/<exec> staged/"`
match; it now compares basenames the way `xtask/tests/artifact.rs` already did,
which is also what keeps it pointed at the site that changes most often. Both
tests were re-checked by deleting a `cp` line and watching them fail.
Also drops `DUCK_BUILD_TIME` from local pushes. Both it and `DUCK_REVISION` are
read with `option_env!` in `duck-ipc-proto`, which every daemon depends on, so a
value that changes on every run invalidates all of them: five crates rebuilt per
push (~30s) versus nothing at all for an unchanged tree, measured both ways.
`robotctl version` reports the revision and not the build time, and the version
string already carries the push's epoch.
Assisted-by: Claude:claude-opus-5[1m]
`scripts/dev-push.sh <user@board>` cross-compiles here, packages the same
artifact a release does, signs it with the dev key, copies it to the board and
applies it — about a minute, against a push plus a CI run.
The board takes it through `robotctl update apply --from <dir>`, a per-call
source override on `update.apply`. A config edit to `local_dir` would have
needed no code, and would have cost the board every other way in: `--ref`,
`--staging` and a plain `apply` back onto the release stream all stop working
until the edit is undone. As an option it is one flag, and everything else about
the apply is unchanged — preflight, signature, hash, compatibility, the health
gate, auto-rollback. That last part is the whole reason this is not
`updaterd install --from`, which forces the gate off and therefore refuses to
touch a live release: a dev board running a build made ten seconds ago is where
auto-rollback earns its keep.
Local relaxes nothing. The directory is read by the same `LocalDir` source the
tests and the offline installer use, so a build installs because the dev key is
in that board's trusted set — a customer robot refuses it exactly as it refuses
`--ref`. The downgrade guard stands aside for `--from` for the reason it stands
aside for `--version`: a directory named by an operator with root is not a
mirror that has gone backwards, and a local build is a prerelease that sorts
below whatever the board is running, so guarding it would refuse every push.
`API_VERSION` 4 → 5. Additive, and that is the reason to bump rather than not:
serde ignores what it does not know, so a v4 `updaterd` would have accepted
`--from` and installed from its configured source while reporting success.
Refusing the call is what the constant is for. Consequence: the first push to a
board is `scripts/dev-push.sh --bootstrap`, once, which stops robotd and gives
up the gate for that one install because the binary that would run the gate is
the one being replaced.
`padd` is the one thing that does not cross-compile on macOS: `gilrs` needs
libudev, and `scripts/ci-cross-deps.sh` gets it from apt, which a Mac has no
equivalent of. The script copies `libudev.so.1` off the board itself — the exact
library the binary will load there — and writes it a `.pc` file. Dropping padd
from the artifact instead would have made the local push differ from a release,
and left the gamepad broken after every push.
dev-push.sh is a third packaging site, so it is covered by the tests that exist
because two hand-maintained copies of these lists had already drifted: its `cp`
and `--include` lines are textually what the workflows use, and
`xtask/tests/artifact.rs` now opens the tarball all three produce.
Assisted-by: Claude:claude-opus-5[1m]