| --- |
| thumbnail: https://huggingface.co/HannesVonEssen/microduck-swing/resolve/main/media/social-preview.png |
| pipeline_tag: robotics |
| tags: [microduck, microduck-policy, mjlab, robotics, reinforcement-learning, swing] |
| license: apache-2.0 |
| --- |
| |
| # microduck-swing |
|
|
| This MicroDuck policy starts motionless at the bottom of a two-cord swing and |
| pumps with its articulated head and legs. The best strict 36-second rollout |
| reaches a **173.20° full span**; 71 of 100 randomized seeds pass every |
| full-horizon physical-validity gate. |
|
|
| The complete task, PPO configuration, selected PyTorch checkpoint and |
| selection endpoints, deterministic evaluator, seat generator, printable |
| meshes, and collision hulls are in |
| [`Vottivott/microduck-playground`](https://github.com/Vottivott/microduck-playground) |
| at commit |
| [`c5fcc50`](https://github.com/Vottivott/microduck-playground/commit/c5fcc50219fef01ac9931d0079c583ccbb29b689). |
|
|
| ## Retained seat |
|
|
| The printable seat, strap, buckle, clearance reports, and parametric source are |
| in [`hardware/swing-seat`](https://github.com/Vottivott/microduck-playground/tree/c5fcc50219fef01ac9931d0079c583ccbb29b689/hardware/swing-seat). |
|
|
| | Front | Three-quarter | Side | |
| |---|---|---| |
| |  |  |  | |
|
|
| ## Try it in simulation |
|
|
| ```bash |
| git clone https://github.com/Vottivott/microduck-playground.git |
| cd microduck-playground |
| git checkout c5fcc50219fef01ac9931d0079c583ccbb29b689 |
| uv sync |
| |
| # Reproduce the best strict 36-second audit from the source checkpoint. |
| uv run python scripts/evaluate_swing_checkpoint.py \ |
| experiments/swing/checkpoints/alpha050.pt \ |
| --output /tmp/swing-seed27.json \ |
| --device cpu --duration 36 --seed 27 |
| |
| # Download the deployment graph separately. |
| hf download HannesVonEssen/microduck-swing policy.onnx config.json \ |
| --local-dir policies/swing |
| ``` |
|
|
| ## Continue training |
|
|
| `checkpoint.pt` contains the exact alpha-0.50 actor used in this |
| video. Its critic is copied from the interpolation source endpoint; optimizer |
| moments are empty, the learning rate is `1e-7`, and exploration standard |
| deviation is `0.02`. Place it at |
| `logs/rsl_rl/microduck_swing/release-alpha050/model_3500.pt`, then resume with: |
|
|
| ```bash |
| uv run train Mjlab-SwingPump-MicroDuck \ |
| --agent.resume True --agent.load-run release-alpha050 \ |
| --agent.load-checkpoint model_3500.pt --agent.max-iterations 25 |
| ``` |
|
|
| The released lineage ends here, at the policy shown in the 173.20° video. |
| PyTorch checkpoints use pickle internally; load them only from a repository |
| and revision you trust. |
|
|
| ## Runtime contract |
|
|
| - input: `obs`, float32 `[1, 61]` |
| - output: `actions`, float32 `[1, 14]` |
| - control rate: 50 Hz |
| - action scale: 0.7 rad, joint-position targets around MicroDuck HOME |
| - action clipping: `[-1, 1]`, baked into `policy.onnx` to match training |
| - observation normalizer: baked into `policy.onnx` |
| - entry state: retained in the seat, bottom of the arc, motionless |
| - robot: MicroDuck hardware revision 1, 14 Dynamixel XL330 servos |
| - mechanism: two independent 380 mm elastic, tension-only cords |
| - policy horizon: trained episodically; evaluated for 36 seconds |
|
|
| The observation order is `base_ang_vel(3), projected_gravity(3), |
| joint_pos(14), joint_vel(14), previous_actions(14), swing_plane_cue(3), |
| zeros(4), zeros(6)`. |
|
|
| ### Important: the three cue slots are not velocity commands |
|
|
| This model preserves the standard 61-D MicroDuck tensor shape, but repurposes |
| the usual three twist-command slots as a deployable swing-plane feedback cue: |
|
|
| ```text |
| [0, body_y_axis_world.x, body_y_axis_world.z] |
| ``` |
|
|
| `body_y_axis_world` must come from the robot's IMU orientation expressed |
| relative to the known still-start frame. The remaining 10 command slots are |
| zeros. A standard walking runtime that supplies a requested velocity in these |
| slots is therefore incompatible without this small observation adapter. No |
| cord, pivot, camera, or motion-capture measurement is supplied to the actor. |
|
|
| ## Simulation evaluation |
|
|
| The selected model is the exact all-row alpha-0.50 final-layer interpolation |
| documented in the source repository. Selection uses mechanism validity rather |
| than angle alone. |
|
|
| | metric | result | |
| |---|---:| |
| | randomized evaluation | 100 seeds × 36 s | |
| | strict full-horizon passes | 71/100 | |
| | geometry-debt-free passes | 73/100 | |
| | median peak-to-peak span | 163.03° | |
| | median final-six half-cycle span | 161.09° | |
| | best strict rollout | seed 27, 173.20° | |
| | seed-27 cord envelope | 370.38–392.02 mm | |
| | seed-27 maximum lateral displacement | 10.35 mm | |
| | seed-27 maximum attachment-alignment penalty | 0.02037 | |
|
|
| Strict screening rejects a rollout for excessive lateral displacement, |
| attachment misalignment, deep cord slack, overextension, NaNs, reset, or |
| accumulated geometry debt. The preview is the strict seed-27 rollout; it is |
| silent and the overlay reports the running maximum full-span angle. |
|
|
| ## Sim-to-real boundary |
|
|
| The task retains deployment-oriented MicroDuck modeling, including BAM XL330 |
| voltage/back-EMF/current behavior, battery variation and load-dependent sag, |
| control delay, actuator friction variation, encoder bias, IMU/encoder noise, |
| and two independent elastic tension-only cords. The actor uses only |
| IMU/encoder/action-history signals available on the robot. |
|
|
| This is a **simulation result, not a hardware-validated policy**. It requires |
| the retained swing seat, 380 mm cords, and a suitable rigid frame. Cord knots, |
| frame flex, textile strap contact, seat padding, real collision geometry, |
| servo temperature, assembly tolerances, and the IMU-frame calibration are not |
| fully captured. Use a separate safety tether, current limits, an emergency |
| stop, a clear exclusion zone, and conservative incremental testing. |
|
|
| <a href="https://hfviewer.com/HannesVonEssen/microduck-swing?utm_source=huggingface&utm_medium=embedded_model_card&utm_campaign=HannesVonEssen__microduck-swing_card&utm_content=embedded_card_open_viewer&from=embedded-model-card" target="_blank" rel="noopener"> |
| <img |
| src="https://hfviewer.com/api/card.svg?source=HannesVonEssen%2Fmicroduck-swing&granularity=auto&v=20260902-action-contract-r2" |
| alt="Architecture graph for HannesVonEssen/microduck-swing. Open in hfviewer" |
| width="100%" |
| /> |
| </a> |
|
|
