Commands and reference

Last updated 2026-09-03

Lookup material — not meant to be read front to back.

Three tools, and which one you want

This is what newcomers mix up most. Microduck has three command-line tools; they run in different places and solve different problems.

Tool	Runs on	Reach for it when
`robotctl`	the robot	Everything day to day: diagnosis, configuration, driving, updates. It ships in the release.
`duckctl`	your laptop	The robot has no network, or you would rather not ssh. Goes over Bluetooth LE.
`scripts/dev-push.sh`	your laptop	You changed the robot’s code and want it installed without waiting for CI.

Three rules decide it:

You can ssh in → robotctl.
The robot has never joined a wifi network → only duckctl works. wifi connect goes over the radio and needs no network of its own; this is the only way out of that chicken-and-egg.
Never install duckctl on the robot. Nothing in a release depends on it.

One rule about privilege

Read-only commands need none.
Anything that changes the robot needs sudo, or membership of configd’s --allow-user / --allow-group, or updater.toml’s allow_uids / allow_gids.

The fixed three steps

Whatever the symptom, these are worth running first:

robotctl version    # is the running code the code you think it is
robotctl health     # is anything unhealthy, and why
robotctl monitor    # requested vs applied, and why it was clamped

version is first because a daemon still serving old code after an update looks exactly like the fix you just shipped not working.

On a dev board there is one more: robotctl health’s units block lists which release each daemon was launched from, and warns by name when that disagrees with what is installed.

Deeper material (Chinese)

robotctl reference — every command, grouped
duckctl — reaching a robot with no network
System architecture — what each of the seven daemons owns
Glossary — the English terms with their meaning in this project

In this section

Official Microduck resources
Pollen Robotics' repositories, documentation, product pages and media assets, grouped by the problem each one solves.
robotctl version
Reports what each daemon is running against what is installed, and warns when they disagree.
What sim2real is, and why it is the hard step
Moving a policy from simulation onto hardware. A policy that walks well in simulation and falls over on the robot is the normal outcome.
Glossary
The English terms that carry a specific meaning in this project, with what each one means here.
robotctl health
Hardware and software in one report, exiting non-zero when the robot is unhealthy.
robotctl reference
Every robotctl command, grouped by what it is for, with the privilege rules.
The BAM actuator model
Rhoban's servo physics model. Treating a servo as an ideal torque source is the most common root cause of sim2real failure.
Domain randomisation
Randomising physics during training so the policy holds across the real distribution. Not the same as adding observation noise.
Microduck system architecture
What each of the seven daemons owns, why the split falls where it does, and how they talk.
robotctl monitor
Live comparison of what was requested against what was applied, with the reason when they differ.
Backlash, and which side the encoder sits on
Gear play. Microduck models ±1° per servo, and the point is that the encoder reads through it.
duckctl: reach the robot with no network and no ssh
Find a robot over Bluetooth, join it to wifi, open its console, install updates — even if it has never seen a network.
sudo robotctl configure
An interactive editor for robotd.toml, validated by the daemon itself before saving.
Build here, install on the board
Skip CI: cross-compile from a clone, sign it, and install over ssh in about a minute.
sudo robotctl robot init
Powers the joints and ramps to the home pose over about two seconds.
The 61-dimensional observation contract
Every policy shares one observation format, which is what lets the runtime hot-swap between walking, recovery and tricks.
deadman: why there is no stop button
A timeout that zeroes velocity when no fresh intent arrives. It is what stops the robot when the pad process dies.
Dev board cheat sheet
The commands that only make sense on a dev board, and the restart traps that make a fix look installed and inert.
sudo robotctl robot relax
Cuts joint power. The robot collapses if nothing is holding it.
golden: the boot recovery net
The fallback release, always kept stable. A branch build never becomes golden.
robotctl pad status
Reports the pad connection and the padd driver on separate lines, because they fail separately.
sudo robotctl pad pair
Finds a pad in pairing mode and bonds it. Once per pad.
The health gate and automatic rollback
Every update is health-checked afterwards and reverted if it fails. This is why pushing your own build cannot brick the board.
Control plane and data plane
Every daemon shares one JSON-RPC contract, but sensor streams do not travel over it.
sudo robotctl pad forget
Removes the robot's half of a pad bond — the only half a robot can remove.
Projected gravity: how the robot knows it fell
The only IMU quantity on the state stream. Upright is about [0, 0, -1], and the fall verdict is drawn from it.
robotctl quack
Makes the robot quack. The most reliable way to tell two ducks apart.
Policy hot-swapping
Switching between walking, recovery and trick policies at runtime, with no restart and no stop.
robotctl chorale
Several ducks singing four parts together. Off by default, and invisible when off.
robotctl net status
Reports the current SSID, signal strength and addresses.
The voice bank: every duck sounds different
The sound bank is generated from the SoC serial, so a robot's voice identifies which one you are connected to.
robotctl net scan
Has the robot sweep the radio for networks in range.
sudo robotctl net connect
Joins the robot to a wireless network.
sudo robotctl net forget
Removes a saved wireless network.
robotctl system info
Reports the robot's name, serial and uptime.
robotctl system pin
Shows this robot's pairing PIN.
sudo robotctl system set-name
Renames the robot, and when you have to.
sudo robotctl system set-pin
Sets the six-digit pairing PIN.
sudo robotctl system reboot
Reboots the robot — and why most "just reboot it" cases have a sharper answer.
robotctl update status
Reports the installed version, available updates, and the state of the update system.
robotctl update check
Asks whether a newer release exists, without installing anything.
sudo robotctl update apply
Installs an update. Every one is signature-verified, health-gated and reversible.
sudo robotctl update rollback
Deliberately goes back to the previous version.
robotctl update log
Lists the update history — including rollbacks the robot did by itself.
robotctl update show
Shows what happened during one specific update.
robotctl update watch
Follows an update in progress, phase by phase.
sudo robotctl update select
Switches to an already-downloaded version without downloading again.
sudo robotctl update pin
Pins the robot to a version, or unpins it.
sudo robotctl update reset-to-golden
Returns to golden, the fallback release the boot recovery net holds.