# watonomous/pioneer_humanoid architecture

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

- Interactive diagram: https://gitdiagram.com/watonomous/pioneer_humanoid
- Repository: https://github.com/watonomous/pioneer_humanoid
- Video tour (about a minute): https://gitdiagram.com/watonomous/pioneer_humanoid/video

## Overview

Pioneer is a humanoid-robot software and firmware repository. Its documented real-robot workflow connects operator teleoperation or a deployed policy through ROS 2/CAN interfacing to embedded motor firmware, with perception alongside it. A second workflow collects demonstrations in simulation or on hardware, records datasets, and trains policies; simulation RL is a separate capability. The graph preserves those branches and the documented perception, robot-model, and FreeRTOS subsystems. Broad workflow edges cite the README; unsampled implementations are represented by their exact enclosing directories.

Main entry points: [`src/teleop/pioneer_leader_arm_teleop/real_arm.py`](https://github.com/watonomous/pioneer_humanoid/blob/main/src/teleop/pioneer_leader_arm_teleop/real_arm.py) (Leader-arm teleop), [`src/interfacing/joint_command/src/joint_command_core.cpp`](https://github.com/watonomous/pioneer_humanoid/blob/main/src/interfacing/joint_command/src/joint_command_core.cpp) (Joint commands), [`src/simulation/mujoco_scenes/humanoid_mujoco_scenes`](https://github.com/watonomous/pioneer_humanoid/tree/main/src/simulation/mujoco_scenes/humanoid_mujoco_scenes) (MuJoCo scenes), [`src/robot_learning/humanoid_robot_learning/recording`](https://github.com/watonomous/pioneer_humanoid/tree/main/src/robot_learning/humanoid_robot_learning/recording) (Dataset recording)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_robot["Robot and firmware"]
  node_arm_model["Robot model<br/>[bimanual_arm.py]"]
  node_joint_command["Joint commands"]
  node_can_bridge["CAN bridge<br/>[can_node.cpp]"]
  node_motor_firmware["STM32 firmware<br/>[main.cpp]"]
  node_freertos["FreeRTOS kernel"]
end

subgraph group_perception["Perception"]
  node_calibration["Camera calibration"]
  node_slam["Visual odometry<br/>[vo.py]"]
  node_perception_nodes["Shuttlecock tracking"]
  node_voxel_grid["Voxel mapping<br/>[voxel_grid_node.py]"]
end

subgraph group_teleop["Teleoperation"]
  node_leader_teleop["Leader-arm teleop<br/>[real_arm.py]"]
  node_quest_teleop["Quest teleop<br/>[scene_driver.py]"]
  node_synthetic_tasks["Synthetic tasks<br/>[synthetic_tasks.py]"]
end

subgraph group_simulation["Simulation and RL"]
  node_mujoco_scenes["MuJoCo scenes"]
  node_badminton_sim["Badminton simulation"]
  node_rl_tasks["Humanoid RL tasks"]
end

subgraph group_learning["Learning and deployment"]
  node_recording["Dataset recording"]
  node_policy_training["Policy training<br/>[train.py]"]
  node_policy_deploy["Policy deployment"]
end

node_operator(("Operator"))

node_operator -->|"drives"| node_leader_teleop
node_operator -->|"controls"| node_quest_teleop
node_leader_teleop -->|"commands"| node_joint_command
node_quest_teleop -->|"controls simulation"| node_mujoco_scenes
node_synthetic_tasks -->|"generates demonstrations"| node_mujoco_scenes
node_mujoco_scenes -->|"supplies demonstrations"| node_recording
node_leader_teleop -->|"records demonstrations"| node_recording
node_recording -->|"provides datasets"| node_policy_training
node_policy_training -->|"produces policies"| node_policy_deploy
node_policy_deploy -->|"commands robot"| node_joint_command
node_joint_command -->|"sends ROS commands"| node_can_bridge
node_can_bridge -->|"exchanges CAN frames"| node_motor_firmware
node_motor_firmware -.->|"runs on"| node_freertos
node_arm_model -->|"configures arm"| node_leader_teleop
node_operator -.->|"calibrates cameras"| node_calibration
node_calibration -.->|"calibrates camera input"| node_slam
node_perception_nodes -->|"informs motion"| node_joint_command
node_operator -.->|"runs simulations"| node_badminton_sim
node_rl_tasks -->|"trains RL policies"| node_policy_training
node_voxel_grid -.->|"provides mapped environment"| node_operator

click node_arm_model "https://github.com/watonomous/pioneer_humanoid/blob/main/src/pioneer_humanoid/pioneer_humanoid/bimanual_arm.py"
click node_joint_command "https://github.com/watonomous/pioneer_humanoid/blob/main/src/interfacing/joint_command/src/joint_command_core.cpp"
click node_can_bridge "https://github.com/watonomous/pioneer_humanoid/blob/main/src/interfacing/can/src/can_node.cpp"
click node_motor_firmware "https://github.com/watonomous/pioneer_humanoid/blob/main/src/embedded/STM32/src/main.cpp"
click node_freertos "https://github.com/watonomous/pioneer_humanoid/tree/main/src/embedded/STM32/lib/FreeRTOS-Kernel"
click node_calibration "https://github.com/watonomous/pioneer_humanoid/blob/main/src/perception/camera_calibration/calibrate_intrinsics.py"
click node_slam "https://github.com/watonomous/pioneer_humanoid/blob/main/src/perception/slam/prototype/vo.py"
click node_perception_nodes "https://github.com/watonomous/pioneer_humanoid/tree/main/src/perception/perception/perception"
click node_voxel_grid "https://github.com/watonomous/pioneer_humanoid/blob/main/src/perception/voxel_grid/voxel_grid/voxel_grid_node.py"
click node_leader_teleop "https://github.com/watonomous/pioneer_humanoid/blob/main/src/teleop/pioneer_leader_arm_teleop/real_arm.py"
click node_quest_teleop "https://github.com/watonomous/pioneer_humanoid/blob/main/src/teleop/quest_controller_teleop/scene_driver.py"
click node_synthetic_tasks "https://github.com/watonomous/pioneer_humanoid/blob/main/src/teleop/pioneer_leader_arm_teleop/synthetic/synthetic_tasks.py"
click node_mujoco_scenes "https://github.com/watonomous/pioneer_humanoid/tree/main/src/simulation/mujoco_scenes/humanoid_mujoco_scenes"
click node_badminton_sim "https://github.com/watonomous/pioneer_humanoid/tree/main/src/simulation/badminton"
click node_rl_tasks "https://github.com/watonomous/pioneer_humanoid/tree/main/src/simulation/humanoid_rl_tasks/humanoid_rl_tasks"
click node_recording "https://github.com/watonomous/pioneer_humanoid/tree/main/src/robot_learning/humanoid_robot_learning/recording"
click node_policy_training "https://github.com/watonomous/pioneer_humanoid/blob/main/src/robot_learning/humanoid_robot_learning/train.py"
click node_policy_deploy "https://github.com/watonomous/pioneer_humanoid/blob/main/src/robot_learning/humanoid_robot_learning/deploy/pioneer_interface.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_arm_model,node_joint_command,node_can_bridge,node_motor_firmware,node_freertos toneBlue
class node_calibration,node_slam,node_perception_nodes,node_voxel_grid toneAmber
class node_leader_teleop,node_quest_teleop,node_synthetic_tasks toneMint
class node_mujoco_scenes,node_badminton_sim,node_rl_tasks toneRose
class node_recording,node_policy_training,node_policy_deploy,node_operator toneIndigo
```

## Components

### Robot and firmware

- [Robot model](https://github.com/watonomous/pioneer_humanoid/blob/main/src/pioneer_humanoid/pioneer_humanoid/bimanual_arm.py): `src/pioneer_humanoid/pioneer_humanoid/bimanual_arm.py`
- [Joint commands](https://github.com/watonomous/pioneer_humanoid/blob/main/src/interfacing/joint_command/src/joint_command_core.cpp): `src/interfacing/joint_command/src/joint_command_core.cpp`
- [CAN bridge](https://github.com/watonomous/pioneer_humanoid/blob/main/src/interfacing/can/src/can_node.cpp): `src/interfacing/can/src/can_node.cpp`
- [STM32 firmware](https://github.com/watonomous/pioneer_humanoid/blob/main/src/embedded/STM32/src/main.cpp): `src/embedded/STM32/src/main.cpp`
- [FreeRTOS kernel](https://github.com/watonomous/pioneer_humanoid/tree/main/src/embedded/STM32/lib/FreeRTOS-Kernel): `src/embedded/STM32/lib/FreeRTOS-Kernel`

### Perception

- [Camera calibration](https://github.com/watonomous/pioneer_humanoid/blob/main/src/perception/camera_calibration/calibrate_intrinsics.py): `src/perception/camera_calibration/calibrate_intrinsics.py`
- [Visual odometry](https://github.com/watonomous/pioneer_humanoid/blob/main/src/perception/slam/prototype/vo.py): `src/perception/slam/prototype/vo.py`
- [Shuttlecock tracking](https://github.com/watonomous/pioneer_humanoid/tree/main/src/perception/perception/perception): `src/perception/perception/perception`
- [Voxel mapping](https://github.com/watonomous/pioneer_humanoid/blob/main/src/perception/voxel_grid/voxel_grid/voxel_grid_node.py): `src/perception/voxel_grid/voxel_grid/voxel_grid_node.py`

### Teleoperation

- [Leader-arm teleop](https://github.com/watonomous/pioneer_humanoid/blob/main/src/teleop/pioneer_leader_arm_teleop/real_arm.py): `src/teleop/pioneer_leader_arm_teleop/real_arm.py`
- [Quest teleop](https://github.com/watonomous/pioneer_humanoid/blob/main/src/teleop/quest_controller_teleop/scene_driver.py): `src/teleop/quest_controller_teleop/scene_driver.py`
- [Synthetic tasks](https://github.com/watonomous/pioneer_humanoid/blob/main/src/teleop/pioneer_leader_arm_teleop/synthetic/synthetic_tasks.py): `src/teleop/pioneer_leader_arm_teleop/synthetic/synthetic_tasks.py`

### Simulation and RL

- [MuJoCo scenes](https://github.com/watonomous/pioneer_humanoid/tree/main/src/simulation/mujoco_scenes/humanoid_mujoco_scenes): `src/simulation/mujoco_scenes/humanoid_mujoco_scenes`
- [Badminton simulation](https://github.com/watonomous/pioneer_humanoid/tree/main/src/simulation/badminton): `src/simulation/badminton`
- [Humanoid RL tasks](https://github.com/watonomous/pioneer_humanoid/tree/main/src/simulation/humanoid_rl_tasks/humanoid_rl_tasks): `src/simulation/humanoid_rl_tasks/humanoid_rl_tasks`

### Learning and deployment

- [Dataset recording](https://github.com/watonomous/pioneer_humanoid/tree/main/src/robot_learning/humanoid_robot_learning/recording): `src/robot_learning/humanoid_robot_learning/recording`
- [Policy training](https://github.com/watonomous/pioneer_humanoid/blob/main/src/robot_learning/humanoid_robot_learning/train.py): `src/robot_learning/humanoid_robot_learning/train.py`
- [Policy deployment](https://github.com/watonomous/pioneer_humanoid/blob/main/src/robot_learning/humanoid_robot_learning/deploy/pioneer_interface.py): `src/robot_learning/humanoid_robot_learning/deploy/pioneer_interface.py`

### Other components

- **Operator**

## Connections

- Operator → Leader-arm teleop: drives
- Operator → Quest teleop: controls
- Leader-arm teleop → Joint commands: commands
- Quest teleop → MuJoCo scenes: controls simulation
- Synthetic tasks → MuJoCo scenes: generates demonstrations (evidence: `src/teleop/pioneer_leader_arm_teleop/synthetic/synthetic_tasks.py`)
- MuJoCo scenes → Dataset recording: supplies demonstrations
- Leader-arm teleop → Dataset recording: records demonstrations (evidence: `src/teleop/pioneer_leader_arm_teleop/real_arm.py`)
- Dataset recording → Policy training: provides datasets
- Policy training → Policy deployment: produces policies
- Policy deployment → Joint commands: commands robot
- Joint commands → CAN bridge: sends ROS commands
- CAN bridge → STM32 firmware: exchanges CAN frames
- STM32 firmware → FreeRTOS kernel: runs on
- Robot model → Leader-arm teleop: configures arm (evidence: `src/teleop/pioneer_leader_arm_teleop/real_arm.py`)
- Operator → Camera calibration: calibrates cameras
- Camera calibration → Visual odometry: calibrates camera input
- Shuttlecock tracking → Joint commands: informs motion
- Operator → Badminton simulation: runs simulations
- Humanoid RL tasks → Policy training: trains RL policies
- Voxel mapping → Operator: provides mapped environment