# itu-auv/auv-software architecture

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

- Interactive diagram: https://gitdiagram.com/itu-auv/auv-software
- Repository: https://github.com/itu-auv/auv-software

## Overview

This repository is the ITU AUV Team’s ROS software stack. Its principal workflow is mission state machines selecting task behavior, planning paths, and executing vehicle control through thruster allocation; hardware bridges connect ROS to vehicle devices. Separate branches provide perception, localization and mapping, teleoperation, and simulation. The tree and excerpts establish some module relationships, but many runtime ROS-topic and action-server connections are not shown, so those links are omitted or marked unverified.

Main entry points: [`auv_smach/src/auv_smach/common.py`](https://github.com/itu-auv/auv-software/blob/main/auv_smach/src/auv_smach/common.py) (Mission Behaviors), [`auv_control/auv_control/include/auv_control/controller_ros.h`](https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_control/include/auv_control/controller_ros.h) (ROS Controller), [`auv_navigation/auv_navigation/src/auv_navigation/path_planning/path_planners.py`](https://github.com/itu-auv/auv-software/blob/main/auv_navigation/auv_navigation/src/auv_navigation/path_planning/path_planners.py) (Path Planners), [`auv_navigation/auv_navigation/scripts/follow_path_action_server.py`](https://github.com/itu-auv/auv-software/blob/main/auv_navigation/auv_navigation/scripts/follow_path_action_server.py) (Follow Path Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mission_navigation["Mission &amp; Navigation"]
  node_mission["Mission State Machine"]
  node_task_states["Task States"]
  node_mission_common["Mission Behaviors<br/>[common.py]"]
  node_path_planners["Path Planners<br/>[path_planners.py]"]
  node_path_helpers["Path Helpers"]
  node_follow_action["Follow Path Server"]
  node_follow_client["Follow Path Client"]
end

subgraph group_control["Vehicle Control"]
  node_controller_ros["ROS Controller<br/>[controller_ros.h]"]
  node_pid_controller["6-DOF PID"]
  node_controller_model["Vehicle Model<br/>[model.h]"]
  node_thruster_manager["Thruster Manager"]
  node_thruster_allocator["Thruster Allocator"]
end

subgraph group_sensing["Sensing &amp; Mapping"]
  node_camera_nodes["Camera Nodes"]
  node_vision_nodes["Vision &amp; Detection"]
  node_localization["Localization"]
  node_mapping["Mapping &amp; Objects"]
end

subgraph group_interfaces["Hardware &amp; Teleop"]
  node_hardware_bridge["Serial Bridge"]
  node_teleop["Teleoperation GUI<br/>[taluy_gui.py]"]
end

subgraph group_simulation["Simulation"]
  node_sim_mock["Simulation Mock"]
  node_sim_thrusters["Sim Thrusters<br/>[sim_thruster_ros.h]"]
end

node_operator(("Operator"))

node_operator -.->|"starts missions"| node_mission
node_mission -.->|"dispatches tasks"| node_task_states
node_task_states -.->|"uses behaviors"| node_mission_common
node_mission_common -->|"plans paths"| node_path_planners
node_mission_common -->|"sends goals"| node_follow_client
node_path_planners -->|"generates waypoints"| node_path_helpers
node_path_planners -.->|"provides paths"| node_follow_action
node_follow_client -.->|"sends action goals"| node_follow_action
node_follow_action -.->|"requests control"| node_controller_ros
node_controller_ros -->|"calls controller"| node_pid_controller
node_pid_controller -->|"uses model"| node_controller_model
node_controller_ros -.->|"publishes wrench"| node_thruster_manager
node_thruster_manager -->|"allocates thrust"| node_thruster_allocator
node_camera_nodes -.->|"provides images"| node_vision_nodes
node_vision_nodes -.->|"provides detections"| node_mapping
node_localization -.->|"provides pose"| node_mission_common
node_teleop -.->|"sends commands"| node_controller_ros
node_hardware_bridge -.->|"bridges device I/O"| node_thruster_manager
node_sim_mock -->|"publishes thruster inputs"| node_sim_thrusters

click node_mission "https://github.com/itu-auv/auv-software/blob/main/auv_smach/scripts/main_state_machine.py"
click node_task_states "https://github.com/itu-auv/auv-software/tree/main/auv_smach/src/auv_smach"
click node_mission_common "https://github.com/itu-auv/auv-software/blob/main/auv_smach/src/auv_smach/common.py"
click node_path_planners "https://github.com/itu-auv/auv-software/blob/main/auv_navigation/auv_navigation/src/auv_navigation/path_planning/path_planners.py"
click node_path_helpers "https://github.com/itu-auv/auv-software/blob/main/auv_navigation/auv_navigation/src/auv_navigation/path_planning/path_planning_helpers.py"
click node_follow_action "https://github.com/itu-auv/auv-software/blob/main/auv_navigation/auv_navigation/scripts/follow_path_action_server.py"
click node_follow_client "https://github.com/itu-auv/auv-software/blob/main/auv_navigation/auv_navigation/src/auv_navigation/follow_path_action/follow_path_client.py"
click node_controller_ros "https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_control/include/auv_control/controller_ros.h"
click node_pid_controller "https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_controllers/include/auv_controllers/multidof_pid_controller.h"
click node_controller_model "https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_controllers/include/auv_controllers/model.h"
click node_thruster_manager "https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_control/include/auv_control/thruster_manager_ros.h"
click node_thruster_allocator "https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_control/include/auv_control/thruster_allocation.h"
click node_camera_nodes "https://github.com/itu-auv/auv-software/tree/main/auv_hardware/auv_cam/src"
click node_vision_nodes "https://github.com/itu-auv/auv-software/tree/main/auv_vision/auv_vision/scripts"
click node_localization "https://github.com/itu-auv/auv-software/tree/main/auv_navigation/auv_localization/scripts"
click node_mapping "https://github.com/itu-auv/auv-software/tree/main/auv_navigation/auv_mapping"
click node_hardware_bridge "https://github.com/itu-auv/auv-software/blob/main/auv_hardware/auv_hardware_bridge/src/serial_to_ros_bridge.cpp"
click node_teleop "https://github.com/itu-auv/auv-software/blob/main/auv_teleop/scripts/taluy_gui.py"
click node_sim_mock "https://github.com/itu-auv/auv-software/blob/main/auv_sim/auv_sim_bridge/include/auv_sim_bridge/simulation_mock_ros.h"
click node_sim_thrusters "https://github.com/itu-auv/auv-software/blob/main/auv_sim/auv_sim_bridge/include/auv_sim_bridge/sim_thruster_ros.h"

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_mission,node_task_states,node_mission_common,node_path_planners,node_path_helpers,node_follow_action,node_follow_client toneBlue
class node_controller_ros,node_pid_controller,node_controller_model,node_thruster_manager,node_thruster_allocator toneAmber
class node_camera_nodes,node_vision_nodes,node_localization,node_mapping toneMint
class node_hardware_bridge,node_teleop toneRose
class node_sim_mock,node_sim_thrusters,node_operator toneIndigo
```

## Components

### Mission & Navigation

- [Mission State Machine](https://github.com/itu-auv/auv-software/blob/main/auv_smach/scripts/main_state_machine.py): `auv_smach/scripts/main_state_machine.py`
- [Task States](https://github.com/itu-auv/auv-software/tree/main/auv_smach/src/auv_smach): `auv_smach/src/auv_smach`
- [Mission Behaviors](https://github.com/itu-auv/auv-software/blob/main/auv_smach/src/auv_smach/common.py): `auv_smach/src/auv_smach/common.py`
- [Path Planners](https://github.com/itu-auv/auv-software/blob/main/auv_navigation/auv_navigation/src/auv_navigation/path_planning/path_planners.py): `auv_navigation/auv_navigation/src/auv_navigation/path_planning/path_planners.py`
- [Path Helpers](https://github.com/itu-auv/auv-software/blob/main/auv_navigation/auv_navigation/src/auv_navigation/path_planning/path_planning_helpers.py): `auv_navigation/auv_navigation/src/auv_navigation/path_planning/path_planning_helpers.py`
- [Follow Path Server](https://github.com/itu-auv/auv-software/blob/main/auv_navigation/auv_navigation/scripts/follow_path_action_server.py): `auv_navigation/auv_navigation/scripts/follow_path_action_server.py`
- [Follow Path Client](https://github.com/itu-auv/auv-software/blob/main/auv_navigation/auv_navigation/src/auv_navigation/follow_path_action/follow_path_client.py): `auv_navigation/auv_navigation/src/auv_navigation/follow_path_action/follow_path_client.py`

### Vehicle Control

- [ROS Controller](https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_control/include/auv_control/controller_ros.h): `auv_control/auv_control/include/auv_control/controller_ros.h`
- [6-DOF PID](https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_controllers/include/auv_controllers/multidof_pid_controller.h): `auv_control/auv_controllers/include/auv_controllers/multidof_pid_controller.h`
- [Vehicle Model](https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_controllers/include/auv_controllers/model.h): `auv_control/auv_controllers/include/auv_controllers/model.h`
- [Thruster Manager](https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_control/include/auv_control/thruster_manager_ros.h): `auv_control/auv_control/include/auv_control/thruster_manager_ros.h`
- [Thruster Allocator](https://github.com/itu-auv/auv-software/blob/main/auv_control/auv_control/include/auv_control/thruster_allocation.h): `auv_control/auv_control/include/auv_control/thruster_allocation.h`

### Sensing & Mapping

- [Camera Nodes](https://github.com/itu-auv/auv-software/tree/main/auv_hardware/auv_cam/src): `auv_hardware/auv_cam/src`
- [Vision & Detection](https://github.com/itu-auv/auv-software/tree/main/auv_vision/auv_vision/scripts): `auv_vision/auv_vision/scripts`
- [Localization](https://github.com/itu-auv/auv-software/tree/main/auv_navigation/auv_localization/scripts): `auv_navigation/auv_localization/scripts`
- [Mapping & Objects](https://github.com/itu-auv/auv-software/tree/main/auv_navigation/auv_mapping): `auv_navigation/auv_mapping`

### Hardware & Teleop

- [Serial Bridge](https://github.com/itu-auv/auv-software/blob/main/auv_hardware/auv_hardware_bridge/src/serial_to_ros_bridge.cpp): `auv_hardware/auv_hardware_bridge/src/serial_to_ros_bridge.cpp`
- [Teleoperation GUI](https://github.com/itu-auv/auv-software/blob/main/auv_teleop/scripts/taluy_gui.py): `auv_teleop/scripts/taluy_gui.py`

### Simulation

- [Simulation Mock](https://github.com/itu-auv/auv-software/blob/main/auv_sim/auv_sim_bridge/include/auv_sim_bridge/simulation_mock_ros.h): `auv_sim/auv_sim_bridge/include/auv_sim_bridge/simulation_mock_ros.h`
- [Sim Thrusters](https://github.com/itu-auv/auv-software/blob/main/auv_sim/auv_sim_bridge/include/auv_sim_bridge/sim_thruster_ros.h): `auv_sim/auv_sim_bridge/include/auv_sim_bridge/sim_thruster_ros.h`

### Other components

- **Operator**

## Connections

- Operator → Mission State Machine: starts missions
- Mission State Machine → Task States: dispatches tasks
- Task States → Mission Behaviors: uses behaviors (evidence: `auv_smach/src/auv_smach/pipeline.py`)
- Mission Behaviors → Path Planners: plans paths (evidence: `auv_smach/src/auv_smach/common.py`)
- Mission Behaviors → Follow Path Client: sends goals (evidence: `auv_smach/src/auv_smach/common.py`)
- Path Planners → Path Helpers: generates waypoints (evidence: `auv_navigation/auv_navigation/src/auv_navigation/path_planning/path_planners.py`)
- Path Planners → Follow Path Server: provides paths
- Follow Path Client → Follow Path Server: sends action goals
- Follow Path Server → ROS Controller: requests control
- ROS Controller → 6-DOF PID: calls controller (evidence: `auv_control/auv_control/include/auv_control/controller_ros.h`)
- 6-DOF PID → Vehicle Model: uses model
- ROS Controller → Thruster Manager: publishes wrench
- Thruster Manager → Thruster Allocator: allocates thrust (evidence: `auv_control/auv_control/include/auv_control/thruster_manager_ros.h`)
- Camera Nodes → Vision & Detection: provides images
- Vision & Detection → Mapping & Objects: provides detections
- Localization → Mission Behaviors: provides pose
- Teleoperation GUI → ROS Controller: sends commands
- Serial Bridge → Thruster Manager: bridges device I/O
- Simulation Mock → Sim Thrusters: publishes thruster inputs (evidence: `auv_sim/auv_sim_bridge/include/auv_sim_bridge/simulation_mock_ros.h`)
