# apirrone/open_duck_mini architecture

> Architecture diagram of the GitHub repository apirrone/open_duck_mini, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apirrone/open_duck_mini
- Repository: https://github.com/apirrone/open_duck_mini

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Design Layer
    subgraph "Design Layer"
        direction TB
        CAD["CAD & Robot Description<br/><i>URDF/XML, meshes, config.json</i>"]:::design
    end

    %% Simulation & Training Layer
    subgraph "Simulation & Training Layer"
        direction TB
        SIM["MuJoCo Simulation<br/><i>MuJoCo, scene.xml</i>"]:::simulation
        TRAIN["RL Training Pipeline<br/><i>Python, HDF5</i>"]:::training
        IDENT["Actuator Identification<br/><i>BAM, Python</i>"]:::analysis
        UTILS["Experiment Utilities & Libraries<br/><i>walk engines, rl_utils</i>"]:::utils
    end

    %% Deployment Layer
    subgraph "Deployment Layer"
        direction TB
        MODELS["Model Artifacts<br/><i>.onnx policies</i>"]:::data
        RUNTIME["Embedded Runtime<br/><i>Raspberry Pi Zero 2W</i>"]:::deployment
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        HW["Real Hardware<br/><i>IMU, pressure, motors</i>"]:::hardware
    end

    %% Documentation & Build Tools
    DOCS["Documentation & Build Tools<br/><i>docs/*.md, pyproject.toml</i>"]:::docs

    %% External Systems
    EXT["External Systems<br/><i>GitHub, BOM, Discord</i>"]:::external

    %% Connections
    CAD -->|"imports URDF/XML & meshes"| SIM
    SIM <-->|"uses utils"| UTILS
    SIM <-->|"feeds trajectories & rewards"| TRAIN
    TRAIN -->|"produces ONNX"| MODELS
    MODELS -->|"loaded by"| RUNTIME
    RUNTIME <-->|"sensor data in / motor commands out"| HW
    HW -->|"data for calibration"| IDENT
    IDENT -->|"tunes parameters for"| TRAIN
    TRAIN -->|"evaluation data"| SIM
    DOCS -.-> CAD
    DOCS -.-> SIM
    DOCS -.-> TRAIN
    DOCS -.-> RUNTIME
    EXT -.-> DOCS

    %% Click Events
    click CAD "https://github.com/apirrone/open_duck_mini/tree/v2/mini_bdx/robots/open_duck_mini_v2/"
    click SIM "https://github.com/apirrone/open_duck_mini/tree/v2/experiments/mujoco/"
    click TRAIN "https://github.com/apirrone/open_duck_mini/blob/v2/experiments/RL/train.py"
    click MODELS "https://github.com/apirrone/open_duck_mini/blob/v2/experiments/RL/BEST_WALK_ONNX.onnx"
    click IDENT "https://github.com/apirrone/open_duck_mini/blob/v2/experiments/identification/get_data.py"
    click RUNTIME "https://github.com/apirrone/open_duck_mini/blob/v2/mini_bdx/robots/open_duck_mini_v2/config.json"
    click UTILS "https://github.com/apirrone/open_duck_mini/blob/v2/mini_bdx/mini_bdx/utils/mujoco_utils.py"
    click DOCS "https://github.com/apirrone/open_duck_mini/blob/v2/docs/assembly_guide.md"

    %% Styles
    classDef design fill:#D0E6FF,stroke:#009,stroke-width:2px;
    classDef simulation fill:#DFFFE0,stroke:#080,stroke-width:2px;
    classDef training fill:#DFFFE0,stroke:#080,stroke-width:2px;
    classDef analysis fill:#FFF5CC,stroke:#AA0,stroke-width:2px;
    classDef utils fill:#F0F0F0,stroke:#666,stroke-width:2px;
    classDef data fill:#FFE0E0,stroke:#A00,stroke-width:2px;
    classDef deployment fill:#FFEBD0,stroke:#A50,stroke-width:2px;
    classDef hardware fill:#E0E0E0,stroke:#444,stroke-width:2px;
    classDef docs fill:#F5F5F5,stroke:#888,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#FFFFFF,stroke:#AAA,stroke-width:1px,stroke-dasharray: 2 2;
```
