Developer's Guide

QGroundControl is a modular application whose architecture is optimized for future extensions and open-source contributions. This sections gives an overview of the application architecture.

Building QGroundControl

To work with the application source, please first install the Qt environment and then download and compile the QGroundControl source.

  1. Qt and Dependencies Installation – Install Qt toolchain
  2. Build from Source – Build from source
  3. Common Build Mistakes – If you run into trouble during building
  4. Deployment – Deploy on multiple machines

To use QGroundControl with your system, please follow the tutorials below to integrate it with your robot.

This website lists the different MAVLink ENUMs and messages as human-readable documentation:

Contribute Code and Documentation

Libraries and Add-Ons

An Important Note

On most platforms Qt Creator will be the IDE of choice. Please note however that although it's a nice and convenient tool, it sometimes fails to rebuild everything needed on large code changes. Effectively this results in random crashes of QGroundControl. The solution is quite easy: Delete the build folder manually. On Linux and Mac OS delete "qgroundcontrol-build-desktop", which is a folder in the same parent directory as the "qgroundcontrol" folder. On Windows with Visual Studio, delete the "release" and "debug" folders inside the "qgroundcontrol" folder.


QGroundControl is an object-oriented C++/Qt application allowing to represent and control micro air vehicles. QGroundControl adheres to the model-view-controller and ISO/OSI layer design patterns. This means that data, data manipulation and user interface representation are separated and that the access on hardware/communication links is abstracted from the application layer.

QGroundControl Architecture


  • Interface: An abstract class that can be inherited but not instanced
  • Model: Data structure / container representing a physical object (e.g. a MAV)
  • View: User interface component visualizing the data of the model
  • Controller: Class/functions to manipulate the model
  • Widget: One view, one component of the user interface. E.g. a list of the MAVs is one widget

In practice data enters and leaves the application through the LinkInterface class, is then handled/parsed by the ProtocolInterface class and then fed into the model representing one unmanned system, the UASInterface class. All these classes are abstract and can't be instantiated, instead inherited classes are used as instances. The user interface layer, e.g. the head up display HUD, interfaces to the UASInterface class, representing the model. Because QGroundControl is a streaming/control centered application, model and controller are often combined in the same class.

Main Layers

Extending QGroundControl

QGroundControl's modular design allows to extend it on each layer: New physical links can be added, new physical links and protocols can be added. And to represent a new type of system, e.g. a ground robot, new robot objects can be added. The most common extension will be new user interface widgets. To extend QGroundControl, please clone the GitHub repository, add your changes and send a pull request to the maintainer, explaining what you did and what the benefit of your changes is.

Code Checking using cppcheck

In ubuntu the following command can be used to check the project code using cppcheck

$cd pixhawk/qgroundcontrol
$cppcheck --enable=all src/ 2> cppcheck.log

cppcheck can be obtained from the ubuntu repos using

$sudo aptitude install cppcheck

There are other levels of reporting that can be configured. These levels are documented in the manual.

The cppcheck source also includes a gui which can be compiled using qtcreator.

Unit Testing the Source Code

In an effort to get the best possibly reliability from the code, the complete code based will gradually be unit tested. The unit tests in the codebase use the QTestLib framework which is part of Qt, so there are no additional dependencies.

It is ideal that if you are writing a new class for your autopilot you implement unit tests for that class. Although currently it is not a requirement, in the near future you will be encouraged to write unit test for your classes in order for them to be merged into the main repository. This will give you at the same time the comfort that you did not break anybody else's code and that if you are pulling others' changes, they did not break yours.

To run the test suite, simply run the debug build with –unittest on the command line. Existing unit test can be found int the src\qgcunittest directory.


As QGroundControl represents physical objects, clear conventions are important for the coordinate frames and units. All units in QGroundControl are SI-units (from physics) and represented in IEEE-754 double precision floating point numbers. All units that do not have a physical SI unit should be normalized between 0 and 1, all percentages between 0 and 100.


Tabs/Spaces: Tabs are set at 4, Tabs are converted to spaces

Style: Best way to describe the style to follow is with an example. Please follow the style as seen in src/ui/px4_configuration/PX4RCCalibration.h|cc.

Documentation: Use the oxygen tags as shown in the example. Guidelines as to where method documentation should go are as follows: Public and Private methods should be documented in the header file. Private method should be documented in the source file.

File Formats

The standard file formats for log files and waypoints is a tab-separated plain text format. This allows easy importing into Microsoft Excel / OpenOffice and Matlab.

Physical Coordinate Frame

As QGroundControl is mainly used in the MAV / aeronautical domain, all 3D position data is assumed to be in the standard aeronautical frame in SI units. This implies a right-handed, positive Z pointing downwards coordinate frame convention. This frame is usually called NED (x: north, y: east, z: down).

UI Coordinate System

QGroundControl uses the standard top-left OpenGL screen coordinate frame. See details here.