# circuit-digest/esp-drone architecture

> Architecture diagram of the GitHub repository circuit-digest/esp-drone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/circuit-digest/esp-drone
- Repository: https://github.com/circuit-digest/esp-drone

## Overview

1. **Repository shape**
   - This repo is split into two major domains: **Firmware** for the ESP32-based drone controller, and **Hardware** for the KiCad board design, BOM, Gerbers, and production outputs.
   - The firmware is the runtime system; the hardware folder defines the physical drone electronics and PCB layout.

2. **Firmware technology stack**
   - The firmware is an **ESP-IDF** project for the ESP32, built with **FreeRTOS** and CMake/Ninja.
   - The compiled app is flashed as a bootloader, partition table, and main application binary at fixed offsets:
     - bootloader at `0x1000`
     - partition table at `0x8000`
     - app at `0x10000`

3. **Top-level firmware entry point**
   - `Firmware/esp-drone/main/main.c` is the application entry point.
   - From there, control is handed into the project’s component graph, which is organized around the Crazyflie firmware architecture and ESP32-specific drivers.

4. **Core control stack**
   - `components/core/crazyflie` is the heart of the flight-control logic.
   - It contains three important layers:
     - **HAL**: hardware abstraction for sensors, links, timing, power, storage, and actuators
     - **Modules**: stabilization, estimation, command routing, logging, parameters, planners, and services
     - **Utils**: math, filtering, calibration, timing helpers, CRC, and storage support
   - This is where the flight behavior, telemetry, and control-loop orchestration live.

5. **Primary data flow: sensor → estimate → control → motors**
   - Sensor data comes in through drivers for the IMU and other optional sensors.
   - That data is processed by estimation modules such as complementary/Kalman estimators and fusion code.
   - The stabilizer and controller modules compute motor outputs.
   - Motor commands are finally emitted through the motor driver layer.
   - This closed loop is the central architectural path for flight.

6. **ESP32-specific driver layer**
   - `components/drivers` contains the board-specific implementations that back the core HAL.
   - Key subgroups:
     - **general**: motors, LEDs, buzzer, Wi-Fi, ADC
     - **i2c_bus**: shared I2C transport
     - **i2c_devices**: MPU6050 IMU, HMC5883L magnetometer, MS5611 barometer, VL53L0/VL53L1 ranging sensors, EEPROM
     - **spi_devices**: PMW3901 optical-flow sensor
     - **deck**: connector/expansion board support
   - These are the concrete hardware adapters used by the flight stack.

7. **Board/platform abstraction**
   - `components/platform` separates board-level behavior from the rest of the firmware.
   - The presence of `platform_esp32.c`, `platform_cf2.c`, and `stm32_legacy.h` suggests the codebase carries compatibility with Crazyflie-style platforms while mapping them onto ESP32 hardware.
   - `components/config` holds board configuration headers such as `config.h` and interrupt/NVIC-related settings.

8. **Connectivity and control links**
   - Wi-Fi is a first-class control path via the `wifi` driver and Crazyflie link modules such as `wifilink`, `crtp`, `comm`, and `commander`.
   - The control protocol appears to be Crazyflie-compatible CRTP-based messaging, used for command input, telemetry, logging, and parameter updates.
   - The README indicates the drone is intended for **phone-based Wi-Fi control**.

9. **Telemetry, configuration, and services**
   - The firmware includes modules for:
     - **logging** and **parameter management**
     - **console/CLI**
     - **system load and diagnostics**
     - **storage/config blocks**
     - **high-level command handling**
   - These subsystems are important because they provide tuning, debugging, and runtime observability beyond the core stabilization loop.

10. **Optional sensing and advanced navigation support**
    - The codebase contains support for additional sensors and features beyond a minimal quadcopter:
      - altitude/height hold via barometer or range sensors
      - position-related modules and optical flow support
      - lighthouse/TD0A-related utility code inherited from Crazyflie-style navigation stacks
    - The README specifically mentions **height hold** and **position hold** as later capabilities.

11. **Math/DSP support**
    - `components/lib/dsp_lib` is an Xtensa-optimized math/DSP library.
    - It supports filtering, transforms, matrix math, and PID helpers needed for real-time control and sensor fusion on the ESP32.
    - This matters architecturally because the control loop depends on low-latency numeric processing.

