• Introduction
• Prerequisites
• Qt Download and Install
• Configure and Build
• Adding Firmware Build Target
• Troubleshooting & Tips
• Additional Resources

NOTE: this document is still evolving, though all the existing information should be correct.

Qt provides a full-featured editor and IDE (QtCreator) with its open-source binary distributions which can be quickly set up and used to build OpenTX Companion/Simulator with the minimal number of external dependencies required (eg. you don't need Visual Studio or the full XCode installs, etc). With the optional addition of ARM and/or AVR toolchains, radio firmware can also be built from inside QtCreator, all using a full GUI environment. It has good support for CMake-style projects, which is how OpenTX is set up.

These instructions will first focus on getting Companion & Simulator builds set up and then add the firmware option later.

Also on Windows we're focusing on using the MinGW-w64 compiler which has a number of advantages over using Microsoft's MSVC compiler, primarily download size, fewer 3rd-party dependencies, and ease of installation (already part of Qt installer). Please note that MinGW and MinGW-w64 are different toolchains (the numbers have nothing to do with "bitness"). We're using MinGW-w64 because that is what Qt supports best and comes with, and it generally supports more WinAPI functions than MinGW.

Of course it wouldn't be a true "developer experience" if you didn't need to install some more stuff first. :) Naturally this varies by OS, and exact details for each package can be found elsewhere in this wiki or the Internets (more links to be added here).

You will obviously need the OpenTX code itself -- download an archive from GitHub or use your favorite Git client to clone. Make sure you have the right branch selected (if downloading) or checked out (if cloning).

If you want to build with TELEMETRY=MAVLINK, please do a recursive clone (git clone --recursive).

