# qqqlab/madflight architecture

> Architecture diagram of the GitHub repository qqqlab/madflight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qqqlab/madflight
- Repository: https://github.com/qqqlab/madflight

## Overview

1. **What this repo is**
   - `madflight` is a cross-platform flight-controller library/toolbox, not a single standalone app.
   - It targets Arduino IDE and PlatformIO, and is built for ESP32/ESP32-S3, RP2040/RP2350, and STM32.
   - The architecture is organized as reusable subsystems under `src/`, with small example flight-controller sketches in `examples/` providing the application layer.

2. **Application boundary: examples own the flight mode logic**
   - The `examples/00.HelloWorld`, `10.Quadcopter`, `11.QuadcopterAdvanced`, and `20.Plane` sketches show the intended integration pattern.
   - These sketches include `madflight_config.h` plus a minimal `main.cpp`/`.ino`, while the library handles the hardware and low-level control plumbing.
   - In other words, the repo separates “aircraft behavior” from “flight-controller infrastructure.”

3. **Platform abstraction layer**
   - `src/hal/` is the hardware abstraction boundary for MCU-specific services.
   - There are dedicated implementations for `ESP32`, `RP2040`, and `STM32`, including serial, PWM, and DShot/DShot bidirectional support.
   - This layer is the main portability boundary: higher-level modules talk to `hal.h` and board-agnostic interfaces instead of chip-specific APIs.

4. **Board definition layer**
   - `src/brd/` contains board profiles and pin mappings.
   - The repo supports a large set of Betaflight-derived board definitions under `src/brd/betaflight/`, plus Madflight-specific defaults like `madflight_FC1.h`, `FC2`, `FC3`, etc.
   - These board headers encode the hardware topology: which MCU pins connect to IMU, receiver, ESC outputs, telemetry, LEDs, SD card, and other peripherals.

5. **Sensor input subsystems**
   - Sensor families are split into dedicated modules: `imu`, `bar`, `mag`, `gps`, `rdr` (range sensors), `ofl` (optical flow), and `bat`.
   - Each subsystem contains a generic wrapper plus concrete device drivers, for example IMUs like MPU/ICM/LSM6, barometers like BMP/DPS/MS5611, magnetometers like BMM150/QMC/RM3100, and battery monitors like ADC/INA226/INA228.
   - The common pattern is: device driver -> gizmo wrapper -> subsystem API. That keeps device-specific code isolated from the rest of the flight stack.

6. **Estimation and state derivation**
   - `src/ahr/` contains attitude and heading reference algorithms: Madgwick, Mahony, and VQF.
   - `src/alt/` computes altitude from barometer/other sources using complementary and Kalman-style filters.
   - `src/nav/` provides math, filtering, and navigation primitives, including L1 position control and matrix/vector utilities.
   - These modules turn raw sensor streams into flight-state estimates used by the controller.

7. **Control and vehicle logic**
   - `src/pid/` contains the PID control implementation and filtering helpers.
   - `src/veh/` represents vehicle-level behavior, while the example sketches likely assemble attitude/altitude/navigation control loops using the lower-level modules.
   - The data flow here is estimator output -> control law -> actuator commands.

8. **Receiver and external command inputs**
   - `src/rcl/` handles RC/command links, with support for SBUS, CRSF, DSM/DSMX, IBus, PPM, and MAVLink.
   - The presence of MAVLink and telemetry-oriented message packs indicates that the repo supports both traditional RC receivers and companion-computer/autopilot integration.
   - This is a major input boundary: commands can come from hobby receivers or from a higher-level MAVLink endpoint.

9. **Actuation and output**
   - `src/out/` is the output layer, while the HAL provides the electrical signaling backends such as PWM and DShot.
   - That means actuator commands are abstracted from the specific transport used to drive ESCs, motors, servos, or other outputs.
   - `src/led/` is a separate output path for status indication and user feedback, with NeoPixel support.

10. **Configuration, CLI, and scripting**
   - `src/cfg/` stores configuration/state.
   - `src/cli/` provides command-line and runtime management, including MSP support under `src/cli/msp/`.
   - `src/lua/` embeds Lua, suggesting the system can expose runtime scripting or advanced configuration hooks beyond static compile-time settings.

11. **Logging, tracing, and offline analysis**
   - `src/bbx/` implements binary logging and SD-card-oriented log writing.
   - `extras/BinLogTools/` contains Python utilities to inspect and analyze those logs offline.
   - `src/tbx/` provides supporting infrastructure such as scheduling, mutexes, queues, message broker utilities, CRC, and runtime tracing; this is the internal “plumbing” layer tying the real-time modules together.

