# horizon-fyz/esp32-s3-below architecture

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

- Interactive diagram: https://gitdiagram.com/horizon-fyz/esp32-s3-below
- Repository: https://github.com/horizon-fyz/esp32-s3-below

## Overview

This firmware is an ESP32-S3 underwater robot remote execution node. The principal workflow is a TCP command from the surface controller, parsed and dispatched by the application, then applied to horizontal thrusters, ballast thrusters, bucket motor, or light; sensor and controller status is reported back. The vertical-control branch combines depth and attitude feedback with PID and motor allocation. Network-driver internals are shown as a supporting layer. README documents additional console and ESC-test modes; source excerpts are partial, so uncertain internal links are omitted.

Main entry points: [`main/main.c`](https://github.com/horizon-fyz/esp32-s3-below/blob/main/main/main.c) (Remote-node application), [`components/vertical_ctrl/vertical_ctrl.c`](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/vertical_ctrl/vertical_ctrl.c) (Vertical control), [`components/wiznet/src/wiznet_manager.c`](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/src/wiznet_manager.c) (Network manager), [`components/wiznet/src/wiznet_socket.c`](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/src/wiznet_socket.c) (Socket wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application workflow"]
  node_app["Remote-node application<br/>[main.c]"]
  node_protocol["Frame protocol<br/>[control.c]"]
end

subgraph group_control["Actuation and sensing"]
  node_vctrl["Vertical control<br/>[vertical_ctrl.c]"]
  node_pid["PID loops<br/>[pid.c]"]
  node_imu["UART IMU<br/>[imu.c]"]
  node_depth["MS5837 pressure<br/>[ms5837.c]"]
  node_motor["Motor outputs<br/>[motor.c]"]
end

subgraph group_network["W5500 networking"]
  node_manager["Network manager<br/>[wiznet_manager.c]"]
  node_spi["SPI bridge<br/>[wiznet_spi.c]"]
  node_socketwrap["Socket wrapper<br/>[wiznet_socket.c]"]
  node_ethsocket["ioLibrary sockets<br/>[socket.c]"]
  node_wizchip["W5500 configuration<br/>[wizchip_conf.c]"]
  node_w5500["W5500 driver<br/>[w5500.c]"]
end

subgraph group_diagnostics["Test mode"]
  node_esc["ESC test mode<br/>[esc_test.c]"]
end

node_controller(("Surface controller"))

node_controller -->|"sends commands"| node_app
node_app -->|"uses frames"| node_protocol
node_app -->|"initializes network"| node_manager
node_app -->|"uses sockets"| node_socketwrap
node_app -->|"starts control"| node_vctrl
node_app -->|"initializes IMU"| node_imu
node_app -->|"configures depth"| node_depth
node_app -->|"dispatches outputs"| node_motor
node_app -->|"reports status"| node_controller
node_vctrl -->|"runs loops"| node_pid
node_vctrl -->|"reads attitude"| node_imu
node_vctrl -->|"reads depth"| node_depth
node_vctrl -->|"sets thrusters"| node_motor
node_manager -->|"configures bridge"| node_spi
node_manager -->|"initializes chip"| node_wizchip
node_socketwrap -->|"wraps calls"| node_ethsocket
node_wizchip -->|"configures driver"| node_w5500
node_app -->|"selects test mode"| node_esc

click node_app "https://github.com/horizon-fyz/esp32-s3-below/blob/main/main/main.c"
click node_protocol "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/control/control.c"
click node_vctrl "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/vertical_ctrl/vertical_ctrl.c"
click node_pid "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/vertical_ctrl/pid.c"
click node_imu "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/imu/imu.c"
click node_depth "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/ms5837/ms5837.c"
click node_motor "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/motor/motor.c"
click node_manager "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/src/wiznet_manager.c"
click node_spi "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/src/wiznet_spi.c"
click node_socketwrap "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/src/wiznet_socket.c"
click node_ethsocket "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/Ethernet/socket.c"
click node_wizchip "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/Ethernet/wizchip_conf.c"
click node_w5500 "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/Ethernet/W5500/w5500.c"
click node_esc "https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/esc_test/esc_test.c"

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_app,node_protocol toneBlue
class node_vctrl,node_pid,node_imu,node_depth,node_motor toneAmber
class node_manager,node_spi,node_socketwrap,node_ethsocket,node_wizchip,node_w5500 toneMint
class node_esc toneRose
class node_controller toneIndigo
```

## Components

### Application workflow

- [Remote-node application](https://github.com/horizon-fyz/esp32-s3-below/blob/main/main/main.c): `main/main.c`
- [Frame protocol](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/control/control.c): `components/control/control.c`

### Actuation and sensing

- [Vertical control](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/vertical_ctrl/vertical_ctrl.c): `components/vertical_ctrl/vertical_ctrl.c`
- [PID loops](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/vertical_ctrl/pid.c): `components/vertical_ctrl/pid.c`
- [UART IMU](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/imu/imu.c): `components/imu/imu.c`
- [MS5837 pressure](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/ms5837/ms5837.c): `components/ms5837/ms5837.c`
- [Motor outputs](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/motor/motor.c): `components/motor/motor.c`

### W5500 networking

- [Network manager](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/src/wiznet_manager.c): `components/wiznet/src/wiznet_manager.c`
- [SPI bridge](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/src/wiznet_spi.c): `components/wiznet/src/wiznet_spi.c`
- [Socket wrapper](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/src/wiznet_socket.c): `components/wiznet/src/wiznet_socket.c`
- [ioLibrary sockets](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/Ethernet/socket.c): `components/wiznet/Ethernet/socket.c`
- [W5500 configuration](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/Ethernet/wizchip_conf.c): `components/wiznet/Ethernet/wizchip_conf.c`
- [W5500 driver](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/wiznet/Ethernet/W5500/w5500.c): `components/wiznet/Ethernet/W5500/w5500.c`

### Test mode

- [ESC test mode](https://github.com/horizon-fyz/esp32-s3-below/blob/main/components/esc_test/esc_test.c): `components/esc_test/esc_test.c`

### Other components

- **Surface controller**

## Connections

- Surface controller → Remote-node application: sends commands (evidence: `README.md`)
- Remote-node application → Frame protocol: uses frames (evidence: `main/main.c`)
- Remote-node application → Network manager: initializes network (evidence: `main/main.c`)
- Remote-node application → Socket wrapper: uses sockets (evidence: `main/main.c`)
- Remote-node application → Vertical control: starts control (evidence: `main/main.c`)
- Remote-node application → UART IMU: initializes IMU (evidence: `main/main.c`)
- Remote-node application → MS5837 pressure: configures depth (evidence: `main/main.c`)
- Remote-node application → Motor outputs: dispatches outputs (evidence: `main/main.c`)
- Remote-node application → Surface controller: reports status (evidence: `README.md`)
- Vertical control → PID loops: runs loops (evidence: `components/vertical_ctrl/vertical_ctrl.c`)
- Vertical control → UART IMU: reads attitude (evidence: `components/vertical_ctrl/vertical_ctrl.c`)
- Vertical control → MS5837 pressure: reads depth
- Vertical control → Motor outputs: sets thrusters (evidence: `components/vertical_ctrl/vertical_ctrl.c`)
- Network manager → SPI bridge: configures bridge (evidence: `components/wiznet/src/wiznet_manager.c`)
- Network manager → W5500 configuration: initializes chip (evidence: `components/wiznet/src/wiznet_manager.c`)
- Socket wrapper → ioLibrary sockets: wraps calls (evidence: `components/wiznet/src/wiznet_socket.c`)
- W5500 configuration → W5500 driver: configures driver
- Remote-node application → ESC test mode: selects test mode (evidence: `main/main.c`)