User's Guide

This user guide covers the whole application, split into the individual widgets.

Important things to know

  • You can add a new link (serial/radio modem) by clicking NetworkAdd Link
  • The groundstation listens on UDP port 14550 for incoming MAVLink Micro Air Vehicle Communication Protocol messages.
  • It can log data via the line chart view and plot directly or export to e.g. Matlab.
  • It can log the raw data packets (in the link settings menu) and replay whole flights/missions later.

Contact to other Users and online Help

Google Groups
Visit this group

Bug Reports

Want to file a bug report? Please head to the GitHub issue tracker. All filed bugs will be resolved!.

Getting Started

Once you start up QGroundControl, you will get a 2D aerial map and an information box on the right. Please note that in this mode most widgets are hidden, so you won't see the full functionality until a system is connected. Click on “Simulate” to simulate two vehicles to see QGroundControl in action. Once the simulation is running, you won't see more widgets immediately, but you have now the option to enable them through the menu. Start to explore the application by selecting different views (e.g. Google Earth, Line charts, etc.) and by adding widgets to your current view, e.g. the Flight Display or Payload Status. This setup will be stored for the next time you start up QGroundControl, so take your time to customize it.

Google Earth 3D View

Please not that due to Google's strict plugin policy there is at this point no Google Earth support for Linux. Google Earth is fully supported on Mac OS X and Windows.

Google Earth 3D View with Mission Plan Widget docked on bottom

QGroundControl Google Earth View

MAV / UAS Controls

  • Choose either the distance to the MAV or the distance to the ground as camera height
  • Select the distance with the distance slider
  • Enable / disable following
  • Enable / disable the display of the flight trajectory / trail
  • You can clear the current trajectory, a new trajectory starting at the current position will be created

Jump to Latitude / Longitude Coordinates

  • Click on Lat/Lon and enter the coordinates

Add / Edit Waypoints and Home Location

  1. Click on edit to activate edit mode
  2. Double click in the map to create a waypoint
  3. Click on “Set Home” to change the home location, click on once in the map to set the new location
  4. Drag the waypoints (red, numbers) and home location (black “H”) as you like

Please note:

  • You can save waypoints in the waypoint mission plan widget to text files and re-import them
  • Your home location is stored by QGroundControl, so you can start with the last location

View Controls

  • Enable / disable daylight simulation mode, where the earth is displayed at day or night
  • Enable / disable natural sky mode, where the earth is displayed with haze and blue horizon

Local 3D View

Currently only enabled on Linux and Mac OS X

QGroundControl Google Earth View

Flight / Gauge Display

The flight display allows to show relevant system information in form of gauges (will be extended to sliders, etc.). You can customize the widget by right-clicking on it. You can define the number of columns for the instruments as well as what should be displayed. The syntax is pretty simple:

min,curve name,max

