q2p/microduck-beak-throw

beak-throw

Wind up, throw a 24 mm ball from the beak, and recover to a two-foot stand.

The 4K preview shows three separately reset episodes from the released checkpoint at half speed with low, locked cameras: the ball comes toward the lens, then crosses to the right and left of it.

Command — one-shot skill: robotctl robot do beak-throw. The 14-action network controls the body and head; the mouth is synchronized by the runtime.

phase	body / mouth behavior
0.00–0.30	learned wind-up; mouth holds at +20°
0.30–0.34	learned snap; mouth opens to +30°
0.34–1.00	follow-through and recovery; mouth remains open
after 2.4 s	runtime switches to alpha_stand.onnx

What it does — throws a 24 mm / 3 g simulated ball about 0.53 m forward, then hands control to the supplied standing policy. The ball is a free rigid body held by upper/lower compliant pads, a rounded front lip, a rear stop, and side cheeks; it is not welded or teleported during the throw.

Limits (simulation-validated, hardware-unvalidated) — 50/50 randomized simulator trials released, landed, passed the ≥0.50 m forward / ≤0.20 m lateral gate, and recovered. The raw network exceeded the strict joint-target limit in 50/50 trials (median 0.751 rad), so the supplied runtime's anatomical clamp is mandatory. This is an experimental supervised policy, not a production-safe skill. The first physical run must be empty-beak.

Try it in simulation (laptop, no robot) — reconstructs the exact task from the public patch/overlay, then downloads the selected RSL-RL checkpoint:

git clone https://github.com/llama/microduck-beak-throw.git
git clone https://github.com/pollen-robotics/microduck_rl.git && cd microduck_rl
git checkout d424a0c899f6b33cbd3daeb279913134349c0b63
git apply ../microduck-beak-throw/training/microduck_rl-shared-files.patch
rsync -a ../microduck-beak-throw/training/overlay/ ./
uv sync
uv run hf download q2p/microduck-beak-throw checkpoints/model_2150.pt --local-dir policies/beak-throw

On Linux:

uv run play Mjlab-BeakThrow-Hardware-MicroDuck \
  --checkpoint-file policies/beak-throw/checkpoints/model_2150.pt --num-envs 1

On macOS (MuJoCo requires mjpython):

ln -sf "$(.venv/bin/python -c 'import sys; print(sys.base_prefix)')/lib/libpython3.12.dylib" .venv/libpython3.12.dylib
.venv/bin/mjpython .venv/bin/play Mjlab-BeakThrow-Hardware-MicroDuck \
  --checkpoint-file policies/beak-throw/checkpoints/model_2150.pt --num-envs 1

Try it on the robot — requires the patched Microduck runtime; unlike the flamingo policy, this cannot safely be installed as a simple policy swap:

git clone https://github.com/pollen-robotics/microduck.git && cd microduck
git checkout 590b986bd8c0d50ae02cb3ea2f59c463b6828168
hf download q2p/microduck-beak-throw beak_throw.onnx alpha_stand.onnx runtime/microduck-runtime.patch --local-dir beak-throw
git apply beak-throw/runtime/microduck-runtime.patch
cp beak-throw/beak_throw.onnx policies/beak_throw.onnx
cp beak-throw/alpha_stand.onnx policies/alpha_stand.onnx
scripts/dev-push.sh --docker radxa@<robot>

On the robot, add these keys to the existing [policy] section of /etc/robot/robotd.toml (do not create a second section), then restart:

beak_throw = "/opt/robot/current/policies/beak_throw.onnx"
beak_throw_period = 2.4
beak_throw_action_scale = 1.0
beak_throw_gain_ratio = 1.0

sudo systemctl restart robotd
robotctl health
robotctl monitor
robotctl robot enable
robotctl robot do beak-throw     # EMPTY BEAK FIRST

Before hardware use, read hardware/INSTALL_AND_TEST.md and complete hardware/HARDWARE_COMPATIBILITY.md. Use a padded high-friction floor, eye protection, a clear exclusion zone, and pretyped abort/torque-off commands. The reference liner must be measured and adapted to the physical bill before any loaded trial.

Contract obs[1,61] f32 → actions[1,14] f32, normalizer baked in, 50 Hz, action scale 1.0, kind episodic, duration 2.4 s, entry pose standing. The phase command occupies twist slots as [cos(2π phase), sin(2π phase), 0].

Provenance Mjlab-BeakThrow-Hardware-MicroDuck — pollen-robotics/microduck_rl @ d424a0c; selected checkpoint model_2150.pt from q2p/beak-hardware-straight-v3-20260901-a100; exported with the baked-in observation normalizer. Runtime patch base: pollen-robotics/microduck @ 590b986.

Files beak_throw.onnx · alpha_stand.onnx · checkpoints/model_2150.pt · manifest.json · media/preview.mp4 · runtime/ · hardware/ · docs/ · SHA256SUMS

Source and issues: llama/microduck-beak-throw. Format: Microduck policy sharing.