# legubiao/quadruped_ros2_control architecture

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

- Interactive diagram: https://gitdiagram.com/legubiao/quadruped_ros2_control
- Repository: https://github.com/legubiao/quadruped_ros2_control

## Overview

#### Purpose and Runtime

A ROS 2 Jazzy workspace for ros2_control-based quadruped locomotion across simulation and real Unitree hardware. It combines robot descriptions, ros2_control hardware adapters, command publishers, and interchangeable controllers: classical Unitree Guide, OCS2 MPC/WBC, RL policy, and leg PD. ROS 2 launch files are the operational entry points; build uses colcon/CMake.

#### System Entry Points

Typical startup loads a robot description plus hardware adapter and controller via:
- `controllers/unitree_guide_controller/launch/gazebo.launch.py`
- `controllers/unitree_guide_controller/launch/mujoco.launch.py`
- `libraries/gz_quadruped_playground/launch/ocs2.launch.py`

Inputs are separate ROS nodes, notably keyboard and joystick publishers:
- `commands/keyboard_input/src/KeyboardInput.cpp`
- `commands/control_input_msgs/msg/Inputs.msg`
- `commands/joystick_input/launch/joystick.launch.py`

#### Robot Model and ros2_control Boundary

Each supported robot is a package containing URDF/Xacro, transmissions, Gazebo integration, and controller parameters. The description is the contract binding controller joint/foot assumptions to simulation or hardware interfaces. Go2 is the primary documented deployment target:
- `descriptions/unitree/go2_description/xacro/robot.xacro`
- `descriptions/unitree/go2_description/xacro/ros2_control.xacro`
- `descriptions/unitree/go2_description/config/robot_control.yaml`

Equivalent model packages cover Unitree, Deep Robotics, Xiaomi/Magiclab, and ANYmal variants.

#### Hardware and Simulation Adapters

ros2_control controllers operate against hardware-system plugins rather than simulator- or device-specific APIs. Gazebo Harmonic uses a custom GZ system/plugin; real Unitree control uses Unitree SDK2 with its DDS/network stack:
- `hardwares/gz_quadruped_hardware/src/gz_system.cpp`
- `hardwares/gz_quadruped_hardware/src/gz_quadruped_plugin.cpp`
- `hardwares/hardware_unitree_sdk2/src/HardwareUnitree.cpp`

MuJoCo support is launched through controller packages and depends on the external `unitree_mujoco` environment. The README identifies an RMW compatibility boundary between CycloneDDS and `unitree_sdk2`.

#### Controller Families

The controller packages are alternative ros2_control execution cores, each translating state and command inputs into joint commands:
- Unitree Guide FSM locomotion: `controllers/unitree_guide_controller/src/UnitreeGuideController.cpp`, `controllers/unitree_guide_controller/src/FSM/StateTrotting.cpp`
- OCS2 MPC locomotion: `controllers/ocs2_quadruped_controller/src/Ocs2QuadrupedController.cpp`, `controllers/ocs2_quadruped_controller/src/FSM/StateOCS2.cpp`
- RL inference locomotion: `controllers/rl_quadruped_controller/src/RlQuadrupedController.cpp`, `controllers/rl_quadruped_controller/src/FSM/StateRL.cpp`
- Direct leg PD control: `controllers/leg_pd_controller/src/LegPdController.cpp`

Shared FSM interfaces and safe stand/passive states live in `libraries/controller_common/include/controller_common/FSM/`.

#### Locomotion Data Flow

Command nodes publish `Inputs`; selected controllers consume commands alongside ros2_control joint/IMU/contact state. The Unitree Guide path estimates state, selects FSM behavior, generates gait phase and foot targets, solves balance control, then emits leg commands. Its key stages are:
- `controllers/unitree_guide_controller/src/control/Estimator.cpp`
- `controllers/unitree_guide_controller/src/gait/GaitGenerator.cpp`
- `controllers/unitree_guide_controller/src/control/BalanceCtrl.cpp`

The RL path buffers filtered observations and evaluates packaged PyTorch policies associated with robot descriptions, e.g. `descriptions/unitree/go2_description/config/legged_gym/policy.pt`.