The curve name consists of the MAV ID (in this case MAV #1, so M1), the message name (attitude) and the field name (pitch). The syntax allows to e.g. have two gauges indicating the airspeed of two or more different aircraft.

If you want to have a symmetric gauge with 0 position at top (north), add an s to the specs and choose a symmetric range (e.g. -3 to 3 radians):

min,curve name,max

The dialog will offer a list of the available curves once you click on “New curve” in the mouse context menu.

Horizontal Situation Indicator

The horizontal situation indicator shows the “world” from above in the body coordinate frame. The view thus turns with the vehicle and shows its current sourrounding. This is in contrast to the global 2D map, which shows the usual north-up orientation.

The view in detail:

  • ATT: Attitude control enabled, either  ON   or  OFF  
  • PXY: Horizontal position control enabled, either  ON   or  OFF  
  • PZ: Vertical position / altitude control enabled, either  ON   or  OFF  
  • YAW: Yaw angle control enabled (on helicopters), either  ON   or  OFF  
  • POS: Position lock from all sensors together, either  2D  ,  3D   or  NO  
  • VIS: Position lock from vision only, either  2D  ,  3D   or  NO  
  • GPS: Position lock from GPS only, either  2D  ,  3D   or  NO  
  • IRU: Position lock from InfraRed or Ultrasound, either  2D  ,  3D   or  NO  
  • Bottom left text: Ground speed in meters per second
  • Bottom right: Current position in meters
  • Far bottom left combobox: Allows to zoom in/out
  • Circle: Compass indicating north, etc.
  • Diamonds: Waypoints of this vehicle (colored in the vehicle color, in this case red), current selected waypoint in blue
  • Long line: Indicates current position controller setpoint / current vector

The serial link configuration windows allow you to configure the serial port according to your needs. You can add a new serial link by clicking NetworkAdd Link in the main menu.

QGroundControl Serial Port Settings

Additional Options

  • Emit heartbeat – Sends a heartbeat message to the MAVs. Per default QGC is completely silent
  • Log all MAVLink packets – Logs the packets to disk, once checked you can select the filename. (Can be replayed later with the MAVLink Logplayer widget)
  • Only accept MAVs with same protocol version – Does reject the connection attempts of MAVs not having the same MAVLink version, as stated on this page: MAVLink Micro Air Vehicle Communication Protocol.

Onboard Parameters and Transmission Settings

The onboard parameters widget allows to read and set onboard parameters. Typically these are controller gains, calibration values, system ids, serial port baud rate, etc. If you follow the standard implementation, only the MAV has to know its parameters and sends the list to the GCS on system startup (and on user-request). This is very convenient, as adding a parameter does not require any change to the GCS.

Parameters can be either just set in the current RAM or permantly stored to EEPROM. The widget only sends those parameter that were changed, so after the list is transmitted once, it is very bandwidth-effective.

The transmission checkboxes below the parameter interface allow to enable / disable data transmission on user request. This saves precious wireless modem bandwidth but still allows you to e.g. have a look at raw sensor values if needed.

Telemetry Data Linechart Plot

The line chart allows to plot any incoming telemetry data in realtime. It allows to select/deselect single curves and autoscales. It also allows to zoom in. The main functions are:

  • LIN button: Linear axis scales
  • LOG Button: Logarithmic axis scales
  • AVG Window: Number of samples to be averaged for mean and variance calculation
  • Start logging: Opens up a file select dialog to log to MATLAB EXCEL OPENOFFICE and other tools that can read CSV files with <tab> as separator.
  • Ground time: Overwrites the MAVLink timestamps with the current groundtime. Useful if your MAV sends wrong timestamps
  • Show units: Shows the units in the curve list widget of each value.

Joystick Configuration Window

The joystick configuration window allow you to configure and test your joystick. The ground control station will automatically detect all present joysticks on startup.

Communication Debug Console

The purpose of the communication debug console is to allow low-level access to the data on the communication link. This is not only helpful for work on the communication itself, but allows also some handy 'hacks' in the daily development.

Communication Console

OpenMAV Groundstation Debug Console

  • Link: Select which link output to show
  • Auto Hold: The window will stop updating if more than a few kb/s of data are streamed. Constant updates can be enforced by unchecking the box
  • Hide MAVLink: Tries to ignore valid MAVLink packets - FIXME Not perfect yet
  • HEX: Select hexadecimal or ASCII output


  • Hold: Freeze current output
  • Send: Send content in textbox
  • Clear: Clear text/log window
  • Connect/Disconnect: Connect or disconnect the current link

Mixture of ASCII and protocol payload

The debug console allows to filter out MAVLink messages, thus only leaving any non-protocol text. This way you can e.g. send plaintext from the ARM MCU for debugging/testing purposes while still getting the rest of the data in MAVLINK format.

Send ASCII / HEX values

The debug console also allows to send either ASCII or HEX values, which is also quite helpful during testing. HEX values in these formats are supported:

0x55 0xAA
0x55 0xaa
55 AA
55 aa

The debug console allows to quickly switch between the output of different links and currently (Feb 2010) supports UDP and serial links.

Hold and Clear the Window

The <key>Hold</key> and <key>Clear</key> buttons allow to either hold the current console content to prevent scrolling or to clear all received data so far.

User-Configurable Tool Widgets


MAV Command Button


Installation on Linux (Ubuntu) - set proper permissions

If you have trouble connecting pixhawk, try the following:

  1. sudo chmod 666 /dev/ttyACM0 –> sets the proper permission
  2. sudo usermod -a -G dialout name –> replace name with your account and don't forget to logout/login. This adds your user to the dialout-group
  3. sudo apt-get remove modemmanager –> modemmanager tends to occupy a device only briefly, but it's initial tests make trouble for any firmware upgrade software that reboots the pixhawk