# sailing-team-polimi/2025_software architecture

> Architecture diagram of the GitHub repository sailing-team-polimi/2025_software, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sailing-team-polimi/2025_software
- Repository: https://github.com/sailing-team-polimi/2025_software

## Overview

This is ROS 2 boat-operation software for the 2025 SuMoth competition. The intended operational workflow spans onboard CAN and GPS sensing, sensor conversion and state estimation, then flap control and operator monitoring. The sampled code confirms CAN packet parsing, IMU publication, and the PID controller’s topic-driven control loop; README descriptions establish the broader package capabilities. Several cross-package runtime links are not shown in the available excerpts, so those are omitted or marked unverified rather than presented as confirmed calls.

Main entry points: [`ros2_ws/src/state_estimation/launch/sensor_fusion.launch.py`](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/state_estimation/launch/sensor_fusion.launch.py) (State Fusion), [`ros2_ws/src/flap_control/src/pid_node.cpp`](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/flap_control/src/pid_node.cpp) (PID Controller Node), [`ros2_ws/src/can_bus/src/parsers/Parser.cpp`](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/src/parsers/Parser.cpp) (CAN Parser), [`ros2_ws/src/orca/launch/orca.launch.py`](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/orca/launch/orca.launch.py) (Boat Operations Launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensing["Onboard Sensing"]
  node_uart["UART CAN Interface<br/>[BusInterface.hpp]"]
  node_can_parser["CAN Parser<br/>[Parser.cpp]"]
  node_sensor_api["Sensor Interface<br/>[Sensor.hpp]"]
  node_pot_sensor["Potentiometer Sensor"]
  node_imu_parser["IMU Parser"]
  node_gps["GPS Interface<br/>[gps_node.py]"]
end

subgraph group_estimate["State Estimation"]
  node_sensor_est["Sensor Estimates<br/>[wand2est_node.cpp]"]
  node_gps_local["GPS Local Conversion<br/>[gps_to_local.cpp]"]
  node_gps_global["GPS Coordinate Conversion<br/>[local_to_gps.cpp]"]
  node_state_fusion["State Fusion"]
  node_ride_height["Ride Height"]
end

subgraph group_control["Flap Control"]
  node_pid_node["PID Controller Node<br/>[pid_node.cpp]"]
  node_pid_core["PID Controller<br/>[PIDController.hpp]"]
  node_servo_map["Servo Mapping<br/>[ServoMapper.cpp]"]
  node_wand_servo["Wand Servo Control<br/>[wand2servo.cpp]"]
end

subgraph group_operations["Boat Operations"]
  node_orca["Boat Operations Launcher<br/>[orca.launch.py]"]
end

subgraph group_monitor["Operator Monitoring"]
  node_foxglove["Foxglove and RViz"]
  node_monitor_app["Custom Monitor Bridge<br/>[send_to_monitor.py]"]
end

node_boat(("Boat Sensors"))
node_mcu{{"CAN Microcontroller"}}

node_boat -->|"sends sensor data"| node_mcu
node_mcu -->|"sends CAN over UART"| node_uart
node_uart -->|"provides packets"| node_can_parser
node_can_parser -->|"dispatches packets"| node_sensor_api
node_can_parser -->|"configures and dispatches"| node_pot_sensor
node_pot_sensor -->|"implements interface"| node_sensor_api
node_imu_parser -.->|"publishes IMU data"| node_boat
node_gps -.->|"provides GPS data"| node_gps_local
node_gps_local -.->|"feeds localization"| node_state_fusion
node_sensor_est -.->|"provides estimates"| node_state_fusion
node_state_fusion -.->|"supports coordinate output"| node_gps_global
node_state_fusion -.->|"supports ride-height state"| node_ride_height
node_pid_node -->|"computes control"| node_pid_core
node_pid_core -->|"returns control value"| node_pid_node
node_state_fusion -.->|"provides measurement"| node_pid_node
node_pid_node -.->|"provides control output"| node_servo_map
node_wand_servo -.->|"uses mapping"| node_servo_map
node_orca -.->|"starts operations"| node_can_parser
node_orca -.->|"starts operations"| node_state_fusion
node_orca -.->|"starts control"| node_pid_node
node_state_fusion -.->|"visualizes boat state"| node_foxglove
node_state_fusion -.->|"sends monitoring data"| node_monitor_app

click node_uart "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/include/can_bus/BusInterface.hpp"
click node_can_parser "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/src/parsers/Parser.cpp"
click node_sensor_api "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/include/can_bus/sensors/Sensor.hpp"
click node_pot_sensor "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/src/sensors/PotenziometerSensor.cpp"
click node_imu_parser "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/src/imu_parser_node.cpp"
click node_gps "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/gps_interface/gps_interface/gps_node.py"
click node_sensor_est "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/sensor_estimates/src/wand2est_node.cpp"
click node_gps_local "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/state_estimation/src/gps_to_local.cpp"
click node_gps_global "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/state_estimation/src/local_to_gps.cpp"
click node_state_fusion "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/state_estimation/launch/sensor_fusion.launch.py"
click node_ride_height "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/state_estimation/src/ride_height_node.cpp"
click node_pid_node "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/flap_control/src/pid_node.cpp"
click node_pid_core "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/flap_control/include/flap_control/PIDController.hpp"
click node_servo_map "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/flap_control/src/ServoMapper.cpp"
click node_wand_servo "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/flap_control/src/wand2servo.cpp"
click node_orca "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/orca/launch/orca.launch.py"
click node_foxglove "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/gui/launch/foxglove_full.launch.py"
click node_monitor_app "https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/poli_sail_gui/poli_sail_gui/send_to_monitor.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_uart,node_can_parser,node_sensor_api,node_pot_sensor,node_imu_parser,node_gps toneBlue
class node_sensor_est,node_gps_local,node_gps_global,node_state_fusion,node_ride_height toneAmber
class node_pid_node,node_pid_core,node_servo_map,node_wand_servo toneMint
class node_orca toneRose
class node_foxglove,node_monitor_app,node_boat,node_mcu toneIndigo
```

## Components

### Onboard Sensing

- [UART CAN Interface](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/include/can_bus/BusInterface.hpp): `ros2_ws/src/can_bus/include/can_bus/BusInterface.hpp`
- [CAN Parser](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/src/parsers/Parser.cpp): `ros2_ws/src/can_bus/src/parsers/Parser.cpp`
- [Sensor Interface](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/include/can_bus/sensors/Sensor.hpp): `ros2_ws/src/can_bus/include/can_bus/sensors/Sensor.hpp`
- [Potentiometer Sensor](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/src/sensors/PotenziometerSensor.cpp): `ros2_ws/src/can_bus/src/sensors/PotenziometerSensor.cpp`
- [IMU Parser](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/can_bus/src/imu_parser_node.cpp): `ros2_ws/src/can_bus/src/imu_parser_node.cpp`
- [GPS Interface](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/gps_interface/gps_interface/gps_node.py): `ros2_ws/src/gps_interface/gps_interface/gps_node.py`

### State Estimation

- [Sensor Estimates](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/sensor_estimates/src/wand2est_node.cpp): `ros2_ws/src/sensor_estimates/src/wand2est_node.cpp`
- [GPS Local Conversion](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/state_estimation/src/gps_to_local.cpp): `ros2_ws/src/state_estimation/src/gps_to_local.cpp`
- [GPS Coordinate Conversion](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/state_estimation/src/local_to_gps.cpp): `ros2_ws/src/state_estimation/src/local_to_gps.cpp`
- [State Fusion](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/state_estimation/launch/sensor_fusion.launch.py): `ros2_ws/src/state_estimation/launch/sensor_fusion.launch.py`
- [Ride Height](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/state_estimation/src/ride_height_node.cpp): `ros2_ws/src/state_estimation/src/ride_height_node.cpp`

### Flap Control

- [PID Controller Node](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/flap_control/src/pid_node.cpp): `ros2_ws/src/flap_control/src/pid_node.cpp`
- [PID Controller](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/flap_control/include/flap_control/PIDController.hpp): `ros2_ws/src/flap_control/include/flap_control/PIDController.hpp`
- [Servo Mapping](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/flap_control/src/ServoMapper.cpp): `ros2_ws/src/flap_control/src/ServoMapper.cpp`
- [Wand Servo Control](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/flap_control/src/wand2servo.cpp): `ros2_ws/src/flap_control/src/wand2servo.cpp`

### Boat Operations

- [Boat Operations Launcher](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/orca/launch/orca.launch.py): `ros2_ws/src/orca/launch/orca.launch.py`

### Operator Monitoring

- [Foxglove and RViz](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/gui/launch/foxglove_full.launch.py): `ros2_ws/src/gui/launch/foxglove_full.launch.py`
- [Custom Monitor Bridge](https://github.com/sailing-team-polimi/2025_software/blob/main/ros2_ws/src/poli_sail_gui/poli_sail_gui/send_to_monitor.py): `ros2_ws/src/poli_sail_gui/poli_sail_gui/send_to_monitor.py`

### Other components

- **Boat Sensors**
- **CAN Microcontroller**

## Connections

- Boat Sensors → CAN Microcontroller: sends sensor data
- CAN Microcontroller → UART CAN Interface: sends CAN over UART
- UART CAN Interface → CAN Parser: provides packets (evidence: `ros2_ws/src/can_bus/src/parsers/Parser.cpp`)
- CAN Parser → Sensor Interface: dispatches packets (evidence: `ros2_ws/src/can_bus/src/parsers/Parser.cpp`)
- CAN Parser → Potentiometer Sensor: configures and dispatches (evidence: `ros2_ws/src/can_bus/src/parsers/Parser.cpp`)
- Potentiometer Sensor → Sensor Interface: implements interface
- IMU Parser → Boat Sensors: publishes IMU data
- GPS Interface → GPS Local Conversion: provides GPS data
- GPS Local Conversion → State Fusion: feeds localization
- Sensor Estimates → State Fusion: provides estimates
- State Fusion → GPS Coordinate Conversion: supports coordinate output
- State Fusion → Ride Height: supports ride-height state
- PID Controller Node → PID Controller: computes control (evidence: `ros2_ws/src/flap_control/src/pid_node.cpp`)
- PID Controller → PID Controller Node: returns control value (evidence: `ros2_ws/src/flap_control/src/pid_node.cpp`)
- State Fusion → PID Controller Node: provides measurement
- PID Controller Node → Servo Mapping: provides control output
- Wand Servo Control → Servo Mapping: uses mapping
- Boat Operations Launcher → CAN Parser: starts operations
- Boat Operations Launcher → State Fusion: starts operations
- Boat Operations Launcher → PID Controller Node: starts control
- State Fusion → Foxglove and RViz: visualizes boat state
- State Fusion → Custom Monitor Bridge: sends monitoring data
