How apirrone/open_duck_mini works
Project Type and Purpose
• This is a robotics simulation and control codebase for the “Open Duck Mini v2” robot: a 42 cm tall, low-cost, bipedal droid.
• It centralizes CAD assets, simulation setup (MuJoCo), reinforcement-learning (RL) training pipelines, model artifacts (.onnx), on-robot runtime code, identification scripts, and assorted documentation.
Top‐Level Architectural Components
a. CAD & Robot Description
• Directories: mini_bdx/robots/... (URDF/XML, STL/PRT, config.json)
• Purpose: defines kinematics, collision geometry, meshes for sim & real build.
b. Simulation Environment
• Scripts & configs in experiments/**/mujoco, docs/prepare_robot.md
• Physics engine: MuJoCo, uses URDF/XML and scene.xml.
c. RL Training Pipeline
• experiments/RL/new, experiments/RL/*
• Environments (env.py, simple_env.py, footsteps_env.py), pretraining (BC, GAIL), training loops, data recording (HDF5), evaluation scripts.
• Model artifacts: BEST_WALK_ONNX.onnx, BEST_WALK_ONNX_2.onnx
d. Actuator Identification
• experiments/identification (speed checks, data acquisition, plotting)
• Uses BAM (external) for model fitting.
e. Embedded Runtime & Deployment
• External repo: Open_Duck_Mini_Runtime (onboard code for Raspberry Pi Zero 2W)
• Inputs: ONNX policy, config.json, sensor readings (IMU, pressure).
• Outputs: motor commands via PWM, logs.
f. Documentation & Build Tools
• docs/*.md (assembly, wiring, print guides, sim2real notes)
• pyproject.toml, setup.cfg, scripts.
g. Experiment Utilities & Libraries
• mini_bdx/mini_bdx (walk engines: old_walk_engine, placo_walk_engine)
• mini_bdx/utils (rl_utils, mujoco_utils, poly_spline, xbox_controller)
Relationships & Data Flows
• CAD assets → imported by MuJoCo scene → simulation environments
• Simulation environments ↔ RL training scripts (generate trajectories, collect rewards, record data)
• RL training → produces ONNX policy artifacts
• Identification scripts ↔ real hardware data (calibration) → tuning control parameters
• Deployment pipeline: ONNX model + runtime code → Raspberry Pi → real-time sensor loop → actuator commands
• Logging & evaluation data → back into experiments (for further training or identification)
Architectural Patterns & Principles
• Layered separation: Design assets / Simulation / Training / Deployment
• Modular experiments folder: each experiment can be swapped in/out
• Data-driven pipelines: HDF5 recording, ONNX interoperability
• Clear separation between sim-only components and hardware-specific modules
Detailed Capturing of Essential Elements
• URDF and mesh files are grouped under “CAD & Robot Description.”
• That experiments/identification feeds into parameter tuning.
• That docs and build scripts support the pipeline but are not part of the runtime loop.
• Two ONNX models as example policies.
Final Advice
• Don’t over-break into trivial subfolders—group related modules logically.