Last updated
Last updated
The following instructions explain how to set up a PX4 development environment on Windows 10 or Windows 11 (preferred), running on Ubuntu Linux within .
This environment can be used to build PX4 for:
:::tip This setup is supported by the PX4 dev team. The environment should in theory be able to build any target that can be built on Ubuntu. The list above are those targets that have been tested. :::
:::note This setup be used on Windows 10, with some . :::
The () allows users to install and run the on Windows, almost as though we were running it on a Linux computer.
With this environment developers can:
Build any simulator or hardware target supported by in the WSL Shell. (Ubuntu is the best supported and tested PX4 development platform).
Debug code in (Windows).
Monitor a simulation using QGroundControl for Linux running in WSL. QGC for Linux connects automatically to the simulation.
QGroundControl for Windows is additionally required if you need to:
on a real vehicle.
Monitor a real vehicle. Note that you can also use it to monitor a simulation, but you must manually .
Windows 10 builds do not yet support GUIs for WSL2 apps, so windowed, graphics features will not work. This includes Gazebo Classic and jMAVSim rendered visualization, QGC for Linux running in WSL, git gui, etc.
Development is possible as you can still:
Build PX4 in WSL2 and flash it to boards using QGC from Windows.
To install WSL2 with the default Ubuntu distribution on a new installation of Windows 11:
Make sure your computer your computer's virtualization feature is enabled in the BIOS. It's usually referred as "Virtualization Technology", "Intel VT-x" or "AMD-V" respectively.
Open cmd.exe as administrator. This can be done by pressing the start key, typing cmd, right klicking on the Command prompt entry and selecting Run as administrator.
Execute the command wsl --install to run the installation routine for WSL.
Reboot the computer.
Open cmd again as a normal user (not as administrator). This can be done by pressing the Start key, typing cmd and pressing Enter.
Execute the command wsl to access the WSL shell.
WSL will prompt you for a user name and password for the Ubuntu installation. Record these credentials as you will need them later on!
All operations to install and build PX4 must be done within a WSL Shell (you can use the same shell that was used to install WSL2 or open a new one).
To open a WSL shell:
Open a command prompt:
Press the Windows Start key.
Type cmd and press Enter to open the prompt.
To start WSL and access the WSL shell, execute the command:
:::note Enter the following commands to first close the WSL shell, and then shut down WSL:
Alternatively, after entering exit you can just close the prompt. :::
Next we download the PX4 source code within the WSL2 environment, and use the normal Ubuntu installer script to to set up the developer environment. This will install the toolchain for Gazebo Classic simulation, JMAVSim simulation and Pixhawk/NuttX hardware.
To install the development toolchain:
Execute the command cd ~ to switch to the home folder of WSL for the next steps.
:::warning This is important! If you work from a location outside of the WSL file system you'll run into issues such as very slow execution and access right/permission errors. :::
Download the PX4 source code using git (which is already installed in WSL2):
Run the ubuntu.sh installer script and acknowledge any prompts as the script progresses:
:::note This installs tools to build PX4 for Pixhawk, Gazebo Classic and JMAVSim targets:
You can use the --no-nuttx and --no-sim-tools options to omit the NuttX and/or simulation tools.
Restart the "WSL computer" after the script completes (exit the shell, shutdown WSL, and restart WSL):
Switch to the PX4 repository in the WSL home folder:
Build the PX4 SITL target and test your environment:
VS Code running on Windows is well integrated with WSL.
To set up the integration:
Open VS Code.
In the WSL shell, switch to the PX4 folder:
In the WSL shell, start VS Code:
This will open the IDE fully integrated with the WSL shell.
Make sure you always open the PX4 repository in the Remote WSL mode.
Next time you want to develop WSL2 you can very easily open it again in Remote WSL mode by selecting Open Recent (as shown below). This will start WSL for you.
Note however that the IP address of the WSL virtual machine will have changed, so you won't be able to monitor simulation from QGC for Windows (you can still monitor using QGC for Linux)
The easiest way to set up and use QGroundControl is to download the Linux version into your WSL.
You can do this using from within the WSL shell.
Right-click on the QGroundControl.AppImage link, and select "Copy link address". This will be something like https://d176td9ibe4jno.cloudfront.net/builds/master/QGroundControl.AppImage
Run QGroundControl:
QGroundControl will launch and automatically connect to a running simulation and allow you to monitor and control your vehicle(s).
You will not be able to use it to install PX4 firmware because WSL does not allow access to serial devices.
These steps describe how you can connect to the simulation running in the WSL:
Check the IP address of the WSL virtual machine by running the command ip addr | grep eth0:
Copy the first part of the eth0 interface inet address to the clipboard. In this case: 172.18.46.131.
In QGC go to Q > Application Settings > Comm Links
Add a UDP Link called "WSL" to port 18570 of the IP address copied above.
Save it and connect to it.
:::note You will have to update the WSL comm link in QGC every time WSL restarts (because it gets a dynamic IP address). :::
Do the following steps to flash your custom binary built in WSL:
Note: Use the correct target for your board. "fmu-v5" can be used for a Pixhawk 4 board.
Detach the USB cable of your Pixhawk board from the computer if it was plugged.
Open QGC.
In QGC go to Q > Vehicle Setup > Firmware
Plug your pixhawk board via USB
Once connected select "PX4 Flight Stack", check "Advanced settings" and choose "Custom firmware file ..." from the drop down below.
Continue and select the firmware binary you just built before. In the open dialog look for the "Linux" location with the penguin icon in the left pane. It's usually all the way at the bottom. Choose the file in the path: Ubuntu\home\{your WSL user name}\PX4-Autopilot\build\{your build target}\{your build target}.px4 :::note You can add the folder to the favourites to access it quickly next time. :::
Start the flashing.
:::note Connecting to a real device from within WSL is not supported, so you can't update firmware using the option when building on the command line, or from QGroundControl for Linux. :::
:::note The approach is similar to installing PX4 in your own virtual machine, as described in . The benefit of WSL2 is that its virtual machine is deeply integrated into Windows, system-managed, and performance optimised. :::
Run simulations in (by prefixing the make command with HEADLESS=1). Connect using QGC on Windows or in WSL.
:::note WSL2 GUI support is provided by the . This is present in stable Windows 11 builds by default. It is not yet in stable Windows 10 (only insider previews). See the link for rollout information. :::
:::note If you have any problems with your setup, check the current . :::
(if it is still open you can use the same one that was used to install WSL2).
:::note The environment setup scripts in the source usually work for recent PX4 releases. If working with an older version of PX4 you may need to . :::
Other Linux build targets are untested (you can try these by entering the appropriate commands in into the WSL shell). :::
For more build options see .
and install Visual Studio Code (VS Code) on Windows,
Install the extension called (marketplace)
You can run QGroundControl in either WSL or Windows to connect to the running simulation. If you need to with new firmware you can only do this from the QGroundControl for Windows.
In a web browser, navigate to the QGC
and enter the following commands to download the appimage and make it executable (replace the AppImage URL where indicated):
Install if you want to be able to update hardware with firmware created within PX4.
Flashing a custom built PX4 binary has to be done using since WSL2 does not natively offer direct access to serial devices like Pixhawk boards.
If you haven't already build the binary in WSL e.g. with a and by running:
