# horizon-fyz/esp32-s3-above architecture

> Architecture diagram of the GitHub repository horizon-fyz/esp32-s3-above, 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-above
- Repository: https://github.com/horizon-fyz/esp32-s3-above

## Overview

This firmware is an ESP32-S3 surface-robot controller. The main workflow is a host sending TCP control frames: the application parses them, mixes propulsion commands, and drives the ESCs and drum motor; it also accepts console commands and reports navigation/status data. Other documented capabilities include gimbal positioning, optional MPU-based stabilization, and W5500 networking. The README establishes several subsystem links; sampled source confirms the network manager’s SPI and chip initialization. Unsampled runtime details are not expanded beyond documented behavior.

Main entry points: [`main/main.c`](https://github.com/horizon-fyz/esp32-s3-above/blob/main/main/main.c) (Application Runtime), [`components/wiznet/src/wiznet_manager.c`](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/src/wiznet_manager.c) (Network Manager), [`components/gimbal/gimbal.c`](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/gimbal/gimbal.c) (Gimbal Planner), [`components/nav/nav.c`](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/nav/nav.c) (Navigation Driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main_app["Application Runtime<br/>[main.c]"]
  node_console["Serial Console<br/>[main.c]"]
end

subgraph group_network["W5500 Networking"]
  node_network_manager["Network Manager<br/>[wiznet_manager.c]"]
  node_spi_bridge["SPI Bridge<br/>[wiznet_spi.c]"]
  node_socket_api["Socket Wrappers<br/>[wiznet_socket.c]"]
  node_socket_stack["TCP Socket Stack<br/>[socket.c]"]
  node_chip_driver["W5500 Driver<br/>[w5500.c]"]
end

subgraph group_control["Control and Motion"]
  node_control_protocol["Frame Protocol<br/>[control.c]"]
  node_motor_control["Motor Control<br/>[motor.c]"]
  node_gimbal_planner["Gimbal Planner<br/>[gimbal.c]"]
  node_servo_driver["Servo Driver<br/>[servo.c]"]
end

subgraph group_sensing["Sensors and Telemetry"]
  node_imu_driver["Gimbal IMU<br/>[imu.c]"]
  node_nav_driver["Navigation Driver<br/>[nav.c]"]
end

node_host(("Control Host"))
node_navigation_module(("Navigation Module"))

node_host -->|"sends frames"| node_main_app
node_main_app -->|"starts networking"| node_network_manager
node_main_app -->|"serves TCP"| node_socket_api
node_socket_api -->|"wraps calls"| node_socket_stack
node_network_manager -->|"initializes"| node_spi_bridge
node_network_manager -->|"configures"| node_chip_driver
node_main_app -->|"parses commands"| node_control_protocol
node_control_protocol -->|"calls callback"| node_main_app
node_main_app -->|"applies drive"| node_motor_control
node_main_app -->|"handles commands"| node_console
node_main_app -->|"sets position"| node_gimbal_planner
node_gimbal_planner -->|"writes trajectories"| node_servo_driver
node_main_app -->|"initializes"| node_servo_driver
node_main_app -->|"starts navigation"| node_nav_driver
node_navigation_module -->|"streams UART data"| node_nav_driver
node_nav_driver -->|"provides snapshots"| node_main_app
node_main_app -->|"sends telemetry"| node_host
node_main_app -->|"initializes optionally"| node_imu_driver
node_imu_driver -.->|"feeds attitude"| node_gimbal_planner

click node_main_app "https://github.com/horizon-fyz/esp32-s3-above/blob/main/main/main.c"
click node_console "https://github.com/horizon-fyz/esp32-s3-above/blob/main/main/main.c"
click node_control_protocol "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/control/control.c"
click node_motor_control "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/motor/motor.c"
click node_gimbal_planner "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/gimbal/gimbal.c"
click node_servo_driver "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/servo/servo.c"
click node_imu_driver "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/imu/imu.c"
click node_nav_driver "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/nav/nav.c"
click node_network_manager "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/src/wiznet_manager.c"
click node_spi_bridge "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/src/wiznet_spi.c"
click node_socket_api "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/src/wiznet_socket.c"
click node_socket_stack "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/Ethernet/socket.c"
click node_chip_driver "https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/Ethernet/W5500/w5500.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_main_app,node_console toneBlue
class node_network_manager,node_spi_bridge,node_socket_api,node_socket_stack,node_chip_driver toneAmber
class node_control_protocol,node_motor_control,node_gimbal_planner,node_servo_driver toneMint
class node_imu_driver,node_nav_driver toneRose
class node_host,node_navigation_module toneIndigo
```

## Components

### Application

- [Application Runtime](https://github.com/horizon-fyz/esp32-s3-above/blob/main/main/main.c): `main/main.c`
- [Serial Console](https://github.com/horizon-fyz/esp32-s3-above/blob/main/main/main.c): `main/main.c`

### W5500 Networking

- [Network Manager](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/src/wiznet_manager.c): `components/wiznet/src/wiznet_manager.c`
- [SPI Bridge](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/src/wiznet_spi.c): `components/wiznet/src/wiznet_spi.c`
- [Socket Wrappers](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/src/wiznet_socket.c): `components/wiznet/src/wiznet_socket.c`
- [TCP Socket Stack](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/Ethernet/socket.c): `components/wiznet/Ethernet/socket.c`
- [W5500 Driver](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/wiznet/Ethernet/W5500/w5500.c): `components/wiznet/Ethernet/W5500/w5500.c`

### Control and Motion

- [Frame Protocol](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/control/control.c): `components/control/control.c`
- [Motor Control](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/motor/motor.c): `components/motor/motor.c`
- [Gimbal Planner](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/gimbal/gimbal.c): `components/gimbal/gimbal.c`
- [Servo Driver](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/servo/servo.c): `components/servo/servo.c`

### Sensors and Telemetry

- [Gimbal IMU](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/imu/imu.c): `components/imu/imu.c`
- [Navigation Driver](https://github.com/horizon-fyz/esp32-s3-above/blob/main/components/nav/nav.c): `components/nav/nav.c`

### Other components

- **Control Host**
- **Navigation Module**

## Connections

- Control Host → Application Runtime: sends frames (evidence: `README.md`)
- Application Runtime → Network Manager: starts networking (evidence: `main/main.c`)
- Application Runtime → Socket Wrappers: serves TCP (evidence: `main/main.c`)
- Socket Wrappers → TCP Socket Stack: wraps calls
- Network Manager → SPI Bridge: initializes (evidence: `components/wiznet/src/wiznet_manager.c`)
- Network Manager → W5500 Driver: configures (evidence: `components/wiznet/src/wiznet_manager.c`)
- Application Runtime → Frame Protocol: parses commands (evidence: `README.md`)
- Frame Protocol → Application Runtime: calls callback
- Application Runtime → Motor Control: applies drive (evidence: `README.md`)
- Application Runtime → Serial Console: handles commands (evidence: `README.md`)
- Application Runtime → Gimbal Planner: sets position (evidence: `README.md`)
- Gimbal Planner → Servo Driver: writes trajectories
- Application Runtime → Servo Driver: initializes (evidence: `main/main.c`)
- Application Runtime → Navigation Driver: starts navigation (evidence: `README.md`)
- Navigation Module → Navigation Driver: streams UART data (evidence: `README.md`)
- Navigation Driver → Application Runtime: provides snapshots
- Application Runtime → Control Host: sends telemetry (evidence: `README.md`)
- Application Runtime → Gimbal IMU: initializes optionally (evidence: `main/main.c`)
- Gimbal IMU → Gimbal Planner: feeds attitude
