# theshaboury/autonomous-warehouse-robot architecture

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

- Interactive diagram: https://gitdiagram.com/theshaboury/autonomous-warehouse-robot
- Repository: https://github.com/theshaboury/autonomous-warehouse-robot

## Overview

This repository is the ROS 2 runtime for a real-hardware warehouse AMR, with a separate simulation mode. The principal workflow is to launch the robot, accept joystick or Nav2 goals, estimate motion from wheel odometry and IMU, and execute motion through ros2_control and the Arduino serial link. Mapping and saved-map localization are separate operating modes; LiDAR feeds those modes directly. The README documents the overall integrations, while sampled code confirms the Arduino interface, serial messaging, and MPU6050 driver. Other launch/config subsystems are represented from the tree and README, not inspected in source.

Main entry points: [`src/arduino_hardware_interface/src/arduino_system.cpp`](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/arduino_hardware_interface/src/arduino_system.cpp) (Arduino System Interface), [`src/warehouse_real_description/config/twist_mux.yaml`](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_description/config/twist_mux.yaml) (Velocity Arbitration), [`src/warehouse_real_nav/launch/navigation_launch.py`](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_nav/launch/navigation_launch.py) (Nav2 Planning), [`src/warehouse_real_bringup/launch/launch_robot.launch.py`](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_bringup/launch/launch_robot.launch.py) (Robot Launch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Robot Bringup"]
  node_bringup["Robot Launch"]
  node_mux["Velocity Arbitration<br/>[twist_mux.yaml]"]
  node_description["Robot Model<br/>[robot.urdf.xacro]"]
  node_controllers["ros2_control Config"]
end

subgraph group_hardware["Robot Hardware"]
  node_hardware_interface["Arduino System Interface<br/>[arduino_system.cpp]"]
  node_arduino_comms["Arduino Messaging<br/>[arduino_comms.hpp]"]
  node_serial["Serial Library"]
end

subgraph group_state["Sensing And State"]
  node_imu_driver["MPU6050 ROS Driver<br/>[mpu6050driver.cpp]"]
  node_imu_sensor["MPU6050 I2C Sensor<br/>[mpu6050sensor.cpp]"]
  node_ekf["EKF Fusion<br/>[ekf.yaml]"]
end

subgraph group_autonomy["Mapping And Navigation"]
  node_slam["SLAM Toolbox"]
  node_maps[("Saved Maps")]
  node_amcl["AMCL Localization"]
  node_nav2["Nav2 Planning"]
end

node_operator(("Joystick / Goal"))
node_arduino["Arduino Controller"]
node_motors["Motors / Encoders"]
node_lidar["RPLIDAR A1"]

node_operator -->|"sends teleop"| node_mux
node_operator -->|"sets goal"| node_nav2
node_bringup -->|"loads model"| node_description
node_bringup -->|"configures"| node_controllers
node_bringup -->|"starts"| node_mux
node_description -->|"declares hardware"| node_hardware_interface
node_controllers -->|"uses interface"| node_hardware_interface
node_hardware_interface -->|"calls messaging"| node_arduino_comms
node_arduino_comms -->|"uses serial API"| node_serial
node_serial -->|"transfers commands"| node_arduino
node_arduino -->|"controls hardware"| node_motors
node_motors -->|"returns encoders"| node_hardware_interface
node_imu_driver -->|"reads sensor"| node_imu_sensor
node_imu_sensor -->|"publishes IMU data"| node_ekf
node_motors -->|"provides odometry"| node_ekf
node_ekf -->|"provides estimate"| node_nav2
node_lidar -->|"supplies scans"| node_slam
node_slam -->|"creates maps"| node_maps
node_maps -->|"provides saved map"| node_amcl
node_lidar -->|"supplies scans"| node_amcl
node_amcl -->|"provides localization"| node_nav2
node_nav2 -.->|"commands motion"| node_mux
node_mux -.->|"routes velocity"| node_hardware_interface

click node_bringup "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_bringup/launch/launch_robot.launch.py"
click node_mux "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_description/config/twist_mux.yaml"
click node_description "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_description/description/robot.urdf.xacro"
click node_controllers "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_description/config/my_controllers.yaml"
click node_hardware_interface "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/arduino_hardware_interface/src/arduino_system.cpp"
click node_arduino_comms "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/arduino_hardware_interface/include/arduino_hardware_interface/arduino_comms.hpp"
click node_serial "https://github.com/theshaboury/autonomous-warehouse-robot/tree/main/src/serial"
click node_imu_driver "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/mpu6050driver/src/mpu6050driver.cpp"
click node_imu_sensor "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/mpu6050driver/src/mpu6050sensor.cpp"
click node_ekf "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_nav/config/ekf.yaml"
click node_slam "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_slam/launch/online_async_launch.py"
click node_maps "https://github.com/theshaboury/autonomous-warehouse-robot/tree/main/src/warehouse_real_slam/maps"
click node_amcl "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_nav/launch/localization_launch.py"
click node_nav2 "https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_nav/launch/navigation_launch.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_bringup,node_mux,node_description,node_controllers toneBlue
class node_hardware_interface,node_arduino_comms,node_serial toneAmber
class node_imu_driver,node_imu_sensor,node_ekf toneMint
class node_slam,node_maps,node_amcl,node_nav2 toneRose
class node_operator,node_arduino,node_motors,node_lidar toneIndigo
```

## Components

### Robot Bringup

- [Robot Launch](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_bringup/launch/launch_robot.launch.py): `src/warehouse_real_bringup/launch/launch_robot.launch.py`
- [Velocity Arbitration](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_description/config/twist_mux.yaml): `src/warehouse_real_description/config/twist_mux.yaml`
- [Robot Model](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_description/description/robot.urdf.xacro): `src/warehouse_real_description/description/robot.urdf.xacro`
- [ros2_control Config](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_description/config/my_controllers.yaml): `src/warehouse_real_description/config/my_controllers.yaml`

### Robot Hardware

- [Arduino System Interface](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/arduino_hardware_interface/src/arduino_system.cpp): `src/arduino_hardware_interface/src/arduino_system.cpp`
- [Arduino Messaging](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/arduino_hardware_interface/include/arduino_hardware_interface/arduino_comms.hpp): `src/arduino_hardware_interface/include/arduino_hardware_interface/arduino_comms.hpp`
- [Serial Library](https://github.com/theshaboury/autonomous-warehouse-robot/tree/main/src/serial): `src/serial`

### Sensing And State

- [MPU6050 ROS Driver](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/mpu6050driver/src/mpu6050driver.cpp): `src/mpu6050driver/src/mpu6050driver.cpp`
- [MPU6050 I2C Sensor](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/mpu6050driver/src/mpu6050sensor.cpp): `src/mpu6050driver/src/mpu6050sensor.cpp`
- [EKF Fusion](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_nav/config/ekf.yaml): `src/warehouse_real_nav/config/ekf.yaml`

### Mapping And Navigation

- [SLAM Toolbox](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_slam/launch/online_async_launch.py): `src/warehouse_real_slam/launch/online_async_launch.py`
- [Saved Maps](https://github.com/theshaboury/autonomous-warehouse-robot/tree/main/src/warehouse_real_slam/maps): `src/warehouse_real_slam/maps`
- [AMCL Localization](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_nav/launch/localization_launch.py): `src/warehouse_real_nav/launch/localization_launch.py`
- [Nav2 Planning](https://github.com/theshaboury/autonomous-warehouse-robot/blob/main/src/warehouse_real_nav/launch/navigation_launch.py): `src/warehouse_real_nav/launch/navigation_launch.py`

### Other components

- **Joystick / Goal**
- **Arduino Controller**
- **Motors / Encoders**
- **RPLIDAR A1**

## Connections

- Joystick / Goal → Velocity Arbitration: sends teleop (evidence: `README.md`)
- Joystick / Goal → Nav2 Planning: sets goal (evidence: `README.md`)
- Robot Launch → Robot Model: loads model (evidence: `README.md`)
- Robot Launch → ros2_control Config: configures (evidence: `README.md`)
- Robot Launch → Velocity Arbitration: starts (evidence: `README.md`)
- Robot Model → Arduino System Interface: declares hardware (evidence: `README.md`)
- ros2_control Config → Arduino System Interface: uses interface (evidence: `README.md`)
- Arduino System Interface → Arduino Messaging: calls messaging (evidence: `src/arduino_hardware_interface/src/arduino_system.cpp`)
- Arduino Messaging → Serial Library: uses serial API (evidence: `src/arduino_hardware_interface/include/arduino_hardware_interface/arduino_comms.hpp`)
- Serial Library → Arduino Controller: transfers commands (evidence: `README.md`)
- Arduino Controller → Motors / Encoders: controls hardware (evidence: `README.md`)
- Motors / Encoders → Arduino System Interface: returns encoders (evidence: `README.md`)
- MPU6050 ROS Driver → MPU6050 I2C Sensor: reads sensor (evidence: `src/mpu6050driver/src/mpu6050driver.cpp`)
- MPU6050 I2C Sensor → EKF Fusion: publishes IMU data (evidence: `README.md`)
- Motors / Encoders → EKF Fusion: provides odometry (evidence: `README.md`)
- EKF Fusion → Nav2 Planning: provides estimate (evidence: `README.md`)
- RPLIDAR A1 → SLAM Toolbox: supplies scans (evidence: `README.md`)
- SLAM Toolbox → Saved Maps: creates maps (evidence: `README.md`)
- Saved Maps → AMCL Localization: provides saved map (evidence: `README.md`)
- RPLIDAR A1 → AMCL Localization: supplies scans (evidence: `README.md`)
- AMCL Localization → Nav2 Planning: provides localization (evidence: `README.md`)
- Nav2 Planning → Velocity Arbitration: commands motion
- Velocity Arbitration → Arduino System Interface: routes velocity
