# mpc-berkeley/racing-lmpc-ros2 architecture

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

- Interactive diagram: https://gitdiagram.com/mpc-berkeley/racing-lmpc-ros2
- Repository: https://github.com/mpc-berkeley/racing-lmpc-ros2

## Overview

##### Project Type and Purpose
- This is a full-stack ROS2 application in C++ implementing Learning Model Predictive Control (LMPC) for autonomous racing.
- It comprises ROS2 packages for simulation, state estimation, various controllers (LMPC, MPC, LQR, vanilla), vehicle dynamics models, common message definitions, and utility tools.
- The system runs under ROS2 Humble, uses CasADi for optimization, and integrates with Foxglove Studio (or RViz2) for visualization.

##### File-Structure Analysis
- Top-level “src” contains multiple ROS2 packages, each with its own `package.xml` and `CMakeLists.txt`.
- `src/common`: Shared custom message definitions (`lmpc_msgs` and `mpclab_msgs`).
- `src/vehicle_dynamics_models`: Several vehicle model implementations (kinematic bicycle, single/double-track, etc.) and a factory to choose at runtime.
- `src/state_estimators/ekf_state_estimator`: Implements an EKF node.
- `src/mpc`: Core optimization packages: `racing_lqr`, `racing_mpc`.
- `src/controllers`: High-level controllers wrapping the MPC solvers into ROS2 nodes (e.g., `racing_lmpc`, `vanilla_controller`).
- `src/simulation/racing_simulator`: Simulator node publishing synthetic sensor data and accepting control inputs.
- `src/tools`: Helper libraries (transforms, profiling, logging, parameter helpers).
- `src/launch/racing_lmpc_launch`: ROS2 launch scripts tying together simulator, controller, and Foxglove Bridge.
- Configuration (`param`) and launch (`launch/*.launch.py`) subdirectories provide YAML parameter sets and launch descriptions.

##### README Insights
- The “Run LMPC” instructions show the runtime pipeline:
simulator node → controller node → Foxglove Bridge → visualization.
- Emphasizes CasADi dependency for on-the-fly optimization.
- Lists required ROS2 topics (telemetry, trajectory commands) and launch sequences.

##### Core Components
a. ROS2 Middleware (DDS) – backbone for pub/sub
b. Common Messages
- lmpc_msgs: telemetry ∔ trajectory_cmd
- mpclab_msgs: raw sensor ∔ actuation/status
c. Simulator Node
- Publishes simulated sensor data to topics under `mpclab_msgs`
- Subscribes to control commands (`TrajectoryCommand.msg`)
d. State Estimator Node (EKF)
- Subscribes: raw sensors → publishes estimated state
e. Vehicle Dynamics Model Library
- Underlies both simulator and controllers; loaded via a factory
f. Controller Nodes
- LMPC (`racing_lmpc_node`)
- Classic MPC (`racing_mpc_node`)
- LQR (`racing_lqr` library)
- Vanilla PID-style controller
- Each subscribes: estimated state + reference trajectory, publishes: control trajectory
g. MPC Solver Backend
- CasADi JIT + Ipopt for nonlinear optimization
h. Tools & Utilities
- Parameter loaders, logging, transform helpers
i. Launch Manager
- ROS2 launch files orchestrating simulator, controllers, Foxglove Bridge
j. Foxglove Bridge & Studio
- Bridge node converts ROS2 topics → WebSocket → Foxglove Studio UI

##### Relationships and Data Flow
- Simulator → publishes sensor topics → EKF → publishes `/vehicle_state`
- Reference trajectory (from simulator or prerecorded maps) → Controller
- Controller → computes optimal trajectory/actuation → publishes `/trajectory_command`
- Simulator subscribes `/trajectory_command`, advances simulation
- Foxglove Bridge subscribes key topics (telemetry, state, control), streams to UI
- All nodes communicate via ROS2 DDS (pub/sub)

