From 0a05a9bf604d49911bdd5c1be53e69a6a72ff9f1 Mon Sep 17 00:00:00 2001 From: MathieuMRodrigue Date: Wed, 20 May 2026 12:16:27 -0400 Subject: [PATCH 1/8] Create components.md for system architecture diagram Added a component map diagram to illustrate system architecture. --- doc/architecture/components.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 doc/architecture/components.md diff --git a/doc/architecture/components.md b/doc/architecture/components.md new file mode 100644 index 0000000..bd92a96 --- /dev/null +++ b/doc/architecture/components.md @@ -0,0 +1,27 @@ +--- + +# ✅ 📁 docs/architecture/components.md + +```markdown +# Component Map + +This diagram shows the internal structure of the system and relationships between key components. + +```mermaid +flowchart TD + Teleop[Teleop / Joy Input] + Arbitration[cmd_vel_arbitration] + Shim[cmd_vel_to_ackermann_drive] + Controller[Ackermann Controllers] + Bridge[ros_gz_bridge] + Gazebo[Gazebo Ackermann Plugin] + VESC[VESC Driver] + + Teleop --> Arbitration + Arbitration --> Shim + Shim --> Controller + + Controller --> Bridge + Bridge --> Gazebo + + Controller --> VESC From 7c4eb2580c40b30c9e879f787821bd9ad5ae6886 Mon Sep 17 00:00:00 2001 From: MathieuMRodrigue Date: Wed, 20 May 2026 12:24:13 -0400 Subject: [PATCH 2/8] Revise system context and component map diagrams Updated system context and component map diagrams to reflect new architecture. --- doc/architecture/components.md | 35 +++++++++++++++------------------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/doc/architecture/components.md b/doc/architecture/components.md index bd92a96..121b9ae 100644 --- a/doc/architecture/components.md +++ b/doc/architecture/components.md @@ -1,27 +1,22 @@ ---- +# System Context -# ✅ 📁 docs/architecture/components.md - -```markdown -# Component Map - -This diagram shows the internal structure of the system and relationships between key components. +This diagram shows how the system interacts with external actors such as the user and simulation environment. ```mermaid -flowchart TD - Teleop[Teleop / Joy Input] - Arbitration[cmd_vel_arbitration] - Shim[cmd_vel_to_ackermann_drive] - Controller[Ackermann Controllers] +flowchart LR + User[User / Developer] + Teleop[Teleoperation Nodes] + ROS[ROS2 System] Bridge[ros_gz_bridge] - Gazebo[Gazebo Ackermann Plugin] - VESC[VESC Driver] + Gazebo[Gazebo Simulation] + Car[Racecar Model] + Hardware[Physical Vehicle] - Teleop --> Arbitration - Arbitration --> Shim - Shim --> Controller - - Controller --> Bridge + User --> Teleop + Teleop --> ROS + ROS --> Bridge Bridge --> Gazebo + Gazebo --> Car + + ROS --> Hardware - Controller --> VESC From b6d998f40e6e104d2824123f2cdba57ae0785af5 Mon Sep 17 00:00:00 2001 From: MathieuMRodrigue Date: Wed, 20 May 2026 12:36:58 -0400 Subject: [PATCH 3/8] Attempt for documentation --- doc/architecture/README.md | 32 ++++++++++++++++++++++++++++++++ doc/architecture/context.md | 14 ++++++++++++++ doc/architecture/sequences.md | 27 +++++++++++++++++++++++++++ 3 files changed, 73 insertions(+) create mode 100644 doc/architecture/README.md create mode 100644 doc/architecture/context.md create mode 100644 doc/architecture/sequences.md diff --git a/doc/architecture/README.md b/doc/architecture/README.md new file mode 100644 index 0000000..63dd12c --- /dev/null +++ b/doc/architecture/README.md @@ -0,0 +1,32 @@ + +# 🏎️ Architecture Documentation + +This section describes the architecture of the racecar system. + +## Overview + +The system is built using a modular ROS2 architecture that supports both: + +- Simulation (Gazebo) +- Real vehicle hardware (VESC) + +The same control flow is reused for both environments. + +--- + +## 📊 Architecture Diagrams + +- [System Context](context.md) + High-level view of how the system interacts with users and external systems. + +- [Component Map](components.md) + Internal structure of the system and relationships between modules. + +- [Sequence Diagram](sequences.md) + Step-by-step command flow through the system. + +--- + +## 🧠 Summary + +The architecture follows a layered approach: diff --git a/doc/architecture/context.md b/doc/architecture/context.md new file mode 100644 index 0000000..f7cfaac --- /dev/null +++ b/doc/architecture/context.md @@ -0,0 +1,14 @@ + +# System Context + +This diagram shows how the system interacts with external actors such as the user and the simulation environment. + +```mermaid +flowchart LR + User[User / Developer] + Teleop[Teleoperation Nodes] + ROS[ROS2 System] + Bridge[ros_gz_bridge] + Gazebo[Gazebo Simulation] + Car[Racecar Model] + Hardware[Physical Vehicle (VESC)] diff --git a/doc/architecture/sequences.md b/doc/architecture/sequences.md new file mode 100644 index 0000000..3854807 --- /dev/null +++ b/doc/architecture/sequences.md @@ -0,0 +1,27 @@ +--- + +# ✅ 📁 `docs/architecture/sequences.md` + +```markdown +# Command Flow Sequence + +This diagram describes how a command flows from the user to the vehicle. + +```mermaid +sequenceDiagram + participant User + participant Teleop + participant Arbiter + participant Converter + participant Controller + participant Bridge + participant Gazebo + + User->>Teleop: joystick input + Teleop->>Arbiter: cmd_vel + Arbiter->>Converter: selected cmd_vel + Converter->>Converter: convert to Ackermann + Converter->>Controller: send command + Controller->>Bridge: publish cmd_vel + Bridge->>Gazebo: gz.msgs.Twist + Gazebo->>Gazebo: compute steering + motion \ No newline at end of file From 8d3efdfc910bb48c1934979cc5ec35a362cfe28f Mon Sep 17 00:00:00 2001 From: MathieuMRodrigue Date: Wed, 20 May 2026 12:51:38 -0400 Subject: [PATCH 4/8] fix mermaid code --- doc/architecture/context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/architecture/context.md b/doc/architecture/context.md index f7cfaac..80642c1 100644 --- a/doc/architecture/context.md +++ b/doc/architecture/context.md @@ -11,4 +11,4 @@ flowchart LR Bridge[ros_gz_bridge] Gazebo[Gazebo Simulation] Car[Racecar Model] - Hardware[Physical Vehicle (VESC)] + Hardware[Physical Vehicle ] From 3be1438104a1741505920a7bc0084619c5195e6b Mon Sep 17 00:00:00 2001 From: MathieuMRodrigue Date: Wed, 20 May 2026 13:10:59 -0400 Subject: [PATCH 5/8] Fix formatting in sequences.md --- doc/architecture/sequences.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/doc/architecture/sequences.md b/doc/architecture/sequences.md index 3854807..30e16ea 100644 --- a/doc/architecture/sequences.md +++ b/doc/architecture/sequences.md @@ -1,8 +1,4 @@ ---- -# ✅ 📁 `docs/architecture/sequences.md` - -```markdown # Command Flow Sequence This diagram describes how a command flows from the user to the vehicle. @@ -24,4 +20,4 @@ sequenceDiagram Converter->>Controller: send command Controller->>Bridge: publish cmd_vel Bridge->>Gazebo: gz.msgs.Twist - Gazebo->>Gazebo: compute steering + motion \ No newline at end of file + Gazebo->>Gazebo: compute steering + motion From b1bdf5c612077856695b6d8248b175d56e1522fc Mon Sep 17 00:00:00 2001 From: Mathieu Melanson Rodrigue Date: Fri, 22 May 2026 13:17:09 -0400 Subject: [PATCH 6/8] update doc --- doc/architecture/README.md | 9 +-- doc/architecture/components.md | 110 ++++++++++++++++++++++++++++----- doc/architecture/context.md | 39 +++++++++--- 3 files changed, 128 insertions(+), 30 deletions(-) diff --git a/doc/architecture/README.md b/doc/architecture/README.md index 63dd12c..4dc3c9a 100644 --- a/doc/architecture/README.md +++ b/doc/architecture/README.md @@ -1,5 +1,5 @@ -# 🏎️ Architecture Documentation +# Architecture Documentation This section describes the architecture of the racecar system. @@ -8,13 +8,13 @@ This section describes the architecture of the racecar system. The system is built using a modular ROS2 architecture that supports both: - Simulation (Gazebo) -- Real vehicle hardware (VESC) +- Real vehicle hardware (Racecar) The same control flow is reused for both environments. --- -## 📊 Architecture Diagrams +## Architecture Diagrams - [System Context](context.md) High-level view of how the system interacts with users and external systems. @@ -27,6 +27,3 @@ The same control flow is reused for both environments. --- -## 🧠 Summary - -The architecture follows a layered approach: diff --git a/doc/architecture/components.md b/doc/architecture/components.md index 121b9ae..9e55ed8 100644 --- a/doc/architecture/components.md +++ b/doc/architecture/components.md @@ -1,22 +1,98 @@ -# System Context -This diagram shows how the system interacts with external actors such as the user and simulation environment. +# Component Map + +This diagram shows the relationship between the major modules of the system. ```mermaid + flowchart LR - User[User / Developer] - Teleop[Teleoperation Nodes] - ROS[ROS2 System] - Bridge[ros_gz_bridge] - Gazebo[Gazebo Simulation] - Car[Racecar Model] - Hardware[Physical Vehicle] - - User --> Teleop - Teleop --> ROS - ROS --> Bridge - Bridge --> Gazebo - Gazebo --> Car - - ROS --> Hardware + User[User] + +%% -------------------- +%% INPUT INTERFACES +%% -------------------- + subgraph Input [Input Interfaces] + Control["(Joystick / Web Interface)"] + end + +%% -------------------- +%% ROS SYSTEM +%% -------------------- + subgraph ROS [ROS2 System] + direction LR +%% Control (grouped) + subgraph Controls [Arduino Motor Controls] + direction LR + SpeedControl[SpeedControl] + PositionControl[PositionControl] + Openloop[Openloop] + end + +%% Perception + subgraph Perception [Perception] + Lidar[Lidar] + Camera[Camera] + end + +%% Odometry / state + subgraph State [Odometry] + direction LR + IMU[IMU] + Encoder[Wheel Encoder] + Steering[Steering Angle] + end + +%% Navigation / decision + subgraph Navigation [Navigation Algorithms] + direction LR + SLAM[SLAM] + Blob[Blob Detection] + Brushfire[Brushfire] + Autopilot[Autopilot] + end + +end + +%% -------------------- +%% EXECUTION +%% -------------------- + subgraph Execution [Execution Systems] + direction LR + Racecar[Racecar] + Gazebo[Gazebo Simulation] + end +%% -------------------- +%% MONITORING INTERFACES +%% -------------------- + + subgraph Monitoring [Monitoring and Tools] + direction LR + RViz[RViz] + RQt[RQt] + ROS2Bag[ROS2Bag] + end + + ROS --> Monitoring + +%% -------------------- +%% FLOW +%% -------------------- + +%% Inputs into system + User --> Input + Input --> ROS + +%% Sensor pipeline + State --> Navigation + State --> Controls + Perception --> Navigation + + +%% Navigation feeds control + Navigation --> Controls + +%% Brushfire separate (map-level) + +%% Control outputs + ROS --> Execution diff --git a/doc/architecture/context.md b/doc/architecture/context.md index 80642c1..9aee402 100644 --- a/doc/architecture/context.md +++ b/doc/architecture/context.md @@ -4,11 +4,36 @@ This diagram shows how the system interacts with external actors such as the user and the simulation environment. ```mermaid + flowchart LR - User[User / Developer] - Teleop[Teleoperation Nodes] - ROS[ROS2 System] - Bridge[ros_gz_bridge] - Gazebo[Gazebo Simulation] - Car[Racecar Model] - Hardware[Physical Vehicle ] + + User[User] + + subgraph Input [Input Interfaces] + Control["(Joystick / Web Interface)"] + end + + subgraph Core [ROS2 System] + ROS[ROS2 Nodes] + end + + subgraph Execution [Execution Systems] + Gazebo["Simulation (Gazebo)"] + Hardware[Racecar] + end + + User --> Control + Control --> ROS + ROS --> Gazebo + ROS --> Hardware + + + + + + + + + + + From fb0af433e556710ff1aea66c43922c571d9021ed Mon Sep 17 00:00:00 2001 From: MathieuMRodrigue Date: Fri, 22 May 2026 13:59:47 -0400 Subject: [PATCH 7/8] Revise command flow Updated the command flow sequence diagram to include a more complex core logic flow during autonomous operation. --- doc/architecture/sequences.md | 54 +++++++++++++++++++++++------------ 1 file changed, 35 insertions(+), 19 deletions(-) diff --git a/doc/architecture/sequences.md b/doc/architecture/sequences.md index 30e16ea..39f42de 100644 --- a/doc/architecture/sequences.md +++ b/doc/architecture/sequences.md @@ -1,23 +1,39 @@ +# Sequence Diagram -# Command Flow Sequence - -This diagram describes how a command flows from the user to the vehicle. +This diagram illustrates the most complex core logic flow of the system during autonomous operation. ```mermaid sequenceDiagram - participant User - participant Teleop - participant Arbiter - participant Converter - participant Controller - participant Bridge - participant Gazebo - - User->>Teleop: joystick input - Teleop->>Arbiter: cmd_vel - Arbiter->>Converter: selected cmd_vel - Converter->>Converter: convert to Ackermann - Converter->>Controller: send command - Controller->>Bridge: publish cmd_vel - Bridge->>Gazebo: gz.msgs.Twist - Gazebo->>Gazebo: compute steering + motion + + participant Sensors + participant ROS2 + participant Navigation as Navigation and SLAM + participant Blob as Blob Detection + participant Autopilot + participant Arduino + + %% Initialization + ROS2->>Navigation: load map and initialize path + + %% Continuous loop + loop Autonomous Navigation + + Sensors->>ROS2: publish sensor data (lidar, camera, imu, encoder) + + %% Localization and navigation + ROS2->>Navigation: send lidar and odometry + Navigation->>ROS2: position estimate + + %% Blob detection + ROS2->>Blob: send lidar and camera data + Blob->>ROS2: detected balloons + + %% Autopilot (reactive wall avoidance) + ROS2->>Autopilot: send lidar data + Autopilot->>ROS2: generate steering and speed commands + + %% Execution + ROS2->>Arduino: send control commands + Arduino-->>ROS2: odometry feedback + + end From c6a083244958c341fcb4294d2c17ee6788c86d01 Mon Sep 17 00:00:00 2001 From: MathieuMRodrigue Date: Fri, 22 May 2026 14:02:19 -0400 Subject: [PATCH 8/8] update architecture documentation --- doc/architecture/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/architecture/README.md b/doc/architecture/README.md index 4dc3c9a..14e7407 100644 --- a/doc/architecture/README.md +++ b/doc/architecture/README.md @@ -23,7 +23,7 @@ The same control flow is reused for both environments. Internal structure of the system and relationships between modules. - [Sequence Diagram](sequences.md) - Step-by-step command flow through the system. + Step-by-step of the most complex core logic flow through the system. ---