README.md 14.8 KB
Newer Older
1
# QGroundControl
2 3
## Open Source Micro Air Vehicle Ground Control Station

4 5 6
[![Travis Build Status](https://travis-ci.org/mavlink/qgroundcontrol.svg?branch=master)](https://travis-ci.org/mavlink/qgroundcontrol)
[![Appveyor Build Status](https://ci.appveyor.com/api/projects/status/crxcm4qayejuvh6c/branch/master?svg=true)](https://ci.appveyor.com/project/mavlink/qgroundcontrol)

The Gitter Badger's avatar
The Gitter Badger committed
7 8
[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/mavlink/qgroundcontrol?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

9 10 11 12 13 14 15 16 17 18 19 20

* Project:
<http://qgroundcontrol.org>

* Files:
<http://github.com/mavlink/qgroundcontrol>

* Credits:
<http://qgroundcontrol.org/credits>


## Documentation
Don Gagne's avatar
Don Gagne committed
21
For generating documentation, refer to this readme or the <http://qgroundcontrol.org> website.
22

Don Gagne's avatar
Don Gagne committed
23 24
## Obtaining source code
There are three ways to obtain the QGroundControl source code from our GitHub repository. You can either download a snapshot of the code in a ZIP file, clone the repository, or fork the repository if you plan to contribute to development. If you prefer one of the last two options you will need Git installed on your system; goto GitHub Help and see Set Up Git.
25

Don Gagne's avatar
Don Gagne committed
26 27
### Clone the Repository
This option assumes that you have Git already. To clone (checkout) the QGC repository, run the following command in the directory that you want the qgroundcontrol folder to be created:
28

29 30 31
```
git clone --recursive git://github.com/mavlink/qgroundcontrol.git
```
32

Don Gagne's avatar
Don Gagne committed
33 34
### Fork the Repository
If you plan to contribute to the development of QGC, you will want this option, which also requires that you have Git set up. To fork the QGC repository, do the following:
35

Don Gagne's avatar
Don Gagne committed
36 37
Goto GitHub Help and see Fork A Repo
Fork the QGC Repo
38

Don Gagne's avatar
Don Gagne committed
39 40
### Initialize submodules
After cloning or forking you will need to initialize and update the submodules using these commands in you qgroundcontrol source directory:
41

Stefano Probst's avatar
Stefano Probst committed
42
```
Don Gagne's avatar
Don Gagne committed
43 44
git submodule init
git submodule update
Stefano Probst's avatar
Stefano Probst committed
45
```
46

Don Gagne's avatar
Don Gagne committed
47
Each time you pull new source to your repository you should re-run "git submodule update" to get the latest submodules as well.
48

49
## Building QGroundControl
Don Gagne's avatar
Don Gagne committed
50
QGroundControl builds are supported for OSX, Linux and Windows. See the individual sections below for instruction on how to build on each OS. Also make sure to look at the "Additional Build Notes" section below.
51

Don Gagne's avatar
Don Gagne committed
52 53
### Build on Mac OSX
Supported builds are 64 bit, built using the clang compiler.
54

Don Gagne's avatar
Don Gagne committed
55
#### Install QT
56

Don Gagne's avatar
Don Gagne committed
57
1. Download Qt 5.4 from: <http://download.qt-project.org/official_releases/qt/5.4/5.4.0/qt-opensource-mac-x64-clang-5.4.0.dmg>
Don Gagne's avatar
Don Gagne committed
58
2. Double click the package installer and follow instructions.
59

Don Gagne's avatar
Don Gagne committed
60 61
#### Build QGroundControl
1. From the terminal change directory to your `groundcontrol` directory
Don Gagne's avatar
Don Gagne committed
62
2. Run `~/Qt/5.4/clang_64/bin/qmake qgroundcontrol.pro -r -spec macx-clang`. If you installed a different version of Qt, or installed to a different location you may need to change the first portion of the path.
Don Gagne's avatar
Don Gagne committed
63
3. Run `make`
64

Don Gagne's avatar
Don Gagne committed
65 66
### Build on Linux
Supported builds for Linux are 32 or 64-bit, built using gcc.
67

Don Gagne's avatar
Don Gagne committed
68
#### Install Qt5.4 and SDL1.2 prerequistites
69
* For Fedora: `sudo yum install qt-creator qt5-qtbase-devel qt5-qtdeclarative-devel qt5-qtserialport-devel qt5-qtsvg-devel qt5-qtwebkit-devel SDL-devel SDL-static systemd-devel qt5-qtgraphicaleffects qt5-qtquickcontrols qt5-qtlocation-devel`
Don Gagne's avatar
Don Gagne committed
70
* For Arch Linux: `pacman -Sy qtcreator qt5-base qt5-declarative qt5-serialport qt5-svg qt5-webkit`
71
* For Ubuntu: Please be aware that the time of writing, Qt5.4 is unavailable in the official repositories Ubuntu 14.04/Mint 17
Lorenz Meier's avatar
Lorenz Meier committed
72 73
    * Add this PPA for Qt5.4: `sudo add-apt-repository ppa:beineri/opt-qt542-trusty`
        * If you get a 404 error from "apt-get update" below, open System Settings:Software & Updates:Other Software and edit the entry for opt-qt542-trusty to reference Distribution: trusty.
Don Gagne's avatar
Don Gagne committed
74
    * Run the following in your terminal: `sudo apt-get update && sudo apt-get install qt54tools qt54base qt54declarative qt54serialport qt54svg qt54webkit qt54quickcontrols qt54xmlpatterns qt54x11extras qt54websockets qt54sensors qt54script qt54quick1 qt54multimedia qt54location qt54imageformats qt54graphicaleffects qt54connectivity libsdl1.2-dev libudev-dev`
Don Gagne's avatar
Don Gagne committed
75 76
    * Next, set the environment variables by executing in the terminal: `source /opt/qt54/bin/qt54-env.sh` or copy and paste the contents to your `~/.profile` file to set them on login.
    * Verify that the variables have been set: `echo $PATH && echo $QTDIR`. The output should read `/opt/qt54/bin:...` and `/opt/qt54`.
77

78 79
If you get this error when running qgroundcontrol: /usr/lib/x86_64-linux-gnu/libstdc++.so.6: version 'GLIBCXX_3.4.20' not found. You need to either update to the latest gcc, or install the latest libstdc++.6 using: sudo apt-get install libstdc++6.

Don Gagne's avatar
Don Gagne committed
80
#### [Optional] Install additional libraries
Don Gagne's avatar
Don Gagne committed
81
* For text-to-speech (espeak)
Thomas Gubler's avatar
Thomas Gubler committed
82 83
	* For Ubuntu: `sudo apt-get install espeak libespeak-dev`
	* For Fedora: `sudo yum install espeak espeak-devel`
Julian Oes's avatar
Julian Oes committed
84
	* For Arch Linux: `pacman -Sy espeak`
Don Gagne's avatar
Don Gagne committed
85
* For 3D flight view (openscenegraph)
86
	* For Ubuntu: `sudo apt-get install libopenscenegraph-dev`
Susurrus's avatar
Susurrus committed
87 88
	* For Fedora: `sudo yum install OpenSceneGraph`
	* For Arch Linux: `pacman -Sy openscenegraph`
89

Don Gagne's avatar
Don Gagne committed
90
#### Build QGroundControl
Don Gagne's avatar
Don Gagne committed
91
1. Change directory to you `qgroundcontrol` source directory.
92
2. Run `qmake -r qgroundcontrol.pro`
Don Gagne's avatar
Don Gagne committed
93
3. Run `make`
94

Don Gagne's avatar
Don Gagne committed
95 96
### Build on Windows
Supported builds for Windows are 32 bit only built using Visual Studio 2013 or higher.
97

Don Gagne's avatar
Don Gagne committed
98 99 100
#### Install Windows USB driver to connect to Pixhawk/PX4Flow/3DR Radio
Install from here: http://www.pixhawk.org/firmware/downloads

Don Gagne's avatar
Don Gagne committed
101 102
#### Install Visual Studio Express 2013
Only compilation using Visual Studio 2013 is supported. Download and install Visual Studio Express Edition (free) from here: <http://www.visualstudio.com/downloads/download-visual-studio-vs#d-express-windows-desktop>. Make sure you install the Windows Desktop version.
103

Don Gagne's avatar
Don Gagne committed
104 105
#### Install Qt5.4
Download Qt 5.4 from here: <http://download.qt-project.org/official_releases/qt/5.4/5.4.0/qt-opensource-windows-x86-msvc2013_opengl-5.4.0.exe>
Don Gagne's avatar
Don Gagne committed
106
  * The Qt variant should be for VS 2013, 32 bit (not 64) and include opengl.
107

Don Gagne's avatar
Don Gagne committed
108 109 110
#### Build QGroundControl
1. Open the Qt Command Prompt program from the Start Menu
2. Change directory to your 'qgroundcontrol' source folder.
111 112
3. Run `qmake -r -tp vc qgroundcontrol.pro`.  This will create a 'qgroundcontrol.sln' *Solution* file which is capable of building both debug and release configurations.
4. Now open the generated 'qgroundcontrol.sln' file in Visual Studio.
113
5. Compile and edit in Visual Studio. If you need to add new files to the qgroundcontrol project, add them to QGCApplication.pro and re-run qmake from step 3.
114

115
Note that the *Solution* contains two projets. The main QGroundControl project and the QGC Geoservice Provider Factory plugin. From within Visual Studio, before running or debugging, make sure you have *qgroundcontrol* as the current project (right-click and select *Set as Current Project*)
116

Gus Grubba's avatar
Gus Grubba committed
117 118 119 120 121 122
#### Alternate (Qt Creator IDE) Build Type (Any OS)
All steps below assume you already have a running software development enviroment (i.e. gcc/g++ on Ubuntu, Xcode on Mac OSX along with the command line tools, Visual Studio on Windows, etc.) along with the various external dependencies described elsewhere in this document.
* Download the Qt Online Installer executable from <http://www.qt.io/download-open-source/>
    * On Ubuntu, you have to set the file to executable:`chmod +x ~/Downloads/qt-opensource-linux-x64-1.6.0-8-online.run\`
* Run the installer and follow the installation steps.
    * Select the directory you want to install Qt, which is handy if you don't want to install system wide or don't have root access.
dogmaphobic's avatar
dogmaphobic committed
123
    * Select the components you want to install. *Tools* will be selected by default. You also want to install the Qt 5.4 module along with the targets you are interested in (i.e. 32-Bit OpenGL for Windows, etc.). On Ubuntu, *Android armv7* will be selected by default as well. You may or may not want to install that, depending on your desire to target that platform. Same idea for OS X. It will have *iOS* Kits selected as well.
Gus Grubba's avatar
Gus Grubba committed
124 125 126 127 128 129 130 131
    * Accept the license and the installer will download all the necessary modules and install where you told it to install.
* Go to the Qt Creator directory:
	* `~/local/Qt/Tools/QtCreator/bin` for Ubuntu (if that's where you installed it)
	* `~/local/Qt/Qt Creator.app` for OS X (if that's where you installed it)
	* `C:/local/Qt/Tools/QtCreator/bin` for Windows (if that's where you installed it)
* Launch Qt Creator and open the `qgroundcontrol.pro` project.

When you open a project in Qt Creator for the first time, it will ask what targets (*Kits*) you want to target. The options will depend on what modules you downloaded above. For instance, on Mac OS X you would select *Desktop Qt 5.4.1 clang 64bit*.
dogmaphobic's avatar
dogmaphobic committed
132 133
It's also a good idea to go into *Projects/Build Steps* (side tool bar) and select Make's *Details*. For *Make Arguments*, add `-jx` (`/J x` on Windows) where `x` is at least the numbers of cores you have. That is, if you are running on a Mac Pro with 24 cores, you would use `-j24`. That will run 24 concurrent compiler instances at a time and run the build a whole lot faster. Your mileage may vary depending on your disk IO throughput. Note that for Windows, this method will build QGC x many times faster than when using Visual Studio as described above. Visual Studio allocates one process per *Project*. As QGroundControl is one very large project, it will still compile one file at a time within that one process. When you build from within Qt Creator (and give the ```/J x``` option to make), it will use x number of concurrent compiler processes.

Gus Grubba's avatar
Gus Grubba committed
134 135
Qt Creator is a full-blown development IDE. You can even debug right from within it and it provides the full Qt API documentation. Just place the mouse cursor over a Qt class/element and hit the F1 key.

Don Gagne's avatar
Don Gagne committed
136
### Additional build notes for all supported OS
137

Don Gagne's avatar
Don Gagne committed
138
* Debug Builds: By default qmake will create makefiles for a release build. If you want a debug build add `CONFIG+=debug` to the command line.
139
* Warnings as Errors: Specifying `CONFIG+=WarningsAsErrorsOn` will turn all warnings into errors which break the build. If you are working on a pull request you plan to submit to github for consideration, you should always run with this settings turned on, since it is required for all pull requests. NOTE: Putting this line into a file called "user_config.pri" in the top-level directory will set this flag on all builds without interfering with the GIT history.
Don Gagne's avatar
Don Gagne committed
140 141 142 143 144
* Parallel builds: For Linux and OSX you can use the '-j#' option to run parellel builds. On Windows parallel builds are on by default.
* Location of built files: Individual build file results can be found in the `build_debug` or `build_release` directories. The built executable can be found in the `debug` or `release` directory.
* Incremental builds: Incremental builds may not be 100% reliable. If you find something strange happening that seems like a bad build. Delete your `build_debug` and `build_release` directories and run qmake again.
* Single release congfiguration on Windows: If you want to build a vs project that does not create both debug and release builds. Include `CONFIG-=debug_and_release` on the qmake command line plus either `CONFIG+=debug` or 
`CONFIG+=release` depending on the build type you want.
Don Gagne's avatar
Don Gagne committed
145
* Build using QtCreator: It is possible to build and debug using QtCreator as well. The above instructions should provide you with enough information to setup QtCreator on OSX and Linux. QtCreator on Windows is supposedly possible but we don't have any instructions available for that.
146
* QGroundControl is using the Qt QLoggingCategory class for logging (<http://qt-project.org/doc/qt-5/qloggingcategory.html>). Since logging is on by default, an example qtlogging.ini file is included at the root of the repository which disables logging. Follow the instructions from Qt as to why and where to put this file. You can then edit the file to get a logging level that suits your needs.
147

Don Gagne's avatar
Don Gagne committed
148
## Additional functionality
149
QGroundcontrol has functionality that is dependent on the operating system and libraries installed by the user. The following sections describe these features, their dependencies, and how to disable/alter them during the build process. These features can be forcibly enabled/disabled by specifying additional values for variables either at the command line when calling `qmake` or in the `user_config.pri`. When calling `qmake` additional variables can be set using the syntax `VARIABLE="SPACE_SEPARATED_VALUES"`, which can be repeated for multiple variables. For example: `qmake DEFINES="DISABLE_QUPGRADE DISABLE_SPEECH" MAVLINK_CONF="sensesoar"` disables the QUpgrade widget, speech functionality, and sets the MAVLink dialect to sensesoar. These values can be more permanently specified by setting them in the `user_config.pri` file in the root directly. Create this file as a plain text file and ensure it ends in .pri (not .pri.txt!).
Don Gagne's avatar
Don Gagne committed
150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167

**NOTE:** Any variables specified at the command line call to `qmake` will override those set in `user_config.pri`.

### Specifying MAVLink dialects
The MAVLink dialect compiled by default by QGC is for the pixhawk. Setting the `MAVLINK_CONF` variable sets the dialects.

### Opal-RT's RT-LAB simulator
Integration with Opal-RT's RT-LAB simulator can be enabled on Windows by installing RT-LAB 7.2.4. This allows vehicles to be simulated in RT-LAB and communicate directly with QGC on the same computer as if the UAS was actually deployed. This support is enabled by default once the requisite RT-LAB software is installed. Disabling this can be done by adding `DISABLE_RTLAB` to the `DEFINES` variable.

### Speech syntehsis
QGroundcontrol can notify the controller of information via speech synthesis. This requires the `espeak` library on Linux. On Mac and Windows support is built in to the OS as of OS X 10.6 (Snow Leopard) and Windows Vista. This support is enabled by default on all platforms if the dependencies are met. Disabling this functionality can be done by adding `DISABLE_SPEECH` to the `DEFINES` variable.

### 3D mouse support
Connexion's 3D mice are supported through the 3DxWARE driver available on Linux and Windows. Download and install the driver from 3DConnexion to enable support. This support is enabled by default with driver installation. To disable add `DISABLE_3DMOUSE` to the `DEFINES` variable.

### XBee support
QGroundControl can talk to XBee wireless devices using their proprietary protocol directly on Windows and Linux platforms. This support is not necessary if you're not using XBee devices or aren't using their proprietary protocol. On Windows, the necessary dependencies are included in this repository and no additional steps are required. For Linux, change to the `libs/thirdParty/libxbee` folder and run `make;sudo make install` to install libxbee on your system (uninstalling can be done with a `sudo make uninstall`). `qmake` will automatically detect the library on Linux, so no other work is necessary.

168
To disable XBee support you may add `DISABLE_XBEE` to the DEFINES argument.