# alaaradhwan/underwater-rocket-esp32-firmware architecture

> Architecture diagram of the GitHub repository alaaradhwan/underwater-rocket-esp32-firmware, 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/alaaradhwan/underwater-rocket-esp32-firmware
- Repository: https://github.com/alaaradhwan/underwater-rocket-esp32-firmware

## Overview

This is a portfolio repository for ESP32 underwater-vehicle attitude control, with three firmware generations, an earlier WebSocket PID-tuning prototype, and a MATLAB/Simulink study. The principal documented workflow is operator input plus IMU measurements, attitude estimation and heading/control logic, then fin actuation and throttle output. The Aug 2025 workflow is best documented; other firmware and simulation branches are represented without assuming their unsampled internal wiring. Edges are limited to README relationships and excerpt/index-supported references.

Main entry points: [`firmware/graduation_aug26_ps5_heading_hold/src/main.cpp`](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/src/main.cpp) (PS5 Runtime), [`prototypes/2025_early_websocket_pid_tuner/lib/WebServer_Module/WebServer_Module.cpp`](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/prototypes/2025_early_websocket_pid_tuner/lib/WebServer_Module/WebServer_Module.cpp) (WebSocket Server), [`prototypes/2025_early_websocket_pid_tuner/src/main.cpp`](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/prototypes/2025_early_websocket_pid_tuner/src/main.cpp) (WebSocket Runtime), [`firmware/graduation_aug26_ps5_heading_hold/lib/Servo_Controller/Servo_Controller.cpp`](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/lib/Servo_Controller/Servo_Controller.cpp) (Fin Control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_aug["Graduation Firmware"]
  node_augmain["PS5 Runtime<br/>[main.cpp]"]
  node_augest["Attitude Estimate<br/>[main.cpp]"]
  node_augcontrol["Fin Control"]
  node_augservo["PCA9685 Outputs<br/>[Servo_Module.h]"]
  node_augmotor["ESC Throttle<br/>[Motor_Module.cpp]"]
end

subgraph group_mission["Mission Firmware"]
  node_missionmain["Mission Runtime<br/>[main.cpp]"]
  node_missioncontrol["Mission Fin Control"]
  node_missionoutputs["PCA9685 Outputs<br/>[Servo_Module.cpp]"]
end

subgraph group_wifi["Wi-Fi Firmware"]
  node_wifimain["Browser Runtime<br/>[main.cpp]"]
  node_wificontrol["Stabilization Control"]
  node_wifioutputs["PCA9685 Outputs<br/>[Servo_Module.cpp]"]
end

subgraph group_prototype["Tuning Prototype"]
  node_webmain["WebSocket Runtime<br/>[main.cpp]"]
  node_webserver["WebSocket Server"]
  node_rocketctrl["PID Tuning Control"]
  node_webui["Tuning Web UI<br/>[script.js]"]
end

subgraph group_sim["Simulation"]
  node_simmodel["Pitch-Yaw-Depth Model"]
  node_simpid["Discrete PID Simulation<br/>[main.m]"]
end

node_operator(("PS5 Operator"))
node_imu{{"IMU Sensor"}}
node_fins{{"Fin Servos"}}
node_esc{{"ESC"}}
node_browser(("Browser Operator"))

node_operator -->|"sets mode/throttle"| node_augmain
node_imu -->|"supplies readings"| node_augmain
node_augmain -->|"estimates attitude"| node_augest
node_augmain -->|"updates control"| node_augcontrol
node_augcontrol -->|"writes fin angles"| node_augservo
node_augservo -->|"drives"| node_fins
node_augmain -->|"sets throttle"| node_augmotor
node_augmotor -->|"drives"| node_esc
node_missionmain -.->|"uses controller"| node_missioncontrol
node_missioncontrol -->|"writes fin angles"| node_missionoutputs
node_browser -->|"sends commands"| node_wifimain
node_wifimain -.->|"stabilizes attitude"| node_wificontrol
node_wificontrol -.->|"writes fin angles"| node_wifioutputs
node_webui -.->|"exchanges commands"| node_webserver
node_webmain -->|"registers commands"| node_webserver
node_webmain -->|"updates controller"| node_rocketctrl
node_rocketctrl -.->|"writes fin servos"| node_webserver
node_simpid -.->|"simulates dynamics"| node_simmodel

click node_augmain "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/src/main.cpp"
click node_augest "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/src/main.cpp"
click node_augcontrol "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/lib/Servo_Controller/Servo_Controller.cpp"
click node_augservo "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/lib/Servo_Module/Servo_Module.h"
click node_augmotor "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/lib/Motor_Module/Motor_Module.cpp"
click node_missionmain "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2025_teknofest_mission/src/main.cpp"
click node_missioncontrol "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2025_teknofest_mission/lib/Servo_Controller/Servo_Controller.cpp"
click node_missionoutputs "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2025_teknofest_mission/lib/Servo_Module/Servo_Module.cpp"
click node_wifimain "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2026_wifi_control/src/main.cpp"
click node_wificontrol "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2026_wifi_control/lib/Servo_Controller/Servo_Controller.cpp"
click node_wifioutputs "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2026_wifi_control/lib/Servo_Module/Servo_Module.cpp"
click node_webmain "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/prototypes/2025_early_websocket_pid_tuner/src/main.cpp"
click node_webserver "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/prototypes/2025_early_websocket_pid_tuner/lib/WebServer_Module/WebServer_Module.cpp"
click node_rocketctrl "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/prototypes/2025_early_websocket_pid_tuner/lib/Rocket_Controller/Rocket_Controller.cpp"
click node_webui "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/prototypes/2025_early_websocket_pid_tuner/Rocket_Web/script.js"
click node_simmodel "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/simulation/graduation_2025/rocket_pitch_dynamics.m"
click node_simpid "https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/simulation/graduation_2025/main.m"

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_augmain,node_augest,node_augcontrol,node_augservo,node_augmotor,node_browser toneBlue
class node_missionmain,node_missioncontrol,node_missionoutputs toneAmber
class node_wifimain,node_wificontrol,node_wifioutputs toneMint
class node_webmain,node_webserver,node_rocketctrl,node_webui toneRose
class node_simmodel,node_simpid,node_operator,node_imu,node_fins,node_esc toneIndigo
```

## Components

### Graduation Firmware

- [PS5 Runtime](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/src/main.cpp): `firmware/graduation_aug26_ps5_heading_hold/src/main.cpp`
- [Attitude Estimate](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/src/main.cpp): `firmware/graduation_aug26_ps5_heading_hold/src/main.cpp`
- [Fin Control](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/lib/Servo_Controller/Servo_Controller.cpp): `firmware/graduation_aug26_ps5_heading_hold/lib/Servo_Controller/Servo_Controller.cpp`
- [PCA9685 Outputs](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/lib/Servo_Module/Servo_Module.h): `firmware/graduation_aug26_ps5_heading_hold/lib/Servo_Module/Servo_Module.h`
- [ESC Throttle](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/graduation_aug26_ps5_heading_hold/lib/Motor_Module/Motor_Module.cpp): `firmware/graduation_aug26_ps5_heading_hold/lib/Motor_Module/Motor_Module.cpp`

### Mission Firmware

- [Mission Runtime](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2025_teknofest_mission/src/main.cpp): `firmware/2025_teknofest_mission/src/main.cpp`
- [Mission Fin Control](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2025_teknofest_mission/lib/Servo_Controller/Servo_Controller.cpp): `firmware/2025_teknofest_mission/lib/Servo_Controller/Servo_Controller.cpp`
- [PCA9685 Outputs](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2025_teknofest_mission/lib/Servo_Module/Servo_Module.cpp): `firmware/2025_teknofest_mission/lib/Servo_Module/Servo_Module.cpp`

### Wi-Fi Firmware

- [Browser Runtime](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2026_wifi_control/src/main.cpp): `firmware/2026_wifi_control/src/main.cpp`
- [Stabilization Control](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2026_wifi_control/lib/Servo_Controller/Servo_Controller.cpp): `firmware/2026_wifi_control/lib/Servo_Controller/Servo_Controller.cpp`
- [PCA9685 Outputs](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/firmware/2026_wifi_control/lib/Servo_Module/Servo_Module.cpp): `firmware/2026_wifi_control/lib/Servo_Module/Servo_Module.cpp`

### Tuning Prototype

- [WebSocket Runtime](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/prototypes/2025_early_websocket_pid_tuner/src/main.cpp): `prototypes/2025_early_websocket_pid_tuner/src/main.cpp`
- [WebSocket Server](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/prototypes/2025_early_websocket_pid_tuner/lib/WebServer_Module/WebServer_Module.cpp): `prototypes/2025_early_websocket_pid_tuner/lib/WebServer_Module/WebServer_Module.cpp`
- [PID Tuning Control](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/prototypes/2025_early_websocket_pid_tuner/lib/Rocket_Controller/Rocket_Controller.cpp): `prototypes/2025_early_websocket_pid_tuner/lib/Rocket_Controller/Rocket_Controller.cpp`
- [Tuning Web UI](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/prototypes/2025_early_websocket_pid_tuner/Rocket_Web/script.js): `prototypes/2025_early_websocket_pid_tuner/Rocket_Web/script.js`

### Simulation

- [Pitch-Yaw-Depth Model](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/simulation/graduation_2025/rocket_pitch_dynamics.m): `simulation/graduation_2025/rocket_pitch_dynamics.m`
- [Discrete PID Simulation](https://github.com/alaaradhwan/underwater-rocket-esp32-firmware/blob/main/simulation/graduation_2025/main.m): `simulation/graduation_2025/main.m`

### Other components

- **PS5 Operator**
- **IMU Sensor**
- **Fin Servos**
- **ESC**
- **Browser Operator**

## Connections

- PS5 Operator → PS5 Runtime: sets mode/throttle (evidence: `README.md`)
- IMU Sensor → PS5 Runtime: supplies readings (evidence: `README.md`)
- PS5 Runtime → Attitude Estimate: estimates attitude (evidence: `README.md`)
- PS5 Runtime → Fin Control: updates control (evidence: `README.md`)
- Fin Control → PCA9685 Outputs: writes fin angles (evidence: `firmware/graduation_aug26_ps5_heading_hold/lib/Servo_Controller/Servo_Controller.cpp`)
- PCA9685 Outputs → Fin Servos: drives (evidence: `README.md`)
- PS5 Runtime → ESC Throttle: sets throttle (evidence: `README.md`)
- ESC Throttle → ESC: drives (evidence: `README.md`)
- Mission Runtime → Mission Fin Control: uses controller
- Mission Fin Control → PCA9685 Outputs: writes fin angles (evidence: `firmware/2025_teknofest_mission/lib/Servo_Controller/Servo_Controller.cpp`)
- Browser Operator → Browser Runtime: sends commands (evidence: `README.md`)
- Browser Runtime → Stabilization Control: stabilizes attitude
- Stabilization Control → PCA9685 Outputs: writes fin angles
- Tuning Web UI → WebSocket Server: exchanges commands
- WebSocket Runtime → WebSocket Server: registers commands (evidence: `prototypes/2025_early_websocket_pid_tuner/src/main.cpp`)
- WebSocket Runtime → PID Tuning Control: updates controller (evidence: `prototypes/2025_early_websocket_pid_tuner/src/main.cpp`)
- PID Tuning Control → WebSocket Server: writes fin servos
- Discrete PID Simulation → Pitch-Yaw-Depth Model: simulates dynamics
