PX4 MAVSDK – C++ Programming [Part 1] Library Overview and Architecture

Hello! I’m Aiden from the Marketing Team.

Today, we will be diving into PX4 Autopilot, the world’s most widely used open-source flight control stack, and MAVSDK C++, the essential library for controlling drones from a Companion Computer. In this first session, before we get our hands dirty with code, we’ll cover the background, communication protocols, and the overall system architecture of MAVSDK.

The Genesis of MAVSDK and the MAVLink Protocol

In the past, drones were primarily operated manually by pilots using radio controllers. Today, however, drones have evolved into “Autonomous Flying Robots” that carry various sensors like cameras and LiDAR, and use AI to plan paths and avoid obstacles.

To achieve such high levels of autonomy, seamless communication between the Flight Control Unit (FCU)—the brain of the drone—and a high-performance Companion Computer (which handles complex computations) is essential. MAVSDK (MAVLink SDK) acts as the bridge between these two. Formerly known as the ‘Dronecode SDK’, this project abstracts the standard MAVLink protocol into modern C++ object-oriented code, allowing researchers to focus on their autonomous flight algorithms rather than getting bogged down by complex communication specs.

💡 What is the MAVLink Protocol?

The backbone of MAVSDK, MAVLink (Micro Air Vehicle Link), is an ultra-lightweight binary serialization protocol designed for communication between resource-constrained microcontrollers and higher-level computers.

• Data Serialization Mechanism: MAVLink automatically generates source code from XML-based message definition files. It consumes much less bandwidth than text-based formats like JSON or XML and maintains high transmission speeds with minimal CPU overhead.
• Evolution of MAVLink v2.0: The current version supported by MAVSDK, MAVLink v2.0, supports an expanded 24-bit message ID system, allowing for thousands of message types. It also includes message signing for security to prevent data spoofing attacks.

2. PX4 Autopilot Internal Structure and uORB Middleware

To write effective MAVSDK C++ code, you must understand how the PX4 Autopilot—our target system—operates internally. PX4 is divided into the Flight Stack and the Middleware.

The core of the middleware layer is the uORB (Micro Object Request Broker), an asynchronous messaging bus. It operates on a Publish-Subscribe model.

How it works:

1. A sensor driver measures acceleration data and Publishes it to a uORB Topic.
2. The Position Estimator (EKF2) module Subscribes to this data to calculate the drone’s current position and velocity.
3. PX4’s MAVLink module also Subscribes to these internal uORB topics to create packets for the external MAVSDK, and conversely Publishes incoming commands from MAVSDK to uORB topics to control the aircraft.

Essentially, when you call takeoff() in MAVSDK, it is converted into a MAVLink message, sent to the drone, passed through uORB, and finally reaches the motor controllers.

3. MAVSDK C++ Architecture: Core and Plugins

Companion computers or embedded boards (e.g., Raspberry Pi, NVIDIA Jetson) used in research often have limited computing resources. The MAVSDK C++ library uses a modular architecture consisting of a Core and independent Plugins to ensure both performance and scalability.

1) The Core Layer

The Core handles the low-level communication. It analyzes Heartbeat messages sent periodically by the drone via UDP, TCP, or Serial ports to ‘Discover’ the system. Once discovered, the drone is instantiated in memory as a System C++ object.

2) Plugin-Based Functional Separation

Every control feature is provided as a completely independent plugin. This is safe because modifying one plugin does not affect others.

• Action: Controls basic flight maneuvers like Takeoff, Land, and Arming.
• Telemetry: Subscribes to real-time sensor data such as GPS position, battery status, and flight modes.
• Offboard: A precision control mode that feeds AI or vision-based setpoints (velocity, attitude, position) directly to the drone.
• Mission: Uploads and executes complex autonomous flight paths using waypoints.

4. Object-Oriented Programming (OOP) and Resource Management

MAVSDK C++ is built on the modern C++17 standard. It leverages OOP features to make the code highly intuitive.

The first step is creating the Mavsdk object, which manages the program’s lifecycle. From there, you obtain a System object representing the connected drone. All plugins (Action, Telemetry, etc.) are created as Shared Pointers (std::shared_ptr) based on this System object. When the main program terminates, the parent objects are destroyed, and all related resources are automatically cleaned up without memory leaks.

