# mit-biomimetics/cheetah-software architecture

> Architecture diagram of the GitHub repository mit-biomimetics/cheetah-software, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mit-biomimetics/cheetah-software
- Repository: https://github.com/mit-biomimetics/cheetah-software

## Overview

##### Project Type & Purpose
- This is a robotics control and simulation framework for MIT’s Cheetah‐3 and Mini Cheetah robots.
- It consists of:
- A shared “common” library (dynamics, state estimation, controllers, utilities)
- A real–hardware robot executable (hardware interfaces, real‐time loops)
- A Qt-based simulator executable (visualization, simulator loop)
- Multiple user‐supplied controller executables (e.g. JPos, MIT_Controller, etc.)
- LCM‐based messaging for inter‐process communication
- Embedded third-party libraries (solvers, EtherCAT stack, YAML parser, IMU drivers)

##### File Structure
- Top‐level directories:
- cmake/ & CMakeLists.txt – build configuration
- common/ – static library containing Dynamics, Collision, Controllers, Math, Utilities, simulation helpers, + unit tests
- robot/ – RobotRunner, HardwareBridge (EtherCAT, SPI, serial, VectorNav), control loops, real‐time support
- sim/ – Simulation engine, Qt UI panels, Graphics3D, RobotInterface, joystick support
- user/ – Example controllers, each in its own subfolder, linking common + robot logic into standalone executables
- lcm-types/ – .lcm message definitions (robot state, commands, visualization data)
- third-party/ – Bundled libraries (OSQP, qpOASES, SOEM, ParamHandler, inih, LORD IMU, vectornav)
- scripts/ – Helper scripts for building, LCM type generation, network setup, logging, deployment
- Each of common/robot/sim/user targets links against common/libbiomimetics.a, LCM, Eigen, Qt (sim_only), and the third-party libs it needs.

##### Pull Insights from README
- common/ produces a single static library `libbiomimetics.a` with all simulation, dynamics, and control-code.
- robot/ and sim/ are separate executables; sim/ is the only one requiring Qt5.
- user/ controllers are launched either in sim mode (`s`) or real‐robot mode (`r`), passing in robot type (3 or m).
- Communication between robot, sim, and user controllers is handled by LCM pub/sub.

##### Capturing Essential Detail
- Don’t hesitate to break out subcomponents for clarity (e.g., within Common Library: DynamicsSimulator, GaitScheduler, FootSwingTrajectory, ContactEstimator).
- Build-time relationships if relevant (e.g., CMake target dependencies), but focus primarily on runtime architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Shared Libraries
    subgraph "Shared Libraries"
        direction TB
        CommonLib["Common Library"]:::shared
        ThirdParty["Third-Party Libraries"]:::shared
    end

    %% Middleware
    LCM["LCM Message Bus"]:::middleware

    %% Processes
    subgraph "Real-Time Domain"
        direction TB
        Robot["Robot Process"]:::process
        RobotDeps1 -. links against .-> CommonLib
        RobotDeps2 -. links against .-> ThirdParty
    end

    subgraph "Simulation Domain"
        direction TB
        Simulator["Simulator Process"]:::process
        SimulatorDeps1 -. links against .-> CommonLib
        SimulatorDeps2 -. links against .-> ThirdParty
    end

    subgraph "User Controllers"
        direction TB
        UC1["Example_Leg_InvDyn Controller"]:::process
        UC2["JPos Controller"]:::process
        UC3["MIT Controller"]:::process
        UC4["MiniCheetahSpi Controller"]:::process
        UC1Deps -. links against .-> CommonLib
        UC1Deps -. links against .-> ThirdParty
        UC2Deps -. links against .-> CommonLib
        UC2Deps -. links against .-> ThirdParty
        UC3Deps -. links against .-> CommonLib
        UC3Deps -. links against .-> ThirdParty
        UC4Deps -. links against .-> CommonLib
        UC4Deps -. links against .-> ThirdParty
    end

    %% Data Flows
    UC1 -->|"leg_control_command_lcmt"| LCM
    UC2 -->|"jpos_command_lcmt"| LCM
    UC3 -->|"mit_command_lcmt"| LCM
    UC4 -->|"spi_command_lcmt"| LCM

    LCM -->|"state_estimate_lcmt"| UC1
    LCM -->|"state_estimate_lcmt"| UC2
    LCM -->|"state_estimate_lcmt"| UC3
    LCM -->|"state_estimate_lcmt"| UC4

    LCM -->|"control_command_lcmt"| Robot
    Robot -->|"sensor_data_lcmt"| LCM
    Simulator -->|"sim_sensor_data_lcmt"| LCM
    LCM -->|"sim_feedback_lcmt"| UC1
    LCM -->|"sim_feedback_lcmt"| UC2
    LCM -->|"sim_feedback_lcmt"| UC3
    LCM -->|"sim_feedback_lcmt"| UC4

    %% External & Tools
    subgraph "Build & Config"
        direction TB
        CMake["CMake & Build Scripts"]:::external
        Scripts["Helper Scripts"]:::external
        Config["Configuration Files"]:::external
        Resources["3D Resources"]:::external
    end

    CMake --> CommonLib
    CMake --> Robot
    CMake --> Simulator
    CMake --> UC1
    CMake --> UC2
    CMake --> UC3
    CMake --> UC4

    Scripts --> CMake
    Config --> Robot
    Config --> Simulator
    Resources --> Simulator

    %% Click Events
    click CommonLib "https://github.com/mit-biomimetics/cheetah-software/tree/master/common/"
    click ThirdParty "https://github.com/mit-biomimetics/cheetah-software/tree/master/third-party/"
    click Robot "https://github.com/mit-biomimetics/cheetah-software/tree/master/robot/"
    click Simulator "https://github.com/mit-biomimetics/cheetah-software/tree/master/sim/"
    click UC1 "https://github.com/mit-biomimetics/cheetah-software/tree/master/user/Example_Leg_InvDyn/"
    click UC2 "https://github.com/mit-biomimetics/cheetah-software/tree/master/user/JPos_Controller/"
    click UC3 "https://github.com/mit-biomimetics/cheetah-software/tree/master/user/MIT_Controller/"
    click UC4 "https://github.com/mit-biomimetics/cheetah-software/tree/master/user/MiniCheetahSpi_Controller/"
    click LCM "https://github.com/mit-biomimetics/cheetah-software/tree/master/lcm-types/"
    click CMake "https://github.com/mit-biomimetics/cheetah-software/tree/master/cmake/"
    click Scripts "https://github.com/mit-biomimetics/cheetah-software/tree/master/scripts/"
    click Config "https://github.com/mit-biomimetics/cheetah-software/tree/master/config/"
    click Resources "https://github.com/mit-biomimetics/cheetah-software/tree/master/resources/"

    %% Styles
    classDef shared fill:#cce5ff,stroke:#004085,color:#004085;
    classDef process fill:#d4edda,stroke:#155724,color:#155724;
    classDef middleware fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
