# bitcraze/crazyflie-firmware architecture

> Architecture diagram of the GitHub repository bitcraze/crazyflie-firmware, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bitcraze/crazyflie-firmware
- Repository: https://github.com/bitcraze/crazyflie-firmware

## Overview

##### Project type and purpose
- This is the Crazyflie firmware: a low-level, embedded C codebase running on an STM32 microcontroller. It implements real-time flight control, sensor fusion, communication stacks and a plug-in “deck” hardware abstraction for modular sensor/deck expansions.

##### File structure
- Top-level layers:
- src/ (core firmware: init, RTOS glue, system startup)
- hal/ (hardware abstraction layer for MCU peripherals)
- drivers/ (concrete drivers for sensors, radios, decks)
- modules/ (high-level services: estimators, controllers, CRTP/CPX comms, supervisor state machine)
- app_api/ (application API, sample apps)
- bindings/ (Python/CFFI bindings)
- lib/ (third-party libraries: CMSIS, FatFS, USB stacks)
- platform/ (platform-specific configurations and porting)
- utils/ (utility code: math, Kalman engines, data structures)
- tests/ and test_python/ (unit and integration tests)
- tools/ (build, flash, docs generation, system-ID, logging, debugging scripts)

##### README for additional insights
- Confirms it’s firmware for multi-platform Crazyflie drones, built with Make/Kbuild, configured with Kconfig, tested via C unit tests and Python tests, and extensible through “deck” APIs and Python bindings.

