MAVLink Ground Control Integration Tutorial

This tutorial covers the integration of new MAVLink packet formats. Assuming you successfully followed the MAVLink Onboard Integration Tutorial, you can now receive data from your MAV.

This is work in progress, please feel free to edit/extend it


Integrating your messages has two primary phases:

  1. Expose your custom messages to QGroundControl, which enables basic functionality like data logging, the MAVLink receive widget, and the MAVLink send widget
  2. Create a new UAS subclass that can appropriately handle the data coming in from your new messages.

Exposing custom messages to QGroundControl

Follow the instructions below to compile QGroundControl with your own custom messages. This provides a base set of functionality such as data logging, using the MAVLink Receive widget to view incoming messages, and using the MAVLink Transmit widget to manually transmit messages.


  1. Make a MAVLink message definition .xml file like the one shown below (reference the files in /message_definitions in the MAVLink project).
  2. Follow the MAVLink library generation instructions to generate a custom MAVLink library (this will involve using in the MAVLink project to create a custom 1.0 version of MAVLink for the C language).
  3. Copy the generated files into the libs/mavlink directory.
  4. Rename user_config.pri.dist to user_config.pri and modify it so that the MAVLINK_CONF variable is set to the name of your custom messages: for example, if your file was called slugs.xml, then MAVLINK_CONF should be set to slugs.
  5. Optional: Follow the instructions in the section below about extending the UAS base class
  6. Follow the build instructions for QGC for your platform.

Creating a new UAS subclass

If additional functionality is required, you'll need to write some C++ code. QGroundControl represents each MAV with its own class, which derives from the base class of UAS. This is the default class for all MAVs, though that can be overridden by specifying the correct AUTOPILOT_TYPE in heartbeat messages transmit from your autopilot. An example of an existing subclass of UAS, like what you will create, can be found in the PxQuadMAV class, which represents a PIXHAWK quadrotor.

To begin your integration:

  1. Create a new class (in /src/uas) that derives from UAS, implements UASInterface, and is a Q_OBJECT (reference PxQuadMAV if necessary).
    • The primary function of this class will be in the overridden receiveMessage() function that processes all MAVLink messages as they're received.
  2. Modify /src/uas/ to add a switch for your Autopilot type and to instantiate the correct class.
  3. Choose an unused value for your AUTOPILOT_TYPE transmit in your heartbeat message and check for that value. If you're looking to push your code back into QGroundControl also modify the AUTOPILOT_TYPE_ENUM in common.xml with a new value for your specific autopilot.
  4. If necessary, modify other code within QGroundControl by checking for the QGC_USE_%1_MESSAGES where the %1 is replaced with your autopilot name (which was specified in the MAVLINK_CONF variable. Use the standard C/C++ #ifdef/#endif to isolate your changes to only when QGroundControl is compiled for your autopilot.
  5. Modify the file to include the header and source file for your new class when compiling.