How circuit-digest/esp-drone works
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: modules Modules · drivers Drivers · stabilizer.c Control loop · build Build tree
Components 24
Firmware
ESP32 drone controller runtime and build system
- Main app · Application entry that boots the firmware subsystems
Firmware/esp-drone/main/main.c - Platform · Board abstraction for ESP32 and Crazyflie compatibility
Firmware/esp-drone/components/platform - Drivers · ESP32-specific hardware drivers and transports
Firmware/esp-drone/components/drivers - HAL · Crazyflie hardware abstraction for sensors, links, timing, power, and actuators
Firmware/esp-drone/components/core/crazyflie/hal - Modules · Stabilization, estimation, command routing, telemetry, and services
Firmware/esp-drone/components/core/crazyflie/modules - Utils · Math, filtering, calibration, timing, CRC, and storage helpers
Firmware/esp-drone/components/core/crazyflie/utils - DSP lib · Xtensa-optimized numeric and signal-processing routines
Firmware/esp-drone/components/lib/dsp_lib - Wi-Fi · Wireless control and networking path for phone-based operation
Firmware/esp-drone/components/drivers/general/wifi - Sensors · IMU and environmental sensor drivers backing the flight loop
Firmware/esp-drone/components/drivers/i2c_devices - Range/flow · Altitude and optical-flow sensing for hold and navigation features
Firmware/esp-drone/components/drivers/i2c_devices/vl53l0 - Motors · Motor output generation and mixer definitions
Firmware/esp-drone/components/drivers/general/motors - Console · Interactive console and runtime command interface
Firmware/esp-drone/components/core/crazyflie/modules/src/console.c - Log/param · Logging, parameter management, and tuning support
Firmware/esp-drone/components/core/crazyflie/modules/src/log.c - Control loop · Estimation, stabilization, and controller stack that computes thrust and attitude outputs
Firmware/esp-drone/components/core/crazyflie/modules/src/stabilizer.c - Commander · CRTP command intake and control routing
Firmware/esp-drone/components/core/crazyflie/modules/src/commander.c - CRTP · Crazyflie-compatible protocol for command and telemetry messages
Firmware/esp-drone/components/core/crazyflie/modules/src/crtp.c - Storage · 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 · KiCad schematic, PCB, and project files for the drone electronics
Hardware/ESP32 drone.kicad_pcb - Production · Gerbers, BOM, positions, and production ZIP outputs
Hardware/production
Artifacts
Generated flash images and build outputs
- Build tree · Generated binaries, linker artifacts, and dependency outputs
Firmware/esp-drone/build - Bootloader · Bootloader image flashed at 0x1000
Firmware/esp-drone/build/bootloader.bin - Partition table · Partition table image flashed at 0x8000
Firmware/esp-drone/build/partition_table/partition-table.bin - App binary · Main application image flashed at 0x10000
Firmware/esp-drone/build/ESPDrone.bin
Other components
- Project map · Top-level overview and usage notes
README.md
Connections 24
- 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