# qiayuanl/legged_control architecture

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

- Interactive diagram: https://gitdiagram.com/qiayuanl/legged_control
- Repository: https://github.com/qiayuanl/legged_control

## Overview

##### Project Type and Purpose
- This is a full-stack ROS-based control framework (“legged_control”) for quadrupedal robots implementing Nonlinear Model Predictive Control (NMPC), Whole-Body Control (WBC), and state estimation.
- It provides:
- Core control algorithms (NMPC via OCS2, WBC via QP)
- A state estimator (linear Kalman filter)
- ROS controller plugins and hardware interfaces for both Gazebo simulation and real Unitree hardware
- Example URDFs, launch files, and configuration for A1, AlienGo, GO1

##### File Structure Analysis
Top-level packages (all built with catkin in a workspace):
- legged_common: shared interfaces (joint, contact sensor) and URDF/URDF‐generation scripts
- legged_interface: formulates NMPC problem, constraints & cost definitions (wrapping OCS2)
- legged_wbc: hierarchical whole-body QP solver (defines tasks, priorities)
- legged_estimation: state estimation (Kalman filter)
- legged_controllers: ROS controller plugins (switchable NMPC+WBC controller), gait/trajectory publisher, safety checks, controller configurations
- legged_hw: abstract hardware interface base (LeggedHW)
- legged_gazebo: Gazebo hardware simulator plugin (LeggedHWSim)
- legged_examples:
- legged_unitree_description: URDF, meshes, xacro, launch files for simulation
- legged_unitree_hw: UnitreeHW implementation for real robot, SDK wrappers, config & launch
- qpoases_catkin: QPOASES solver for QP in catkin

a. Sensors & Inputs
- IMU, joint_state publishers (from real robot or Gazebo)
- User commands: geometry_msgs/Twist or move_base goals
b. State Estimator (legged_estimation)
- Subscribes to IMU & joint_states
- Publishes filtered base pose & velocity, joint states
c. Trajectory & Gait Publisher (legged_controllers/TargetTrajectoriesPublisher)
- Subscribes to user commands
- Publishes desired COM trajectory & foot trajectories + gait phase
d. NMPC Node (legged_interface + OCS2)
- Subscribes to state_estimate, desired trajectories
- Solves optimal control problem via OCS2 backend
- Publishes optimal state & contact force trajectories
e. WBC Node (legged_wbc)
- Subscribes to NMPC outputs & current state
- Solves hierarchical QP for joint accelerations & torques
- Publishes torque feedforward + PD setpoints
f. ros_control Controller Manager (legged_controllers plugins)
- Loads “legged_controller” plugin
- Forwards torque + PD commands to hardware interface
g. Hardware Interface Layer
- Simulation: legged_gazebo’s LeggedHWSim plugin
- Real robot: legged_unitree_hw’s UnitreeHW plugin
- Implements read() (sensor feedback) and write() (send torques/commands)
h. Dependencies
- OCS2 for NMPC
- QPOASES / HPIPM for QP solving
- pinocchio, hpp-fcl for kinematics/collision

##### Relationships & Data Flow
- Sensors → State Estimator → {NMPC, WBC}
- User Cmds → Trajectory Publisher → NMPC
- NMPC → WBC → ros_control → Hardware Interface → Robot/SIM
- Hardware Interface → Sensors → State Estimator (loop)

##### Architectural Patterns & Principles
- Modular ROS nodes with clear separation of concerns
- Catkin multi-package workspace: each major function in its own package
- Dependency inversion: abstract LeggedHW vs. concrete simulation/real plugins
- Hierarchical optimization: OCS2 for long horizon, WBC for instantaneous control
- Use of established frameworks (ros_control, OCS2, pinocchio)

##### Detail Level
- Both simulation and real-robot branches
- Loops (feedback loops from hardware to estimator to controller)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Inputs
    Sensors["Sensors: IMU & joint_states"]:::input
    UserCmd["User Commands\n(cmd_vel, move_base)"]:::input

    %% Processing Nodes
    Estimator["State Estimator\n(legged_estimation)"]:::estimation
    Traj["Trajectory & Gait Publisher\n(legged_controllers)"]:::planning
    NMPC["NMPC Node\n(legged_interface + OCS2)"]:::planning
    WBC["WBC Node\n(legged_wbc)"]:::control
    CtrlMgr["ros_control Controller Manager\n(plugin: legged_controller)"]:::control

    %% Hardware Layer
    HWBase["Abstract Hardware Interface\n(legged_hw)"]:::hardware
    Sim["Gazebo HW Sim Plugin\n(legged_gazebo)"]:::hardware
    Real["Unitree HW Plugin\n(legged_unitree_hw)"]:::hardware
    Desc["URDF & Description\n(legged_unitree_description)"]:::hardware
    Robot["Robot / Gazebo SIM"]:::external

    %% External Dependencies
    OCS2["OCS2\n(External)"]:::cloud
    QPOASES["QPOASES\n(qpoases_catkin)"]:::cloud
    Pinocchio["pinocchio, hpp-fcl"]:::cloud
    Common["Shared Interfaces & URDF Gen\n(legged_common)"]:::external

    %% Data Flow
    Sensors -->|"IMU & joint_states"| Estimator
    UserCmd -->|"cmd_vel / goals"| Traj
    Estimator -->|"state_estimate"| NMPC
    Traj -->|"desired_trajectories"| NMPC
    NMPC -->|"optimal_forces"| WBC
    Estimator -->|"current_state"| WBC
    WBC -->|"joint_commands"| CtrlMgr
    CtrlMgr -->|"read()/write()"| HWBase
    HWBase -->|"interface"| Sim
    HWBase -->|"interface"| Real
    Sim -->|"simulated_feedback"| Robot
    Real -->|"hardware_feedback"| Robot
    Robot -->|"IMU & joint_states"| Sensors

    %% Dependencies
    OCS2 --> NMPC
    QPOASES --> WBC
    Pinocchio --> NMPC
    Pinocchio --> WBC
    Common --> Sim
    Common --> Real

    %% Click Events
    click Estimator "https://github.com/qiayuanl/legged_control/tree/master/legged_estimation/"
    click Traj "https://github.com/qiayuanl/legged_control/tree/master/legged_controllers/"
    click NMPC "https://github.com/qiayuanl/legged_control/tree/master/legged_interface/"
    click WBC "https://github.com/qiayuanl/legged_control/tree/master/legged_wbc/"
    click CtrlMgr "https://github.com/qiayuanl/legged_control/tree/master/legged_controllers/"
    click HWBase "https://github.com/qiayuanl/legged_control/tree/master/legged_hw/"
    click Sim "https://github.com/qiayuanl/legged_control/tree/master/legged_gazebo/"
    click Real "https://github.com/qiayuanl/legged_control/tree/master/legged_examples/legged_unitree/legged_unitree_hw/"
    click Desc "https://github.com/qiayuanl/legged_control/tree/master/legged_examples/legged_unitree/legged_unitree_description/"
    click Common "https://github.com/qiayuanl/legged_control/tree/master/legged_common/"
    click QPOASES "https://github.com/qiayuanl/legged_control/tree/master/qpoases_catkin/"

    %% Styles
    classDef input fill:#a2d5f2,stroke:#333,stroke-width:1px
    classDef estimation fill:#b3e6b3,stroke:#333,stroke-width:1px
    classDef planning fill:#add8e6,stroke:#333,stroke-width:1px
    classDef control fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef hardware fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef cloud fill:#e0e0e0,stroke-dasharray:5 5
    classDef external fill:#f2e6ff,stroke:#333,stroke-width:1px
```
