# lihanchen2004/pb_rm_simulation architecture

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

- Interactive diagram: https://gitdiagram.com/lihanchen2004/pb_rm_simulation
- Repository: https://github.com/lihanchen2004/pb_rm_simulation

## Overview

##### Project type and purpose
- This is a ROS2-based robotics simulation and navigation stack. It uses Gazebo Classic to simulate an omnidirectional robot equipped with a Livox Mid360 LiDAR and an IMU. It supports both simulation and Sim2Real operation, offering multiple localization (FAST_LIO, Point_LIO, slam_toolbox, AMCL, ICP) and navigation (Nav2 + TEB) options.

##### File-structure overview
- Top level: devcontainer, docs, build scripts, Dockerfile, README.
- src/: a ROS2 workspace containing packages in five domains:
- rm_driver: Livox ROS driver
- rm_localization: LIO (FAST_LIO, Point_LIO) and ICP registration
- rm_nav_bringup: bring-up launch files, maps, configs, URDFs for both sim & real
- rm_navigation: core Nav2 stack extensions (costmap_converter, fake_vel_transform, teb_local_planner)
- rm_perception: helper nodes (IMU complementary filter, ground segmentation, pointcloud↔laserscan)
- rm_simulation: Gazebo plugins for LiDAR, world and robot meshes, URDFs, simulation launch

##### Key architecture insights from README
- Four main pipelines: Sensor simulation (Gazebo plugins) → Perception & LIO → Localization → Nav2 planning & control → Robot actuation
- Topic interfaces (/livox/lidar, /livox/imu, /cmd_vel, /odom, etc.)
- Configurable parameters for sim vs. real (“world”, “mode”, “lio”, “localization”, viz flags)

A. Simulation/Hardware layer (leftmost, boxed in blue)
1. Gazebo Classic
- World model (RMUC/RMUL .world)
- pb_rm_simulation meshes & obstacles plugin
2. Robot model (URDF/XACRO)
- livox_laser_simulation plugin → publishes `/livox/lidar` (CustomMsg)
- Gazebo IMU plugin → publishes `/livox/imu` (sensor_msgs/Imu)
- Gazebo drive plugin subscribes to `/cmd_vel`

B. ROS2 middleware (central, gray background)
1. rm_driver/livox_ros_driver2 (only for real-world)
2. Topics:
- `/livox/lidar/pointcloud` (PointCloud2)
- `/livox/imu`
- `/odom`
- `/cmd_vel`

C. Perception & Odometry layer (green)
1. rm_perception
- imu_complementary_filter → refines IMU data
- linefit_ground_segmentation → ground removal
- pointcloud_to_laserscan → publishes fake `/scan` for Nav2
2. rm_localization
- FAST_LIO / Point_LIO → subscribes to `/livox/lidar`, `/livox/imu` → publishes `/odom`
- icp_registration (optional initial pose)
(Use branching to show choice FAST_LIO vs. Point_LIO vs. ICP)

D. Localization layer (orange)
- slam_toolbox / AMCL / ICP_localization
- Inputs: `/odom`, map server topics (`/map`, `/initialpose`)
- Outputs: `/tf`, refined pose for Nav2

E. Navigation & Planning layer (red)
1. rm_navigation
- costmap_converter → 3D→2D costmap
- fake_vel_transform → corrects LiDAR/twist frames
- teb_local_planner → local trajectory optimization
2. Nav2 core nodes (map_server, planner_server, controller_server, bt_navigator)
- Configs in rm_nav_bringup/config
3. rviz (visualization)

F. Actuation layer (purple)
- `/cmd_vel` → robot base controller (sim plugin or real driver)

