Flight32 Flight Controller Firmware

A high-performance, open-source flight controller firmware designed to unleash the full potential of the ESP32.

---

Flight32 is a robust, extensible, and user-friendly firmware that turns any ESP32 into a powerful flight controller. Built for stability, performance, and ease of use, it's the perfect brain for your next drone project.

✨ Core Features

• 🚀 Peak Performance & Stability: Experience ultra-stable flight with a real-time FreeRTOS-based scheduler that guarantees reliable, predictable performance.
• 🧠 Dual-Core Powerhouse: Harnesses the full power of the ESP32's dual-core architecture, dedicating one core to flight-critical tasks and the other to communications.
• 🛡️ Robust System State Machine: A built-in state machine ensures safe and predictable behavior, from initialization to in-flight, with robust error handling and failsafe modes.
• 🧩 Clean & Modular Architecture: A clean, object-oriented design makes the firmware easy to understand, modify, and extend.
• ✈️ Configurable Flight Modes: Seamlessly switch between Acro (rate-based) and Stabilized (angle-based) flight modes using a dedicated RC channel. Stabilized mode utilizes a cascaded PID control loop for precise angle holding.
• 📊 Real-time System Insights: Tune and debug on the fly with a powerful, built-in terminal and a web-based serial monitor. The firmware's MultiWii Serial Protocol (MSP) implementation is now highly compatible with Betaflight Configurator (tested against versions 4.0.6 and 4.2.11), ensuring seamless integration with external tools. Monitor CPU load, loop times, memory usage, and more.
• 🎛️ Persistent On-the-Fly Tuning: A full PID controller and complete channel mapping are easily adjustable via the terminal, with all settings saved persistently to non-volatile storage.
• 📡 Extensible Receiver & IMU Support: Built with a generic task structure to easily support new receiver protocols (currently IBUS, PPM) and IMU sensors (currently MPU6050/MPU6500).
• Robust Attitude Estimation: Utilizes a Mahony filter to provide highly accurate and robust orientation data (quaternions), essential for stable flight, derived directly from raw IMU sensor data, without relying on the MPU6050/MPU6500's Digital Motion Processor (DMP).
• Comprehensive MSP Compatibility: Achieved full alignment with Betaflight's MSP protocol, including accurate command ID mapping and robust default data responses for previously unimplemented commands. This ensures a fluid experience with Betaflight Configurator and other MSP-compatible tools.
• Configurable IMU: Fine-tune your IMU with configurable gyroscope range, accelerometer range, and low-pass filter settings, along with improved temperature accuracy.
• ⚙️ DShot Motor Control: Precise and efficient digital motor control using the ESP32's RMT peripheral.
• Configurable Gyro Filtering: A configurable Biquad filter cascade, including a low-pass filter and two notch filters, to eliminate noise for smoother flight.
• ESC Passthrough Mode: Directly configure and flash BLHeli_S Electronic Speed Controllers (ESCs) via the flight controller's serial port, eliminating the need for dedicated programming hardware.

🏗️ Architecture Overview

Flight32 is built on a modern, modular software architecture designed for real-time performance, safety, and extensibility.

• FreeRTOS Task-Based Model: The firmware's core is a set of independent, real-time tasks managed by the FreeRTOS kernel. Each critical function—such as sensor reading (ImuTask), receiver processing (RxTask), PID calculations (PidTask), and motor control (MotorTask)—runs in its own dedicated task. This ensures that a delay in one part of the system (like serial communication) does not impact flight-critical operations.

• System State Machine: To ensure robust and predictable operation, the firmware is governed by a central state machine (SystemState). The controller transitions through well-defined states like INITIALIZING, CALIBRATING, READY, and FAILSAFE. This prevents unsafe actions, such as arming the motors before the IMU is ready, and provides a clear, safe path for handling system errors.

• Object-Oriented and Data-Driven Design: The codebase is written in C++ with a strong emphasis on object-oriented principles. Hardware and protocols are abstracted behind common interfaces (e.g., ImuSensor, RxProtocol), making it simple to add support for new components. Attitude estimation is handled by a Mahony filter, derived directly from raw IMU sensor data, without relying on the MPU6050/MPU6500's Digital Motion Processor (DMP). Configuration is managed centrally and loaded from non-volatile storage, allowing the system's behavior to be modified without recompiling the firmware.

🛠️ ESC Passthrough Mode

Flight32 features an experimental ESC Passthrough mode, allowing direct communication with BLHeli_S Electronic Speed Controllers (ESCs) for configuration and firmware updates. This eliminates the need to physically disconnect ESCs from the flight controller or use specialized programming tools.