12. **Build and artifact boundaries**
    - The checked-in `build/` tree contains the generated binaries, linker artifacts, and dependency libraries from a completed ESP-IDF build.
    - The project is therefore not just source code; it also includes reproducible flash outputs and linker/partition metadata.

13. **Hardware subsystem**
    - `Hardware/` contains the PCB and manufacturing assets: schematic, PCB layout, interactive BOM, netlist, positions, Gerbers, and production ZIPs.
    - The hardware appears designed around the same sensor/actuator stack assumed by the firmware: ESP32, IMU, motor outputs, and supporting peripherals.
    - This is the physical boundary where firmware assumptions become wiring, power, and component placement.

14. **Diagram-friendly summary**
    - The key architecture to diagram is:
      - **Phone/user control over Wi-Fi**
      - into **ESP32 communications modules**
      - into **Crazyflie command/stabilization/estimation logic**
      - fed by **sensor drivers**
      - driving **motor outputs**
      - with **config/log/CLI/storage** as supporting subsystems
      - all mapped onto a **custom KiCad-designed PCB**.

Main entry points: [`Firmware/esp-drone/components/core/crazyflie/modules`](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/core/crazyflie/modules) (Modules), [`Firmware/esp-drone/components/drivers`](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers) (Drivers), [`Firmware/esp-drone/components/core/crazyflie/modules/src/stabilizer.c`](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/stabilizer.c) (Control loop), [`Firmware/esp-drone/build`](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/build) (Build tree)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware"]
  node_main["Main app<br/>entrypoint<br/>[main.c]"]
  node_platform["Platform<br/>board layer"]
  node_drivers["Drivers<br/>device adapters"]
  node_crazyflie_hal["HAL<br/>hardware abstraction"]
  node_crazyflie_modules["Modules<br/>flight logic"]
  node_crazyflie_utils["Utils<br/>math/support"]
  node_dsp_lib["DSP lib<br/>xtensa math"]
  node_wifi["Wi-Fi<br/>link transport"]
  node_sensors["Sensors<br/>imu & env"]
  node_range_flow["Range/flow<br/>nav sensing"]
  node_motors["Motors<br/>actuator driver"]
  node_console["Console<br/>cli service<br/>[console.c]"]
  node_log_param["Log/param<br/>telemetry config<br/>[log.c]"]
  node_stabilize_estimate(("Control loop<br/>flight loop<br/>[stabilizer.c]"))
  node_commander["Commander<br/>command path<br/>[commander.c]"]
  node_crtp["CRTP<br/>protocol<br/>[crtp.c]"]
  node_storage["Storage<br/>persistent state<br/>[storage.c]"]
end

subgraph group_hardware["Hardware"]
  node_hardware_board["PCB design<br/>kicad board"]
  node_hardware_prod["Production<br/>manufacturing"]
end

subgraph group_artifacts["Artifacts"]
  node_firmware_build[("Build tree<br/>esp-idf build")]
  node_bootloader["Bootloader<br/>flash image<br/>[bootloader.bin]"]
  node_partition_table["Partition table<br/>flash image"]
  node_app_bin["App binary<br/>flash image<br/>[ESPDrone.bin]"]
end

node_readme["Project map<br/>docs<br/>[README.md]"]

node_readme -->|"describes"| node_main
node_readme -->|"describes"| node_hardware_board
node_main -->|"starts on"| node_platform
node_main -->|"enters"| node_crazyflie_modules
node_platform -->|"binds"| node_drivers
node_drivers -->|"implements"| node_wifi
node_drivers -->|"implements"| node_sensors
node_drivers -->|"implements"| node_range_flow
node_drivers -->|"implements"| node_motors
node_crazyflie_modules -->|"uses"| node_crazyflie_hal
node_crazyflie_modules -->|"orchestrates"| node_stabilize_estimate
node_crazyflie_modules -->|"routes"| node_commander
node_crazyflie_modules -->|"speaks"| node_crtp
node_crazyflie_modules -->|"exposes"| node_console
node_crazyflie_modules -->|"supports"| node_log_param
node_crazyflie_modules -->|"persists"| node_storage
node_stabilize_estimate -->|"consumes"| node_sensors
node_stabilize_estimate -->|"computes with"| node_dsp_lib
node_stabilize_estimate -->|"drives"| node_motors
node_wifi -->|"transports"| node_crtp
node_firmware_build -->|"contains"| node_bootloader
node_firmware_build -->|"contains"| node_partition_table
node_firmware_build -->|"contains"| node_app_bin
node_hardware_board -->|"produces"| node_hardware_prod