##### Architectural patterns & design principles
- ROS2 node-based modularity: each function lives in its own package.
- Launch‐time composition: use ROS2 launch to swap LIO/localization modules and sim vs. real.
- Layered pipeline: sensing → perception → motion estimation → localization → planning → control.
- Plugin‐based Gazebo integration: robot sensors and world elements.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Simulation/Hardware Layer
    subgraph "Simulation/Hardware"
        Gazebo["Gazebo Classic"]:::simulation
        RMUCWorld["RMUC2024_world (.world)"]:::simulation
        RMULWorld["RMUL2024_world_dynamic_obstacles (.world)"]:::simulation
        RobotModel["Robot Model URDF/XACRO"]:::simulation
        LivoxPlugin["livox_laser_simulation plugin"]:::simulation
        IMUPlugin["Gazebo IMU plugin"]:::simulation
        DrivePlugin["Gazebo Drive plugin"]:::simulation
        ObstaclePlugin["Obstacle Plugin"]:::simulation
    end

    Gazebo --> RMUCWorld
    Gazebo --> RMULWorld
    Gazebo --> RobotModel
    RMUCWorld --> ObstaclePlugin
    RobotModel --> LivoxPlugin
    RobotModel --> IMUPlugin
    RobotModel --> DrivePlugin

    %% ROS2 Middleware Layer
    subgraph "ROS2 Middleware"
        DriverReal["Livox Real-World Driver"]:::middleware
        LidarTopic["/livox/lidar/pointcloud"]:::middleware
        ImuTopic["/livox/imu"]:::middleware
        OdomTopic["/odom"]:::middleware
        CmdVelTopic["/cmd_vel"]:::middleware
    end

    LivoxPlugin --> LidarTopic
    IMUPlugin --> ImuTopic
    DrivePlugin --> CmdVelTopic
    DriverReal --> LidarTopic
    DriverReal --> ImuTopic

    %% Perception & Odometry Layer
    subgraph "Perception & Odometry"
        ComplementaryFilter["imu_complementary_filter"]:::perception
        GroundSeg["linefit_ground_segmentation"]:::perception
        PC2Scan["pointcloud_to_laserscan"]:::perception
        FASTLIO["FAST_LIO"]:::perception
        PointLIO["Point_LIO"]:::perception
        ICPReg["ICP Registration"]:::perception
    end

    LidarTopic --> GroundSeg
    LidarTopic --> PC2Scan
    LidarTopic --> FASTLIO
    LidarTopic --> PointLIO
    LidarTopic --> ICPReg
    ImuTopic --> ComplementaryFilter
    ImuTopic --> FASTLIO
    ImuTopic --> PointLIO
    ImuTopic --> ICPReg
    GroundSeg -->|"filtered cloud"| FASTLIO
    PC2Scan -->|"fake /scan"| Nav2

    FASTLIO --> OdomTopic
    PointLIO --> OdomTopic
    ICPReg --> OdomTopic

    %% Localization Layer
    subgraph "Localization"
        AMCL["AMCL"]:::localization
        SLAMToolbox["slam_toolbox"]:::localization
        ICPLoc["ICP Localization"]:::localization
    end

    OdomTopic --> AMCL
    OdomTopic --> SLAMToolbox
    OdomTopic --> ICPLoc

    %% Navigation & Planning Layer
    subgraph "Navigation & Planning"
        CostmapConv["costmap_converter"]:::navigation
        FakeVel["fake_vel_transform"]:::navigation
        TebPlanner["teb_local_planner"]:::navigation
        MapServer["map_server"]:::navigation
        NavLaunch["navigation_launch"]:::navigation
        NavParamsSim["nav2_params_sim.yaml"]:::navigation
        NavParamsReal["nav2_params_real.yaml"]:::navigation
        RViz["RViz"]:::navigation
    end

    PC2Scan --> CostmapConv
    FakeVel --> CostmapConv
    OdomTopic --> FakeVel
    AMCL --> CostmapConv
    SLAMToolbox --> CostmapConv
    ICPLoc --> CostmapConv

    CostmapConv --> TebPlanner
    TebPlanner --> NavLaunch
    MapServer --> NavLaunch
    NavParamsSim --> NavLaunch
    NavParamsReal --> NavLaunch
    MapServer --> RViz
    CostmapConv --> RViz

    %% Actuation Layer
    subgraph "Actuation"
        SimDrive["Gazebo Drive Plugin"]:::actuation
        RealActuation["Real Robot Base Controller"]:::actuation
    end

    NavLaunch --> CmdVelTopic
    CmdVelTopic --> SimDrive
    CmdVelTopic --> RealActuation

    %% Click Events
    click RMUCWorld "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_simulation/pb_rm_simulation/world/RMUC2024_world/RMUC2024_world.world"
    click RMULWorld "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_simulation/pb_rm_simulation/world/RMUL2024_world/RMUL2024_world_dynamic_obstacles.world"
    click RobotModel "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_nav_bringup/urdf/sentry_robot_sim.xacro"
    click RobotModel "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_nav_bringup/urdf/sentry_robot_real.xacro"
    click LivoxPlugin "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_simulation/livox_laser_simulation_RO2/src/livox_points_plugin.cpp"
    click ObstaclePlugin "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_simulation/pb_rm_simulation/meshes/obstacles/obstacle_plugin/obstacles.cc"
    click DriverReal "https://github.com/lihanchen2004/pb_rm_simulation/tree/main/src/rm_driver/livox_ros_driver2"
    click ComplementaryFilter "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_perception/imu_complementary_filter/src/complementary_filter_node.cpp"
    click GroundSeg "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_perception/linefit_ground_segementation_ros2/linefit_ground_segmentation_ros/src/ground_segmentation_node.cc"
    click PC2Scan "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_perception/pointcloud_to_laserscan/src/pointcloud_to_laserscan_node.cpp"
    click FASTLIO "https://github.com/lihanchen2004/pb_rm_simulation/tree/main/src/rm_localization/FAST_LIO"
    click PointLIO "https://github.com/lihanchen2004/pb_rm_simulation/tree/main/src/rm_localization/point_lio"
    click ICPReg "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_localization/icp_registration/src/icp_registration.cpp"
    click AMCL "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_navigation/rm_navigation/launch/localization_amcl_launch.py"
    click SLAMToolbox "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_nav_bringup/launch/bringup_sim.launch.py"
    click CostmapConv "https://github.com/lihanchen2004/pb_rm_simulation/tree/main/src/rm_navigation/costmap_converter"
    click FakeVel "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_navigation/fake_vel_transform/src/fake_vel_transform.cpp"
    click TebPlanner "https://github.com/lihanchen2004/pb_rm_simulation/tree/main/src/rm_navigation/teb_local_planner"
    click MapServer "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_navigation/rm_navigation/launch/map_server_launch.py"
    click NavLaunch "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_navigation/rm_navigation/launch/navigation_launch.py"
    click NavParamsSim "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_nav_bringup/config/simulation/nav2_params_sim.yaml"
    click NavParamsReal "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_nav_bringup/config/reality/nav2_params_real.yaml"
    click SimDrive "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_simulation/pb_rm_simulation/launch/rm_simulation.launch.py"
    click RealActuation "https://github.com/lihanchen2004/pb_rm_simulation/blob/main/src/rm_nav_bringup/launch/bringup_real.launch.py"

    %% Styles
    classDef simulation fill:#D0E6FF,stroke:#3B78FF,color:#000
    classDef middleware fill:#F0F0F0,stroke:#888888,color:#000
    classDef perception fill:#E6FFE6,stroke:#00A000,color:#000
    classDef localization fill:#FFE6CC,stroke:#FF8000,color:#000
    classDef navigation fill:#FFE6E6,stroke:#FF0000,color:#000
    classDef actuation fill:#F3E6FF,stroke:#8000FF,color:#000
```