1. CMake v3+ (https://cmake.org/download/).
2. Python (v2 or v3) (https://www.python.org/downloads/).
   • OTX v2.2.2 and later:
     • For Linux and OS X use
       pip install pillow
     • For Windows, open a command prompt then use
       python -m pip install pillow
   • OTX v2.2.0 and v2.2.1: PyQt4 or PyQt5 to match the Python version (https://sourceforge.net/projects/pyqt/files/).
3. SDL Development Libraries v1.2 (https://www.libsdl.org/download-1.2.php) - optional to support sound in radio simulators.

1. Standard gcc-dev tools (compiler & binutils)

(E.g. apt-get install gcc build-essential libsdl1.2-dev)

1. XCode Command Line Tools (instructions or Google it)
   Note that you do NOT need the full multi-GB XCode package, but you can use that if you want or have it already.

No additional requirements! (Shocking, I know.)

Download a Qt Installer package for your operating system from https://www.qt.io/download-open-source/
NOTE: click the "View All Downloads" link to get a full list of available options then choose an "Online" (recommended) or "Offline" installer -- the big green "Download Now" button tries to auto-determine your current OS, which is sometimes wrong.

If selecting an "offline" installer for Windows be sure to choose the one with MinGW in the name, eg. "Qt 5.7.1 for Windows 32-bit (MinGW 5.3.0)." Here is the url to get offline installer for Qt 5.7.1: Qt Downloads

Run the Qt installer. If you selected the "online" version, then when it comes time to choose packages you will have many options, including which version(s) of Qt libraries to actually install. This will vary a bit by operating system.

1. Expand the Qt version category you want ("Qt 5.7" as of this writing) and select (usually) the first sub-item there:
   • Linux: "Desktop gcc 64-bit"
   • OS X: "Desktop clang-64"
   • Windows: "MinGW x.y.z 32 bit" (where x.y.z is a version number, eg. "5.3.0")
2. In "Qt->Tools" section, "Qt Creator" should already be selected (and probably can't be deselected anyway)
3. Windows: In "Qt->Tools" select "MinGW x.y.z" where again x.y.z matches the version you selected in step 1 (usually the highest version number, 5.3.0 at time of writing). Note this is the MinGW version, not Qt version.

The above choices are all that are required, though you could add other stuff if you want. Proceed with the installation and exit the installer once done. To update or change installed packages in the future, run the "Qt Maintenance Tool" program which gets installed with the other Qt bits.

Example from Linux, others are very similar. (click for larger version)

See also: QtCreator - Checking Build and Run Settings

First we'll verify that the compiler and Qt libraries are installed and discovered correctly. Qt organizes these into "Kits," with each Kit having a particular compiler, Qt version, and other attributes. Each project you work on can be built with one or more Kit(s) of your choice, and each of those configurations can have multiple build flavors, eg. Release or Debug.

1. Run QtCreator.
2. Navigate to Tools -> Options -> Build & Run.
3. In the "CMake" tab make sure your cmake executable was auto-detected, otherwise add it manually and set it as default.
4. In the "Kits" tab there should be the Qt library version(s) you just installed all ready to go under "Auto-detected" category. Eg. "Desktop Qt 5.7.1 MinGW 32bit".
5. If you see the right Kit in the list and there are no red error icons showing then you're all set. Otherwise, you will need to correct these manually... That's a whole other topic but in brief you want to check the "Qt Versions" and "Compilers" tabs to see if anything is missing or misconfigured.
   • If the Kits/Versions/Compilers list is really messed up then it is most likely that something went wrong with the installation. Perhaps a re-install or update using the Maintenance Tool may help. It should really all "just work" out of the box, so to speak.

Example from Linux, but again others are very similar. (click for larger version)

See also: QtCreator - Building CMake Projects

1. In QtCreator menu, go to File -> Open File or Project...
2. Navigate to the root of the OpenTX code folder and select CMakeLists.txt file (make sure it is the one at the root, not in any sub-folder of the project).
3. QtCreator will present a list of the Qt Kits currently configured, and let you select which one(s) to use for this project. The default Kit will be selected automatically.
   • Select the build types you will use for each Kit -- usually only having Release and (perhaps) Debug build types is plenty, although QtC suggests like 5 different flavors. Just un-select the ones you don't want.
   • Configure the folder you want each build type to go into. This should be outside the source code folder, which is what Qt suggests by default. The defaults are usually fine unless you're particular. (The folders are not created until the first time you actually use the build flavor.)
   • Click "Configure Project" (or similar) button at the bottom.
4. At this point QtCreator will load the project and run CMake in the background.
   • You can see the actual CMake output in the QtCreator General Messages output pane (click the tab at bottom or select from Window->Panes menu).
   • If CMake generates "real" errors or warnings, they will show up in the Issues output pane (CMake can also generate some "noise" warnings which QtC will usually ignore).
5. If CMake runs OK w/out any major errors, you will see all of the many build-time options displayed in the project configuration page.
   • All project configuration happens here, including selecting which OpenTX options you want (eg. the radio (PCB) type and so on).
   • If CMake can't find some parts needed for the build, you can provide "hints" here by setting the relevant variables. For example if your SDL installation wasn't found, you can specify the SDL_LIBRARY_PATH value manually.
   • After making any changes push the "Apply Configuration Changes" button. Sometimes you need to press this twice for all the changes to take effect. Make sure the button stays disabled, then you're set.
   • Windows: The WIN_EXTRA_LIBS_PATH variable specifies the root folder for common pre-requisites like SDL. By default this is c:/Programs to conform with past OpenTX convention. NOTICE THE FORWARD SLASH in the path name! You will get CMake errors if you use backslashes here (or in many of the other paths as well).
     For e.g. SDL folders (./bin, ./build-scripts, etc.) and files from the archive SDL-devel-1.2.xxx-mingw32.tar.gz must be extracted directly in c:/Programs folder.
6. Under the options list there is a "Build Steps" section where you can choose what part(s) of the project to build (expand "Build -> Details -> Targets" to see all the options).
   • If the list of targets is blank, something went wrong during the CMake steps... check the output for errors and check the Troubleshooting section below.
   • If all is OK, by default the all target should be selected, which is a good place to start.
   • You can add/enable/disable individual targets here as well -- the most common ones are companion, simulator, & libsimulator (which is specific for each radio type). For example you can build companion/simulator targets once, then only libsimulator for each additional radio (PCB) type you'd like to simulate. The fewer targets selected, the faster the build process.
   • Windows: Another good target to start with is install which is like all but will also copy some required DLLs into the build folder so Companion/Simulator can be run directly.

Example setup: (click for larger version)

Once CMake reports no errors and you have selected your build target(s), it's ready to go.

1. In QtCreator make sure the build type you want is selected (for example if you configured both Release and Debug build types). You can do this at the top of the Build Settings page using "Edit Build Configuration" selector box, or using the big menu button on the lower left of QtCreator toolbar, just above the green "Play" button.
2. Then hit that big green "Play" button or press Ctrl-B or select "Build -> Build Project OpenTX" from the menu. You can monitor the progress in the Compile Output panel and any errors will show up in Issues panel.

After the build, the results will all be in the build folder previously configured.

Windows: To run Companion/Simulator from this folder you'll first need to copy some extra DLLs from Qt installation. Simplest method is to just build the install target as mentioned above, which does it all for you.

Not much else to say here except for when it doesn't work... which will need to be in the separate Troubleshooting section (WIP).

This is pretty straight-forward once you have the main project set up. First you'll need the compiler(s) ("toolchain(s)") for the radio firmware you want to build.

ARM (Taranis, Horus, SKY9X, AR9X, 9XRPRO): GNU ARM Embedded Toolchain v4.7 (https://launchpad.net/gcc-arm-embedded/4.7/4.7-2014-q2-update)

AVR (Other 9X radios, MEGA2560, etc): AVR GCC Toolchain (v4.7 if you can find it) (http://avr-eclipse.sourceforge.net/wiki/index.php/The_AVR_GCC_Toolchain). (You can also get the AVR toolchain as part of any Arduino IDE installation, which may be a good option esp. for Windows.)

Install one or both. "Installing" is basically unpacking the files into some folder, although some downloads include basic installers which do that for you. Use folder paths w/out spaces to avoid headaches later on.

Now, back in QtCreator, in the project configuration screen there is a section for setting up the Build Environment (at the bottom). Expand that, and find the PATH entry. Edit the PATH to add the full path(s) to the bin folder(s) of your ARM/AVR toolchain(s). For example: c:\Programs\gcc\4.7\bin or /opt/gcc-arm/4.7/bin. The bin folder you want to point to will contain arm-none-eabi-gcc[.exe] for ARM or avr-gcc[.exe] for AVR.

Once you edit the PATH variable, QtCreator will automatically re-run CMake. After this, the firmware target should now be available in the list of other targets you can build (it will also automatically be included if you build the all target). If it's not, check the CMake output for any warnings or errors.

Keep in mind that the firmware type being built depends on the PCB project configuration variable. The resulting binary file is always named firmware.bin (or .hex for AVR) so it is not obvious which radio it is for. Likewise, if you change the PCB type and re-build the project, any existing firmware binary in the build folder will be overwritten with the new one.

Reference image, highlights/notes are described below. (click for larger version)

• CMake error about the C compiler not being found. Sometimes there is a bug/issue with QtCreator where it doesn't configure a default C compiler (only C++) but then passes a blank CMAKE_C_COMPILER option to CMake. This is easy to fix by going to the Kit configuration options (see § in above image) and removing the problem line from the CMake Configuration.

• To speed up builds with make (the default with QtCreator), add the environment variable MAKEFLAGS with a value of -j N where N is the number of concurrent make processes to use (typically the number of CPU threads on your machine). You can add this variable either globally in the "usual" way for your OS, or add it to the Builds Envoronment settings in QtCreator (you can do this for each build setup individually or in QtCreator Kits settings (see † in image above), or globally on your system).

• To speed up builds even more, download and install ninja (Win/Linux/OSX). In QtCreator, in Options -> Build & Run -> Kits (see ‡ in image above) change the CMake generator to use Generator: Ninja and Extra generator: CodeBlocks.

• QtCreator Code Formatter set up for the preferred OpenTx style.
• QtCreator documentation