README.md 9.49 KB
Newer Older
1
# QGroundControl
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
## Open Source Micro Air Vehicle Ground Control Station


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

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

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


## Documentation
For generating documentation, refer to /doc/README.

## Notes
19 20
Please make sure to delete your build folder before re-building. Independent of which
build system you use (this is not related to Qt or your OS) the dependency checking and
21 22
cleaning is based on the current project revision. So if you change the project and don't remove the build folder before your next build, incremental building can leave you with stale object files.

23
## Additional functionality
24 25 26
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. Copy the `user_config.pri.dist` file and name the copy `user_config.pri`, uncommenting the lines with the variables to modify and set their values as you desire.

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

28
### QUpgrade
29
QUpgrade is a submodule (a Git feature like a sub-repository) that contains extra functionality. It is compiled in by default if it has initialized and updated. It can be disabled by specifying `DISABLE_QUPGRADE` in the `DEFINES` variable.
30

31 32 33
To include QUpgrade functionality run the following (only needs to be done once after cloning the qggroundcontrol git repository):
  * `git submodule init`
  * `git submodule update`
34

35
The QUpgrade module relies on `libudev` on Linux platforms, so be sure to install the development version of that package.
36

37
### Specifying MAVLink dialects
38
The MAVLink dialect compiled by default by QGC is for the ardupilotmega. This will happen if no other dialects are specified. Setting the `MAVLINK_CONF` variable sets the dialects, with more than one specified in a space-separated list. Note that doing this may result in compilation errors as certain dialects may conflict with each other!
39

40
### Opal-RT's RT-LAB simulator
41
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.
42

43
### Speech syntehsis
44
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.
45

46 47 48
### 3D view
The OpenSceneGraph libraries provide 3D rendering to the map overlays that QGC can provide.

49
OpenSceneGraph support is built-in to Mac OS X. On Linux it is commonly available through the libopenscenegraph and libopenscenegraph-qt developer packages. Windows support does not currently exist. This functionality with be automatically built if the proper libraries are installed. Disabling this feature can be done by adding `DISABLE_OPEN_SCENE_GRAPH` to the `DEFINES` variable.
50

51
### 3D mouse support
52
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.
53

54
### XBee support
55
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.
56

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

59 60 61 62 63 64
# Build on Mac OSX

To build on Mac OSX (10.6 or later):
- - -
### Install SDL

Susurrus's avatar
Susurrus committed
65
1. Download SDL 1.2 from:  <http://www.libsdl.org/release/SDL-1.2.14.dmg>
66 67 68 69
2. From the SDL disk image, copy the `sdl.framework` bundle to `/Library/Frameworks` directory (if you are not an admin copy to `~/Library/Frameworks`)

### Install QT
- - -
Susurrus's avatar
Susurrus committed
70
1. Download Qt 5.3 from: <http://download.qt-project.org/official_releases/qt/5.3/5.3.1/qt-opensource-mac-x64-clang-5.3.1.dmg>
Don Gagne's avatar
Don Gagne committed
71
2. Double click the package installer and follow instructions.
72 73 74 75 76 77 78 79 80 81

### Build QGroundControl
- - -
 (use clang compiler - not gcc)

1. From the terminal go to the `groundcontrol` directory
2. Run `qmake qgroundcontrol.pro -r -spec unsupported/macx-clang CONFIG+=x86_64`
3. Run `make -j4`


82
# Build on Linux
83 84 85

To build on Linux:
- - -
Susurrus's avatar
Susurrus committed
86 87 88 89
1. Install base dependencies (QT5.1+, SDL1.2)
  * For Ubuntu: `sudo apt-get install qtcreator qtbase5-dev qt5-default libqt5declarative5-dev libqt5serialport5-dev libqt5svg5-dev libqt5webkit5-dev libsdl1.2-dev build-essential libudev-dev`
  * For Fedora: `sudo yum install qt-creator qt5-qtbase qt5-qtdeclarative qt5-qtserialport qt5-qtsvg qt5-qtwebkit SDL-devel SDL-static systemd-devel`
  * For Arch Linux: `pacman -Sy qtcreator qt5-base qt5-declarative qt5-serialport qt5-svg qt5-webkit`