Supported ESCs: BLHeli_S ESCs (using a Betaflight-compatible 4-way serial protocol and 1-Wire communication).

How to use:

1. Connect your Flight32-powered ESP32 to your computer via USB.
2. Ensure ESCs are powered (e.g., connect a LiPo battery to your drone with propellers removed for safety).
3. Open your preferred BLHeli_S configurator software (e.g., BLHeliSuite, ESC-Configurator).
4. Enter Passthrough mode on Flight32: In the Flight32 serial terminal (e.g., using Arduino Serial Monitor or a dedicated terminal program), type:

   esc_passthrough
   

   You will see a confirmation message: FlightController: Entering ESC Passthrough mode.
5. Connect in Configurator: In your BLHeli_S configurator software, select the serial port corresponding to your Flight32 and initiate the connection. The configurator should now be able to detect and communicate with your ESCs.
6. Perform ESC operations: You can now read/write settings, flash firmware, or perform other supported operations using your configurator.
7. Exit Passthrough mode: To exit passthrough mode and return to normal Flight32 operation, type quit in the configurator's serial interface or physically disconnect/reconnect the Flight32. Flight32 will automatically re-initialize its tasks and resume normal operation.

Current Limitations & Future Work:

• Basic Protocol Implementation: The current passthrough implementation focuses on establishing the low-level communication (1-Wire bit-banging) and handshake with BLHeli_S ESCs using a Betaflight-compatible 4-way serial protocol.
• BLHeli_S Bootloader Command Translation: The passthroughRead, passthroughWrite, and passthroughErase functions in MotorTask contain placeholder logic. Fully functional read/write/erase operations require precise translation of the specific command sequences from the BLHeli_S bootloader assembly (e.g., BLHeliBootLoad.inc). This is the next phase of development.

🎬 Terminal in Action

Get immediate insight into the system's performance with the tasks command.

[Flight32 ~]$ tasks

Task Name        State      Prio   CPU %    Loop (us)  Avg (us)   Max (us)   Stack HWM (bytes)
-------------------------------------------------------------------------------------------------------------------
RX / Receiver    Waiting    4      0.06     1          0          7          3556
IMU / Sensor     Waiting    5      1.29     351        354        488        2716
MOTORS / DShot   Waiting    3      0.70     100        100        285        3112
PID Controller   Waiting    4      10.76    1766       1744       1998       2516
Serial Manager   Running    1      0.03     7          7          34         7216
-------------------------------------------------------------------------------------------------------------------

📂 Codebase Structure

The Flight32 firmware is organized into a clean, modular structure to promote readability, maintainability, and ease of extension.

/
├── flight32.ino                # Main Arduino sketch file
├── install_libs.sh             # Script to install required libraries
├── README.md                   # You are here!
└── src/
    ├── com_manager.cpp/h       # Core communication (logging) manager
    ├── flight_controller.cpp/h # Main flight controller class
    ├── settings_manager.cpp/h  # Manages persistent settings in NVS
    ├── config/                 # Header-only configuration files for modules
    ├── imu/                    # IMU sensor interfaces and implementations (e.g., MPU6500_WE integration)
    ├── pid/                    # PID controller implementation
    ├── protocols/              # MSP (v1/v2), IBUS, and other communication protocols
    ├── scheduler/              # FreeRTOS task scheduler
    ├── tasks/                  # All major system tasks (IMU, RX, Motor, etc.)
    ├── terminal/               # Interactive serial terminal
    └── utils/                  # Utility functions, system constants, version information, and MahonyAHRS.h/cpp for attitude estimation

🏁 Quick Start

Get your drone in the air in just a few minutes.

1. Install Board Support: Make sure you have the ESP32 board package installed in your Arduino environment.

2. Install External Libraries: Run the provided script to automatically install the required external libraries.

   # Make the script executable
   chmod +x install_libs.sh
   
   # Run the installer
   ./install_libs.sh

3. Compile & Upload (Arduino IDE): Open flight32.ino in the Arduino IDE, select your board and port, and hit upload. The IMU will automatically calibrate on every boot.

For Power Users (Arduino CLI)

# 1. Install libraries first by running ./install_libs.sh

# 2. Compile the firmware
arduino-cli compile --fqbn esp32:esp32:esp32 flight32.ino

# 3. Upload to your flight controller
arduino-cli upload -p /dev/ttyUSB0 --fqbn esp32:esp32:esp32 flight32.ino

🎛️ Full Control via Serial Manager