#### OCS2 Planning, Constraints, and Perception

OCS2 is the advanced planning/control pipeline: target and gait managers establish references; a legged model interface constructs MPC costs and constraints; WBC converts planned motion into executable joint-level commands. Safety and perceptive terrain extensions are explicit layers:
- `controllers/ocs2_quadruped_controller/src/control/TargetManager.cpp`
- `controllers/ocs2_quadruped_controller/src/interface/LeggedInterface.cpp`
- `controllers/ocs2_quadruped_controller/src/wbc/HierarchicalWbc.cpp`

Perceptive locomotion consumes planar terrain/elevation data, chooses convex foothold regions, and applies foot-placement/collision constraints. Gazebo playground provides worlds, camera/lidar models, and Cartographer or FAST-LIO launch/configuration:
- `controllers/ocs2_quadruped_controller/src/perceptive/synchronize/PlanarTerrainReceiver.cpp`
- `libraries/gz_quadruped_playground/launch/slam/fast_lio.launch.py`
- `libraries/gz_quadruped_playground/worlds/warehouse.sdf`

Main entry points: [`commands/control_input_msgs/msg/Inputs.msg`](https://github.com/legubiao/quadruped_ros2_control/blob/main/commands/control_input_msgs/msg/Inputs.msg) (Inputs), [`controllers/unitree_guide_controller/src/UnitreeGuideController.cpp`](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/unitree_guide_controller/src/UnitreeGuideController.cpp) (Unitree Guide FSM), [`controllers/ocs2_quadruped_controller/src/Ocs2QuadrupedController.cpp`](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/ocs2_quadruped_controller/src/Ocs2QuadrupedController.cpp) (OCS2 MPC controller), [`controllers/rl_quadruped_controller/src/RlQuadrupedController.cpp`](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/rl_quadruped_controller/src/RlQuadrupedController.cpp) (RL controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Launch & Inputs"]
  node_gazebo_launch["Gazebo launch<br/>ROS launch<br/>[gazebo.launch.py]"]
  node_mujoco_launch["MuJoCo launch<br/>ROS launch<br/>[mujoco.launch.py]"]
  node_ocs2_launch["OCS2 launch<br/>ROS launch<br/>[ocs2.launch.py]"]
  node_keyboard["Keyboard input<br/>command publisher<br/>[KeyboardInput.cpp]"]
  node_joystick["Joystick launch<br/>command publisher<br/>[joystick.launch.py]"]
  node_inputs["Inputs<br/>ROS message<br/>[Inputs.msg]"]
end

subgraph group_model["Robot Contract"]
  node_go2_description["Go2 robot description<br/>URDF/Xacro<br/>[robot.xacro]"]
  node_ros2_control_contract["ros2_control contract<br/>hardware description<br/>[ros2_control.xacro]"]
  node_controller_config["Controller parameters<br/>robot config<br/>[robot_control.yaml]"]
end

subgraph group_controllers["Controller Cores"]
  node_guide_controller["Unitree Guide FSM<br/>locomotion controller"]
  node_guide_pipeline["Guide estimation, gait &amp; balance<br/>control pipeline<br/>[Estimator.cpp]"]
  node_ocs2_controller["OCS2 MPC controller<br/>locomotion controller"]
  node_ocs2_pipeline["OCS2 planning &amp; WBC<br/>MPC pipeline<br/>[TargetManager.cpp]"]
  node_rl_controller["RL controller<br/>locomotion controller"]
  node_rl_policy["Go2 RL policy<br/>PyTorch model<br/>[policy.pt]"]
  node_leg_pd["Leg PD controller<br/>joint controller"]
end

subgraph group_runtime["Execution Backends"]
  node_ros2_control{{"ros2_control manager<br/>control boundary"}}
  node_gz_hardware["Gazebo hardware system<br/>ros2_control plugin<br/>[gz_system.cpp]"]
  node_unitree_hardware["Unitree SDK2 hardware<br/>ros2_control plugin"]
end

subgraph group_perception["Perception"]
  node_terrain_receiver["Planar terrain receiver<br/>terrain input"]
  node_fast_lio["FAST-LIO launch<br/>SLAM pipeline<br/>[fast_lio.launch.py]"]
  node_warehouse["Warehouse world<br/>Gazebo world<br/>[warehouse.sdf]"]
end

node_keyboard -->|"publishes"| node_inputs
node_joystick -->|"publishes"| node_inputs
node_gazebo_launch -->|"loads"| node_go2_description
node_gazebo_launch -->|"starts"| node_guide_controller
node_mujoco_launch -->|"starts"| node_guide_controller
node_ocs2_launch -->|"starts"| node_ocs2_controller
node_ocs2_launch -.->|"optionally starts"| node_fast_lio
node_go2_description -->|"includes"| node_ros2_control_contract
node_controller_config -->|"configures"| node_ros2_control
node_ros2_control_contract -->|"declares interfaces"| node_ros2_control
node_ros2_control -->|"uses"| node_gz_hardware
node_ros2_control -->|"uses"| node_unitree_hardware
node_ros2_control -->|"state / commands"| node_guide_controller
node_ros2_control -->|"state / commands"| node_ocs2_controller
node_ros2_control -->|"state / commands"| node_rl_controller
node_ros2_control -->|"state / commands"| node_leg_pd
node_inputs -->|"commands"| node_guide_controller
node_inputs -->|"commands"| node_ocs2_controller
node_inputs -->|"commands"| node_rl_controller
node_guide_controller -->|"executes"| node_guide_pipeline
node_ocs2_controller -->|"executes"| node_ocs2_pipeline
node_terrain_receiver -->|"terrain constraints"| node_ocs2_pipeline
node_fast_lio -->|"terrain mapping"| node_terrain_receiver
node_warehouse -->|"simulated environment"| node_fast_lio
node_rl_controller -->|"evaluates"| node_rl_policy

click node_gazebo_launch "https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/unitree_guide_controller/launch/gazebo.launch.py"
click node_mujoco_launch "https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/unitree_guide_controller/launch/mujoco.launch.py"
click node_ocs2_launch "https://github.com/legubiao/quadruped_ros2_control/blob/main/libraries/gz_quadruped_playground/launch/ocs2.launch.py"
click node_keyboard "https://github.com/legubiao/quadruped_ros2_control/blob/main/commands/keyboard_input/src/KeyboardInput.cpp"
click node_joystick "https://github.com/legubiao/quadruped_ros2_control/blob/main/commands/joystick_input/launch/joystick.launch.py"
click node_inputs "https://github.com/legubiao/quadruped_ros2_control/blob/main/commands/control_input_msgs/msg/Inputs.msg"
click node_go2_description "https://github.com/legubiao/quadruped_ros2_control/blob/main/descriptions/unitree/go2_description/xacro/robot.xacro"
click node_ros2_control_contract "https://github.com/legubiao/quadruped_ros2_control/blob/main/descriptions/unitree/go2_description/xacro/ros2_control.xacro"
click node_controller_config "https://github.com/legubiao/quadruped_ros2_control/blob/main/descriptions/unitree/go2_description/config/robot_control.yaml"
click node_gz_hardware "https://github.com/legubiao/quadruped_ros2_control/blob/main/hardwares/gz_quadruped_hardware/src/gz_system.cpp"
click node_unitree_hardware "https://github.com/legubiao/quadruped_ros2_control/blob/main/hardwares/hardware_unitree_sdk2/src/HardwareUnitree.cpp"
click node_guide_controller "https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/unitree_guide_controller/src/UnitreeGuideController.cpp"
click node_guide_pipeline "https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/unitree_guide_controller/src/control/Estimator.cpp"
click node_ocs2_controller "https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/ocs2_quadruped_controller/src/Ocs2QuadrupedController.cpp"
click node_ocs2_pipeline "https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/ocs2_quadruped_controller/src/control/TargetManager.cpp"
click node_rl_controller "https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/rl_quadruped_controller/src/RlQuadrupedController.cpp"
click node_rl_policy "https://github.com/legubiao/quadruped_ros2_control/blob/main/descriptions/unitree/go2_description/config/legged_gym/policy.pt"
click node_leg_pd "https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/leg_pd_controller/src/LegPdController.cpp"
click node_terrain_receiver "https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/ocs2_quadruped_controller/src/perceptive/synchronize/PlanarTerrainReceiver.cpp"
click node_fast_lio "https://github.com/legubiao/quadruped_ros2_control/blob/main/libraries/gz_quadruped_playground/launch/slam/fast_lio.launch.py"
click node_warehouse "https://github.com/legubiao/quadruped_ros2_control/blob/main/libraries/gz_quadruped_playground/worlds/warehouse.sdf"

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_gazebo_launch,node_mujoco_launch,node_ocs2_launch,node_keyboard,node_joystick,node_inputs toneBlue
class node_go2_description,node_ros2_control_contract,node_controller_config toneAmber
class node_guide_controller,node_guide_pipeline,node_ocs2_controller,node_ocs2_pipeline,node_rl_controller,node_rl_policy,node_leg_pd toneMint
class node_ros2_control,node_gz_hardware,node_unitree_hardware toneRose
class node_terrain_receiver,node_fast_lio,node_warehouse toneIndigo
```

## Components

### Launch & Inputs

- [Gazebo launch](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/unitree_guide_controller/launch/gazebo.launch.py): ROS launch · Starts the Guide controller simulation stack. · `controllers/unitree_guide_controller/launch/gazebo.launch.py`
- [MuJoCo launch](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/unitree_guide_controller/launch/mujoco.launch.py): ROS launch · Starts controller packages against external unitree_mujoco. · `controllers/unitree_guide_controller/launch/mujoco.launch.py`
- [OCS2 launch](https://github.com/legubiao/quadruped_ros2_control/blob/main/libraries/gz_quadruped_playground/launch/ocs2.launch.py): ROS launch · Starts the OCS2 playground stack. · `libraries/gz_quadruped_playground/launch/ocs2.launch.py`
- [Keyboard input](https://github.com/legubiao/quadruped_ros2_control/blob/main/commands/keyboard_input/src/KeyboardInput.cpp): command publisher · `commands/keyboard_input/src/KeyboardInput.cpp`
- [Joystick launch](https://github.com/legubiao/quadruped_ros2_control/blob/main/commands/joystick_input/launch/joystick.launch.py): command publisher · `commands/joystick_input/launch/joystick.launch.py`
- [Inputs](https://github.com/legubiao/quadruped_ros2_control/blob/main/commands/control_input_msgs/msg/Inputs.msg): ROS message · Shared locomotion command message. · `commands/control_input_msgs/msg/Inputs.msg`

### Robot Contract

- [Go2 robot description](https://github.com/legubiao/quadruped_ros2_control/blob/main/descriptions/unitree/go2_description/xacro/robot.xacro): URDF/Xacro · Primary robot model and controller joint contract. · `descriptions/unitree/go2_description/xacro/robot.xacro`
- [ros2_control contract](https://github.com/legubiao/quadruped_ros2_control/blob/main/descriptions/unitree/go2_description/xacro/ros2_control.xacro): hardware description · Declares the hardware-system interface for the model. · `descriptions/unitree/go2_description/xacro/ros2_control.xacro`
- [Controller parameters](https://github.com/legubiao/quadruped_ros2_control/blob/main/descriptions/unitree/go2_description/config/robot_control.yaml): robot config · `descriptions/unitree/go2_description/config/robot_control.yaml`

### Controller Cores

- [Unitree Guide FSM](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/unitree_guide_controller/src/UnitreeGuideController.cpp): locomotion controller · Classical FSM locomotion execution core. · `controllers/unitree_guide_controller/src/UnitreeGuideController.cpp`
- [Guide estimation, gait & balance](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/unitree_guide_controller/src/control/Estimator.cpp): control pipeline · Estimates state, generates foot targets, and computes balanced leg commands. · `controllers/unitree_guide_controller/src/control/Estimator.cpp`
- [OCS2 MPC controller](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/ocs2_quadruped_controller/src/Ocs2QuadrupedController.cpp): locomotion controller · MPC/WBC locomotion execution core. · `controllers/ocs2_quadruped_controller/src/Ocs2QuadrupedController.cpp`
- [OCS2 planning & WBC](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/ocs2_quadruped_controller/src/control/TargetManager.cpp): MPC pipeline · Builds references, constraints, MPC costs, and executable whole-body commands. · `controllers/ocs2_quadruped_controller/src/control/TargetManager.cpp`
- [RL controller](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/rl_quadruped_controller/src/RlQuadrupedController.cpp): locomotion controller · Runs filtered observations through a packaged policy. · `controllers/rl_quadruped_controller/src/RlQuadrupedController.cpp`
- [Go2 RL policy](https://github.com/legubiao/quadruped_ros2_control/blob/main/descriptions/unitree/go2_description/config/legged_gym/policy.pt): PyTorch model · `descriptions/unitree/go2_description/config/legged_gym/policy.pt`
- [Leg PD controller](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/leg_pd_controller/src/LegPdController.cpp): joint controller · Direct leg-level alternative controller. · `controllers/leg_pd_controller/src/LegPdController.cpp`

### Execution Backends

- **ros2_control manager**: control boundary · Routes controller state and joint commands through hardware-system plugins.
- [Gazebo hardware system](https://github.com/legubiao/quadruped_ros2_control/blob/main/hardwares/gz_quadruped_hardware/src/gz_system.cpp): ros2_control plugin · `hardwares/gz_quadruped_hardware/src/gz_system.cpp`
- [Unitree SDK2 hardware](https://github.com/legubiao/quadruped_ros2_control/blob/main/hardwares/hardware_unitree_sdk2/src/HardwareUnitree.cpp): ros2_control plugin · Connects real hardware through SDK2 DDS/network transport. · `hardwares/hardware_unitree_sdk2/src/HardwareUnitree.cpp`

### Perception

- [Planar terrain receiver](https://github.com/legubiao/quadruped_ros2_control/blob/main/controllers/ocs2_quadruped_controller/src/perceptive/synchronize/PlanarTerrainReceiver.cpp): terrain input · Supplies terrain/elevation data to perceptive locomotion. · `controllers/ocs2_quadruped_controller/src/perceptive/synchronize/PlanarTerrainReceiver.cpp`
- [FAST-LIO launch](https://github.com/legubiao/quadruped_ros2_control/blob/main/libraries/gz_quadruped_playground/launch/slam/fast_lio.launch.py): SLAM pipeline · `libraries/gz_quadruped_playground/launch/slam/fast_lio.launch.py`
- [Warehouse world](https://github.com/legubiao/quadruped_ros2_control/blob/main/libraries/gz_quadruped_playground/worlds/warehouse.sdf): Gazebo world · `libraries/gz_quadruped_playground/worlds/warehouse.sdf`

## Connections

- Keyboard input → Inputs: publishes
- Joystick launch → Inputs: publishes
- Gazebo launch → Go2 robot description: loads
- Gazebo launch → Unitree Guide FSM: starts
- MuJoCo launch → Unitree Guide FSM: starts
- OCS2 launch → OCS2 MPC controller: starts
- OCS2 launch → FAST-LIO launch: optionally starts
- Go2 robot description → ros2_control contract: includes
- Controller parameters → ros2_control manager: configures
- ros2_control contract → ros2_control manager: declares interfaces
- ros2_control manager → Gazebo hardware system: uses
- ros2_control manager → Unitree SDK2 hardware: uses
- ros2_control manager → Unitree Guide FSM: state / commands
- ros2_control manager → OCS2 MPC controller: state / commands
- ros2_control manager → RL controller: state / commands
- ros2_control manager → Leg PD controller: state / commands
- Inputs → Unitree Guide FSM: commands
- Inputs → OCS2 MPC controller: commands
- Inputs → RL controller: commands
- Unitree Guide FSM → Guide estimation, gait & balance: executes
- OCS2 MPC controller → OCS2 planning & WBC: executes
- Planar terrain receiver → OCS2 planning & WBC: terrain constraints
- FAST-LIO launch → Planar terrain receiver: terrain mapping
- Warehouse world → FAST-LIO launch: simulated environment
- RL controller → Go2 RL policy: evaluates