90 91

2. **[OPTIONAL]** Install additional libraries
92
  * For text-to-speech (espeak)
Thomas Gubler's avatar
Thomas Gubler committed
93 94
	* For Ubuntu: `sudo apt-get install espeak libespeak-dev`
	* For Fedora: `sudo yum install espeak espeak-devel`
Julian Oes's avatar
Julian Oes committed
95
	* For Arch Linux: `pacman -Sy espeak`
96 97
  * For 3D flight view (openscenegraph)
	* For Ubuntu: `sudo apt-get install libopenscenegraph-dev`
Susurrus's avatar
Susurrus committed
98 99
	* For Fedora: `sudo yum install OpenSceneGraph`
	* For Arch Linux: `pacman -Sy openscenegraph`
100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121

3. Clone the repository
  1. `cd PROJECTS_DIRECTORY`
  2. git clone https://github.com/mavlink/qgroundcontrol.git
  3. **[OPTIONAL]** For QUpgrade integration:
	1. `cd qgroundcontrol`
	2. `git submodule init`
	3. `git submodule update`

4. **[OPTIONAL]** Build and install XBee support:
  1. ` cd libs/thirdParty/libxbee`
  2. `make`
  3. `sudo make install`

5. Build QGroundControl:
  1. Go back to root qgroundcontrol directory
  2. `qmake`
  3. `make`
	* To enable parallel compilation add the `-j` argument with the number of cores you have. So on a quad-core processor: `make -j4`

6. Run qgroundcontrol
  1. `./release/qgroundcontrol`
122 123 124 125

# Build on Windows
- - -

Susurrus's avatar
Susurrus committed
126
Only compilation using Visual Studio 2010, 2012, and 2013 are supported.
127

Susurrus's avatar
Susurrus committed
128 129
1. Download and install Visual Studio Express Edition (free) from here: <http://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx>.
  * If installing VS2010, make sure to install Service Pack 1, which fixes a linking error: <http://www.microsoft.com/en-us/download/details.aspx?id=23691>.
130

Susurrus's avatar
Susurrus committed
131
2. Download and install the Qt 5.3 libraries for your version of Visual Studio from here: <http://download.qt-project.org/official_releases/qt/5.3/5.3.1>
132

Susurrus's avatar
Susurrus committed
133
3. **[OPTIONAL]** Go to the QGroundControl folder and then to thirdParty/libxbee and build it following the instructions in win32.README
134

Susurrus's avatar
Susurrus committed
135
4. Open the Qt Command Prompt program from the Start Menu, navigate to the source folder of QGroundControl, and create the Visual Studio project by typing `qmake -tp vc qgroundcontrol.pro`
136

Susurrus's avatar
Susurrus committed
137
5. Now open the generated `qgroundcontrol.vcxproj` file.
138 139 140 141 142

6. Compile and edit in Visual Studio. If you need to add new files, add them to qgroundcontrol.pro and re-run `qmake -tp vc qgroundcontrol.pro`


## Repository Layout
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161
The following describes the directory structure and important files in the QGroundControl repository

Folders:

  * data     - Miscellaneous support files.
  * deploy   - Contains scripts for packaging QGC for all supported systems.
  * doc      - Output directory for generated Doxygen documentation. See README contained within for details.
  * files    - Contains miscellaneous data including vehicle models and autopilot-specific data files.
  * images   - UI images.
  * libs     - Library dependencies for QGC.
  * qupgrade - Source file for the qupgrade, a firmware flashing utility for the APM. Compiled into QGC by default.
  * qml      - QML source files for the project.
  * src      - Source code for QGroundControl. Split into subfolders for communications, user interface, autopilot-specific files, etc.
  * tools    - Additional tools for developers.

Important files:

  * qgroundcontrol.pro - Primary project file for building QGC. Open this in qtcreator or pass this to qmake on the command line to build QGC.
  * qgcvideo.pro       - Builds a standalone executable for viewing UDP video streams from a vehicle.