The PX4 project provides a set of recommended tools that you can use to develop, build and debug PX4 Autopilot and other Dronecode software projects, as well as Apache NuttX RTOS.
To start building PX4 Autopilot from source, you should first install the PX4 toolchain. This provides you with all the tools required to develop, build and debug PX4 Autopilot, but the same tools may also be used for other software projects, such as Apache NuttX.
These tools can be installed for various operating systems, but are best supported for Ubuntu. Some tools or features may not work if installed on different operating systems. Therefore we recommended to install Ubuntu either natively or inside a virtual machine. The step-by-step instructions below will be specific to Ubuntu 20.04 (or 22.04) and may not work if you are using a different OS.
The minimal installation that we selected does not include Git by default. Git is a very popular distributed version-control system and you will probably use it a lot when developing software for the HoverGames. It will also allow us to easily download ("clone") the PX4 code because it is available on GitHub, which is a Git-based source code hosting platform.
So let's install Git using the following command:
Before we install any tools we will download the PX4 Autopilot source code. The PX4 developers have included a script with their source code that makes it much easier to install all required tools. Let's first create a folder to hold all sourcecode that we are going to work with. The following command creates the "src" folder in the user's home folder (if it doesn't exist already):
The next step is to actually download the source code. We will use Git to create a local copy of the online repository that is hosted on GitHub. The following command first changes the working directory to the "src" folder that we just created, then it will "clone" the whole PX4 Autopilot repository, including submodules, in a new "PX4-Autopilot" folder.
Note that it will take a while to clone the whole repository. The PX4 source code should now be available in the ~/src/PX4-Autopilot folder. The tilde represents the current user's home folder within the file system. You can also browse to this location with the file manager.
As already mentioned, the PX4 developers provide a bash script to easily install all the tools that you need to build the PX4 firmware. We already cloned the PX4 source code, so we can just change our working directory and run the script:
You should reboot the (virtual) machine after the installation is done.
Make sure to reboot your computer after the toolchain installation is finished. Then change your working directory to the PX4 Autopilot repository again and start a build for the FMUK66E using the following command:
If you still have the older FMUK66 Rev. C or Rev. D then you should use a slightly different target:
After the build process has finished, you should be able to find .bin, .px4 and .elf files in the ~/src/px4-firmware/build/nxp_fmuk66-e_default or ~/src/px4-firmware/build/nxp_fmuk66-v3_default folder (depending on which target you have chosen). We will revisit the build process when we set up the NXP MCUXpresso integrated development environment (IDE) to edit, build and debug the PX4 firmware.
We are going to set up a Linux virtual machine that can be used for developing, building and debugging software for HoverGames and other NXP Mobile Robotics platforms.
Most of the popular tools that you can use to develop software for the HoverGames drone kit are best supported under a Linux operating system. Therefore it is strongly recommended to either use a native Linux setup, or a virtual machine (VM) running Linux on top of a Windows (or Mac) operating system. Using a VM instead of a native setup comes at the cost of processing power and flexibility, but should not be a big issue if you have a modern computer.
It is strongly recommended to use a recent Ubuntu LTS (long-term support) version as the basis of your development environment. It is a beginner-friendly Linux distribution that is widely used for software development. Most of our required tools are guaranteed to work on recent Ubuntu versions. As of August 2022, the PX4 Autopilot build system supports Ubuntu 18.04, Ubuntu 20.04 as well as Ubuntu 22.04. We strongly recommend to use Ubuntu 20.04 because it is also supported by most NXP tools, though all instructions have also been tested with Ubuntu 22.04. Use of another Linux distribution or Ubuntu version may give some unexpected issues.
You can download the "desktop image" (.iso file) for free from the Ubuntu website:
VirtualBox is a beginner-friendly and cost-effective package for creating and running virtual machines, because it is also an open source project and available free of charge. As of August 2022, the latest version is VirtualBox 6.1.36. Please install VirtualBox and all of its components on your computer before you continue.
VirtualBox provides an "Extension Pack", which provides support for USB 2.0 and USB 3.0 devices. It is not strictly required, but may improve the performance of USB devices when used with a VM.
Employees of NXP Semiconductors or other organizations should check with their IT departments for license requirements and costs.
Open VirtualBox and create a new virtual machine using the blue "New" button at the top of the screen, or using the "New..." option under the "Machine" tab. Fill in a descriptive and easily recognizable name for your virtual machine, such as "NXP HoverGames" or "NXP Mobile Robotics". The default machine folder location should be okay, but may be changed if you want. The type should be changed to Linux and the right version is Ubuntu (64-bit).
If your computer appears to not support 64-bit guest operating systems, you may need to enable hardware virtualization in your BIOS/UEFI. Look for settings that are called something like "Enable VT-x" (for Intel processors) or "Enable AMD-V" (for AMD processors).
Set the memory size to at least 4096 MiB, assuming you have at least 8 GiB of RAM available on your computer. It is recommended to allocate even more memory to your virtual machine if your computer has more RAM installed. For example, if your computer has 16 GiB RAM, you can usually allocate 8 GiB (8192 MiB) to the VM without issues. More allocated memory generally means a more responsive virtual machine and quicker software builds. Less than 4096 MiB might work, but your VM will probably be very slow.
The next window will ask you to add a virtual hard disk. Choose the option to create a new one. The default VDI file format is fine, and it is a good idea to make it dynamically allocated. You can keep the default name. Please increase the size of the virtual hard disk to at least 60.00 GB. This will be the maximum amount of space that the virtual hard disk may (eventually) use.
Select your newly created virtual machine and click the orange "Settings" button at the top of the screen, or the "Settings..." option under the "Machine" tab.
Under "General", go to the "Advanced" tab. Enable the shared clipboard and set it to bidirectional. It allows you to easily copy and paste text between your host and guest operating systems. You may also enable the drag'n'drop feature, but this has not been the most stable feature of VirtualBox. It is easier to work with a shared folder, which we will create later.
Under "System", you can go to the "Processor" tab. Assuming your CPU has at least 4 cores, you should add at least a second core to your virtual machine. If your CPU has more cores you can even consider to add a third and a fourth. This will generally make your virtual machine more responsive and speeds up software builds tremendously.
Under "Display", you can increase the video memory. You usually want to set this to the maximum value available, but any value within the green range should work well. The green range is the recommended range based on your computer hardware and the selected guest OS.
Under "Storage", select the empty disk drive in the middle of the window, then click on the small disk icon on the right side of the window and look for the "Choose a disk file..." option. Then find the Ubuntu .iso file you downloaded before. The right file might also be listed in the menu already!
If you have the VirtualBox Extension Pack installed, you can select the USB 2.0 or USB 3.0 controller under "USB". Otherwise you will be stuck with the USB 1.1 controller, which should be fine as well. The USB 2.0 controller is the default option when the extension pack is installed, but you may opt to select the USB 3.0 controller if you want to use superspeed USB devices.
While you're at this screen, consider to add some filters for the USB devices that you will be using. This allows the virtual machine to access these devices whenever they are plugged into your computer while the VM is running. Note that these devices will then not be available on your host operating system. You can also add filters at a later time or pass through USB devices manually.
To easily add a device filter, make sure the device is plugged in and click on the icon with the "+" sign. It is recommended that you add filters for the FMUK66, the J-Link debugger and the USB-UART cable.
Make sure to add filters for both the FMUK66 bootloader and the "standard" FMUK66 device. If you don't see the bootloader device in the list, make sure the FMU is not powered by anything else than the USB cable. Plug the USB cable in again and quickly click the icon while the bootloader is still active (orange LED on the FMU will blink). You have to do this quickly!
Also, make sure to plug in the debugger and USB-TTL-3V3 cable and add filters for "SEGGER J-Link" and "FTDI TTL232R-3V3" (or a name that looks similar). Be aware that the telemetry radios may also present themselves as a FTDI USB UART device if you have one connected to your computer! Their product number should be slightly different, but it's better to disconnect them to avoid confusion.
The list should look similar to this:
Under "Shared Folders", we can also setup a folder that will be accessible on both your host and guest operating systems. Please create an empty folder on your host operating system. The folder name should be short and clear. This name will be used to identify the folder in the guest operating system (Ubuntu). You can also enable auto-mount. This will make sure that the shared folder is automatically mounted after the virtual machine has booted, but first we have to install the OS including guest additions.
You can now press the green "Start" button to run your virtual machine. You may be asked first to select the right boot disk, make sure you select the Ubuntu image. The VM should then start and boot from the provided .iso disk image, starting the installation process for Ubuntu. We will continue on the next page and guide you through this process.
The MCUXpresso Integrated Development Environment allows developers to edit, compile and debug code for many NXP microcontrollers. For HoverGames it is a useful tool for debugging the PX4 code.
We will install MCUXpresso inside the Linux environment (native or virtual). This allows MCUXpresso to build PX4 Autopilot, flash it to the FMUK66E and debug the code while it is running on the board. You can also install MCUXpresso on your host operating system, but we recommend to keep all tools in the same (Linux) environment.
The MCUXpresso IDE is available free of charge and can be downloaded from the NXP website, but you will need to create a (free) NXP account:
Click on the download button and login to your NXP account. The next page will show the current available releases. There is also a tab for previous releases. You should download the current release (11.6 as of August 2022), click on "MCUXpresso IDE" to continue. You will have to agree with some terms and conditions before you can download the software.
Assuming you have the file stored in the ~/Downloads folder, you should first enter the command below to allow the package to be executed and installed. You should replace the last part of the filename with the right version number for your download! You can use the auto-complete feature for this by pressing the tab key. Just start typing the command below and press tab when you get to the version number in the file name.
Now you can install MCUXpresso by executing the installer package, for which you again have to modify the filename to match the right version:
You might get asked to accept an agreement (use the arrow keys to select "Yes" and press enter). Then wait for the installation to finish.
Now we should start MCUXpresso. You can find it in Ubuntu's launcher menu (the icon in the bottom left corner of the screen). Look for the blue icon with the "X", or just type "MCUXpresso". MCUXpresso will immediately ask at what location the workspace should be saved. You can chose your own directory, or leave the default as is. You can also create additional workspaces for different projects if you want.
You will then be greeted by a welcome screen. You can close the "Welcome" tab or press the "IDE" button on the top right to continue. Once you are in the main view of the IDE, find the location were you stored the Kinetis K66 SDK .zip file, and drag the archive into the area of the IDE window that says "Installed SDKs". It's usually located at the bottom. It will ask you to confirm that you want to import the SDK. Just press "OK". It might take a few seconds to install.
Now that MCUXpresso and the Kinetis K66 SDK are installed, we can continue and create a PX4 project. You can create a new project in MCUXpresso by going to "File", "New", and then "Project". A list with different project types will appear, from which you should select "Makefile Project with Existing Code" under "C/C++".
You can use any project name, but for clarity we will call it "HoverGames PX4". You should select /home/hovergames/src/px4-firmware as the existing code location. This is the folder where we cloned the PX4 firmware code. Make sure that both the C and C++ languages are selected. For "Toolchain for Indexer Settings", select "NXP MCU Tools". Click "Finish" to create the project.
Before we continue we should change some project properties. Select the project we just created on the left side of the screen, go to "Project" in the menu at the top and then select "Properties".
Go to "MCU Settings" under "C/C++ Build". An error might pop up, complaining about invalid values. If this happens you can close the error, switch to another tab and switch back again. You should now see the same screen as shown in the image below. On this "MCU Settings" screen, select the MK66FN2M0xxx18 under the K6x family of MCUs.
Now go to the main "C/C++ Build" tab. Uncheck "Use default build command" and change the build command to just make. The PX4 build scripts will take care of the specifics, we should not supply any additional arguments here.
Then switch to the "Behavior" tab. Uncheck "Enable parallel build", because the PX4 build tools also already takes care of this. Set the "Build (incremental build)" target to nxp_fmuk66-v3_default and change the "Clean" target to distclean. Click "Apply" to apply all changed settings.
You can press "Apply and Close" to apply the changes and close the window.
We now have a build configuration that allows us to create PX4 firmware builds for the FMUK66 board. You can use the hammer icon to start a build for the selected project. If you add multiple configurations you can switch between the different profiles with the small arrow next to the hammer icon.
Give it a try, the console at the bottom of the IDE window will show the progress of the build. Note that this might take a while if you are building PX4 for the first time! When you make changes to the code after the first build it should only rebuild the changed files.
We can now build the PX4 firmware with MCUXpresso. We are now going to also add a run configuration to flash the binary directly to the FMUK66 board with just a USB cable, without debugger!
At the top of the screen, you have a green "Run" icon. Click on the small arrow next to it, and select "Run Configurations...". In the window that opens, select "C/C++ Application" and click the "New" button above it. Name the newly created configuration "PX4 FMUK66 Upload (USB)" to remind you that this will flash the firmware using only USB. Change the field under "C/C++ Application" to /usr/bin/make.
Also go into the "Arguments" tab and add nxp_fmuk66-v3_default upload into "Program arguments".
Finally, go into the "Common" tab. Tick the checkbox in front of "Run" under "Display in favorites menu". Press apply and close the window. You can now upload firmware binaries to the FMUK66 with just the USB cable by clicking on the green "run" icon in the toolbar.
Now in the bottom left of your screen, in the quickstart panel, press the blue bug icon with the label "Debug". Make sure that you have the right project ("HoverGames PX4") selected in the project browser on the top left!
A new window opens and should show the attached J-Link debugger. Select it and press "OK".
When you have the .elf file selected, press "OK". It might start building the code and start a debug session. Wait for it to finish (there is an indicator at the bottom). Then press the "Terminate All Debug sessions" button in the top bar (the red square next to the resume and pause buttons) to stop all debugging sessions.
We should make sure that the generated configuration is correct and make some small changes. Click on the small arrow between the green debug icon and the green run button. Go to "Debug Configurations...".
Under "GDB SEGGER Interface Debugging", select the generated JLink configuration. It is probably called something like "HoverGames PX4 JLink PX4 FMUK66 Default". Make sure "nxp_fmuk66-v3_default.elf" is selected in the field under "C/C++ Application".
In the "Startup" tab, disable the "Set breakpoint at" option. You can set your own breakpoints anywhere you want, we just don't need this default one.
Finally, switch to the "Common" tab, and tick the checkbox in front of "Debug" under "Display in favorites menu". Press "Apply" and close the window. You can now start a debug session with the debug icon!
If you want to do a clean build, press the clean button on the right side first. Then, click the hammer button to build to build the PX4 firmware for the FMUK66. You can check that the build configuration is set to "PX4 FMUK66 Default" by clicking on the dropdown menu next to the hammer icon. After you start the build process, the progress will be shown in the console at the bottom of the screen.
You can upload the firmware with the green "run" icon (not to be confused with the "resume" icon that you can use during debugging). You can again check that you have the right run configuration selected by clicking on the dropdown menu next to the run icon. Keep in mind that the FMUK66 needs to be connected via USB for this to work!
If this does not work, make sure you have the FMUK66 plugged in to your computer and that there are two FMUK66 devices "passed through" to the virtual machine. One for the bootloader, and one for "normal operation".
You can start debugging by clicking the green debug icon, or open the dropdown menu next to it and select the "HoverGames PX4 JLink PX4 FMUK66 Default" configuration. You might get a popup about switching to the debug perspective, which will rearrange some panels within the MCUXpresso window. The debug perspective provides a better overview of the different debug tools. After debugging you can change back to the default view through the "Window" menu at the top.
You can terminate the debug session by clicking on the button with the red square.
The "Advanced Debugging with MCUXpresso IDE" series provides a great introduction to the debugging tools in MCUXpresso. Most of the tools shown in these videos can be directly applied to debugging an FMUK66 board running PX4 Autopilot.
Advanced Debugging with MCUXpresso IDE
The next few steps will guide you through the Ubuntu installer. It does not matter if you install Ubuntu natively or in a virtual machine, the install procedure remains (mostly) the same.
When you boot your (virtual) machine for the first time you will be greeted by a screen that asks you to try Ubuntu first or directly install it. You can select a different language, if you want, though it is recommended to stick to English if you want to follow along with these instructions. Then press the Install Ubuntu button to start the install procedure.
If desired, you can change the keyboard layout. Note that the standard US layout is also often used in other countries. You can test if the setting is correct by typing some (special) characters in the field at the bottom of the screen.
We recommend to do a minimal installation. This will only install a minimal amount of additional software. Especially for users of a virtual machine this will help to keep the amount of occupied disk space low. It is also useful to already install updates and third-party drivers, as you would need to do this anyway after Ubuntu has been installed.
If you are installing Ubuntu within a virtual machine you can safely choose to erase the disk and install Ubuntu, as this will only "erase" your virtual hard disk image and not your actual hard drive. For a native setup you should consider whether you want to erase your disk or shrink the existing partition(s) and put Ubuntu on a second partition. After pressing "Install Now", you might get a pop-up that asks you to confirm that you want to write the changes to the disk, just press continue. After that, you might have to wait for a few minutes.
If you are installing Ubuntu natively you should do your own research about different installation types. If you have Windows installed on the same computer it will probably be detected by the Ubuntu installer and propose a dual-boot setup. This allows you to choose at boot between Windows and Ubuntu. However, this is beyond the scope of this GitBook - and there should be plenty information available on the internet to help you.
The next screen will ask for your location/timezone. It should already provide a default location, which will probably work fine. If it does not match your city our country at all you can select one yourself.
Finally, you will be asked to set up a user account. You can pick a name with which you want to be addressed by the system, for this example we will use "NXP". For compatibility reasons we suggest to use a strictly lowercase computer name, for example "nxpdev". If you are using a virtual machine you can just choose a simple username and password to make it easy to use, such as "nxp". You can also select the option to log in automatically for convenience. However, if you are installing Ubuntu on native hardware you should use a proper username and password combination, to keep your system secured.
It will take a while to finish the installation. You might be asked to restart the (virtual) machine after the installation is finished, just restart it immediately using the button. During shutdown, Ubuntu might also ask to remove the installation medium. You can ignore this when installing inside a virtual machine and immediately press enter on your keyboard.
When the system reboots, you will be greeted by a screen that asks you to connect to your online accounts. You can just skip this for now, as well as the next few tabs, until you are asked to help improve Ubuntu. You can choose to not send system info, if you don't want to. Then just continue until you are done and see the desktop.
You might also get a popup from the software updater. It is recommended to install these updates now. You will most likely be prompted to enter your password. After the updates are installed you get asked to restart again, which you should do before we continue.
After the reboot we will (again) check for and install updates. Open a terminal window by going to the launcher menu (the icon with the 9 dots at the bottom of the dock) and search for the terminal application. Once you have it opened, don't forget to right click the terminal icon on the dock and add it to your favorites - you will be using the terminal much more often! You can also right click and remove the "Help" and "Ubuntu Software" icons from the dock, because you will probably not use them much. You can always find them again in the launcher menu.
We should first update the package lists of the apt package manager with the following command:
The term "sudo" stands for "superuser do" and runs the command that follows with superuser privileges (administrator). You will probably be asked to enter your password. The terminal does not show your password while you type it, so it might seem as if nothing is happening, but just enter your password and press enter.
After the package lists have been updated, you will probably find that there are some updated packages available. We can install these updates with another command:
It will show you a list of packages that are going to be installed (not necessarily the same as shown in the screenshot below) and asks if you want to continue. You can press enter to select the capitalized default option ("Y" for "yes"). Now it might take a while to finish.
We will now install the "VirtualBox Guest Additions", which are some packages that will provide better integration between your guest OS and host OS. Open a terminal and enter the following command:
You will probably be asked again whether you want to install the listed packages. You can just press enter to continue. It might take a while to install.
Copying and pasting commands between your host and guest operating systems is not yet possible. You will need to enter a few more commands yourself until we have installed the guest additions. After that you should be able to just copy the commands directly from these pages.
Go to the "Devices" menu and click on "Insert Guest Additions CD image". It will ask you whether you want to run the software, and may ask you to enter your password. It will then open a terminal window and start the installation.
Wait until the installation has finished and close the terminal window. You can then eject the guest additions disk image by right clicking on the icon on the desktop and selecting the eject option. Now that the guest additions are installed you should be able to maximize the virtual machine window, and the resolution of the Ubuntu desktop should scale with the window size. The shared clipboard should work as well. You might have to reboot the virtual machine again if it is not working.
You should redo the last step when you update VirtualBox. You can just go to the device menu, insert the guest additions image and run the installer again. This will install the new version.
This will give you access to the shared folders. You might get asked for your password. You possibly have to reboot before it becomes active. If after a reboot the shared folder is still not visible from the file manager, you should check the virtual machine settings if the shared folder has auto-mount enabled.
However, this Extension Pack is , which should be okay for most HoverGames participants, but commercial users are asked to pay a fee:
"The VirtualBox Extension Pack is available under the , which is a free license for personal, educational or evaluation use, or an Enterprise License, which is a for-fee license that allows most commercial, non-distribution uses restricted by the PUEL."
On corporate-managed Windows 10 machines it may also be that . You probably have to contact your IT department about this.
For just a few seconds after you plug in the FMU, the "NXP SEMICONDUCTORS PX4 BL FMUK66 E" device will be available in the list. This is the bootloader. After a few seconds, this device will disappear and "NXP SEMICONDUCTORS PX4 FMUK66 E" will appear. Note that this is only the case if the FMU !
Download the .deb.bin file for Linux. You can directly download it using the Firefox browser which is included with Ubuntu, or if you are using a virtual machine you can download it on your host operating system and move it into the , which should be accessible in the file browser.
You can click "Apply" to apply the changes, but don't close the window yet. The current configuration is named "Debug". Let's give that a more descriptive name. Click on the "Manage Configurations..." button and then choose "Rename..." to change the name. We will call it "PX4 FMUK66 Default". You can later add additional configurations if you want to play around with the build variables or if you want to build PX4 for another board, such as the .
Flashing the PX4 firmware without a debugger is only possible (with a compatible debugger and a tool such as JLink Commander).
The next step is to also add a debug configuration. This requires the J-Link EDU Mini debugger that is included with the drone kit. Make sure the debugger is plugged in to your computer and passed through to the VM ().
In the next screen, you should make the "Name" column a bit wider and select "nxp_fmuk66-v3_default.elf". If this file is not being shown, you should cancel and first build the software (you can click on the , or build "manually" ).
Also make sure that the board actually has a .
Further and about MCUXpresso are available on the NXP website. You will probably have to login to access some files and videos. You can .
are in this series, but are outside the scope of the HoverGames.
We when we configured the virtual machine. To make it work within the VM we also need to add our user account to the vboxsf group. Enter the following command in a terminal window:
This section explains how to set up a Linux-based development environment with useful tools to develop, build and debug software for HoverGames and NXP Mobile Robotics platforms.
It is required to setup a Linux-based* development environment, preferably based on Ubuntu 20.04 (or 22.04). If you are not running a Linux OS already, you can consider to install Ubuntu natively besides your Windows setup (dual-boot), or on a separate laptop. Another convenient option would be to use virtualization to run Linux on your Windows computer. There are plenty of tools available, such as Oracle VM VirtualBox, VMware Workstation and even the built-in Windows Subsystems for Linux (WSL).
*A native macOS-based development environment might also work, but not all tools are available. We cannot guarantee support - but you might be able to get help from other developers in the HoverGames community that work with macOS.
NXP and Dronecode used to provide a preconfigured virtual machine image for VirtualBox. This image was based on Ubuntu 18.04 and contained the required tools to start developing and debugging software for HoverGames. We no longer recommend using this image as most preinstalled tools are now outdated and would require significant work to get into a working state again.
A fresh setup based on Ubuntu 20.04 (or 22.04) is now recommended. No preconfigured image will be made available however, as it would again become outdated within months after its initial release. It is more beneficial to learn yourself how to setup and maintain a Linux-based development environment - and it is not difficult!
The next pages will provide step-by-step instructions on how to install Ubuntu 20.04 (though all instructions should also apply to Ubuntu 22.04 as well) with a proper toolchain to develop, build and debug Apache NuttX and PX4 Autopilot for RDDRONE-FMUK66 (Kinetis K66 MCU) as well as other NXP Mobile Robotics platforms.
The first part of the instructions will also explain setting up the VirtualBox software for creating and running a virtual machine. NXP does not specifically endorse VirtualBox, but it is a free open source tool and it is a convenient way to start using Ubuntu as a beginner. More advanced developers may install Ubuntu natively or use different virtualization tools (e.g. VMware, WSL2).
The next step will explain how to install the Ubuntu Linux operating system. We will also download and install the PX4 toolchain, which should provide all the tools already to build your own PX4 firmware binaries from source. The same tools can also be used to build Apache NuttX, which is the Real-Time Operating System (RTOS) that is used by PX4, but can also be used stand-alone.
Finally, we will install NXP MCUXpresso, an integrated development environment (IDE) which allows you to edit, build and debug software for many NXP microcontrollers and processors. The instructions will explain how you can setup a project to build and debug PX4 Autopilot.