Example 1) Connection and Initialization

#include <mavsdk/mavsdk.h>
#include <mavsdk/plugins/action/action.h>
#include <iostream>

using namespace mavsdk;

int main() {
    // 1. Initialize the Core engine
    Mavsdk mavsdk{Mavsdk::Configuration{ComponentType::GroundStation}};

    // 2. Connect to the Simulator (SITL) UDP port
    ConnectionResult connection_result = mavsdk.add_any_connection("udpin://0.0.0.0:14540");
    
    if (connection_result != ConnectionResult::Success) {
        std::cerr << "Connection Failed: " << connection_result << '\n';
        return 1;
    }

    // 3. Wait for Drone system discovery
    auto system = mavsdk.first_autopilot(3.0);
    if (!system) {
        std::cerr << "Timed out: Drone not found.\n";
        return 1;
    }

    // 4. Instantiate Action Plugin
    auto action = Action{system.value()};
    
    std::cout << "Successfully connected to the drone system!\n";
    return 0;
}

#include <mavsdk/mavsdk.h>
#include <mavsdk/plugins/action/action.h>
#include <iostream>

using namespace mavsdk;

int main() {
    // 1. Initialize the Core engine
    Mavsdk mavsdk{Mavsdk::Configuration{ComponentType::GroundStation}};

    // 2. Connect to the Simulator (SITL) UDP port
    ConnectionResult connection_result = mavsdk.add_any_connection("udpin://0.0.0.0:14540");
    
    if (connection_result != ConnectionResult::Success) {
        std::cerr << "Connection Failed: " << connection_result << '\n';
        return 1;
    }

    // 3. Wait for Drone system discovery
    auto system = mavsdk.first_autopilot(3.0);
    if (!system) {
        std::cerr << "Timed out: Drone not found.\n";
        return 1;
    }

    // 4. Instantiate Action Plugin
    auto action = Action{system.value()};
    
    std::cout << "Successfully connected to the drone system!\n";
    return 0;
}

🚨 Result Returns Instead of Exceptions

In robotics or real-time embedded systems, try-catch exceptions can make execution time unpredictable. Therefore, MAVSDK does not throw exceptions. Instead, function calls return Result Enums (e.g., Action::Result). Developers can check these values to determine exactly why a command succeeded or was rejected.

5. Asynchronous Model for Real-Time Control

In autonomous flight research, the program must never “freeze” (block) while waiting for data. MAVSDK provides an event-driven asynchronous architecture for high-performance real-time processing.

Callback Threads and Critical Warnings

When the latest telemetry data arrives from the drone, MAVSDK’s internal background thread immediately calls the callback function we have registered.

Example 2: Subscribing to Data

#include <mavsdk/plugins/telemetry/telemetry.h>

// Assuming a telemetry plugin object exists
telemetry.subscribe_position([](Telemetry::Position position) {
    std::cout << "Current Altitude: " << position.relative_altitude_m << " m\n";
});

#include <mavsdk/plugins/telemetry/telemetry.h>

// Assuming a telemetry plugin object exists
telemetry.subscribe_position([](Telemetry::Position position) {
    std::cout << "Current Altitude: " << position.relative_altitude_m << " m\n";
});

⚠️ Pro-tip for Researchers!
All user callbacks are executed sequentially on a single dedicated MAVSDK callback thread. Therefore, you must NEVER perform heavy tasks (e.g., OpenCV vision processing, Deep Learning inference, or file saving) inside these callback functions.

If the callback thread is blocked, subsequent sensor updates will be delayed, increasing system latency. In Offboard mode, this can trigger a Failsafe and potentially cause the drone to crash. Always process heavy algorithms in a separate Worker Thread using std::thread, and use the callback only to update a global variable with the latest data.

In this first part, we explored why MAVSDK C++ is necessary for autonomous robots, how MAVLink and PX4 communicate, and the design philosophy behind its modular, asynchronous architecture. Understanding “why this library was designed this way” is a crucial foundation for any flight algorithm.

Next Up: [Part 2] Core C++ Syntax for MAVSDK. We will cover the essential C++ concepts—STL, references (&), and lambda functions—needed for MAVSDK programming with practical examples.

Author: Aiden, Marketing Team at QUAD Drone Lab

Date: March 09, 2026