##### Architectural Patterns & Design Principles
- Modular ROS2-package structure: each functional area in its own package
- Publisher‐Subscriber decoupling via common message definitions
- Parameterization through YAML + ROS2 parameters (loaded with `ros_param_loader`)
- Factory pattern for selecting vehicle models at runtime
- CI/CD via GitHub Actions, reproducible builds with colcon + CMake

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    DDS["ROS2 DDS"]:::ext
    CasADi["CasADi + Ipopt"]:::ext

    %% Common Messages
    subgraph "Common Messages"
        direction TB
        LMPC_MSGS[("lmpc_msgs")]:::common
        MPCLAB_MSGS[("mpclab_msgs")]:::common
    end

    %% Simulation Layer
    subgraph "Simulation Layer"
        direction TB
        SIM["Racing Simulator"]:::sim
    end

    %% Estimation Layer
    subgraph "Estimation Layer"
        direction TB
        EKF["EKF State Estimator"]:::core
    end

    %% Control Layer
    subgraph "Control Layer"
        direction TB
        LMPC["Learning MPC Controller"]:::core
        MPC["Classic MPC Node"]:::core
        LQR["LQR Solver Node"]:::core
        VANILLA["Vanilla Controller"]:::core
        CasADi
    end

    %% Vehicle Dynamics Models
    subgraph "Vehicle Dynamics Models" 
        direction TB
        BASE_VEH[("Base Vehicle Model")]:::util
        SINGLE_TK[("Single-Track Planar Model")]:::util
        DOUBLE_TK[("Double-Track Planar Model")]:::util
        KIN_BIKE[("Kinematic Bicycle Model")]:::util
        TRAJECTORY[("Racing Trajectory")]:::util
        FACTORY[("Vehicle Model Factory")]:::util
    end

    %% Tools & Utilities
    subgraph "Tools & Utilities"
        direction TB
        TRANSFORM["Transform Helper"]:::util
        UTIL["General Utilities"]:::util
    end

    %% Launch Manager
    LAUNCH[("Launch Manager")]:::launch

    %% Visualization
    subgraph "Visualization"
        direction TB
        BRIDGE["Foxglove Bridge"]:::vis
        STUDIO["Foxglove Studio"]:::vis
    end

    %% Data Flows
    DDS -->|"/mpclab/raw_sensor"| SIM
    SIM -->|"/mpclab/raw_sensor"| EKF
    EKF -->|"/vehicle_state"| LMPC
    EKF -->|"/vehicle_state"| MPC
    EKF -->|"/vehicle_state"| LQR
    EKF -->|"/vehicle_state"| VANILLA
    LMPC -->|"/lmpc/trajectory_cmd"| SIM
    MPC -->|"/lmpc/trajectory_cmd"| SIM
    LQR -->|"/lmpc/trajectory_cmd"| SIM
    VANILLA -->|"/lmpc/trajectory_cmd"| SIM

    %% Bridge subscriptions
    SIM -->|"/mpclab/raw_sensor"| BRIDGE
    EKF -->|"/vehicle_state"| BRIDGE
    LMPC -->|"/lmpc/trajectory_cmd"| BRIDGE

    BRIDGE -->|"WebSocket"| STUDIO

    %% Launch orchestration
    LAUNCH --> SIM
    LAUNCH --> EKF
    LAUNCH --> LMPC
    LAUNCH --> MPC
    LAUNCH --> LQR
    LAUNCH --> VANILLA
    LAUNCH --> BRIDGE

    %% Vehicle dynamics usage
    SIM --> FACTORY
    LMPC --> FACTORY
    MPC --> FACTORY
    LQR --> FACTORY
    VANILLA --> FACTORY

    FACTORY --> BASE_VEH
    FACTORY --> SINGLE_TK
    FACTORY --> DOUBLE_TK
    FACTORY --> KIN_BIKE
    FACTORY --> TRAJECTORY

    %% Utilities usage
    SIM --> TRANSFORM
    EKF --> TRANSFORM
    LMPC --> UTIL
    MPC --> UTIL
    LQR --> UTIL
    VANILLA --> UTIL

    %% Click Events
    click LMPC_MSGS "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/common/lmpc_msgs"
    click MPCLAB_MSGS "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/common/mpclab_msgs"
    click SIM "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/simulation/racing_simulator"
    click EKF "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/state_estimators/ekf_state_estimator"
    click BASE_VEH "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/vehicle_dynamics_models/base_vehicle_model"
    click SINGLE_TK "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/vehicle_dynamics_models/single_track_planar_model"
    click DOUBLE_TK "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/vehicle_dynamics_models/double_track_planar_model"
    click KIN_BIKE "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/vehicle_dynamics_models/kinematic_bicycle_model"
    click TRAJECTORY "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/vehicle_dynamics_models/racing_trajectory"
    click FACTORY "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/vehicle_dynamics_models/vehicle_model_factory"
    click LMPC "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/controllers/racing_lmpc"
    click VANILLA "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/controllers/vanilla_controller"
    click MPC "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/mpc/racing_mpc"
    click LQR "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/mpc/racing_lqr"
    click CasADi "https://github.com/mpc-berkeley/racing-lmpc-ros2/blob/humble-release/src/tools/lmpc_utils/include/lmpc_utils/casadi_primitives.hpp"
    click TRANSFORM "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/tools/lmpc_transform_helper"
    click UTIL "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/tools/lmpc_utils"
    click LAUNCH "https://github.com/mpc-berkeley/racing-lmpc-ros2/tree/humble-release/src/launch/racing_lmpc_launch"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef sim fill:#90EE90,stroke:#000,stroke-width:1px
    classDef util fill:#FFA500,stroke:#000,stroke-width:1px
    classDef vis fill:#D8BFD8,stroke:#000,stroke-width:1px
    classDef common fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef ext fill:#fffacd,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef launch fill:#f0e68c,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
```
