qgroundcontrol

Table of Contents

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

Including MAVLink into your Autopilot / Robot

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

• MAVLink Onboard Integration Tutorial
• MAVLink Arduino Tutorial
• MAVLink Linux/QNX/MacOs Integration Tutorial (UDP)
• MAVLink Ground Control Integration Tutorial

MAVLink Message Format and Protocols

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

• MAVLink Message Documentation
• Mission Protocol
• Parameter Protocol

Contribute Code and Documentation

• Contributor Guide for QGroundControl – How to contribute code.
• User's Guide – QGroundControl User Guide - please help to contribute
• Record QGroundControl – How to create screen videos and tutorials

Libraries and Add-Ons

• OpenSceneGraph

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.

Architecture

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.

Terminology

• 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

• User interface layer, application widgets, e.g. UASView
• Model/Control layer, e.g. UASInterface
• Protocol layer, e.g. MAVLinkProtocol
• Link layer, e.g. SerialLink

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.

The test suite project

qgcunittest.pro

is in the codebase directory. To run the test suite open the project and run it just as you would any other Qt application.

Conventions

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.

Code

QGroundControl uses the BSD-style code formatting, NOT Java like NOR K&R style. Typically a function should look like this:

void functionName(int paramName1, float paramName2, float* returnValue)
{
   if (paramName1 == paramName2)
   {
      *returnValue = paramName1 + paramName2;
   }
   else
   {
      *returnValue = paramName1;
   }
}

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.