Our interactive serial manager provides complete control over your flight controller through both a powerful command-line interface (CLI) and MultiWii Serial Protocol (MSP) support. Here are some of the available CLI commands (type help in the terminal for a full list).

System Commands

• help - Shows the main help message or help for a specific category.
• status - Displays firmware version and system status.
• tasks - Provides a detailed list of all running tasks.
• mem - Shows current memory usage.
• reboot - Reboots the flight controller.
• factory_reset confirm - Resets all settings to their default values.

Sensor & IMU Commands

• get imu.data - Displays the latest accelerometer, gyroscope, and temperature readings.
• get imu.config - Shows the current sensor configuration.
• set imu.calibrate - Starts the gyro calibration routine.

Receiver (RX) Commands

• get rx.data - Shows the latest RX channel data.
• set rx.protocol <protocol> - Sets the RX protocol (e.g., 'set rx.protocol IBUS').
• get rx.value.all - Shows all mapped RX channel values.
• set rx.channel.<name> <index> - Sets the RX channel mapping (e.g., 'set rx.channel.roll 1').

PID Tuning Commands

• get pid - Gets the current PID gains for all axes.
• set pid <axis> <p|i|d> <value> - Sets a specific PID gain (e.g., set pid roll p 20).
• reset pid confirm - Resets all PID gains to their default values.

Filter Commands

• get filter.<key> - Gets a filter setting (e.g., get filter.lpf_hz).
• set filter.<key> = <value> - Sets a filter setting (e.g., set filter.notch1_hz = 250).
• reset filter confirm - Resets all filter settings to their default values.

Settings & Configuration Commands

• get <key> - Gets the value of a specific setting.
• set <key> <value>- Sets a new value for a setting.
• dump - Dumps all settings in a parsable format for backup.
• save - Saves all current settings to persistent storage.
• settings - Lists all available settings.

🧪 MSP Compatibility Testing

To ensure full compatibility with MultiWii Serial Protocol (MSP) tools and ground stations, the Flight32 firmware includes a dedicated Python testing script: flight32_msp_tester.py. This script rigorously verifies that the firmware correctly responds to a comprehensive set of standard MSP commands, including MSP_IDENT (command 100) which is crucial for Betaflight Configurator connection. The Flight32 firmware's MSP implementation has been extensively tested against Betaflight 4.0.6 and 4.2.11 flight controllers, demonstrating a high level of compliance and robust behavior across all commands.

How to Run the MSP Tester:

1. Ensure Python 3 is installed on your system.
2. Install PySerial: If you don't have it already, install the pyserial library:

   pip install pyserial

3. Connect your ESP32: Connect your Flight32-powered ESP32 to your computer via USB. Ensure it's recognized as a serial port (e.g., /dev/ttyUSB0 on Linux, COMx on Windows).
4. Run the tester script: Navigate to the project's root directory in your terminal and execute the script:

   python3 flight32_msp_tester.py --port /dev/ttyUSB0

The script will connect to the ESP32, send various MSP commands, and report on the success or failure of each test, providing detailed feedback on the MSP implementation's compatibility. The Flight32 firmware is designed to pass all applicable tests, gracefully handling commands for unimplemented hardware by returning appropriate default data.

---

ESP32 Devkit Pinout (Common)

This section provides a common pinout reference for ESP32 Devkit boards, focusing on pins typically used in flight controller applications. Please note that pin configurations can vary between different ESP32 versions and manufacturers. Always refer to your specific board's documentation.

Power & Ground:

• 5V: 5V power supply input/output.
• 3.3V: 3.3V power supply output.
• GND: Ground.

I2C (for IMU, e.g., MPU6050):

• GPIO21 (SDA): I2C Data Line.
• GPIO22 (SCL): I2C Clock Line.

UART (for RX, e.g., IBUS):

• GPIO16 (RX2): UART2 Receive.
• GPIO17 (TX2): UART2 Transmit.

Motor Control (DShot - example GPIOs, can be configured):

• GPIO18: Motor 1 Signal (Front Right).
• GPIO19: Motor 2 Signal (Front Left).
• GPIO23: Motor 3 Signal (Rear Right).
• GPIO25: Motor 4 Signal (Rear Left).

Note: This is a general guide. Always consult the schematic and pinout diagram specific to your ESP32 Devkit board.

---

🤝 Contribute

Have an idea or a bug fix? We welcome all contributions! Feel free to open an issue or submit a pull request. Your input helps make Flight32 the best open-source flight controller firmware available.

---

Licensed under the MIT License.