# pocketxjl/humanoid-control architecture

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

- Interactive diagram: https://gitdiagram.com/pocketxjl/humanoid-control
- Repository: https://github.com/pocketxjl/humanoid-control

## Overview

This repository implements a ROS-based humanoid locomotion stack: commands and robot measurements enter controller nodes, state estimation and OCS2-based model-predictive control produce desired motion, and whole-body control turns that motion into joint commands. Gait scheduling and swing-foot planning shape the motion references; simulation and visualization support operation. The README documents the optimization and estimator behavior, while several internal connections are inferred from those documented responsibilities because their wiring was not sampled.

Main entry points: [`humanoid_controllers/src/humanoidController.cpp`](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_controllers/src/humanoidController.cpp) (Humanoid controller), [`humanoid_interface/src/HumanoidInterface.cpp`](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/HumanoidInterface.cpp) (Humanoid optimal-control interface), [`humanoid_interface/src/reference_manager/SwitchedModelReferenceManager.cpp`](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/reference_manager/SwitchedModelReferenceManager.cpp) (Switched reference manager), [`humanoid_controllers/src/JoyControllerNode.cpp`](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_controllers/src/JoyControllerNode.cpp) (Joy controller node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_command["Commands and runtime"]
  node_joy_node["Joy controller node"]
  node_gait_publisher["Gait command publisher"]
  node_dummy_nodes["OCS2 dummy nodes"]
end

subgraph group_control["Control and estimation"]
  node_controller["Humanoid controller"]
  node_estimator["State estimation"]
  node_kalman["Linear Kalman filter"]
  node_interface["Humanoid optimal-control interface"]
  node_dynamics["Centroidal dynamics"]
  node_constraints["Contact constraints"]
  node_mpc["NMPC and MRT"]
end

subgraph group_planning["Locomotion planning"]
  node_gait["Gait schedule<br/>[GaitSchedule.cpp]"]
  node_reference["Switched reference manager"]
  node_swing["Swing trajectory planner"]
end

subgraph group_execution["Execution and simulation"]
  node_wbc["Whole-body control<br/>[WeightedWbc.cpp]"]
  node_safety["Safety checker<br/>[SafetyChecker.h]"]
  node_sim["MuJoCo simulation<br/>[humanoid_sim.py]"]
  node_teleop["Simulation teleoperation<br/>[teleop.py]"]
end

subgraph group_support["Visualization"]
  node_visualizer["Humanoid visualization"]
end

node_operator(("Operator"))
node_robot(("Robot sensors"))
node_actuators(("Joint actuators"))

node_operator -->|"sends commands"| node_joy_node
node_joy_node -->|"publishes gait"| node_gait_publisher
node_gait_publisher -->|"sends gait command"| node_gait
node_robot -->|"provides measurements"| node_controller
node_controller -->|"updates state"| node_estimator
node_estimator -->|"filters measurements"| node_kalman
node_controller -->|"advances optimization"| node_mpc
node_interface -->|"provides dynamics"| node_dynamics
node_interface -->|"configures constraints"| node_constraints
node_reference -->|"gets mode schedule"| node_gait
node_reference -->|"updates trajectory"| node_swing
node_mpc -->|"modifies references"| node_reference
node_mpc -->|"uses model"| node_interface
node_controller -->|"computes joint commands"| node_wbc
node_controller -->|"checks commands"| node_safety
node_controller -->|"publishes joint targets"| node_actuators
node_controller -->|"publishes observations"| node_visualizer
node_dummy_nodes -->|"publishes robot state"| node_visualizer
node_operator -.->|"provides input"| node_teleop
node_teleop -.->|"controls simulation"| node_sim

click node_joy_node "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_controllers/src/JoyControllerNode.cpp"
click node_gait_publisher "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_dummy/src/gait/GaitKeyboardPublisher.cpp"
click node_controller "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_controllers/src/humanoidController.cpp"
click node_estimator "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_estimation/src/StateEstimateBase.cpp"
click node_kalman "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_estimation/src/LinearKalmanFilter.cpp"
click node_interface "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/HumanoidInterface.cpp"
click node_dynamics "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/dynamics/HumanoidDynamicsAD.cpp"
click node_constraints "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/constraint/FrictionConeConstraint.cpp"
click node_gait "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/gait/GaitSchedule.cpp"
click node_reference "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/reference_manager/SwitchedModelReferenceManager.cpp"
click node_swing "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/foot_planner/SwingTrajectoryPlanner.cpp"
click node_mpc "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_controllers/src/humanoidController.cpp"
click node_wbc "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_wbc/src/WeightedWbc.cpp"
click node_safety "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_controllers/include/humanoid_controllers/SafetyChecker.h"
click node_sim "https://github.com/pocketxjl/humanoid-control/blob/main/mujoco_sim/script/humanoid_sim.py"
click node_teleop "https://github.com/pocketxjl/humanoid-control/blob/main/mujoco_sim/script/teleop.py"
click node_visualizer "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_dummy/src/visualization/HumanoidVisualizer.cpp"
click node_dummy_nodes "https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_dummy/src/HumanoidSqpMpcNode.cpp"

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_joy_node,node_gait_publisher,node_dummy_nodes toneBlue
class node_controller,node_estimator,node_kalman,node_interface,node_dynamics,node_constraints,node_mpc toneAmber
class node_gait,node_reference,node_swing toneMint
class node_wbc,node_safety,node_sim,node_teleop toneRose
class node_visualizer,node_operator,node_robot,node_actuators toneIndigo
```

## Components

### Commands and runtime

- [Joy controller node](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_controllers/src/JoyControllerNode.cpp): `humanoid_controllers/src/JoyControllerNode.cpp`
- [Gait command publisher](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_dummy/src/gait/GaitKeyboardPublisher.cpp): `humanoid_dummy/src/gait/GaitKeyboardPublisher.cpp`
- [OCS2 dummy nodes](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_dummy/src/HumanoidSqpMpcNode.cpp): `humanoid_dummy/src/HumanoidSqpMpcNode.cpp`

### Control and estimation

- [Humanoid controller](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_controllers/src/humanoidController.cpp): `humanoid_controllers/src/humanoidController.cpp`
- [State estimation](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_estimation/src/StateEstimateBase.cpp): `humanoid_estimation/src/StateEstimateBase.cpp`
- [Linear Kalman filter](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_estimation/src/LinearKalmanFilter.cpp): `humanoid_estimation/src/LinearKalmanFilter.cpp`
- [Humanoid optimal-control interface](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/HumanoidInterface.cpp): `humanoid_interface/src/HumanoidInterface.cpp`
- [Centroidal dynamics](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/dynamics/HumanoidDynamicsAD.cpp): `humanoid_interface/src/dynamics/HumanoidDynamicsAD.cpp`
- [Contact constraints](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/constraint/FrictionConeConstraint.cpp): `humanoid_interface/src/constraint/FrictionConeConstraint.cpp`
- [NMPC and MRT](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_controllers/src/humanoidController.cpp): `humanoid_controllers/src/humanoidController.cpp`

### Locomotion planning

- [Gait schedule](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/gait/GaitSchedule.cpp): `humanoid_interface/src/gait/GaitSchedule.cpp`
- [Switched reference manager](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/reference_manager/SwitchedModelReferenceManager.cpp): `humanoid_interface/src/reference_manager/SwitchedModelReferenceManager.cpp`
- [Swing trajectory planner](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_interface/src/foot_planner/SwingTrajectoryPlanner.cpp): `humanoid_interface/src/foot_planner/SwingTrajectoryPlanner.cpp`

### Execution and simulation

- [Whole-body control](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_wbc/src/WeightedWbc.cpp): `humanoid_wbc/src/WeightedWbc.cpp`
- [Safety checker](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_controllers/include/humanoid_controllers/SafetyChecker.h): `humanoid_controllers/include/humanoid_controllers/SafetyChecker.h`
- [MuJoCo simulation](https://github.com/pocketxjl/humanoid-control/blob/main/mujoco_sim/script/humanoid_sim.py): `mujoco_sim/script/humanoid_sim.py`
- [Simulation teleoperation](https://github.com/pocketxjl/humanoid-control/blob/main/mujoco_sim/script/teleop.py): `mujoco_sim/script/teleop.py`

### Visualization

- [Humanoid visualization](https://github.com/pocketxjl/humanoid-control/blob/main/humanoid_dummy/src/visualization/HumanoidVisualizer.cpp): `humanoid_dummy/src/visualization/HumanoidVisualizer.cpp`

### Other components

- **Operator**
- **Robot sensors**
- **Joint actuators**

## Connections

- Operator → Joy controller node: sends commands
- Joy controller node → Gait command publisher: publishes gait
- Gait command publisher → Gait schedule: sends gait command
- Robot sensors → Humanoid controller: provides measurements
- Humanoid controller → State estimation: updates state
- State estimation → Linear Kalman filter: filters measurements
- Humanoid controller → NMPC and MRT: advances optimization
- Humanoid optimal-control interface → Centroidal dynamics: provides dynamics
- Humanoid optimal-control interface → Contact constraints: configures constraints
- Switched reference manager → Gait schedule: gets mode schedule
- Switched reference manager → Swing trajectory planner: updates trajectory
- NMPC and MRT → Switched reference manager: modifies references
- NMPC and MRT → Humanoid optimal-control interface: uses model
- Humanoid controller → Whole-body control: computes joint commands
- Humanoid controller → Safety checker: checks commands
- Humanoid controller → Joint actuators: publishes joint targets
- Humanoid controller → Humanoid visualization: publishes observations
- OCS2 dummy nodes → Humanoid visualization: publishes robot state
- Operator → Simulation teleoperation: provides input
- Simulation teleoperation → MuJoCo simulation: controls simulation