MagisV2 API Documentation

Overview

MagisV2 is a comprehensive flight controller API designed for drone and UAV applications. Built by Drona Aviation, this API provides a complete software framework for controlling autonomous flight systems, managing sensors, handling communication protocols, and interfacing with various hardware peripherals.

Architecture

The MagisV2 flight controller is built around primary blocks responsible for reading sensor data, calculating the drone's state, receiving user input, and controlling the motors. The system architecture ensures real-time performance and modular design for easy integration.

Diagram

Primary Flight Control Blocks

1. FC-Data (Flight Control Data)

Responsible for obtaining and processing the drone's current state through a complete sensor fusion pipeline:

• Sensors: Raw, noisy data from hardware sensors

  • Accelerometer (X, Y, Z, Net_Acc)
  • Gyroscope (X, Y, Z)
  • Magnetometer (X, Y, Z)
  • Barometer (Pressure, Temperature)

• Filters: Processing stage using filtering algorithms (Complementary Filter) to remove noise

• Estimate: Filtered and stable state variables

  • Angle (Roll, Pitch, Yaw)
  • Rate (X, Y, Z)
  • Position (X, Y, Z)
  • Velocity (X, Y, Z)

2. FC-Config (Flight Control Configuration)

Holds key parameters and target values for the control system:

• User Loop Frequency: Main processing rate of the flight controller
• Translational PIDs: Control forward/backward and side-to-side movement
• Rotational PIDs: Control rotational movement with Desired Angle and Desired Rate
• Failsafe Configuration: Safety mechanisms and thresholds

3. FC-Control (Flight Control)

Manages user commands and high-level flight logic:

• Commands: ARM/DISARM, Takeoff/Land/Flip operations
• Flight Status: Current operational state (Landed, Flying, Armed)
• FC-Interface: Processes user input (RC-Data/APP) into RC-Commands
• Rx-Config: Communication receiver configuration (PPM/ESP, Channel Config)
• Flight Modes: Angle Mode, Rate Mode, Altitude Hold, etc.
• HeadFree Mode: Reference orientation storage

4. Motors

Translates control outputs into motor power signals:

• Regular Motors (M5-M8): Unidirectional motor control
• Bi-Directional Motors (M1-M2): Reversible motors with separate initialization

Supporting and Peripheral Blocks

5. BMS (Battery Management System)

Real-time battery health and usage monitoring:

• Voltage and Current readings
• mAh Consumed & Remaining tracking
• Battery Capacity (rated) and Estimated Capacity

6. Peripherals and Serial Communication

Low-level hardware interfaces:

• Peripherals: ADC, GPIO, PWM interfaces
• Serial: I2C, SPI, UART communication protocols

7. Add-Ons

External features and expansion modules:

• OLED: Display screen interface
• X-Ranging: Proximity/distance measurement sensors
• Localisation: Position tracking systems (UWB, WHYCON, VICON)

8. Debugging

Monitoring and logging utilities:

• Print/Graph: Debug output and real-time data plotting
• OLED Display: System status visualization
• Black Box: Flight data logging

Key Features

• Real-time Performance: Configurable loop frequencies (3.5-2000 Hz)
• Multi-mode Flight Control: Manual, stabilized, and autonomous modes
• Advanced Sensor Fusion: Noise filtering and state estimation
• Comprehensive Safety: Failsafe systems and health monitoring
• Modular Design: Clean API separation for easy integration
• Hardware Abstraction: Unified peripheral access

Getting Started

Basic Usage Pattern

#include "API/PlutoPilot.h"

void plutoInit() {
    // Initialize your hardware and configurations
    // Set up flight modes, PID parameters, etc.
}

void plutoLoop() {
    // Main control loop - runs at configured frequency
    // Implement your flight logic here
}

Development Workflow

1. Configuration: Set up receiver modes, flight parameters, and hardware interfaces
2. Initialization: Initialize required sensors, communication interfaces, and peripherals
3. Control Loop: Implement your flight control logic in the main loop
4. Monitoring: Use debugging tools to monitor system performance and sensor data

API Documentation

The MagisV2 API documentation is organized by header file:

Core System

• PlutoPilot.h: Main system interface and loop management
• API-Utils.h: System utilities and global variables
• Specifiers.h: Pin specification definitions

Flight Control

• FC-Control.h: Flight status, modes, and commands
• FC-Config.h: PID configuration and system settings
• FC-Data.h: Sensor data access and state estimation

Sensors & Data

• BMS.h: Battery management system
• XRanging.h: Laser ranging sensors
• Localisation.h: Position tracking systems

Communication

• RC-Interface.h: Remote control interface
• RxConfig.h: Receiver configuration
• Serial-IO.h: UART, I2C, and SPI protocols

Hardware Peripherals

• Motor.h: Motor control interface
• Peripherals.h: GPIO, ADC, and PWM control
• Status-LED.h: Status LED control

Utilities & Debugging

• Debugging.h: Debug output and OLED display
• Scheduler-Timer.h: Timing and task scheduling

Safety Considerations

• Always test in a safe environment before deploying on actual aircraft
• Implement proper failsafe mechanisms for critical operations
• Monitor battery levels and system health continuously
• Follow proper arming/disarming procedures
• Ensure proper calibration of sensors before flight

License

MagisV2 is released under the GNU General Public License v3.0 or later. See the license headers in individual files for complete terms.