# jlancha/convex-mpc-quad-sdk architecture

> Architecture diagram of the GitHub repository jlancha/convex-mpc-quad-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jlancha/convex-mpc-quad-sdk
- Repository: https://github.com/jlancha/convex-mpc-quad-sdk

## Overview

##### Project Type and Purpose
- This is a ROS-based, full-stack robotics framework (“Quad-SDK”) for agile quadrupedal locomotion in simulation and on hardware.
- It integrates planning (global & local), model-predictive control (linear MPC via QP), state estimation, communication, drivers, simulation (Gazebo), visualization (RViz), logging, and developer tools.

##### Top-Level Architecture Components
a. ROS Middleware (core “bus”)
- ROS Master / Parameter Server
- Topic, Service, and Action interfaces defined by **quad_msgs**
b. Perception & Estimation
- **mocap_optitrack**: Motion capture data → robot pose
- **robot_driver/estimators**: IMU, encoders → state estimator (EKF, complementary filter)
- **quad_utils/terrain_map_publisher**: Depth/mesh → terrain map
c. Planning
- **global_body_planner**: Fast global motion planner → `/robot_x/global_plan`
- **local_planner**: Footstep sequence planner → `/robot_x/foot_plan`
d. Control
- **nmpc_controller / lmpc_controller**: Generate optimized gait force/foot trajectories via OSQP-Eigen QP → leg commands
- **robot_driver/controllers**: PID, inverse dynamics → motor torque commands
e. Communication & Teleoperation
- **quad_utils/remote_heartbeat**: Heartbeat, remote supervision
- **teleop_twist_keyboard / teleop_twist_joy**: User cmd_vel → twist commands
f. Simulation & Hardware Interface
- **quad_simulator**: Gazebo URDF/SDF models + plugins (contact, estimator, controller)
- **robot_driver/hardware_interfaces/spirit_interface**: Real hardware abstraction
g. Utilities & Logging
- **quad_logger**: ROS bag reader, plot scripts
- **quad_utils/rviz_interface**, **trajectory_publisher**, **mesh_to_grid_map**, etc.
h. Examples & Third-party
- **casadi_examples**, **communication_test**, **external/** (OSQP, RBDL-orb, grid_map_pcl, mavlink)

##### Component Interactions & Data Flows
- Sensor plugins (Gazebo) & mocap publish raw sensor topics → Estimator nodes → publish `/robot_x/body_state`
- Estimation and user teleop feed into Planners:
Global Planner consumes `/body_state` → publishes global path
Local Planner consumes global path + terrain map → publishes footstep plan
- Controller stack:
MPC (nmpc/lmpc) consumes `/body_state`, footstep plan → computes leg force/foot trajectories → publishes `LegCommandArray`
Motor controllers subscribe to LegCommand → compute low-level torques → publish to hardware interface or Gazebo plugin
- Utils nodes subscribe to topics for visualization (RViz), terrain mapping, logging.
- All inter-node comms via ROS topics/services.

##### Architectural Patterns & Principles
- **Modular ROS packages** for separation of concerns
- **Layered pipeline**: Sensing → Estimation → Planning → Control → Actuation
- **Plug-and-play**: Swap planners or controllers by remapping ROS topics
- **External solver integration**: OSQP via OSQP-Eigen for QP in MPC
- **Simulation-hardware parity** via common ROS interfaces

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% ROS Middleware
    subgraph "ROS Middleware" 
        style ROSMaster fill:#ffffff,stroke:#000000
        ROSMaster["ROS Master / Parameter Server"]:::middleware
        quad_msgs["quad_msgs (Message Definitions)"]:::middleware
    end

    %% Perception & Estimation
    subgraph "Perception & Estimation" 
        style Perception fill:#ccffcc,stroke:#333333
        mocap["mocap_optitrack"]:::perception
        est["robot_driver/estimators (EKF & complementary)"]:::perception
        terrain["terrain_map_publisher"]:::perception
    end

    %% Planning
    subgraph "Planning" 
        style Planning fill:#ccccff,stroke:#333333
        global_planner["global_body_planner"]:::planning
        local_planner["local_planner"]:::planning
    end

    %% Control
    subgraph "Control" 
        style Control fill:#9999ff,stroke:#333333
        nmpc["nmpc_controller"]:::control
        lmpc["lmpc_controller"]:::control
        lowlevel["robot_driver/controllers (PID & inv. dyn)"]:::control
    end

    %% Actuation / Hardware Interface
    subgraph "Actuation / Hardware Interface" 
        style Actuation fill:#ffcc99,stroke:#333333
        quad_sim["quad_simulator (Gazebo models & plugins)"]:::hardware
        spirit["spirit_interface"]:::hardware
    end

    %% Utilities & Teleop
    subgraph "Utilities & Teleop" 
        style Utils fill:#dddddd,stroke:#333333
        heartbeat["remote_heartbeat"]:::utils
        rviz_if["rviz_interface"]:::utils
        traj_pub["trajectory_publisher"]:::utils
        mesh2grid["mesh_to_grid_map_converter"]:::utils
        logger["quad_logger"]:::utils
        teleok["teleop_twist_keyboard"]:::utils
        teleoj["teleop_twist_joy"]:::utils
    end

    %% Examples & Third-Party
    subgraph "Examples & Third-Party" 
        style Examples fill:#ffffff,stroke:#333333
        casadi["casadi_examples"]:::examples
        commtest["communication_test"]:::examples
        ext1["grid_map_pcl"]:::external
        ext2["ipopt"]:::external
        ext3["rbdl-orb"]:::external
        ext4["mavlink"]:::external
    end

    %% Connections
    ROSMaster --> quad_msgs
    quad_msgs --> mocap
    quad_msgs --> est
    quad_msgs --> terrain
    mocap -->|"/mocap/data"| est
    est -->|"body_state"| global_planner
    est -->|"body_state"| nmpc
    terrain -->|"terrain_map"| local_planner
    global_planner -->|"global_plan"| local_planner
    local_planner -->|"foot_plan"| nmpc
    nmpc -->|"LegCommandArray"| lowlevel
    lmpc -->|"LegCommandArray"| lowlevel
    lowlevel --> quad_sim
    lowlevel --> spirit
    heartbeat --> ROSMaster
    teleok -->|"cmd_vel"| local_planner
    teleoj -->|"cmd_vel"| local_planner
    quad_sim --> est
    spirit --> est
    rviz_if --> global_planner
    rviz_if --> local_planner
    mesh2grid --> local_planner
    traj_pub --> local_planner
    logger --> est
    logger --> lowlevel
    casadi -.-> nmpc
    ext1 -.-> mesh2grid
    ext2 -.-> nmpc
    ext3 -.-> lmpc
    ext4 -.-> spirit

    %% Click Events
    click quad_msgs "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/quad_msgs/"
    click mocap "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/external/mocap_optitrack/"
    click est "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/robot_driver/include/robot_driver/estimators/"
    click est "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/robot_driver/src/estimators/"
    click terrain "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/quad_utils/src/terrain_map_publisher/"
    click terrain "https://github.com/jlancha/convex-mpc-quad-sdk/blob/mpc-custom/quad_utils/include/quad_utils/terrain_map_publisher.h"
    click global_planner "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/global_body_planner/"
    click local_planner "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/local_planner/"
    click nmpc "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/nmpc_controller/"
    click lmpc "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/lmpc_controller/"
    click lowlevel "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/robot_driver/src/controllers/"
    click lowlevel "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/robot_driver/include/robot_driver/controllers/"
    click heartbeat "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/quad_utils/src/remote_heartbeat/"
    click heartbeat "https://github.com/jlancha/convex-mpc-quad-sdk/blob/mpc-custom/quad_utils/include/quad_utils/remote_heartbeat.h"
    click teleok "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/external/teleop_twist_keyboard/"
    click teleoj "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/external/teleop_twist_joy/"
    click quad_sim "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/quad_simulator/"
    click spirit "https://github.com/jlancha/convex-mpc-quad-sdk/blob/mpc-custom/robot_driver/include/robot_driver/hardware_interfaces/spirit_interface.h"
    click spirit "https://github.com/jlancha/convex-mpc-quad-sdk/blob/mpc-custom/robot_driver/src/hardware_interfaces/spirit_interface.cpp"
    click logger "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/quad_logger/"
    click rviz_if "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/quad_utils/src/rviz_interface/"
    click rviz_if "https://github.com/jlancha/convex-mpc-quad-sdk/blob/mpc-custom/quad_utils/include/quad_utils/rviz_interface.h"
    click traj_pub "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/quad_utils/src/trajectory_publisher/"
    click traj_pub "https://github.com/jlancha/convex-mpc-quad-sdk/blob/mpc-custom/quad_utils/include/quad_utils/trajectory_publisher.h"
    click mesh2grid "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/quad_utils/src/mesh_to_grid_map_converter/"
    click mesh2grid "https://github.com/jlancha/convex-mpc-quad-sdk/blob/mpc-custom/quad_utils/include/quad_utils/mesh_to_grid_map_converter.hpp"
    click casadi "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/casadi_examples/"
    click commtest "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/communication_test/"
    click ext1 "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/external/grid_map_pcl/"
    click ext2 "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/external/ipopt/"
    click ext3 "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/external/rbdl-orb/"
    click ext4 "https://github.com/jlancha/convex-mpc-quad-sdk/tree/mpc-custom/external/mavlink/"

    %% Styles
    classDef middleware fill:#eeeeff,stroke:#4444ff
    classDef perception fill:#ccffcc,stroke:#339933
    classDef planning fill:#ccccff,stroke:#3333cc
    classDef control fill:#9999ff,stroke:#333399
    classDef hardware fill:#ffcc99,stroke:#cc6600
    classDef utils fill:#dddddd,stroke:#666666
    classDef examples fill:#ffffff,stroke:#999999
    classDef external stroke-dasharray: 5 5,stroke:#ff0000,fill:none
```
