# espressif/esp-drone architecture

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

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

## Overview

Based on your provided file structure and README, ESP-Drone is an embedded firmware project for a drone based on Espressif’s ESP32 family chips. The project closely mirrors the Crazyflie firmware structure and is organized into several distinct layers such as hardware abstraction (HAL), core flight control algorithms (modules), low-level drivers (I2C, SPI, etc.), configuration/initialization, and a DSP library for signal processing. It also contains directories for hardware designs, schematics, BOMs, and documentation.

##### Main Components
- Flight Control Software: This is the heart of the system and includes the “components/core/crazyflie” code. Indicate that this section integrates a HAL layer (drivers/ interfaces for sensors, actuators, communication) and a modules layer (control algorithms such as attitude, stabilization, collision avoidance, navigation, etc.).
- Low-Level Drivers: Gather together all drivers provided in the “components/drivers” directory. They include drivers for digital decks, ADC, buzzer, LED, motors, Wi-Fi, I2C, SPI, and specialized sensor drivers (e.g., for VL53L0x, MPU6050, HMC5883L, etc.).
- DSP and Math Libraries: Under “components/lib/dsp_lib”, signal processing routines, filtering functions, and controller algorithms play an important role in flight stabilization. Show this as a reusable library module.
- Configuration and Utilities: Include the “components/config” and “utils” directories. These provide system constants, board configuration files and utility functions.
- Main Application Entry: The “main” directory contains the firmware’s entry point (main.c), build configuration (CMakeLists.txt, Kconfig files) and integrates all modules.
- Hardware Documentation: Represent the “hardware” directory as a separate reference block that includes BOMs, schematics, PCB layouts, and other design files to show how the physical drone corresponds with the firmware.

##### Relationships and Data Flow
- HAL layer in the “crazyflie/hal” as an intermediary between raw hardware and higher-level software modules.
- That the Modules (e.g., attitude controller, PID controller, collision avoidance) receive sensor data from the HAL, process them (with DSP functions as needed), and then send commands down to the drivers to control motors and actuators.
- Communication paths to the external control units (mobile APP/gamepad) that are interfaced via Wi-Fi or ESP-NOW.

##### Architectural Patterns and Design Principles
- Modular Design: The project is organized into components (config, core, drivers, lib) that decouple hardware abstraction, control algorithms, and system configuration.
- Layered Architecture: Clearly represent the hardware layer, driver/abstraction layer, core control modules, and external interfaces.
- Real-Time Operating System (FreeRTOS): Although not explicitly diagrammed in the file tree, the presence of “FreeRTOSdebug” indicates that task scheduling and timing are managed in an RTOS environment.
- Use of External Libraries: Distinguish the DSP and mathematical libraries that are used for sensor data filtering, matrix calculations, and control algorithms.

##### Relevant Technologies and Frameworks
- ESP-IDF Framework: Emphasize that the code is built on Espressif’s ESP-IDF (ESP-IDF release/v5.0 branch recommended).
- CMake Build System: Mention the use of CMakeLists.txt found in multiple directories.
- FreeRTOS: Note that real-time management is achieved using FreeRTOS (as evidenced by FreeRTOS-specific files in the HAL).
- Wi-Fi and ESP-NOW: Show external communications through Wi-Fi and ESP-NOW protocols.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware Layer"
        HP["ESP32 Flight Controller & Peripherals"]
    end

    subgraph "Firmware Layer"
        subgraph "Core Firmware"
            HAL["HAL - Crazyflie Interface"]
            Modules["Control Modules (PID, Attitude, etc.)"]
        end
        Drivers["Low-Level Drivers"]
        DSP["DSP & Math Library"]
        Configuration["Configuration"]
        Utilities["Utilities"]
        MainApp["Main Application Entry"]
    end

    subgraph "External Interfaces"
        HAL_Interface["HAL Interface (Wi‑Fi/ESP‑NOW)"]
        WiFi_Driver["Wi‑Fi Driver"]
    end

    %% Data flow arrows
    HP -->|"sensor_data"| Drivers
    Drivers -->|"raw_signals"| HAL
    HAL -->|"processed_data"| Modules
    Modules -->|"control_commands"| Drivers
    Drivers -->|"actuation_signals"| HP

    MainApp -->|"init_config"| Configuration
    MainApp -->|"init_utilities"| Utilities
    MainApp -->|"init_HAL"| HAL
    MainApp -->|"init_Modules"| Modules
    MainApp -->|"init_Drivers"| Drivers
    MainApp -->|"init_DSP"| DSP

    DSP -->|"filter_routines"| Modules

    Configuration -->|"settings"| Modules
    Utilities -->|"helper_functions"| Modules

    HAL_Interface -->|"external_commands"| Modules
    WiFi_Driver -->|"external_commands"| Modules

    %% Click events
    click HP "https://github.com/espressif/esp-drone/tree/master/hardware"
    click HAL "https://github.com/espressif/esp-drone/tree/master/components/core/crazyflie/hal"
    click Modules "https://github.com/espressif/esp-drone/tree/master/components/core/crazyflie/modules"
    click Drivers "https://github.com/espressif/esp-drone/tree/master/components/drivers"
    click DSP "https://github.com/espressif/esp-drone/tree/master/components/lib/dsp_lib"
    click Configuration "https://github.com/espressif/esp-drone/tree/master/components/config"
    click Utilities "https://github.com/espressif/esp-drone/tree/master/components/core/crazyflie/utils"
    click MainApp "https://github.com/espressif/esp-drone/tree/master/main"
    click HAL_Interface "https://github.com/espressif/esp-drone/tree/master/components/core/crazyflie/hal/interface"
    click WiFi_Driver "https://github.com/espressif/esp-drone/tree/master/components/drivers/general/wifi"

    %% Class assignments
    class HP hardware;
    class HAL,Modules,MainApp,Configuration,Utilities firmware;
    class Drivers drivers;
    class DSP dsp;
    class HAL_Interface,WiFi_Driver external;

    %% Style definitions
    classDef hardware fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef firmware fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef drivers fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef dsp fill:#f4a460,stroke:#333,stroke-width:2px;
    classDef external fill:#ffb6c1,stroke:#333,stroke-width:2px;
```
