How qqqlab/madflight works
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: hal HAL · veh Vehicle · nav Navigation · examples Examples
Components 23
Examples
Application sketches that assemble aircraft behavior on top of the library.
- Examples · HelloWorld, quadcopter, and plane sketches that define application-level flight logic.
examples
Flight stack
Estimation, control, vehicle logic, and runtime configuration.
- Config · Runtime configuration and persisted settings.
src/cfg - AHRS · Attitude and heading reference algorithms such as Madgwick, Mahony, and VQF.
src/ahr - Altitude · Altitude estimation and filter-based fusion from pressure and other sources.
src/alt - Navigation · Navigation primitives, filters, and vector/matrix math used by guidance and control.
src/nav - PID · PID controller implementation and filtering helpers.
src/pid - Vehicle · Vehicle-level behavior and mode assembly above the low-level controllers.
src/veh
Inputs/outputs
Sensor, receiver, actuator, and status I/O subsystems.
- IMU · Inertial measurement unit subsystem and device drivers.
src/imu - Baro · Barometer subsystem for altitude-related pressure sensing.
src/bar - Mag · Magnetometer subsystem for heading and field sensing.
src/mag - GPS · GPS subsystem with NMEA and u-blox support.
src/gps - Range · Range sensor subsystem for distance and proximity measurements.
src/rdr - Optical flow · Optical-flow subsystem and PMW3901 driver support.
src/ofl - Battery · Battery voltage/current sensing and monitor drivers.
src/bat - RC link · Radio control and MAVLink command input subsystem.
src/rcl - Outputs · Actuator command output abstraction for motors, servos, and similar outputs.
src/out - LED · Status LED and NeoPixel user-feedback output path.
src/led
Hardware layer
Portability boundary for MCU services and board pinmaps.
Infrastructure
Runtime plumbing, logging, scripting, and management channels.
- CLI · Interactive command and runtime management entrypoint, including MSP support.
src/cli - Lua · Embedded Lua runtime and wrappers for scriptable behavior.
src/lua - Toolbox · Scheduling, queues, mutexes, message broker, CRC, and tracing utilities.
src/tbx - Binary log · Binary logging and SD-card log writer support.
src/bbx
Connections 33
- 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.