# Cheat sheet `robotctl`, which runs on the robot. Every command here was taken from `--help` on the branch that ships it, not from memory. Read-only commands need no privilege. Anything that **changes** the robot needs `sudo` (or a user in `--allow-user`/`--allow-group` for `configd`, `allow_uids`/`allow_gids` in `updater.toml` for `updaterd`). Branch builds, release candidates and the restart traps after an update are in [`cheatsheet-dev.md`](cheatsheet-dev.md) — they need a dev board. The same robot over Bluetooth from a laptop, with no network and no ssh, is [`duckctl.md`](duckctl.md). ## On the robot — `robotctl` ### The first thing to run ``` robotctl version ``` What every daemon is *running* against what is *installed*, plus warnings when they disagree. Run this before believing any other diagnosis — a daemon serving old code after an update looks exactly like a bug in the fix you just shipped. See "After an update" below. ``` robotctl health ``` Hardware and software in one report. Exits non-zero when the robot is unhealthy or unreachable, so it can gate a script — a hot motor or a pinned component is reported, not judged, and does not affect the exit code. `--json` for a support bundle; `--check` checks the update source first, so the line about it says whether it answers now. ### Watching the loop ``` robotctl monitor ``` What a client asked for beside what was actually applied, with the reason named when they differ — safety clamps things constantly, and "the stick is forward and the robot is still" is unreadable without that. A limit is spelled out rather than named: `deadman — no intent arrived recently, velocity zeroed`. Also on the frame: every joint measured against what it was commanded, the IMU's projected gravity and the fall verdict drawn from it, and the achieved loop rate as a trace so a stutter that has already recovered is still visible. Projected gravity is the only IMU quantity on this stream — upright is about `[0, 0, -1]`, and it is what `fallen` is decided from. The stale-read counters and the ratios they mean anything against live in `robotctl health`. The last row of the header is the robot's condition rather than its behaviour: the pack's charge in volts and as a fraction, the hottest servo and the board's own temperature. It comes from `robot.health`, polled every two seconds, because none of it is on the state stream — and it is where anything wrong gets named, whether that is `unhealthy: control loop at 43.9 Hz`, `degraded: no robot on the motor bus after 3 attempts` or `orientation frozen — 25 stale reads`. That last one is on this row and nowhere else on the frame: a board that has stopped fusing keeps answering the bus, so nothing errors and the gravity vector above holds a plausible attitude indefinitely. 0% is `BATTERY_EMPTY_V`, which is where `robotd` sits the robot down and cuts power, so the figure is a countdown rather than a gauge — yellow at 30%, red at 15%. A reading that has not been taken says `batt not read yet` instead of `0.00 V`, which is what the first second of an uptime and a bus that cannot answer both look like. The row is drawn even when there is no state at all, and that is the case it matters most in: a board whose servo power is off never completes a control tick, so nothing arrives on the stream and the reason is only on the health answer. The bottom border names the policy that is loaded — the `.onnx` files, and whether a standing network is configured at all — because `walk` is a mode two releases with different gaits both report. A robot with no policy says so, and one whose policy would not load says that instead, which the stream's `held` cannot distinguish. Down the right-hand side, **the robot drawn as it is standing** — the same visual model the policies were trained against, posed by the measured joint angles and tilted by the IMU's gravity vector. A leg folded the wrong way, a head pitched into the floor and a duck lying on its side are all just numbers in the joints table; every one of them is obvious here. It is on by default and appears whenever the terminal is wide enough (about 110 columns — the tables come first, and the robot takes what is spare). **`d`** turns it off; **`[`** and **`]`**, or `←`/`→`, orbit it. Whenever the ToF is delivering frames, what it sees is drawn into the same scene — yellow for a hit, green for floor — depth-tested against the robot's own body, so a point behind the beak is hidden by it. That is what makes "is it seeing my hand, or is it seeing itself" answerable. It needs no key: the points appear when frames arrive and go when they stop. Under it, when the column is tall enough, **a map of where the robot has been**: odometry's track from the foot contacts and the IMU, in braille. The panel never grows — the world zooms out as the track does, so the whole path stays in frame. `+` is where it started, `●` is the robot with a short ray for its heading, screen-up is the heading it booted with. There is no magnetometer, so this is relative motion and it drifts; it answers "did it walk in a circle" and not "where is it". `q` quits; `↑`/`↓` scroll the joint list on a window too short for all of it; `u` switches the angles between degrees and radians; `t` opens the [ToF matrix](#the-tof-sensor-tofd); `c` opens [the camera](#the-camera-mediad); `d` toggles the robot view and `[` / `]` orbit it; `p` opens the pad's raw input stream — every evdev report from the gamepad, with the gaps between them, which is the only place a stalled radio is visible ([pair a gamepad](pair-a-gamepad.md#when-it-drops-while-you-are-driving)). A pad with an inertial unit — the Pro Controller clones have one, the Xbox does not — grows that block by a panel: a wireframe pad that tilts and turns with the one in your hands, its pitch, roll and drifting yaw, the raw acceleration and rates, and whether the gyro's rest bias has been learned yet (hold it still half a second). The yellow bar is the pad's front edge. Angles are degrees on screen — joints, head and the yaw rate. Redirected or piped it prints one line per tick instead, so `> run.log` and `| grep FALLEN` behave, and those numbers stay radians whatever the screen is set to. The joint vectors are in `--json`, which carries the whole state, one object per line: ``` robotctl monitor --json --hz 50 > run.jsonl ``` On a robot whose servos run ROBOTIS's impact guard firmware (V3 or V4), each line also carries `impact_guard`: per joint, 0 armed, 1 braking after an impact, 2 holding softly until the goal comes back past the position, `null` for a servo on another firmware. Reading it costs the bus a millisecond per tick, after the goal positions go out and only while something is subscribed, and `loop.hz` and `loop.missed` on the same line say whether the loop kept its rate. `robotd` names any servo on neither in the journal once a start, and sets every servo's Current Limit to 1000 mA, at the next start with torque off if the robot was standing. V4 hides the guard behind Impact Guard Enable (register 67), which every power-up turns off: `robotd` sets it to `bus.impact_guard` with every torque on, so with the guard on a V4 servo is guarded from the first Start. `bus.impact_guard` in `sudo robotctl configure` switches every guard servo between the guard (on) and settings that never fire (off, the default): the factory firmware with only Current Limit, to compare the two on the same robot. It is off until it is understood why the stress test robot on it, cream-dvt-antoine, fell on its own far more often than any other (2026-11-09): about half its falls, against 8-14 % elsewhere. On writes the six `bus.impact_guard_*` rows beside it, which default to setting R below: V Min (rad/s), Brake Time (ms), Deceleration (rad/s²), i Hold (mA), V Fast (rad/s) and PWM Fast (%). Changing them is how to look for another guard; a start on anything but the defaults names them in the journal. They are written when `robotd` starts with torque off, so relax and restart it: the servos run them from the next Start, no reboot needed. On V4 the on/off switch needs none of this: it follows `bus.impact_guard` at the first Start after a restart, relaxed or not, and off leaves the six settings as they are. `impact_guard` staying at 0 in the recording is what off looks like. The levels a robot test steps through, gentlest first (V Min rad/s, Brake Time ms, Deceleration rad/s², i Hold mA, V Fast rad/s, PWM Fast %): | level | v_min | brake_ms | decel | i_hold_ma | v_fast | pwm_fast | what it is | | --- | --- | --- | --- | --- | --- | --- | --- | | 0 off | | | | | | | `impact_guard = false`: Current Limit only | | 1 taper only | 1 | 50 | 32767 | 32767 | 9 | 80 | no brake, no hold, a gentle speed taper | | 2 light | 3 | 20 | 1500 | 1000 | 9 | 80 | hard impacts only, a short brake, a near-normal hold | | 3 medium | 2 | 30 | 1000 | 800 | 9 | 70 | | | 4 strong | 1 | 40 | 600 | 650 | 9 | 60 | close to the factory | | 5 factory | 1 | 50 | 400 | 500 | 9 | 50 | ROBOTIS's factory values, the gear bench's | | 5a factory, no taper | 1 | 50 | 400 | 500 | 9 | 100 | isolates the taper | | 5b factory, no hold | 1 | 50 | 400 | 32767 | 9 | 50 | the brake and the taper, no soft hold | | 6 factory taper only | 1 | 50 | 32767 | 32767 | 9 | 50 | never brakes | | 7 late short brake | 6 | 20 | 400 | 32767 | 9 | 50 | brakes on arrivals above 6 rad/s only | | 8 late brake | 6 | 50 | 400 | 32767 | 9 | 50 | 7 with the factory brake length | | 9 earlier short brake | 4 | 20 | 400 | 32767 | 9 | 50 | 7 from 4 rad/s | | R default | 6 | 20 | 400 | 32767 | 7 | 40 | 7 with a stronger taper: arrivals capped near 7 rad/s | With the same ONNX, 0 walks and 5, 5a and 5b keep falling. The taper is not the cause: in a guard-off walk the gait never needed more PWM than the factory taper leaves (one sample in 3,455). The brake is: at 5 it fired about 6 times a second across the legs while walking, on nearly every step of each knee, mostly from under 3 rad/s, and 50 ms of shorted bridge is close to limp for a knee in stance. The hold made it worse, since it lasts until the goal comes back past the position, which in stance it does not. On lavandiere (2026-11-05, same ONNX, a minute of walking and about ten pushes per setting), 6 and 7 walked and recovered like 0: no fall in 20 pushes. Every hold (800, 650 or 500 mA, on 7 or 8) and the 50 ms brake weakened push recovery: 6 falls in 31 pushes. A recovery step trips the brake, and the hold then softens the stance leg; a hold reads about half its setting in Present Current. So the hold stays off until the firmware can end it on its own (after 100-150 ms, or once the servo is still). The taper costs nothing up to 40 % from 7 rad/s, which keeps arrivals near 7 rad/s (8.5 guard off). 30 % from 7 felt slightly less steady, so R is one notch inside that edge. R held over 13 minutes of walking and 32 pushes, its battery going from 7.7 to 7.5 V. R is what `impact_guard = true` writes; a robot that should run ROBOTIS's factory values instead takes, in `/var/lib/robot/robotd.toml`: ```toml [bus] impact_guard = true impact_guard_v_min = 1 impact_guard_brake_ms = 50 impact_guard_i_hold_ma = 500 impact_guard_v_fast = 9 impact_guard_pwm_fast = 50 ``` Record every run: `impact_guard` says which joints braked or held. ### Configuring the robot ``` sudo robotctl configure ``` What has been changed on this robot, and nothing else: ``` robotctl configure --list ``` A robot nobody has touched prints nothing — that is the answer. Add `--json` for a support bundle. It needs no root and no terminal, which is the point: it is the first question to ask about a robot behaving oddly, and until now answering it meant a full-screen editor over ssh. An interactive editor over this robot's own settings, `/var/lib/robot/robotd.toml`, layered over the image's `/etc/robot/robotd.toml` ([architecture.md](../design/architecture.md), "Where the state lives"): every key the daemons know, the feature switches first (policy on/off, walk/roller, limp-fall, audio, pet detection, battery shutdown, camera and video quality…), current value against default, one line of doc. SPACE toggles, ENTER types a value, `u` reverts a key to its default, `ctrl+f` opens a fuzzy search over everything on screen (the selection follows as you type; ENTER or ESC keeps it there). Values in yellow (marked `•`) are the keys where this robot diverges from the defaults; everything else is the default, and `unset` optionals show what they resolve to `(auto)`. A key's default is the image's value where the image sets one and the built-in default otherwise, so reverting a key goes back to what the image says — and keeps following it through the next OS update. Three properties worth trusting: - **It cannot disagree with the daemon.** The schema, the defaults and the validation come from the same crate `robotd` parses the file with, and the key list is pinned complete by a test — a new `[section]` in the daemon shows up here or the build fails. - **It cannot eat your file.** Comments, ordering and keys from other releases survive untouched; only the keys you change are written. Reverting a key removes it (and the comment attached to it) rather than pinning the default, so the file stays a list of *decisions*, not a copy of the defaults. - **It cannot write a file robotd refuses to start on.** Every save is validated through the daemon's own loader first, atomically (temp file + rename), and rejected with the reason. Saving offers what the change actually needs, from the daemon that actually reads it: a restart for most keys (`[media]` and `[duck_detector]` are `mediad`'s, `[head_imu]` is `tofd`'s on a zero3 and `robotd`'s on a beta), a `robotd` *reload* for `[policy]` — the motors stay powered — and nothing at all for `[pad]`, `[pad_imu_head_control]` and the other `pad_` sections, which the pad daemon picks up within a second. `[autonomous] enabled` is read at the next boot. `sudo`, because the file is root-owned — without it the editor opens read-only and says so on the first write. `--file` points it elsewhere for a bench copy. The shipped `deploy/robotd.toml` stays the reference for *why* each knob exists; this is for flipping them. #### Video quality ``` sudo robotctl configure ``` Set `media.quality` — `1080p30`, `720p30`, `720p15` or `360p30` — and take the restart it offers. `media.source` set to `test` streams a test pattern instead, which is what a board with no camera wants: the WebRTC *control* channel rides on the video track, so a pipeline that cannot start costs both. The pattern ignores `media.quality` and runs at 256x144@5 — it is there to make the session exist, and drawing a 720p one costs five times the CPU a real camera does. `media.bitrate` follows the quality unless you set it; the unit is bits per second. `media.congestion_control` is the other knob in that section, and it is the one that moves CPU: `disabled` drops the bandwidth estimator, which is the largest single consumer in `mediad` (7.6% of a core against capture's 0.3%), and makes `media.bitrate` the rate rather than a starting point. It costs adaptivity — on a link that degrades, the picture stalls instead of the rate falling. 720p30 is the rung the pipeline was measured at; a rung that does not hold runs slower rather than failing. `robotctl monitor` reports the achieved rate on the bottom border, in yellow with `of ` beside it when it is under 90% of what was asked for. What was applied: ``` journalctl -u mediad -b | grep streaming ``` ### Policies and skills A **slot** is what the robot runs by default — the walking gait, the standing network. A **skill** is what it runs when asked: a kick, the roulade, a bow. Both are files on the Hub, both change without a daemon release, and nothing below needs a restart. What this robot is running right now: ``` robotctl policy list ``` Two tables: the seven slots, then the skills — what runs by default, and what runs when asked. ```text SKILL RUNS FOR POLICY kick_left 0.5 s ball_kick_left.onnx roulade 1 s roulade.onnx * polite-bow 4 s fffiloni/microduck-polite-bow-b1d864/main/policy.onnx ground_pick — driven by the robot itself sit_toggle — driven by the robot itself ``` A `*` marks every row config has an opinion about, with a count at the bottom. A slot you switched off says `switched off` rather than looking like one the robot never had. The directory comes off the path because the `ORIGIN` column already says which one it was. `ground_pick` and `sit_toggle` have no length because the robot drives them itself — they answer to `robot do` like the rest, but they are not entries you can change. #### A newer official set The set the robot walks with lives on the Hub and versions on its own line: ``` robotctl policy check ``` ``` sudo robotctl policy update ``` `check` prints what is installed, what is newest, and what else the repo offers; it changes nothing and says so plainly when the Hub cannot be reached. `update` takes the newest unless you name one — `--version v1` is how to go back. The robot returns to its home pose, re-reads every slot and drives again, and **a slot you loaded yourself is left alone**, because it points somewhere else entirely. #### A newer duck detector The model `mediad` finds other ducks with lives on the Hub the same way (`pollen-robotics/microduck-duck-detector`) and versions on its own line: ``` robotctl duck-detector check ``` ``` sudo robotctl duck-detector update ``` Same shape as the policy pair — `--version ` names one, and `check` changes nothing. `update` restarts `mediad`, which drops the console's video for a moment; whether the detector then runs at all is `[duck_detector] enabled` in `robotctl configure`. #### Trying your own file No release, no file to edit, no restart: ``` sudo robotctl policy load walk /home/microduck/my_walking.onnx ``` If the robot is walking, it goes to its home pose, loads it, and drives again. If it is doing something else — sitting, standing still — nothing moves: the network being replaced is not the one running, and the swap happens underneath. `sudo robotctl policy reset walk` puts that slot back; with no slot, it puts all seven back. #### Trying somebody else's Other people publish policies for this robot: ``` robotctl policy search microduck ``` A robot only fetches policies from `pollen-robotics` until you allow others. Run this, set `policy.allow_community` to `true`, and save: ``` sudo robotctl configure ``` Then: ``` sudo robotctl policy load walk RemiFabre/microduck-flamingo-cycle ``` The repo name is enough — it is fetched and loaded in one step. Add `@v2` for a revision and `:policy.onnx` for a repo carrying more than one. `policy list` marks it `community`. **Nothing a stranger publishes is verified by anybody.** What makes it safe to try is the joint clamps, the fall reflex and the shape gate — not the description. Have the robot on its stand the first time. A policy whose manifest says it will not run here — wrong observation width, a newer daemon, a different robot — is refused before it downloads. One with no manifest is accepted and checked the usual way, at load. #### Adding a skill A policy in the walk slot replaces the gait. A policy added as a *skill* sits alongside it and runs when asked, which is what most published one-shots want: ``` sudo robotctl policy add polite-bow fffiloni/microduck-polite-bow-b1d864 ``` ``` robotctl robot do polite-bow ``` The length comes from the repo's manifest. A policy that holds until told otherwise — a one-footed stand, say — has no length of its own, so give it one, and the twist it reads: ``` sudo robotctl policy add flamingo RemiFabre/microduck-flamingo-cycle --hold 5 --command 1,1,0 ``` `--command` is what the network is fed while it runs. Most skills need none: they are trained on an all-zero command and being selected *is* the trigger. A policy that reads its twist as something else — flamingo's is `[flag, side, 0]` — needs it spelled out, and its README says what the slots mean. `sudo robotctl policy remove ` takes one out. A skill this robot's release ships comes back when you do, since removing the entry only removes the override. The robot must be driving for a skill to run — press **Start** on the pad first, or the request is refused saying so. #### Putting a skill on a button ``` robotctl pad bindings ``` ```text a sit_toggle b ground_pick x (nothing) y excited lb yes rb no `robotctl pad bind