Instructions to use Swenlon/microduck-spin with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Microduck
How to use Swenlon/microduck-spin with Microduck:
# Replace SLOT with the slot specified in the model card (walk, stand, sitstand, ground_pick, kick_left, kick_right, roulade). sudo robotctl policy load SLOT Swenlon/microduck-spin
- Notebooks
- Google Colab
- Kaggle
Download README.md from Swenlon/microduck-spin: direct link, hf CLI and curl.
- Browser
- Download file 6.95 kB
-
https://huggingface.co/Swenlon/microduck-spin/resolve/main/README.md
- Command line
-
hf download hf://Swenlon/microduck-spin/README.md
-
curl -L -o README.md https://huggingface.co/Swenlon/microduck-spin/resolve/main/README.md
language:
- zh
- en
tags:
- microduck
- robotics
- reinforcement-learning
- onnx
- simulation
- spinning
Microduck Spin — 20,000 Updates
Experimental fast-spinning policy initialized from a standard walking base.
This candidate was selected from checkpoint model_19999.pt, representing
20,000 completed PPO updates in march-from-walker. The original
autonomous goose-step objective was not achieved. The owner chose to preserve
the resulting spinning behavior as a separate candidate skill.
Simulation only. Timing-sensitive. Some center drift is present. No safe stop, fall recovery or physical-robot deployment has been validated. Do not replace the normal walking/recovery policy on a real robot based on these videos.
Important correction: actuator delay is external to ONNX
The original local command omitted actuator delay. In the CPU MuJoCo/BAM
rehearsal it triggered the diagnostic fall criterion after about 1.74 s.
Adding --delay 1 (one 20 ms policy-control period) produced five 30-second
runs without that criterion firing. This update corrects the instructions and
adds reproducible configuration; the ONNX weights and original videos are
unchanged.
Training BAM delay of 3–6 means 5 ms physics substeps (15–30 ms). The CPU
script's CLI counts 20 ms control periods. Do not use --delay 3 6 to
reproduce this result: that would mean 60–120 ms. The ONNX includes observation
normalization, but does not contain actuator delay or simulator/recovery code.
The inference_config.json is read by the included launcher; it is not an
automatic configuration of the robot daemon.
Run locally on Mac
Requires a working local microduck_rl checkout with its configured Python
3.12 .venv, MuJoCo, BAM and ONNX Runtime, plus robot assets. The model folder
alone is not a simulator. Reference CPU runs used MuJoCo 3.10.0 and ONNX
Runtime 1.24.4. No training or robot connection is performed by the launcher.
Set the two paths for your computer:
REPO="/absolute/path/to/microduck_rl"
MODEL_DIR="/absolute/path/to/downloaded/microduck-spin"
python3 "$MODEL_DIR/run_local.py" --repo "$REPO"
To verify paths/model identity and print the command without opening a viewer:
python3 "$MODEL_DIR/run_local.py" --repo "$REPO" --check-only
Equivalent direct invocation:
cd "$REPO"
"$REPO/.venv/bin/mjpython" "$REPO/scripts/infer_policy.py" \
--walking "$MODEL_DIR/policy.onnx" \
--scene "$REPO/src/mjlab_microduck/robot/microduck/scene_allcollisions.xml" \
--new-cmd-obs \
--lin-vel-x 1 --lin-vel-y 0 --ang-vel-z 0 \
--action-scale 1 --delay 1 --vin 7.4 --vin-drop-gain 0.1
Initially do not change arrow keys, space, or head/body commands. Press Q in
the terminal to exit. --walking is the script's loading slot, not a normal
walking-policy designation. --lin-vel-x 1 supplies [1,0,0], a constant
behavior request; it is not a requested speed of 1 m/s. Leave BAM enabled,
do not add --no-bam, and do not normalize the input twice. Pausing inference
or closing the simulator does not demonstrate safe stopping or standing up.
Interface
- ONNX input
obs: float32[1,61]; outputactions: float32[1,14]. - Observation order: base angular velocity (3), projected gravity (3), servo position relative to default (14), servo velocity (14), previous action (14), behavior command (3), head command (4), body command (6).
- Fixed command
[1,0,0]; head/body slots zero. Action scale 1.0, with the training default-pose joint-position offset. Exact joint names/order/defaults are in ONNX metadata andprovenance/source.json. - Microduck/14 XL330 actuators, nominal control 50 Hz. This describes the interface, not proof of safe operation on hardware.
- No
command.idleor invented unwind interval: stop/handoff are unvalidated. Informational manifest fields do not make a daemon use this timing or command.
Validation — scopes must not be mixed
Export fidelity: canonical repository runner export with normalization, 66 input vectors compared against the checkpoint's deterministic PyTorch actor. Maximum absolute action difference 9.5367431640625e-7; ONNX structural checks and Mac ONNX Runtime loading passed. Not a motion-safety test.
Original GPU replay: seeds 55/56, two trials per batch, bounded 18 seconds,
four reported no falls; each original video shows the first trial of its batch.
The reports evaluated goose-step criteria, not quantitative spin quality or
safe stopping. Original files in evaluation/ and videos are unchanged.
Additional CPU rehearsal (2026-11-16): same ONNX, nominal 7.4 V battery, 0.1 sag gain, 1.0 action scale, one 20 ms control-step actuator delay, standard all-collisions scene. Initial yaw perturbation ±0.02 rad and joint-position perturbation ±0.005 rad. No extra full GPU domain randomization was reproduced.
| Seed | Time (s) | Diagnostic fall | Yaw turns | Max XY displacement (m) |
|---|---|---|---|---|
| 55 | 30 | No | 24.76 | 0.154 |
| 56 | 30 | No | 25.09 | 0.137 |
| 57 | 30 | No | 24.90 | 0.177 |
| 58 | 30 | No | 24.91 | 0.201 |
| 59 | 30 | No | 25.18 | 0.154 |
Diagnostic fall: trunk height below 0.085 m or projected gravity body Z
above −0.70. Not firing this criterion does not certify safe contacts, torque
limits or perfect posture. Behavior is fast spinning with drift, not
perfect fixed-center rotation. See evaluation/cpu-timing-rehearsal.json.
Files
policy.onnx is the only model; manifest.json, inference_config.json and
run_local.py document/configure the local rehearsal. validation.json holds
export checks and the separately scoped CPU results; provenance/source.json
records origin and source hashes. CHECKSUMS.sha256 covers release files.
replay.mp4 and videos/replay-seed-56.mp4 are the two original videos.
The walking initializer cleared command input columns 48–60 and reset their normalization. This policy is not byte-equivalent to the native walking base. Its former goose-step goal remains unsuccessful; this is a separate candidate.
License and attribution
Training/export code originated in Pollen Robotics microduck_rl. Source
walking weight identity is recorded in provenance, but its upstream weight
license was unavailable in the local snapshot. No weight license has been
selected on the owner's behalf. Confirm redistribution permission before
public release and add an appropriate license. No robot mesh assets,
credentials, optimizer states or checkpoint pickle are in this package.
ONNX SHA-256:
c9bf6d76b327bc25d39c863ef0858cce477209cafd28f3f91a3f8233dcdf0033
Checkpoint SHA-256:
47674317b69de26da4a067d57654dae25f2e9d9ca8bcb26c7ba05b45a66948dc
Documentation/timing revision v2, 2026-11-16. No model retraining or automatic Hugging Face upload was performed to prepare this revision.