##### Essential architectural elements
- Don’t over-decompose; focus on the major layers and extension points (decks, bindings).
- Key boundaries are shown: hardware boundary, RTOS boundary, API boundary, build/test boundary.
- Document any configuration systems (Kconfig) and plug-in mechanisms (Kbuild).
- Review with domain experts to confirm that critical interactions (e.g., sensor → Kalman → controller → motor PWM) are clearly visible.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        Hardware["MCU & Peripherals"]:::hardware
    end
    click Hardware "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/hal/interface/"

    %% BSP/Startup
    subgraph "BSP/Startup"
        MainC["main.c"]:::bsp
        StartupS["startup_stm32f40xx.S"]:::bsp
    end
    click MainC "https://github.com/bitcraze/crazyflie-firmware/blob/master/src/init/main.c"
    click StartupS "https://github.com/bitcraze/crazyflie-firmware/blob/master/src/init/startup_stm32f40xx.S"

    %% RTOS Kernel
    FreeRTOS["FreeRTOS"]:::rtos

    %% HAL & Platform
    subgraph "HAL & Platform Abstraction"
        HAL["HAL"]:::hal
        Platform["Platform"]:::hal
    end
    click HAL "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/hal/src/"
    click Platform "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/platform/src/"

    %% Drivers
    subgraph "Device Drivers"
        DriversMCU["MCU Peripherals"]:::drivers
        Bosch["Bosch Sensor Drivers"]:::drivers
        ESP32["ESP32 Slip Driver"]:::drivers
    end
    click DriversMCU "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/drivers/src/"
    click Bosch "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/drivers/bosch/src/"
    click ESP32 "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/drivers/esp32/src/"

    %% Deck Extension Framework
    subgraph "Deck Extension"
        DeckCore["Deck Core & API"]:::drivers
        DeckDrv["Deck Drivers"]:::drivers
    end
    click DeckCore "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/deck/core/"
    click DeckDrv "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/deck/drivers/src/"

    %% Core Services Modules
    subgraph "Core Services (Modules)"
        Estimator["Estimators"]:::modules
        Kalman["Kalman Core"]:::modules
        Controller["Controllers"]:::modules
        Supervisor["Supervisor State Machine"]:::modules
        CRTP["CRTP/CPX Protocols"]:::modules
        Planner["Planner & State Machine"]:::modules
    end
    click Estimator "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/modules/src/estimator/"
    click Kalman "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/modules/src/kalman_core/"
    click Controller "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/modules/src/controller/"
    click Supervisor "https://github.com/bitcraze/crazyflie-firmware/blob/master/src/modules/src/supervisor_state_machine.c"
    click CRTP "https://github.com/bitcraze/crazyflie-firmware/blob/master/src/modules/src/crtp.c"
    click Planner "https://github.com/bitcraze/crazyflie-firmware/blob/master/src/modules/src/planner.c"

    %% Application API
    AppAPI["Application API\n(C entrypoints)"]:::app
    click AppAPI "https://github.com/bitcraze/crazyflie-firmware/blob/master/app_api/src/app_main.c"

    %% Python/CFFI Bindings
    PyBind["Python/CFFI Bindings"]:::external
    click PyBind "https://github.com/bitcraze/crazyflie-firmware/blob/master/bindings/setup.py"

    %% Build & Configuration
    subgraph "Build & Configuration"
        Kconfig["Kconfig & Kbuild"]:::tools
        BuildTargets["build_targets.json"]:::tools
    end
    click Kconfig "https://github.com/bitcraze/crazyflie-firmware/tree/master/Kconfig"
    click BuildTargets "https://github.com/bitcraze/crazyflie-firmware/blob/master/build_targets.json"

    %% Tests
    subgraph "Tests"
        CTests["C Unit Tests"]:::tests
        PyTests["Python Tests"]:::tests
    end
    click CTests "https://github.com/bitcraze/crazyflie-firmware/tree/master/test/"
    click PyTests "https://github.com/bitcraze/crazyflie-firmware/tree/master/test_python/"

    %% Utils & Libraries
    subgraph "Utilities & Libraries"
        Utils["Utils"]:::lib
        Lib["Third-Party Libraries"]:::lib
    end
    click Utils "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/utils/src/"
    click Lib "https://github.com/bitcraze/crazyflie-firmware/tree/master/src/lib/"

    %% Tools & Scripts
    ToolsAll["Tools & Scripts"]:::tools
    click ToolsAll "https://github.com/bitcraze/crazyflie-firmware/tree/master/tools/"

    %% Connections: Application to Modules
    AppAPI -->|"invoke services"| Estimator
    AppAPI -->|"invoke services"| Controller
    AppAPI -->|"invoke services"| CRTP

    %% Python Bindings to Modules
    PyBind -->|"CFFI calls"| Kalman
    PyBind -->|"CFFI calls"| Planner

    %% Modules to Drivers
    Estimator -->|"SPI read"| DriversMCU
    Kalman -->|"data from"| Estimator
    Controller -->|"control outputs"| DriversMCU
    CRTP -->|"packets"| DriversMCU
    Planner -->|"commands"| Controller

    %% Deck plugin flow
    DeckCore -->|"loads at runtime"| DeckDrv
    DeckDrv -->|"uses"| DriversMCU

    %% Drivers to HAL & Platform
    DriversMCU -->|"HAL calls"| HAL
    Bosch -->|"HAL calls"| HAL
    ESP32 -->|"HAL calls"| HAL
    DeckDrv -->|"HAL calls"| HAL

    %% HAL to Platform & RTOS
    HAL -->|"abstraction layer"| Platform
    Platform -->|"configures"| FreeRTOS

    %% RTOS scheduling
    FreeRTOS -->|"schedules tasks"| Estimator
    FreeRTOS -->|"schedules tasks"| Controller
    FreeRTOS -->|"handles ISRs"| DriversMCU

    %% HAL down to Hardware
    HAL -->|"peripheral access"| Hardware

    %% External interfaces: radio/USB
    CRTP -->|"radio/USB"| Hardware

    %% Build & Tools flow
    ToolsAll -->|"runs build"| Kconfig
    ToolsAll -->|"generates"| BuildTargets
    ToolsAll -->|"executes tests"| CTests
    ToolsAll -->|"executes tests"| PyTests

    %% Utils & Lib usage
    Estimator -->|"uses"| Utils
    Controller -->|"uses"| Utils
    DriversMCU -->|"uses"| Lib
    HAL -->|"uses"| Lib

    classDef hardware fill:#D0E6FF,stroke:#007ACC;
    classDef bsp fill:#E0F7FA,stroke:#006064;
    classDef rtos fill:#F3E5F5,stroke:#4A148C;
    classDef hal fill:#BBDEFB,stroke:#0D47A1;
    classDef drivers fill:#C8E6C9,stroke:#2E7D32;
    classDef modules fill:#FFF9C4,stroke:#F9A825;
    classDef app fill:#FFE0B2,stroke:#EF6C00;
    classDef external fill:#E1BEE7,stroke:#8E24AA;
    classDef tools fill:#CFD8DC,stroke:#455A64;
    classDef tests fill:#F8BBD0,stroke:#C2185B;
    classDef lib fill:#B2DFDB,stroke:#00796B;
```
