# hshi74/toddlerbot architecture

> Architecture diagram of the GitHub repository hshi74/toddlerbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hshi74/toddlerbot
- Repository: https://github.com/hshi74/toddlerbot

## Overview

ToddlerBot is an open-source humanoid robotics platform spanning perception, skill selection, locomotion, and physical control, with simulation and learning workflows supporting development. The README describes the end-to-end depth-driven multi-skill deployment; sampled C++ shows the Dynamixel client and protocol/port layers. Other subsystem connections are included only where supported by the repository layout or README, not assumed from unsampled implementations.

Main entry points: [`toddlerbot/policies/run_multiple_policy.py`](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/policies/run_multiple_policy.py) (Multi-skill Runner), [`toddlerbot/actuation/src/dynamixel_sdk/port_handler_linux.cpp`](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/actuation/src/dynamixel_sdk/port_handler_linux.cpp) (Serial Port), [`toddlerbot/policies/run_policy.py`](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/policies/run_policy.py) (Policy Runner), [`toddlerbot/skill_classifier/run_foundation_stereo.py`](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/skill_classifier/run_foundation_stereo.py) (Depth Estimation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_perception["Perception & Skills"]
  node_depth_server["Depth Estimation"]
  node_depth_data["Depth Data"]
  node_skill_classifier["Skill Classifier<br/>[predictor.py]"]
  node_skill_mapper["Skill Mapper<br/>[skill_mapper.py]"]
end

subgraph group_locomotion["Locomotion"]
  node_multi_policy["Multi-skill Runner"]
  node_policy_runtime["Policy Runner<br/>[run_policy.py]"]
  node_policy_catalog["Locomotion Policies"]
  node_references["Reference Motions"]
end

subgraph group_runtime["Robot Runtime"]
  node_robot["Robot Interface<br/>[robot.py]"]
  node_real_world["Real-world Interface<br/>[real_world.py]"]
  node_actuation["Dynamixel Client"]
  node_protocol["Packet Protocol"]
  node_serial["Serial Port"]
end

subgraph group_learning["Learning &amp; Simulation"]
  node_training["RL Training<br/>[train_mjx.py]"]
  node_mjx_env["MJX Environment<br/>[mjx_env.py]"]
  node_simulation["MuJoCo Simulation<br/>[mujoco_sim.py]"]
end

subgraph group_manipulation["Manipulation &amp; Teleop"]
  node_manipulation["Diffusion Inference<br/>[inference_class.py]"]
  node_teleop["Motion Retargeting<br/>[motion_retarget.py]"]
end

node_operator(("Operator"))
node_stereo(("Stereo Camera"))
node_motors(("Dynamixel Motors"))

node_stereo -->|"provides images"| node_depth_server
node_depth_server -->|"sends depth estimates"| node_skill_classifier
node_skill_classifier -->|"predicts skill"| node_skill_mapper
node_skill_mapper -->|"selects skill"| node_multi_policy
node_operator -->|"starts system"| node_multi_policy
node_multi_policy -->|"loads policies"| node_policy_catalog
node_policy_runtime -->|"runs policy"| node_policy_catalog
node_policy_runtime -->|"issues robot commands"| node_robot
node_robot -->|"uses real interface"| node_real_world
node_real_world -->|"commands motors"| node_actuation
node_actuation -->|"sends packets"| node_protocol
node_protocol -->|"transmits bytes"| node_serial
node_serial -->|"communicates"| node_motors
node_motors -->|"returns status"| node_serial
node_training -->|"trains in"| node_mjx_env
node_mjx_env -->|"simulates robot"| node_simulation
node_operator -->|"starts training"| node_training
node_operator -->|"collects data"| node_depth_data
node_operator -.->|"runs task"| node_manipulation
node_operator -.->|"provides motion"| node_teleop

click node_depth_server "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/skill_classifier/run_foundation_stereo.py"
click node_depth_data "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/skill_classifier/data/create_depth_data.py"
click node_skill_classifier "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/skill_classifier/inference/predictor.py"
click node_skill_mapper "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/skill_classifier/inference/skill_mapper.py"
click node_multi_policy "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/policies/run_multiple_policy.py"
click node_policy_runtime "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/policies/run_policy.py"
click node_policy_catalog "https://github.com/hshi74/toddlerbot/tree/main/toddlerbot/policies"
click node_references "https://github.com/hshi74/toddlerbot/tree/main/toddlerbot/reference"
click node_robot "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/sim/robot.py"
click node_real_world "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/sim/real_world.py"
click node_actuation "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/actuation/src/dynamixel_control/dynamixel_client.cpp"
click node_protocol "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/actuation/src/dynamixel_sdk/protocol2_packet_handler.cpp"
click node_serial "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/actuation/src/dynamixel_sdk/port_handler_linux.cpp"
click node_training "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/locomotion/train_mjx.py"
click node_mjx_env "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/locomotion/mjx_env.py"
click node_simulation "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/sim/mujoco_sim.py"
click node_manipulation "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/manipulation/inference_class.py"
click node_teleop "https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/manipulation/teleoperation/general_motion_retargeting/motion_retarget.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_depth_server,node_depth_data,node_skill_classifier,node_skill_mapper toneBlue
class node_multi_policy,node_policy_runtime,node_policy_catalog,node_references toneAmber
class node_robot,node_real_world,node_actuation,node_protocol,node_serial toneMint
class node_training,node_mjx_env,node_simulation toneRose
class node_manipulation,node_teleop,node_operator,node_stereo,node_motors toneIndigo
```

## Components

### Perception & Skills

- [Depth Estimation](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/skill_classifier/run_foundation_stereo.py): `toddlerbot/skill_classifier/run_foundation_stereo.py`
- [Depth Data](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/skill_classifier/data/create_depth_data.py): `toddlerbot/skill_classifier/data/create_depth_data.py`
- [Skill Classifier](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/skill_classifier/inference/predictor.py): `toddlerbot/skill_classifier/inference/predictor.py`
- [Skill Mapper](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/skill_classifier/inference/skill_mapper.py): `toddlerbot/skill_classifier/inference/skill_mapper.py`

### Locomotion

- [Multi-skill Runner](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/policies/run_multiple_policy.py): `toddlerbot/policies/run_multiple_policy.py`
- [Policy Runner](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/policies/run_policy.py): `toddlerbot/policies/run_policy.py`
- [Locomotion Policies](https://github.com/hshi74/toddlerbot/tree/main/toddlerbot/policies): `toddlerbot/policies`
- [Reference Motions](https://github.com/hshi74/toddlerbot/tree/main/toddlerbot/reference): `toddlerbot/reference`

### Robot Runtime

- [Robot Interface](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/sim/robot.py): `toddlerbot/sim/robot.py`
- [Real-world Interface](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/sim/real_world.py): `toddlerbot/sim/real_world.py`
- [Dynamixel Client](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/actuation/src/dynamixel_control/dynamixel_client.cpp): `toddlerbot/actuation/src/dynamixel_control/dynamixel_client.cpp`
- [Packet Protocol](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/actuation/src/dynamixel_sdk/protocol2_packet_handler.cpp): `toddlerbot/actuation/src/dynamixel_sdk/protocol2_packet_handler.cpp`
- [Serial Port](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/actuation/src/dynamixel_sdk/port_handler_linux.cpp): `toddlerbot/actuation/src/dynamixel_sdk/port_handler_linux.cpp`

### Learning & Simulation

- [RL Training](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/locomotion/train_mjx.py): `toddlerbot/locomotion/train_mjx.py`
- [MJX Environment](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/locomotion/mjx_env.py): `toddlerbot/locomotion/mjx_env.py`
- [MuJoCo Simulation](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/sim/mujoco_sim.py): `toddlerbot/sim/mujoco_sim.py`

### Manipulation & Teleop

- [Diffusion Inference](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/manipulation/inference_class.py): `toddlerbot/manipulation/inference_class.py`
- [Motion Retargeting](https://github.com/hshi74/toddlerbot/blob/main/toddlerbot/manipulation/teleoperation/general_motion_retargeting/motion_retarget.py): `toddlerbot/manipulation/teleoperation/general_motion_retargeting/motion_retarget.py`

### Other components

- **Operator**
- **Stereo Camera**
- **Dynamixel Motors**

## Connections

- Stereo Camera → Depth Estimation: provides images
- Depth Estimation → Skill Classifier: sends depth estimates
- Skill Classifier → Skill Mapper: predicts skill
- Skill Mapper → Multi-skill Runner: selects skill
- Operator → Multi-skill Runner: starts system
- Multi-skill Runner → Locomotion Policies: loads policies
- Policy Runner → Locomotion Policies: runs policy
- Policy Runner → Robot Interface: issues robot commands
- Robot Interface → Real-world Interface: uses real interface
- Real-world Interface → Dynamixel Client: commands motors
- Dynamixel Client → Packet Protocol: sends packets
- Packet Protocol → Serial Port: transmits bytes
- Serial Port → Dynamixel Motors: communicates
- Dynamixel Motors → Serial Port: returns status
- RL Training → MJX Environment: trains in
- MJX Environment → MuJoCo Simulation: simulates robot
- Operator → RL Training: starts training
- Operator → Depth Data: collects data
- Operator → Diffusion Inference: runs task
- Operator → Motion Retargeting: provides motion