click node_readme "https://github.com/circuit-digest/esp-drone/blob/main/README.md"
click node_main "https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/main/main.c"
click node_platform "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/platform"
click node_drivers "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers"
click node_crazyflie_hal "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/core/crazyflie/hal"
click node_crazyflie_modules "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/core/crazyflie/modules"
click node_crazyflie_utils "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/core/crazyflie/utils"
click node_dsp_lib "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/lib/dsp_lib"
click node_wifi "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers/general/wifi"
click node_sensors "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers/i2c_devices"
click node_range_flow "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers/i2c_devices/vl53l0"
click node_motors "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers/general/motors"
click node_console "https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/console.c"
click node_log_param "https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/log.c"
click node_stabilize_estimate "https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/stabilizer.c"
click node_commander "https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/commander.c"
click node_crtp "https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/crtp.c"
click node_storage "https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/hal/src/storage.c"
click node_firmware_build "https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/build"
click node_bootloader "https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/build/bootloader.bin"
click node_partition_table "https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/build/partition_table/partition-table.bin"
click node_app_bin "https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/build/ESPDrone.bin"
click node_hardware_board "https://github.com/circuit-digest/esp-drone/blob/main/Hardware/ESP32 drone.kicad_pcb"
click node_hardware_prod "https://github.com/circuit-digest/esp-drone/tree/main/Hardware/production"

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,node_platform,node_drivers,node_crazyflie_hal,node_crazyflie_modules,node_crazyflie_utils,node_dsp_lib,node_wifi,node_sensors,node_range_flow,node_motors,node_console,node_log_param,node_stabilize_estimate,node_commander,node_crtp,node_storage toneBlue
class node_hardware_board,node_hardware_prod toneAmber
class node_firmware_build,node_bootloader,node_partition_table,node_app_bin toneMint
class node_readme toneNeutral
```

## Components

### Firmware

ESP32 drone controller runtime and build system

- [Main app](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/main/main.c): entrypoint · Application entry that boots the firmware subsystems · `Firmware/esp-drone/main/main.c`
- [Platform](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/platform): board layer · Board abstraction for ESP32 and Crazyflie compatibility · `Firmware/esp-drone/components/platform`
- [Drivers](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers): device adapters · ESP32-specific hardware drivers and transports · `Firmware/esp-drone/components/drivers`
- [HAL](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/core/crazyflie/hal): hardware abstraction · Crazyflie hardware abstraction for sensors, links, timing, power, and actuators · `Firmware/esp-drone/components/core/crazyflie/hal`
- [Modules](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/core/crazyflie/modules): flight logic · Stabilization, estimation, command routing, telemetry, and services · `Firmware/esp-drone/components/core/crazyflie/modules`
- [Utils](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/core/crazyflie/utils): math/support · Math, filtering, calibration, timing, CRC, and storage helpers · `Firmware/esp-drone/components/core/crazyflie/utils`
- [DSP lib](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/lib/dsp_lib): xtensa math · Xtensa-optimized numeric and signal-processing routines · `Firmware/esp-drone/components/lib/dsp_lib`
- [Wi-Fi](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers/general/wifi): link transport · Wireless control and networking path for phone-based operation · `Firmware/esp-drone/components/drivers/general/wifi`
- [Sensors](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers/i2c_devices): imu & env · IMU and environmental sensor drivers backing the flight loop · `Firmware/esp-drone/components/drivers/i2c_devices`
- [Range/flow](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers/i2c_devices/vl53l0): nav sensing · Altitude and optical-flow sensing for hold and navigation features · `Firmware/esp-drone/components/drivers/i2c_devices/vl53l0`
- [Motors](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/components/drivers/general/motors): actuator driver · Motor output generation and mixer definitions · `Firmware/esp-drone/components/drivers/general/motors`
- [Console](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/console.c): cli service · Interactive console and runtime command interface · `Firmware/esp-drone/components/core/crazyflie/modules/src/console.c`
- [Log/param](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/log.c): telemetry config · Logging, parameter management, and tuning support · `Firmware/esp-drone/components/core/crazyflie/modules/src/log.c`
- [Control loop](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/stabilizer.c): flight loop · Estimation, stabilization, and controller stack that computes thrust and attitude outputs · `Firmware/esp-drone/components/core/crazyflie/modules/src/stabilizer.c`
- [Commander](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/commander.c): command path · CRTP command intake and control routing · `Firmware/esp-drone/components/core/crazyflie/modules/src/commander.c`
- [CRTP](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/modules/src/crtp.c): protocol · Crazyflie-compatible protocol for command and telemetry messages · `Firmware/esp-drone/components/core/crazyflie/modules/src/crtp.c`
- [Storage](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/components/core/crazyflie/hal/src/storage.c): persistent state · Configuration blocks and persistent settings storage · `Firmware/esp-drone/components/core/crazyflie/hal/src/storage.c`

### Hardware

KiCad board design and manufacturing outputs

- [PCB design](https://github.com/circuit-digest/esp-drone/blob/HEAD/Hardware/ESP32%20drone.kicad_pcb): kicad board · KiCad schematic, PCB, and project files for the drone electronics · `Hardware/ESP32 drone.kicad_pcb`
- [Production](https://github.com/circuit-digest/esp-drone/tree/main/Hardware/production): manufacturing · Gerbers, BOM, positions, and production ZIP outputs · `Hardware/production`

### Artifacts

Generated flash images and build outputs

- [Build tree](https://github.com/circuit-digest/esp-drone/tree/main/Firmware/esp-drone/build): esp-idf build · Generated binaries, linker artifacts, and dependency outputs · `Firmware/esp-drone/build`
- [Bootloader](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/build/bootloader.bin): flash image · Bootloader image flashed at 0x1000 · `Firmware/esp-drone/build/bootloader.bin`
- [Partition table](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/build/partition_table/partition-table.bin): flash image · Partition table image flashed at 0x8000 · `Firmware/esp-drone/build/partition_table/partition-table.bin`
- [App binary](https://github.com/circuit-digest/esp-drone/blob/main/Firmware/esp-drone/build/ESPDrone.bin): flash image · Main application image flashed at 0x10000 · `Firmware/esp-drone/build/ESPDrone.bin`

### Other components

- [Project map](https://github.com/circuit-digest/esp-drone/blob/main/README.md): docs · Top-level overview and usage notes · `README.md`

## Connections

- Project map → Main app: describes · Repository documentation introduces the firmware entry point
- Project map → PCB design: describes · Repository documentation covers the PCB and manufacturing assets
- Main app → Platform: starts on · Application entry initializes board platform services
- Main app → Modules: enters · Main hands control to the flight-control module graph
- Platform → Drivers: binds · Platform layer maps board behavior onto ESP32 drivers
- Drivers → Wi-Fi: implements · Concrete Wi-Fi driver backs wireless control
- Drivers → Sensors: implements · Concrete I2C device drivers back the sensor HAL
- Drivers → Range/flow: implements · Range and optical-flow devices extend sensing support
- Drivers → Motors: implements · Motor driver layer emits actuator commands
- Modules → HAL: uses · Core modules depend on hardware abstraction interfaces
- Modules → Control loop: orchestrates · Modules coordinate estimation, stabilization, and control
- Modules → Commander: routes · Incoming commands are routed into the commander stack
- Modules → CRTP: speaks · Control and telemetry use Crazyflie-compatible CRTP messaging
- Modules → Console: exposes · Runtime command-line access is provided through the console module
- Modules → Log/param: supports · Telemetry, logging, and parameter tuning are provided by support modules
- Modules → Storage: persists · Configuration blocks and settings are stored persistently
- Control loop → Sensors: consumes · Sensor measurements feed estimation and control
- Control loop → DSP lib: computes with · Real-time numeric processing relies on optimized DSP routines
- Control loop → Motors: drives · Computed control outputs are sent to the motor layer
- Wi-Fi → CRTP: transports · Wi-Fi carries the CRTP control path
- Build tree → Bootloader: contains · Build tree includes the bootloader flash image
- Build tree → Partition table: contains · Build tree includes the partition table image
- Build tree → App binary: contains · Build tree includes the main application binary
- PCB design → Production: produces · PCB design feeds manufacturing artifacts and production packaging