12. **Cross-module runtime model**
   - The stack is sensor-driven and time-sliced: HAL acquires data, subsystem drivers decode it, estimators fuse it, control loops compute outputs, and HAL sends commands to hardware.
   - `src/tbx/MsgBroker` and scheduling utilities suggest internal decoupling between producers and consumers rather than one monolithic loop.
   - This makes the architecture closer to a modular real-time embedded framework than a single-purpose firmware.

13. **Repository support tooling**
   - CI is built around Arduino linting and compile checks for ESP32, RP2040, and STM32 via GitHub Actions and PlatformIO.
   - `library.properties` and `platformio.ini` show the repo is packaged as a consumable library for embedded projects.
   - `extras/betaflight_target_converter/` and the huge board-definition set indicate a strong emphasis on board portability and target adaptation.

14. **How to draw the diagram**
   - Put `examples/` at the top as the application layer.
   - Under that, show the main runtime layers: configuration/CLI, control/estimation, sensor drivers, RC input, outputs.
   - Place `hal/` and `brd/` as the hardware boundary beneath all modules.
   - Add side channels for logging (`bbx`), scripting (`lua`), and telemetry/management (`msp`, MAVLink), since they bypass the core control path but are architecturally important.

Main entry points: [`src/hal`](https://github.com/qqqlab/madflight/tree/main/src/hal) (HAL), [`src/veh`](https://github.com/qqqlab/madflight/tree/main/src/veh) (Vehicle), [`src/nav`](https://github.com/qqqlab/madflight/tree/main/src/nav) (Navigation), [`examples`](https://github.com/qqqlab/madflight/tree/main/examples) (Examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Examples"]
  node_examples["Examples<br/>app sketches"]
end

subgraph group_core["Flight stack"]
  node_cfg["Config"]
  node_ahr["AHRS<br/>attitude estimation"]
  node_alt["Altitude"]
  node_nav["Navigation<br/>guidance math"]
  node_pid["PID<br/>control law"]
  node_veh["Vehicle"]
end

subgraph group_io["Inputs/outputs"]
  node_imu["IMU<br/>attitude sensors"]
  node_bar["Baro<br/>pressure sensors"]
  node_mag["Mag"]
  node_gps["GPS<br/>position sensors"]
  node_rdr["Range"]
  node_ofl["Optical flow<br/>flow sensors"]
  node_bat["Battery<br/>power sensing"]
  node_rcl["RC link<br/>command inputs"]
  node_out["Outputs<br/>actuation"]
  node_led["LED<br/>status output"]
end

subgraph group_platform["Hardware layer"]
  node_hal["HAL<br/>mcu abstraction"]
  node_brd["Boards<br/>board profiles"]
end

subgraph group_infra["Infrastructure"]
  node_cli["CLI<br/>management shell"]
  node_lua["Lua<br/>embedded scripting"]
  node_tbx["Toolbox<br/>runtime plumbing"]
  node_bbx["Binary log<br/>logging"]
end

node_examples -->|"loads"| node_cfg
node_examples -.->|"may use"| node_cli
node_examples -->|"assembles"| node_veh
node_examples -->|"feeds commands"| node_rcl
node_veh -->|"uses"| node_ahr
node_veh -->|"uses"| node_alt
node_veh -->|"uses"| node_nav
node_veh -->|"uses"| node_pid
node_veh -->|"commands"| node_out
node_ahr -->|"fuses"| node_imu
node_alt -->|"fuses"| node_bar
node_nav -->|"uses"| node_gps
node_nav -->|"uses"| node_rdr
node_nav -->|"uses"| node_ofl
node_nav -.->|"uses"| node_mag
node_cfg -->|"selects"| node_brd
node_brd -->|"binds"| node_hal
node_imu -->|"reads via"| node_hal
node_bar -->|"reads via"| node_hal
node_mag -->|"reads via"| node_hal
node_gps -->|"reads via"| node_hal
node_rdr -->|"reads via"| node_hal
node_ofl -->|"reads via"| node_hal
node_bat -->|"reads via"| node_hal
node_rcl -->|"uses"| node_hal
node_rcl -.->|"decouples"| node_tbx
node_cli -.->|"manages"| node_rcl
node_bbx -->|"writes via"| node_hal
node_bbx -.->|"schedules"| node_tbx
node_lua -.->|"extends"| node_cfg
node_lua -.->|"exposed by"| node_cli
node_out -->|"drives via"| node_hal
node_led -->|"drives via"| node_hal

click node_examples "https://github.com/qqqlab/madflight/tree/main/examples"
click node_cfg "https://github.com/qqqlab/madflight/tree/main/src/cfg"
click node_cli "https://github.com/qqqlab/madflight/tree/main/src/cli"
click node_lua "https://github.com/qqqlab/madflight/tree/main/src/lua"
click node_tbx "https://github.com/qqqlab/madflight/tree/main/src/tbx"
click node_bbx "https://github.com/qqqlab/madflight/tree/main/src/bbx"
click node_hal "https://github.com/qqqlab/madflight/tree/main/src/hal"
click node_brd "https://github.com/qqqlab/madflight/tree/main/src/brd"
click node_imu "https://github.com/qqqlab/madflight/tree/main/src/imu"
click node_bar "https://github.com/qqqlab/madflight/tree/main/src/bar"
click node_mag "https://github.com/qqqlab/madflight/tree/main/src/mag"
click node_gps "https://github.com/qqqlab/madflight/tree/main/src/gps"
click node_rdr "https://github.com/qqqlab/madflight/tree/main/src/rdr"
click node_ofl "https://github.com/qqqlab/madflight/tree/main/src/ofl"
click node_bat "https://github.com/qqqlab/madflight/tree/main/src/bat"
click node_ahr "https://github.com/qqqlab/madflight/tree/main/src/ahr"
click node_alt "https://github.com/qqqlab/madflight/tree/main/src/alt"
click node_nav "https://github.com/qqqlab/madflight/tree/main/src/nav"
click node_pid "https://github.com/qqqlab/madflight/tree/main/src/pid"
click node_veh "https://github.com/qqqlab/madflight/tree/main/src/veh"
click node_rcl "https://github.com/qqqlab/madflight/tree/main/src/rcl"
click node_out "https://github.com/qqqlab/madflight/tree/main/src/out"
click node_led "https://github.com/qqqlab/madflight/tree/main/src/led"

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_examples toneBlue
class node_cfg,node_ahr,node_alt,node_nav,node_pid,node_veh toneAmber
class node_imu,node_bar,node_mag,node_gps,node_rdr,node_ofl,node_bat,node_rcl,node_out,node_led toneMint
class node_hal,node_brd toneRose
class node_cli,node_lua,node_tbx,node_bbx toneIndigo
```

## Components

### Examples

Application sketches that assemble aircraft behavior on top of the library.

- [Examples](https://github.com/qqqlab/madflight/tree/main/examples): app sketches · HelloWorld, quadcopter, and plane sketches that define application-level flight logic. · `examples`

### Flight stack

Estimation, control, vehicle logic, and runtime configuration.

- [Config](https://github.com/qqqlab/madflight/tree/main/src/cfg): state/config · Runtime configuration and persisted settings. · `src/cfg`
- [AHRS](https://github.com/qqqlab/madflight/tree/main/src/ahr): attitude estimation · Attitude and heading reference algorithms such as Madgwick, Mahony, and VQF. · `src/ahr`
- [Altitude](https://github.com/qqqlab/madflight/tree/main/src/alt): altitude estimation · Altitude estimation and filter-based fusion from pressure and other sources. · `src/alt`
- [Navigation](https://github.com/qqqlab/madflight/tree/main/src/nav): guidance math · Navigation primitives, filters, and vector/matrix math used by guidance and control. · `src/nav`
- [PID](https://github.com/qqqlab/madflight/tree/main/src/pid): control law · PID controller implementation and filtering helpers. · `src/pid`
- [Vehicle](https://github.com/qqqlab/madflight/tree/main/src/veh): vehicle logic · Vehicle-level behavior and mode assembly above the low-level controllers. · `src/veh`

### Inputs/outputs

Sensor, receiver, actuator, and status I/O subsystems.

- [IMU](https://github.com/qqqlab/madflight/tree/main/src/imu): attitude sensors · Inertial measurement unit subsystem and device drivers. · `src/imu`
- [Baro](https://github.com/qqqlab/madflight/tree/main/src/bar): pressure sensors · Barometer subsystem for altitude-related pressure sensing. · `src/bar`
- [Mag](https://github.com/qqqlab/madflight/tree/main/src/mag): magnetometers · Magnetometer subsystem for heading and field sensing. · `src/mag`
- [GPS](https://github.com/qqqlab/madflight/tree/main/src/gps): position sensors · GPS subsystem with NMEA and u-blox support. · `src/gps`
- [Range](https://github.com/qqqlab/madflight/tree/main/src/rdr): range sensors · Range sensor subsystem for distance and proximity measurements. · `src/rdr`
- [Optical flow](https://github.com/qqqlab/madflight/tree/main/src/ofl): flow sensors · Optical-flow subsystem and PMW3901 driver support. · `src/ofl`
- [Battery](https://github.com/qqqlab/madflight/tree/main/src/bat): power sensing · Battery voltage/current sensing and monitor drivers. · `src/bat`
- [RC link](https://github.com/qqqlab/madflight/tree/main/src/rcl): command inputs · Radio control and MAVLink command input subsystem. · `src/rcl`
- [Outputs](https://github.com/qqqlab/madflight/tree/main/src/out): actuation · Actuator command output abstraction for motors, servos, and similar outputs. · `src/out`
- [LED](https://github.com/qqqlab/madflight/tree/main/src/led): status output · Status LED and NeoPixel user-feedback output path. · `src/led`

### Hardware layer

Portability boundary for MCU services and board pinmaps.

- [HAL](https://github.com/qqqlab/madflight/tree/main/src/hal): mcu abstraction · Hardware abstraction layer for serial, PWM, DShot, and platform services. · `src/hal`
- [Boards](https://github.com/qqqlab/madflight/tree/main/src/brd): board profiles · Board definitions and pin mappings, including default and Betaflight-derived targets. · `src/brd`

### Infrastructure

Runtime plumbing, logging, scripting, and management channels.

- [CLI](https://github.com/qqqlab/madflight/tree/main/src/cli): management shell · Interactive command and runtime management entrypoint, including MSP support. · `src/cli`
- [Lua](https://github.com/qqqlab/madflight/tree/main/src/lua): embedded scripting · Embedded Lua runtime and wrappers for scriptable behavior. · `src/lua`
- [Toolbox](https://github.com/qqqlab/madflight/tree/main/src/tbx): runtime plumbing · Scheduling, queues, mutexes, message broker, CRC, and tracing utilities. · `src/tbx`
- [Binary log](https://github.com/qqqlab/madflight/tree/main/src/bbx): logging · Binary logging and SD-card log writer support. · `src/bbx`

## Connections

- Examples → Config: loads · Example sketches include the per-aircraft configuration header.
- Examples → CLI: may use · Applications can expose runtime management through the CLI.
- Examples → Vehicle: assembles · Examples own the flight-mode and aircraft-behavior composition.
- Examples → RC link: feeds commands · Application sketches connect receiver or MAVLink command inputs into the stack.
- Vehicle → AHRS: uses · Vehicle logic consumes attitude estimates.
- Vehicle → Altitude: uses · Vehicle logic consumes altitude estimates.
- Vehicle → Navigation: uses · Vehicle logic uses guidance and math primitives.
- Vehicle → PID: uses · Vehicle logic uses controller loops.
- Vehicle → Outputs: commands · Vehicle logic produces actuator commands.
- AHRS → IMU: fuses · AHRS consumes inertial sensor streams.
- Altitude → Baro: fuses · Altitude estimation consumes barometer data.
- Navigation → GPS: uses · Navigation can consume GPS data.
- Navigation → Range: uses · Navigation can use range sensing.
- Navigation → Optical flow: uses · Navigation can use optical-flow data.
- Navigation → Mag: uses · Navigation primitives can consume heading sources.
- Config → Boards: selects · Configuration is grounded in board profiles and pin maps.
- Boards → HAL: binds · Board definitions bind hardware topology to the HAL.
- IMU → HAL: reads via · Sensor drivers acquire data through the HAL.
- Baro → HAL: reads via · Pressure sensors use the HAL boundary.
- Mag → HAL: reads via · Magnetometer drivers use the HAL boundary.
- GPS → HAL: reads via · GPS transports are implemented through the HAL.
- Range → HAL: reads via · Range sensor transports are implemented through the HAL.
- Optical flow → HAL: reads via · Optical-flow transport depends on HAL services.
- Battery → HAL: reads via · Battery sensing depends on HAL access to ADC or bus peripherals.
- RC link → HAL: uses · Receiver links and MAVLink I/O rely on the HAL serial and timing services.
- RC link → Toolbox: decouples · Command handling is supported by message-broker and scheduling infrastructure.
- CLI → RC link: manages · CLI/MSP management can interact with RC and autopilot-style control channels.
- Binary log → HAL: writes via · Binary logging ultimately targets HAL-backed storage and transport.
- Binary log → Toolbox: schedules · Logging integrates with shared runtime plumbing.
- Lua → Config: extends · Lua provides runtime scripting and configuration hooks.
- Lua → CLI: exposed by · Lua is typically surfaced through management/runtime interfaces.
- Outputs → HAL: drives via · Actuator outputs are lowered to PWM/DShot and similar HAL backends.
- LED → HAL: drives via · Status lighting uses HAL-backed output support.