# neuroboticsclub/roboracer_stack architecture

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

- Interactive diagram: https://gitdiagram.com/neuroboticsclub/roboracer_stack
- Repository: https://github.com/neuroboticsclub/roboracer_stack

## Overview

This repository is a ROS 2 RoboRacer stack for simulator-connected and onboard driving: vehicle/sensor data enters through bridges and drivers, a LiDAR gap-follow planner selects motion commands, and VESC components translate commands to motor control and odometry. Separate operator paths provide keyboard teleoperation and a remote UDP kill switch; telemetry and laser odometry support observation and localization. The sampled sources establish the simulator bridge, sensor publishing, planner behavior, and remote-stop protocol. Several subsystem links are based on their documented package roles and names in the tree; unsampled launch wiring is not asserted.

Main entry points: [`ros_ws/src/planner_node/src/planner_gap_follow.cpp`](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/planner_node/src/planner_gap_follow.cpp) (Gap-follow planner), [`ros_ws/src/vesc/vesc_driver/src/vesc_driver.cpp`](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/vesc/vesc_driver/src/vesc_driver.cpp) (VESC driver), [`devkit/autodrive_devkit/autodrive_roboracer/autodrive_bridge.py`](https://github.com/neuroboticsclub/roboracer_stack/blob/main/devkit/autodrive_devkit/autodrive_roboracer/autodrive_bridge.py) (AutoDRIVE bridge), [`ros_ws/src/vesc/vesc_ackermann/src/ackermann_to_vesc.cpp`](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/vesc/vesc_ackermann/src/ackermann_to_vesc.cpp) (Ackermann adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator controls"]
  node_gamepad["Gamepad input"]
  node_remote_sender["Remote kill sender"]
  node_keyboard["Keyboard teleop<br/>[teleop_keyboard.py]"]
  node_estop["E-stop console<br/>[estop.cpp]"]
  node_killswitch["Remote stop receiver<br/>[killswitch.cpp]"]
end

subgraph group_integration["Simulator integration"]
  node_bridge["AutoDRIVE bridge"]
  node_telemetry["Telemetry control<br/>[neo_control.py]"]
  node_camera["Camera handling<br/>[camera.py]"]
  node_udp_driver["UDP driver"]
  node_serial_driver["Serial driver"]
  node_vehicle_state["Vehicle and race state"]
end

subgraph group_sensing["Sensing and odometry"]
  node_bno_service["IMU publishing<br/>[SensorService.py]"]
  node_bno_connector["IMU connectors<br/>[Connector.py]"]
  node_lidar["LiDAR odometry"]
  node_vesc_odom["VESC odometry<br/>[vesc_to_odom.cpp]"]
end

subgraph group_driving["Planning and actuation"]
  node_planner["Gap-follow planner"]
  node_ackermann["Ackermann adapter"]
  node_vesc_driver["VESC driver<br/>[vesc_driver.cpp]"]
end

node_operator(("Operator"))
node_simulator(("AutoDRIVE simulator"))
node_vesc_hardware["VESC motor controller"]

node_operator -->|"operates"| node_gamepad
node_gamepad -->|"supplies input"| node_remote_sender
node_remote_sender -.->|"sends UDP heartbeat"| node_udp_driver
node_udp_driver -.->|"delivers heartbeat"| node_killswitch
node_killswitch -->|"asserts stop"| node_planner
node_operator -->|"enters commands"| node_keyboard
node_keyboard -->|"publishes drive commands"| node_ackermann
node_estop -->|"asserts stop"| node_planner
node_simulator -->|"sends vehicle data"| node_bridge
node_bridge -->|"updates state"| node_vehicle_state
node_bridge -->|"sends control and ROS data"| node_simulator
node_telemetry -.->|"exchanges telemetry"| node_simulator
node_camera -.->|"provides camera data"| node_telemetry
node_bno_service -->|"reads sensor"| node_bno_connector
node_bno_service -.->|"publishes IMU data"| node_planner
node_lidar -.->|"publishes odometry"| node_planner
node_planner -->|"publishes drive commands"| node_ackermann
node_ackermann -->|"sends motor commands"| node_vesc_driver
node_vesc_driver -->|"controls"| node_vesc_hardware
node_vesc_hardware -->|"returns feedback"| node_vesc_driver
node_vesc_odom -->|"reads feedback"| node_vesc_driver
node_serial_driver -.->|"transports serial data"| node_vesc_driver

click node_gamepad "https://github.com/neuroboticsclub/roboracer_stack/blob/main/tools/killswitch_remote.py"
click node_remote_sender "https://github.com/neuroboticsclub/roboracer_stack/blob/main/tools/killswitch_remote.py"
click node_keyboard "https://github.com/neuroboticsclub/roboracer_stack/blob/main/devkit/autodrive_devkit/autodrive_roboracer/teleop_keyboard.py"
click node_estop "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/planner_node/src/estop.cpp"
click node_killswitch "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/planner_node/src/killswitch.cpp"
click node_bridge "https://github.com/neuroboticsclub/roboracer_stack/blob/main/devkit/autodrive_devkit/autodrive_roboracer/autodrive_bridge.py"
click node_telemetry "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/neo_telemetry/neo_telemetry/neo_control.py"
click node_camera "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/neo_telemetry/neo_telemetry/camera.py"
click node_bno_service "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/bno055/bno055/sensor/SensorService.py"
click node_bno_connector "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/bno055/bno055/connectors/Connector.py"
click node_lidar "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/rf2o_laser_odometry/src/CLaserOdometry2DNode.cpp"
click node_planner "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/planner_node/src/planner_gap_follow.cpp"
click node_ackermann "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/vesc/vesc_ackermann/src/ackermann_to_vesc.cpp"
click node_vesc_driver "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/vesc/vesc_driver/src/vesc_driver.cpp"
click node_vesc_odom "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/vesc/vesc_ackermann/src/vesc_to_odom.cpp"
click node_udp_driver "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/transport_drivers/udp_driver/src/udp_receiver_node.cpp"
click node_serial_driver "https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/transport_drivers/serial_driver/src/serial_bridge_node.cpp"
click node_vehicle_state "https://github.com/neuroboticsclub/roboracer_stack/blob/main/devkit/autodrive_devkit/autodrive_roboracer/autodrive_bridge.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_gamepad,node_remote_sender,node_keyboard,node_estop,node_killswitch toneBlue
class node_bridge,node_telemetry,node_camera,node_udp_driver,node_serial_driver,node_vehicle_state toneAmber
class node_bno_service,node_bno_connector,node_lidar,node_vesc_odom toneMint
class node_planner,node_ackermann,node_vesc_driver toneRose
class node_operator,node_simulator,node_vesc_hardware toneIndigo
```

## Components

### Operator controls

- [Gamepad input](https://github.com/neuroboticsclub/roboracer_stack/blob/main/tools/killswitch_remote.py): `tools/killswitch_remote.py`
- [Remote kill sender](https://github.com/neuroboticsclub/roboracer_stack/blob/main/tools/killswitch_remote.py): `tools/killswitch_remote.py`
- [Keyboard teleop](https://github.com/neuroboticsclub/roboracer_stack/blob/main/devkit/autodrive_devkit/autodrive_roboracer/teleop_keyboard.py): `devkit/autodrive_devkit/autodrive_roboracer/teleop_keyboard.py`
- [E-stop console](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/planner_node/src/estop.cpp): `ros_ws/src/planner_node/src/estop.cpp`
- [Remote stop receiver](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/planner_node/src/killswitch.cpp): `ros_ws/src/planner_node/src/killswitch.cpp`

### Simulator integration

- [AutoDRIVE bridge](https://github.com/neuroboticsclub/roboracer_stack/blob/main/devkit/autodrive_devkit/autodrive_roboracer/autodrive_bridge.py): `devkit/autodrive_devkit/autodrive_roboracer/autodrive_bridge.py`
- [Telemetry control](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/neo_telemetry/neo_telemetry/neo_control.py): `ros_ws/src/neo_telemetry/neo_telemetry/neo_control.py`
- [Camera handling](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/neo_telemetry/neo_telemetry/camera.py): `ros_ws/src/neo_telemetry/neo_telemetry/camera.py`
- [UDP driver](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/transport_drivers/udp_driver/src/udp_receiver_node.cpp): `ros_ws/src/transport_drivers/udp_driver/src/udp_receiver_node.cpp`
- [Serial driver](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/transport_drivers/serial_driver/src/serial_bridge_node.cpp): `ros_ws/src/transport_drivers/serial_driver/src/serial_bridge_node.cpp`
- [Vehicle and race state](https://github.com/neuroboticsclub/roboracer_stack/blob/main/devkit/autodrive_devkit/autodrive_roboracer/autodrive_bridge.py): `devkit/autodrive_devkit/autodrive_roboracer/autodrive_bridge.py`

### Sensing and odometry

- [IMU publishing](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/bno055/bno055/sensor/SensorService.py): `ros_ws/src/bno055/bno055/sensor/SensorService.py`
- [IMU connectors](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/bno055/bno055/connectors/Connector.py): `ros_ws/src/bno055/bno055/connectors/Connector.py`
- [LiDAR odometry](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/rf2o_laser_odometry/src/CLaserOdometry2DNode.cpp): `ros_ws/src/rf2o_laser_odometry/src/CLaserOdometry2DNode.cpp`
- [VESC odometry](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/vesc/vesc_ackermann/src/vesc_to_odom.cpp): `ros_ws/src/vesc/vesc_ackermann/src/vesc_to_odom.cpp`

### Planning and actuation

- [Gap-follow planner](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/planner_node/src/planner_gap_follow.cpp): `ros_ws/src/planner_node/src/planner_gap_follow.cpp`
- [Ackermann adapter](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/vesc/vesc_ackermann/src/ackermann_to_vesc.cpp): `ros_ws/src/vesc/vesc_ackermann/src/ackermann_to_vesc.cpp`
- [VESC driver](https://github.com/neuroboticsclub/roboracer_stack/blob/main/ros_ws/src/vesc/vesc_driver/src/vesc_driver.cpp): `ros_ws/src/vesc/vesc_driver/src/vesc_driver.cpp`

### Other components

- **Operator**
- **AutoDRIVE simulator**
- **VESC motor controller**

## Connections

- Operator → Gamepad input: operates
- Gamepad input → Remote kill sender: supplies input
- Remote kill sender → UDP driver: sends UDP heartbeat
- UDP driver → Remote stop receiver: delivers heartbeat
- Remote stop receiver → Gap-follow planner: asserts stop
- Operator → Keyboard teleop: enters commands
- Keyboard teleop → Ackermann adapter: publishes drive commands
- E-stop console → Gap-follow planner: asserts stop
- AutoDRIVE simulator → AutoDRIVE bridge: sends vehicle data
- AutoDRIVE bridge → Vehicle and race state: updates state
- AutoDRIVE bridge → AutoDRIVE simulator: sends control and ROS data
- Telemetry control → AutoDRIVE simulator: exchanges telemetry
- Camera handling → Telemetry control: provides camera data
- IMU publishing → IMU connectors: reads sensor
- IMU publishing → Gap-follow planner: publishes IMU data
- LiDAR odometry → Gap-follow planner: publishes odometry
- Gap-follow planner → Ackermann adapter: publishes drive commands
- Ackermann adapter → VESC driver: sends motor commands
- VESC driver → VESC motor controller: controls
- VESC motor controller → VESC driver: returns feedback
- VESC odometry → VESC driver: reads feedback
- Serial driver → VESC driver: transports serial data