# robovision2210/mechaprime_ws architecture

> Architecture diagram of the GitHub repository robovision2210/mechaprime_ws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robovision2210/mechaprime_ws
- Repository: https://github.com/robovision2210/mechaprime_ws

## Overview

MechaPrime is a ROS 2 autonomous differential-drive robot for simulation and real hardware. The main workflow is to launch a robot, obtain sensor data, map or localize, then send navigation or autonomy tasks that produce motion commands for the drive system. The repository also includes teleoperation, docking, maze solving, camera/marker tools, and an RPLIDAR ROS driver/SDK. Several connections are documented in the README; unsampled implementation details are represented only at subsystem level, so the graph omits unverified internal wiring.

Main entry points: [`src/mechaprime_navigation/launch/navigation.launch.py`](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_navigation/launch/navigation.launch.py) (Nav2 Navigation), [`src/mechaprime_bringup/launch/simulated_robot.launch.py`](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_bringup/launch/simulated_robot.launch.py) (Simulation Bringup), [`src/mechaprime_bringup/launch/real_robot.launch.py`](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_bringup/launch/real_robot.launch.py) (Real Robot Bringup), [`src/mechaprime_firmware/src/mechaprime_interface.cpp`](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_firmware/src/mechaprime_interface.cpp) (Hardware Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bringup["Robot Bringup"]
  node_sim_bringup["Simulation Bringup"]
  node_real_bringup["Real Robot Bringup"]
  node_robot_description["Robot and Worlds<br/>[gazebo.launch.py]"]
  node_controller["Drive and Joystick"]
end

subgraph group_sensing["Sensors and Hardware"]
  node_firmware["Hardware Interface"]
  node_lidar_ros["LiDAR ROS Node<br/>[rplidar_node.cpp]"]
end

subgraph group_navigation["Mapping and Navigation"]
  node_slam["SLAM Mapping<br/>[slam.launch.py]"]
  node_localization["AMCL Localization"]
  node_nav2["Nav2 Navigation"]
  node_waypoints["Waypoint Following"]
end

subgraph group_autonomy["Autonomy Features"]
  node_maze["QR Maze Solver<br/>[maze_solver.py]"]
  node_dock["Docking"]
  node_battery_dock["Battery Docking"]
  node_patrol_dock["Patrol and Dock"]
  node_avoidance["Obstacle Avoidance"]
  node_marker["Marker Detection<br/>[detect_marker.py]"]
  node_sensor_tools["Sensor Readers<br/>[read_lidar.py]"]
end

subgraph group_lidar["RPLIDAR Driver"]
  node_lidar_sdk["LiDAR SDK Driver"]
  node_lidar_unpacker["Scan Unpacking"]
end

node_operator(("Operator"))
node_ros_navigation["ROS 2 Navigation Stack"]
node_robot(("Robot Hardware"))

node_operator -->|"launches simulation"| node_sim_bringup
node_operator -->|"launches robot"| node_real_bringup
node_sim_bringup -.->|"starts Gazebo"| node_robot_description
node_sim_bringup -.->|"starts control"| node_controller
node_real_bringup -.->|"starts interface"| node_firmware
node_firmware -->|"reads and drives"| node_robot
node_robot -.->|"provides scans"| node_lidar_ros
node_lidar_ros -.->|"uses driver"| node_lidar_sdk
node_lidar_sdk -->|"decodes scan data"| node_lidar_unpacker
node_operator -->|"starts mapping"| node_slam
node_operator -->|"starts localization"| node_localization
node_operator -->|"starts navigation"| node_nav2
node_localization -->|"provides pose"| node_nav2
node_operator -->|"sends goals"| node_waypoints
node_waypoints -->|"requests navigation"| node_nav2
node_nav2 -->|"sends velocity"| node_controller
node_operator -->|"starts maze run"| node_maze
node_maze -->|"commands motion"| node_robot
node_operator -->|"starts docking"| node_dock
node_dock -->|"uses actions"| node_nav2
node_operator -->|"starts battery mode"| node_battery_dock
node_battery_dock -->|"uses actions"| node_nav2
node_operator -->|"starts patrol"| node_patrol_dock
node_patrol_dock -->|"uses actions"| node_nav2
node_operator -->|"starts avoidance"| node_avoidance
node_avoidance -->|"commands motion"| node_robot
node_operator -->|"starts detection"| node_marker
node_operator -->|"runs readers"| node_sensor_tools
node_ros_navigation -->|"supplies Nav2 stack"| node_nav2

click node_sim_bringup "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_bringup/launch/simulated_robot.launch.py"
click node_real_bringup "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_bringup/launch/real_robot.launch.py"
click node_robot_description "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_description/launch/gazebo.launch.py"
click node_controller "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_controller/launch/controller.launch.py"
click node_firmware "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_firmware/src/mechaprime_interface.cpp"
click node_lidar_ros "https://github.com/robovision2210/mechaprime_ws/blob/main/src/rplidar_ros-24cc9b6dea97e045bda1408eaa867ce730fd3fc3/src/rplidar_node.cpp"
click node_lidar_sdk "https://github.com/robovision2210/mechaprime_ws/blob/main/src/rplidar_ros-24cc9b6dea97e045bda1408eaa867ce730fd3fc3/sdk/src/sl_lidar_driver.cpp"
click node_lidar_unpacker "https://github.com/robovision2210/mechaprime_ws/blob/main/src/rplidar_ros-24cc9b6dea97e045bda1408eaa867ce730fd3fc3/sdk/src/dataunpacker/unpacker/handler_capsules.cpp"
click node_slam "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_mapping/launch/slam.launch.py"
click node_localization "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_localization/launch/global_localization.launch.py"
click node_nav2 "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_navigation/launch/navigation.launch.py"
click node_waypoints "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_navigation/mechaprime_navigation/waypoint_following.py"
click node_maze "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/maze_solver.py"
click node_dock "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/auto_docking_undocking.py"
click node_battery_dock "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/auto_docking_with_battery.py"
click node_patrol_dock "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/docking_with_patrolling.py"
click node_avoidance "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/obstacle_avoidance.py"
click node_marker "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/detect_marker.py"
click node_sensor_tools "https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/read_lidar.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sim_bringup,node_real_bringup,node_robot_description,node_controller toneBlue
class node_firmware,node_lidar_ros toneAmber
class node_slam,node_localization,node_nav2,node_waypoints toneMint
class node_maze,node_dock,node_battery_dock,node_patrol_dock,node_avoidance,node_marker,node_sensor_tools toneRose
class node_lidar_sdk,node_lidar_unpacker,node_operator,node_ros_navigation,node_robot toneIndigo
```

## Components

### Robot Bringup

- [Simulation Bringup](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_bringup/launch/simulated_robot.launch.py): `src/mechaprime_bringup/launch/simulated_robot.launch.py`
- [Real Robot Bringup](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_bringup/launch/real_robot.launch.py): `src/mechaprime_bringup/launch/real_robot.launch.py`
- [Robot and Worlds](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_description/launch/gazebo.launch.py): `src/mechaprime_description/launch/gazebo.launch.py`
- [Drive and Joystick](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_controller/launch/controller.launch.py): `src/mechaprime_controller/launch/controller.launch.py`

### Sensors and Hardware

- [Hardware Interface](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_firmware/src/mechaprime_interface.cpp): `src/mechaprime_firmware/src/mechaprime_interface.cpp`
- [LiDAR ROS Node](https://github.com/robovision2210/mechaprime_ws/blob/main/src/rplidar_ros-24cc9b6dea97e045bda1408eaa867ce730fd3fc3/src/rplidar_node.cpp): `src/rplidar_ros-24cc9b6dea97e045bda1408eaa867ce730fd3fc3/src/rplidar_node.cpp`

### Mapping and Navigation

- [SLAM Mapping](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_mapping/launch/slam.launch.py): `src/mechaprime_mapping/launch/slam.launch.py`
- [AMCL Localization](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_localization/launch/global_localization.launch.py): `src/mechaprime_localization/launch/global_localization.launch.py`
- [Nav2 Navigation](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_navigation/launch/navigation.launch.py): `src/mechaprime_navigation/launch/navigation.launch.py`
- [Waypoint Following](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_navigation/mechaprime_navigation/waypoint_following.py): `src/mechaprime_navigation/mechaprime_navigation/waypoint_following.py`

### Autonomy Features

- [QR Maze Solver](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/maze_solver.py): `src/mechaprime_scripts/mechaprime_scripts/maze_solver.py`
- [Docking](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/auto_docking_undocking.py): `src/mechaprime_scripts/mechaprime_scripts/auto_docking_undocking.py`
- [Battery Docking](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/auto_docking_with_battery.py): `src/mechaprime_scripts/mechaprime_scripts/auto_docking_with_battery.py`
- [Patrol and Dock](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/docking_with_patrolling.py): `src/mechaprime_scripts/mechaprime_scripts/docking_with_patrolling.py`
- [Obstacle Avoidance](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/obstacle_avoidance.py): `src/mechaprime_scripts/mechaprime_scripts/obstacle_avoidance.py`
- [Marker Detection](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/detect_marker.py): `src/mechaprime_scripts/mechaprime_scripts/detect_marker.py`
- [Sensor Readers](https://github.com/robovision2210/mechaprime_ws/blob/main/src/mechaprime_scripts/mechaprime_scripts/read_lidar.py): `src/mechaprime_scripts/mechaprime_scripts/read_lidar.py`

### RPLIDAR Driver

- [LiDAR SDK Driver](https://github.com/robovision2210/mechaprime_ws/blob/main/src/rplidar_ros-24cc9b6dea97e045bda1408eaa867ce730fd3fc3/sdk/src/sl_lidar_driver.cpp): `src/rplidar_ros-24cc9b6dea97e045bda1408eaa867ce730fd3fc3/sdk/src/sl_lidar_driver.cpp`
- [Scan Unpacking](https://github.com/robovision2210/mechaprime_ws/blob/main/src/rplidar_ros-24cc9b6dea97e045bda1408eaa867ce730fd3fc3/sdk/src/dataunpacker/unpacker/handler_capsules.cpp): `src/rplidar_ros-24cc9b6dea97e045bda1408eaa867ce730fd3fc3/sdk/src/dataunpacker/unpacker/handler_capsules.cpp`

### Other components

- **Operator**
- **ROS 2 Navigation Stack**
- **Robot Hardware**

## Connections

- Operator → Simulation Bringup: launches simulation
- Operator → Real Robot Bringup: launches robot
- Simulation Bringup → Robot and Worlds: starts Gazebo
- Simulation Bringup → Drive and Joystick: starts control
- Real Robot Bringup → Hardware Interface: starts interface
- Hardware Interface → Robot Hardware: reads and drives (evidence: `src/mechaprime_firmware/src/mechaprime_interface.cpp`)
- Robot Hardware → LiDAR ROS Node: provides scans
- LiDAR ROS Node → LiDAR SDK Driver: uses driver
- LiDAR SDK Driver → Scan Unpacking: decodes scan data (evidence: `src/rplidar_ros-24cc9b6dea97e045bda1408eaa867ce730fd3fc3/sdk/src/sl_lidar_driver.cpp`)
- Operator → SLAM Mapping: starts mapping
- Operator → AMCL Localization: starts localization
- Operator → Nav2 Navigation: starts navigation
- AMCL Localization → Nav2 Navigation: provides pose
- Operator → Waypoint Following: sends goals
- Waypoint Following → Nav2 Navigation: requests navigation
- Nav2 Navigation → Drive and Joystick: sends velocity
- Operator → QR Maze Solver: starts maze run
- QR Maze Solver → Robot Hardware: commands motion
- Operator → Docking: starts docking
- Docking → Nav2 Navigation: uses actions
- Operator → Battery Docking: starts battery mode
- Battery Docking → Nav2 Navigation: uses actions
- Operator → Patrol and Dock: starts patrol
- Patrol and Dock → Nav2 Navigation: uses actions
- Operator → Obstacle Avoidance: starts avoidance
- Obstacle Avoidance → Robot Hardware: commands motion
- Operator → Marker Detection: starts detection
- Operator → Sensor Readers: runs readers
- ROS 2 Navigation Stack → Nav2 Navigation: supplies Nav2 stack
