# antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization architecture

> Architecture diagram of the GitHub repository antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization
- Repository: https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization

## Overview

This repository is course material for a ROS 2 mobile robot focused on mapping and localization. The principal workflow is to launch the simulated or real robot, drive it, and use sensor and odometry data for localization and mapping; the README also identifies LiDAR, obstacle avoidance, and speed/separation monitoring as capabilities. The excerpts show the differential-drive controller converting velocity commands and wheel states into wheel commands and odometry. Other subsystem links are not demonstrated in sampled source, so those links are marked unverified or omitted.

Main entry points: [`Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/simple_controller.cpp`](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/simple_controller.cpp) (Drive and odometry), [`Section10_SLAM/bumperbot_ws/src/bumperbot_bringup/launch/simulated_robot.launch.py`](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_bringup/launch/simulated_robot.launch.py) (Robot bringup), [`Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/src/bumperbot_interface.cpp`](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/src/bumperbot_interface.cpp) (Hardware interface), [`Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/kalman_filter.cpp`](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/kalman_filter.cpp) (Robot localization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Robot Runtime"]
  node_bringup["Robot bringup"]
  node_sim["Gazebo simulation<br/>[gazebo.launch.py]"]
  node_description["Robot description"]
end

subgraph group_motion["Motion and Hardware"]
  node_controller["Drive and odometry"]
  node_noisy["Noisy controller"]
  node_relay["Twist relay<br/>[twist_relay.cpp]"]
  node_firmware["Hardware interface"]
  node_serial["Serial I/O"]
  node_imu["IMU driver<br/>[mpu6050_driver.py]"]
end

subgraph group_perception["Mapping and Localization"]
  node_lidar["LiDAR sensor"]
  node_localization["Robot localization<br/>[kalman_filter.cpp]"]
  node_motionmodel["Odometry model"]
  node_mapping["SLAM mapping"]
  node_imu_repub["IMU republisher"]
end

subgraph group_safety["Safety"]
  node_safety["Safety stop<br/>[safety_stop.cpp]"]
  node_avoidance["Obstacle avoidance"]
  node_monitoring["Speed monitoring"]
end

node_operator(("Robot operator"))
node_cmd["Velocity commands"]
node_jointstate["Wheel states"]
node_wheelcmd["Wheel commands"]
node_odom["Odometry output"]

node_operator -->|"launches"| node_bringup
node_bringup -.->|"launches simulation"| node_sim
node_cmd -->|"velocity input"| node_controller
node_jointstate -->|"wheel feedback"| node_controller
node_controller -->|"publishes commands"| node_wheelcmd
node_controller -->|"publishes odometry"| node_odom
node_controller -.->|"commands hardware"| node_firmware
node_firmware -.->|"uses serial I/O"| node_serial
node_imu -.->|"supplies IMU data"| node_imu_repub
node_lidar -.->|"provides scans"| node_mapping
node_odom -.->|"provides motion data"| node_localization
node_odom -.->|"provides wheel motion"| node_motionmodel
node_localization -.->|"provides poses"| node_mapping
node_lidar -.->|"supports avoidance"| node_avoidance
node_avoidance -.->|"requests stop"| node_safety
node_monitoring -.->|"monitors motion"| node_safety
node_description -.->|"configures robot"| node_sim

click node_bringup "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_bringup/launch/simulated_robot.launch.py"
click node_sim "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_description/launch/gazebo.launch.py"
click node_description "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/tree/main/Section10_SLAM/bumperbot_ws/src/bumperbot_description"
click node_controller "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/simple_controller.cpp"
click node_noisy "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/noisy_controller.cpp"
click node_relay "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/twist_relay.cpp"
click node_firmware "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/src/bumperbot_interface.cpp"
click node_serial "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/src/simple_serial_receiver.cpp"
click node_imu "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/bumperbot_firmware/mpu6050_driver.py"
click node_localization "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/kalman_filter.cpp"
click node_motionmodel "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/odometry_motion_model.cpp"
click node_mapping "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_mapping/src/mapping_with_known_poses.cpp"
click node_imu_repub "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/imu_republisher.cpp"
click node_safety "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_utils/src/safety_stop.cpp"
click node_avoidance "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/tree/main/Section10_SLAM/bumperbot_ws/src/bumperbot_controller"
click node_monitoring "https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/tree/main/Section10_SLAM/bumperbot_ws/src/bumperbot_utils"

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_sim,node_description toneBlue
class node_controller,node_noisy,node_relay,node_firmware,node_serial,node_imu toneAmber
class node_lidar,node_localization,node_motionmodel,node_mapping,node_imu_repub toneMint
class node_safety,node_avoidance,node_monitoring toneRose
class node_operator,node_cmd,node_jointstate,node_wheelcmd,node_odom toneIndigo
```

## Components

### Robot Runtime

- [Robot bringup](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_bringup/launch/simulated_robot.launch.py): `Section10_SLAM/bumperbot_ws/src/bumperbot_bringup/launch/simulated_robot.launch.py`
- [Gazebo simulation](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_description/launch/gazebo.launch.py): `Section10_SLAM/bumperbot_ws/src/bumperbot_description/launch/gazebo.launch.py`
- [Robot description](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/tree/main/Section10_SLAM/bumperbot_ws/src/bumperbot_description): `Section10_SLAM/bumperbot_ws/src/bumperbot_description`

### Motion and Hardware

- [Drive and odometry](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/simple_controller.cpp): `Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/simple_controller.cpp`
- [Noisy controller](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/noisy_controller.cpp): `Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/noisy_controller.cpp`
- [Twist relay](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/twist_relay.cpp): `Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/twist_relay.cpp`
- [Hardware interface](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/src/bumperbot_interface.cpp): `Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/src/bumperbot_interface.cpp`
- [Serial I/O](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/src/simple_serial_receiver.cpp): `Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/src/simple_serial_receiver.cpp`
- [IMU driver](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/bumperbot_firmware/mpu6050_driver.py): `Section10_SLAM/bumperbot_ws/src/bumperbot_firmware/bumperbot_firmware/mpu6050_driver.py`

### Mapping and Localization

- **LiDAR sensor**
- [Robot localization](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/kalman_filter.cpp): `Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/kalman_filter.cpp`
- [Odometry model](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/odometry_motion_model.cpp): `Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/odometry_motion_model.cpp`
- [SLAM mapping](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_mapping/src/mapping_with_known_poses.cpp): `Section10_SLAM/bumperbot_ws/src/bumperbot_mapping/src/mapping_with_known_poses.cpp`
- [IMU republisher](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/imu_republisher.cpp): `Section10_SLAM/bumperbot_ws/src/bumperbot_localization/src/imu_republisher.cpp`

### Safety

- [Safety stop](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/blob/main/Section10_SLAM/bumperbot_ws/src/bumperbot_utils/src/safety_stop.cpp): `Section10_SLAM/bumperbot_ws/src/bumperbot_utils/src/safety_stop.cpp`
- [Obstacle avoidance](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/tree/main/Section10_SLAM/bumperbot_ws/src/bumperbot_controller): `Section10_SLAM/bumperbot_ws/src/bumperbot_controller`
- [Speed monitoring](https://github.com/antobrandi/self-driving-and-ros-2-learn-by-doing-map-localization/tree/main/Section10_SLAM/bumperbot_ws/src/bumperbot_utils): `Section10_SLAM/bumperbot_ws/src/bumperbot_utils`

### Other components

- **Robot operator**
- **Velocity commands**
- **Wheel states**
- **Wheel commands**
- **Odometry output**

## Connections

- Robot operator → Robot bringup: launches
- Robot bringup → Gazebo simulation: launches simulation
- Velocity commands → Drive and odometry: velocity input (evidence: `Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/simple_controller.cpp`)
- Wheel states → Drive and odometry: wheel feedback (evidence: `Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/simple_controller.cpp`)
- Drive and odometry → Wheel commands: publishes commands (evidence: `Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/simple_controller.cpp`)
- Drive and odometry → Odometry output: publishes odometry (evidence: `Section10_SLAM/bumperbot_ws/src/bumperbot_controller/src/simple_controller.cpp`)
- Drive and odometry → Hardware interface: commands hardware
- Hardware interface → Serial I/O: uses serial I/O
- IMU driver → IMU republisher: supplies IMU data
- LiDAR sensor → SLAM mapping: provides scans
- Odometry output → Robot localization: provides motion data
- Odometry output → Odometry model: provides wheel motion
- Robot localization → SLAM mapping: provides poses
- LiDAR sensor → Obstacle avoidance: supports avoidance
- Obstacle avoidance → Safety stop: requests stop
- Speed monitoring → Safety stop: monitors motion
- Robot description → Gazebo simulation: configures robot
