Official MicroDuck upgrade and recovery
- Before updating, record the installed version and health output; retain the working image and configuration.
- Choose the symptom below and read the checks for that exact release. Connection, service, sensor feedback and policy compatibility are separate conditions.
- After the change, read back the version and settings, then check health and policy selection. Use the recovery procedure for the same image and hardware if a check fails.
MicroDuck 0.20.1: check access before recovery
Official robot only: daemon-v0.20.1, released 2026-11-12, revision 7fba12ed, API 55. We checked the release, fixed source and published archive; no robot was booted or updated for this guide. HD1910 replicas and Open Duck Mini use different software.
Confirm the installed version
From an already authorized laptop connection, run the read-only version and update-status commands below. Record release, revision, API and the update outcome. Reconnect after an update restarts BLE before diagnosing a dropped session.
Keep Setup Code on your own device
Use the robot’s own QR or code with a compatible app. For laptop duckctl, setup-code add reads the code from standard input and stores it locally. A provisioned robot refuses the legacy PIN. A stale key can cause a silent failed handshake; check robot identity and client version before resetting pairings.
Wi-Fi SSH refusal has a separate cause
0.20.0 could open Wi-Fi SSH over BLE using the Setup Code; SSH then accepted a shared operator password. 0.20.1 withdraws that method and duckctl ssh-wifi. Wi-Fi SSH requires a deliberate local USB-C action with the robot open, or a development image. Check the upstream access instructions rather than retrying the removed command. A v54 client requesting system.openWifiSsh is explicitly refused by API 55.
duckctl --name <robot-name> version
duckctl --name <robot-name> update statusIn this stable tag, the policy installer has a v9 minimum, not a v9 ceiling: newer official sets and custom sets are preserved under its source rules. HF v10 and API 56 on later main are separate evidence, not features established by the 0.20.1 tag.
For help, record the access path (BLE / USB-C / Wi-Fi SSH), daemon and client versions, and the first redacted error. Keep Setup Code, QR keys, PIN and network credentials private. The earlier 0.19.0 pairing and camera checks remain below.
MicroDuck 0.19.0 pairing and camera checks
This covers the official daemon 0.19.0 tag released on 2026-11-10. It applies to the official robot. Source and release files were checked. The maintainer’s iOS QR, secure BLE and camera check used a face-board-v1 beta unit.
Setup Code: scan the robot’s QR
Scan the QR for this robot in an app that supports Setup Code. The daemon takes the credential from ID EEPROM or the installed development key. Changing the display name leaves the original duck-xxxx identity used by the code in place.
No credential: label PIN
If the robot has no valid credential, btd uses its PIN path and duck-gateway has no key to serve. If a label is present but the code fails, confirm that it belongs to this robot and check the app version before changing settings.
Paired: check Wi-Fi and video
If secure BLE connects and video is missing, check the phone’s local-network access and the robot’s Wi-Fi first. On iOS, retry video in the app after allowing local-network access. On a provisioned robot the app authenticates to duck-gateway, which forwards to mediad on loopback.
The daemon pins official policies to v9. For VelStand, v9 ships the v7 checkpoint. The newer yaw-remap experiment in microduck_rl has a separate scope.
Before changing pairings or recovery settings, record the installed daemon, phone app version and first error. Use the read-only status command if you already have authorized access. Share the failing stage and a redacted error without the QR, PIN, setup key or Wi-Fi credentials.
robotctl update status- daemon 0.15.2 · Is pickup pause the same as powering off?
- daemon 0.16.1 · Can I keep an older gamepad mapping without checking?
- daemon 0.15.0 · Which records should I keep before upgrading?
- daemon 0.17.1 · Does switching to UDP prove the controller path works?
- daemon 0.17.2 · Are the 300 ms and 1000 ms limits the same event?
- daemon 0.17.4 · Does a missing old robot name mean the robot is offline?
- daemon 0.17.6 · Should I reflash immediately after a response-too-large error?
- daemon 0.17.8 · Does sound on the laptop confirm a robot response?
- daemon 0.17.9 · Does an online service prove camera data is current?
- daemon 0.18.1 · Are service availability, IMU recognition and policy readiness equivalent?
- daemon 0.18.3 · Does changing telemetry consent fix reconnection?
Connect a MicroDuck: Find It, Join Wi-Fi, Open the Console
On an official MicroDuck, use duckctl from a laptop to distinguish Bluetooth discovery, missing Wi-Fi address and console signalling before changing settings.
MicroDuck 0.18.3: Telemetry Controls & Reconnection Checks
Check MicroDuck 0.18.3’s default-on usage telemetry, opt-out readback and SSH address cache, plus 0.18.2 gamepad recovery, before updating a compatible robot.
MicroDuck Policies: Update v8, Inspect Overrides & Reset
Check the official v8 velstand policy, update the separate policy set, identify persistent walk overrides, and reset one slot safely.
Start at the first failing stage.
Use the table matching your environment. A browser loading problem, a missing Python dependency and an ONNX shape mismatch happen at different stages. Keep the original error before changing versions; otherwise you may lose the clue that identifies the failing layer.
Browser simulator problems.
| Symptom | Try this | What to record |
|---|---|---|
| Stuck on loading | Open the direct simulator. Try the official boot diagnostic view ↗. Wait for its asset or policy step to finish. | Browser version, the last loading step and any SYSTEM HALTED error. A transient network failure is not evidence that your GPU cannot train. |
| The robot ignores the arrows | Enter or resume the scene, click it to give it focus, then hold an arrow. Try the direct page if the wrapper is capturing keys. | Whether the welcome overlay closed, whether the page scrolled, and whether the speed readout changed. |
| R sits instead of rolling | Use the current browser key map. R now controls sit/stand in feet mode. | The tutorial URL and simulator revision. Do not substitute shortcuts from the local Python viewer. |
| Kicks fail after switching mode | Return to Feet mode. Kicks and ground pick are legs-only actions; the first Rollers switch also has extra loading. | Selected mode and whether its assets finished loading. |
These checks combine our desktop entry/walking/reset check with the Simulator README: modes, loading and controls ↗ and Browser keyboard implementation ↗. No browser benchmark or mobile compatibility claim is implied.
Installation and CUDA problems.
| Symptom | Next check |
|---|---|
| Python version rejected | Run uv run python --version from the checkout. This revision requires 3.12; use the pinned setup steps. |
| GPU exists, but CUDA is False or GPU count is 0 | Run the Python/CUDA probe from the same environment as training. Record PyTorch’s version and CUDA build, OS and architecture. On Linux ARM, inspect the project’s selected wheel source before changing drivers. |
| ARM dependency download times out | The official quick start suggests a longer uv HTTP timeout for the first large CUDA-wheel download. Try the one-command setting below. It only addresses download timeouts. |
| Jetson Thor: missing NVPL or cuDSS library | Read issue #38 with your exact JetPack, driver and architecture. It documents a Thor-specific package problem; a GB10 package recipe is not automatically a Jetson recipe. The report was still open at review. |
| An unrelated train command runs, or train is missing | Use uv run train inside the synced checkout. The project intentionally owns this entry point; its dependency file documents a previous executable collision. Re-sync the matching revision before altering your system PATH. |
| CUDA out of memory | Record the allocation error, GPU memory and environment count. Close only your own unused GPU jobs, then retry the same task with fewer environments. This is a diagnostic reduction, not a guaranteed cure for every allocation failure. |
UV_HTTP_TIMEOUT=600 uv sync --locked --python 3.12Run that one-line assignment in a POSIX shell such as bash or zsh. The underlying constraints and executable collision are documented in Python, dependency pins and ARM package sources ↗; GPU discovery is described by PyTorch: checking CUDA availability ↗. Jetson Thor report #38 (community report, open at review) ↗ is a user report, not a fix tested by this site.
Export and replay problems.
| Symptom | Next check |
|---|---|
| ONNX expects 61 inputs but receives an older layout | For the reviewed current policy contract, use --new-cmd-obs in the local viewer. Leave it off for legacy 51-input policies. Confirm the actual input shape before choosing. |
| A .pt file will not load as ONNX | Use the official checkpoint exporter. The file types serve different purposes; renaming a checkpoint does not convert it. |
| play looks plausible, but exported replay behaves badly | Check that the official exporter included observation normalization. Then compare task, checkpoint, robot model, action scale and command layout. This is an investigation order, not a diagnosis of your specific policy. |
| A remote job continues after Ctrl-C | Open the saved job URL, inspect its status and explicitly cancel if appropriate. Interrupting the log stream does not stop the job. |
Inspect Local playback flags and keyboard controls ↗ and Official ONNX exporter and observation normalization ↗ for the layout and normalization behavior. The cloud log behavior is documented in MicroDuck cloud job submission guide ↗; cancellation is covered in Hugging Face: managing and cancelling jobs ↗.
On an official robot, separate a Bluetooth pad problem from a control-source change.
Save the read-only baseline below before attempting a new bond, a service restart or a controller setting. configure --list lists overrides, so no netpad.enabled line usually means the default false, not a failed query. The two output lines from systemctl are ordered padd, then netpadd. This is a source-selection check, not another UDP setup tutorial; the 0.17.2 release guide explains the new UDP timing. official commands ↗ source selection ↗.
robotctl version
robotctl configure --list
systemctl is-active padd netpadd
robotctl pad status
robotctl pad bindings
robotctl logs padd -n 100
robotctl logs bluetooth -n 100| What you see | What it can mean | Next step |
|---|---|---|
padd inactive; netpadd active | UDP is the selected source, so a Bluetooth pad cannot drive during that configuration. | Read the configured override and current source-switch guide; do not re-pair a Bluetooth pad to fix a deliberate UDP choice. |
padd active; no pad connected | The driver is running, but there is no current Bluetooth input. A pad shown as paired but NOT trusted may work now yet fail to reconnect after a reboot. | Record pad status and padd/bluetooth logs. If trust is the identified fault, follow the original controller-specific pairing steps; do not erase every bond first. |
Pad connected; padd inactive | The radio bond and the driver can fail separately. A connected icon alone does not prove that the robot receives control. | Compare both service states and the padd journal. If neither source starts, report its first service error before changing settings. |
| Pad connected and driver active; one button does nothing | A binding or mode may explain it. Since 0.16.2, X/Y/LB/RB have no default action; 0.17.2 can also override stick axes, gains and limits. | Read pad bindings, configure --list and the current mode. An empty override list does not print all effective defaults. |
| Pad connected and driver active; input appears to freeze while driving | A radio stall is different from a disconnect. padd can resend the last stick value at 50 Hz, so a fresh downstream intent is not proof of fresh pad reports. | Check the padd journal first. The official robotctl monitor p panel shows raw evdev report gaps, but interpreting it while moving sticks requires a supported, controlled hardware test. |
The original pairing guide ↗ distinguishes a connected controller from an active driver, and its Pro Controller example shows why manual connect-before-pair can leave no input device. Do not change BlueZ Privacy by guesswork: the official document records different failure reasons requiring different settings. Its history script ↗ reads existing padd and kernel journal records without a live pad; a 0x08 supervision timeout points to range or interference, while 0x13/0x16 indicates the pad was switched off. Missing history does not prove a reliable link, and a resting pad sends no reports. Never call a live stick test read-only merely because the monitor command only reads data.
When sharing a question, include the daemon version, source states in order, the two pad status lines, actual button bindings and a short timestamped log excerpt. Remove controller addresses, local IPs, serials and account details. State whether the observation came from an official physical robot; a browser simulation cannot test its Bluetooth radio. The 0.17.2 UDP stale_ms stop and timeout_ms session loss apply to netpadd, not to this Bluetooth pad diagnosis. UDP state machine ↗ stop and loss handling ↗.
Send a report someone can act on.
Replace the fields below with what you observed. Include a short, relevant error excerpt; remove tokens and personal paths before sharing. “What worked last” is often more useful than a screenshot of the final exception alone.
Goal:
Failing stage (browser / setup / CUDA / training / export / replay):
Page URL or repository + full commit:
OS and architecture:
Browser OR Python / uv / PyTorch / CUDA versions:
GPU and driver, if relevant:
Task ID / policy source / input shape:
Exact command or sequence of actions:
Expected behavior:
Actual behavior:
First error (short excerpt, secrets removed):
Last successful step:
One change tried and its result:Start a related discussion →. For a suspected upstream bug, include the same minimal reproduction at the original project’s available support channel.
Continue with your result.
What would you like to understand next?
Keep the source, your environment and your observations together.
Before you continue
Why is Wi-Fi SSH refused after MicroDuck 0.20.1?
Check version and update status over an already authorized connection first. Official 0.20.1/API 55 removes system.openWifiSsh and duckctl ssh-wifi; Wi-Fi SSH needs the local USB-C or development-image route documented upstream. A refusal alone is not proof of an update failure. HD1910 replicas and Open Duck Mini are outside this scope.
Applies to: Pollen Robotics MicroDuck. Keep the model, image, software and driver versions together. The dated sections below retain their original verification limits.
Source checked:
Sources and review (21)
- huggingface.co/spaces/pollen-robotics/microduck-simulator/blob/e81974b932c7ca1819843b7bb3dcd42e2993e98e/README.md
- huggingface.co/spaces/pollen-robotics/microduck-simulator/blob/e81974b932c7ca1819843b7bb3dcd42e2993e98e/app/src/game/controls/keyboard.js
- github.com/pollen-robotics/microduck_rl/blob/2b25a48b08f1f17bc38c90bb03144c81fbd9ed07/pyproject.toml
- docs.pytorch.org/docs/stable/generated/torch.cuda.is_available.html
- github.com/pollen-robotics/microduck_rl/issues/38
- github.com/pollen-robotics/microduck_rl/blob/2b25a48b08f1f17bc38c90bb03144c81fbd9ed07/scripts/infer_policy.py
- github.com/pollen-robotics/microduck_rl/blob/2b25a48b08f1f17bc38c90bb03144c81fbd9ed07/src/mjlab_microduck/export.py
- github.com/pollen-robotics/microduck_rl/blob/2b25a48b08f1f17bc38c90bb03144c81fbd9ed07/scripts/hf/README.md
- huggingface.co/docs/hub/jobs-manage
- github.com/pollen-robotics/microduck/releases/tag/daemon-v0.17.2
- github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/docs/robot/pair-a-gamepad.md
- github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/docs/robot/cheatsheet.md
- github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/scripts/pad-link-test.sh
- github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/docs/robot/udp-pad.md
- github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/netpadd/src/receiver.rs
- github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/netpadd/src/main.rs
- github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/robotd-params/src/pad_axes.rs
- github.com/pollen-robotics/microduck/releases/tag/daemon-v0.20.1
- github.com/pollen-robotics/microduck/pull/574
- github.com/pollen-robotics/microduck/blob/7fba12ed048d0d3a1c306ba8a2787a1a407b9974/docs/robot/duckctl.md
- github.com/pollen-robotics/microduck/blob/7fba12ed048d0d3a1c306ba8a2787a1a407b9974/scripts/seed-policies.sh
Next useful guides
Connect a MicroDuck: Find It, Join Wi-Fi, Open the Console
On an official MicroDuck, use duckctl from a laptop to distinguish Bluetooth discovery, missing Wi-Fi address and console signalling before changing settings.
MicroDuck 0.18.3: Telemetry Controls & Reconnection Checks
Check MicroDuck 0.18.3’s default-on usage telemetry, opt-out readback and SSH address cache, plus 0.18.2 gamepad recovery, before updating a compatible robot.
MicroDuck Policies: Update v8, Inspect Overrides & Reset
Check the official v8 velstand policy, update the separate policy set, identify persistent walk overrides, and reset one slot safely.