mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-11-22 14:19:57 +08:00
* build(git): check only the submodules a build needs Tools/check_submodules.sh fetches every missing submodule, so a build that uses a handful of PX4 libraries still clones NuttX, the simulators and the middleware. Paths given as arguments now limit the check, and the configure step passes PX4_GIT_SUBMODULES when it is set. Builds that do not set it check all submodules as before. A path that is not a submodule, or a submodule the build uses but that is not checked out, stops the configure instead of failing later in the build. Assisted-by: Claude:opus-5.5 Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org> * docs(dev_setup): document PX4_GIT_SUBMODULES The submodule check can be limited to the submodules a build needs. List the variable next to GIT_SUBMODULES_ARE_EVIL, the other way to control the check. Assisted-by: Claude:opus-5.5 Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org> * test(git): cover the submodule check limited to given paths A second top-level submodule gives the tests one to leave out, so they check that paths given to check_submodules.sh limit both the fetch of missing submodules and the report of changed ones, and that a path that is not a submodule fails the check. Assisted-by: Claude:opus-5.5 Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org> --------- Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org> Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
358 lines
16 KiB
Markdown
358 lines
16 KiB
Markdown
# Building PX4 Software
|
|
|
|
PX4 firmware can be built from source code on the console or in an IDE, for both simulated and hardware targets.
|
|
|
|
You need to build PX4 in order to use [simulators](../simulation/index.md), or if you want to modify PX4 and create a custom build.
|
|
If you just want to try out PX4 on real hardware then [load the prebuilt binaries](../config/firmware.md) using QGroundControl (there is no need to follow these instructions).
|
|
|
|
::: info
|
|
Before following these instructions you must first install the [Developer Toolchain](../dev_setup/dev_env.md) for your host operating system and target hardware.
|
|
If you have any problems after following these steps see the [Troubleshooting](#troubleshooting) section below.
|
|
:::
|
|
|
|
## Download the PX4 Source Code
|
|
|
|
The PX4 source code is stored on Github in the [PX4/PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) repository.
|
|
|
|
To get the _very latest_ (`main` branch) version onto your computer, enter the following command into a terminal:
|
|
|
|
```sh
|
|
git clone https://github.com/PX4/PX4-Autopilot.git --recursive
|
|
```
|
|
|
|
Note that you may already have done this when installing the [Developer Toolchain](../dev_setup/dev_env.md)
|
|
|
|
::: info
|
|
This is all you need to do in order to get the latest code.
|
|
If needed you can also [get the source code specific to a particular release](../contribute/git_examples.md#get-a-specific-release).
|
|
[GIT Examples](../contribute/git_examples.md) provides a lot more information working with releases and contributing to PX4.
|
|
:::
|
|
|
|
## First Build (Using a Simulator)
|
|
|
|
First we'll build a simulated target using a console environment.
|
|
This allows us to validate the system setup before moving on to real hardware and an IDE.
|
|
|
|
Navigate into the **PX4-Autopilot** directory and start [Gazebo SITL](../sim_gazebo_gz/index.md) using the following command:
|
|
|
|
```sh
|
|
make px4_sitl gz_x500
|
|
```
|
|
|
|
This will bring up the PX4 console:
|
|
|
|

|
|
|
|
::: info
|
|
You may need to start _QGroundControl_ before proceeding, as the default PX4 configuration requires a ground control connection before takeoff.
|
|
This can be [downloaded from here](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html).
|
|
:::
|
|
|
|
The drone can be flown by typing the following command (as shown in the console above):
|
|
|
|
```sh
|
|
pxh> commander takeoff
|
|
```
|
|
|
|
The vehicle will take off and you'll see this in the Gazebo simulator UI:
|
|
|
|

|
|
|
|
The drone can be landed by typing `commander land` and the whole simulation can be stopped by doing **CTRL+C** (or by entering `shutdown`).
|
|
|
|
Flying the simulation with the ground control station is closer to the real operation of the vehicle.
|
|
Click on a location in the map while the vehicle is flying (takeoff flight mode) and enable the slider.
|
|
This will reposition the vehicle.
|
|
|
|

|
|
|
|
## NuttX / Pixhawk Based Boards
|
|
|
|
### Building for NuttX
|
|
|
|
To build for NuttX- or Pixhawk- based boards, navigate into the **PX4-Autopilot** directory and then call `make` with the build target for your board.
|
|
|
|
For example, to build for [Pixhawk 4](../flight_controller/pixhawk4.md) hardware you could use the following command:
|
|
|
|
```sh
|
|
cd PX4-Autopilot
|
|
make px4_fmu-v5_default
|
|
```
|
|
|
|
:::tip
|
|
You can also build using the [px4-dev Docker container](../test_and_ci/docker.md) without installing the toolchain locally.
|
|
From the PX4-Autopilot directory:
|
|
|
|
```sh
|
|
./Tools/docker_run.sh 'make px4_fmu-v5_default'
|
|
```
|
|
|
|
:::
|
|
|
|
A successful run will end with similar output to:
|
|
|
|
```sh
|
|
-- Build files have been written to: /home/youruser/src/PX4-Autopilot/build/px4_fmu-v4_default
|
|
[954/954] Creating /home/youruser/src/PX4-Autopilot/build/px4_fmu-v4_default/px4_fmu-v4_default.px4
|
|
```
|
|
|
|
The first part of the build target `px4_fmu-v4` indicates the target flight controller hardware for the firmware.
|
|
The suffix, in this case `_default`, indicates a firmware _configuration_, such as supporting or omitting particular features.
|
|
|
|
::: info
|
|
The `_default` suffix is optional.
|
|
For example, `make px4_fmu-v5` and `px4_fmu-v5_default` result in the same firmware.
|
|
:::
|
|
|
|
The following list shows the build commands for the [Pixhawk standard](../flight_controller/autopilot_pixhawk_standard.md) boards:
|
|
|
|
- [Holybro Pixhawk 6X-RT (FMUv6X)](../flight_controller/pixhawk6x-rt.md): `make px4_fmu-v6xrt_default`
|
|
- [Holybro Pixhawk 6X (FMUv6X)](../flight_controller/pixhawk6x.md): `make px4_fmu-v6x_default`
|
|
- [Holybro Pixhawk 6C (FMUv6C)](../flight_controller/pixhawk6c.md): `make px4_fmu-v6c_default`
|
|
- [Holybro Pixhawk 6C Mini (FMUv6C)](../flight_controller/pixhawk6c_mini.md): `make px4_fmu-v6c_default`
|
|
- [Holybro Pix32 v6 (FMUv6C)](../flight_controller/holybro_pix32_v6.md): `make px4_fmu-v6c_default`
|
|
- [Holybro Pixhawk 5X (FMUv5X)](../flight_controller/pixhawk5x.md): `make px4_fmu-v5x_default`
|
|
- [Pixhawk 4 (FMUv5)](../flight_controller/pixhawk4.md): `make px4_fmu-v5_default`
|
|
- [Pixhawk 4 Mini (FMUv5)](../flight_controller/pixhawk4_mini.md): `make px4_fmu-v5_default`
|
|
- [CUAV V5+ (FMUv5)](../flight_controller/cuav_v5_plus.md): `make px4_fmu-v5_default` - Discontinued
|
|
- [CUAV V5 nano (FMUv5)](../flight_controller/cuav_v5_nano.md): `make px4_fmu-v5_default` - Discontinued
|
|
- [Pixracer (FMUv4)](../flight_controller/pixracer.md): `make px4_fmu-v4_default`
|
|
- [Pixhawk 3 Pro](../flight_controller/pixhawk3_pro.md): `make px4_fmu-v4pro_default`
|
|
- [Pixhawk Mini](../flight_controller/pixhawk_mini.md): `make px4_fmu-v3_default`
|
|
- [Pixhawk 2 (Cube Black) (FMUv3)](../flight_controller/pixhawk-2.md): `make px4_fmu-v3_default`
|
|
- [mRo Pixhawk (FMUv3)](../flight_controller/mro_pixhawk.md): `make px4_fmu-v3_default` (supports 2MB Flash)
|
|
- [Holybro pix32 (FMUv2)](../flight_controller/autopilot_discontinued.md): `make px4_fmu-v2_default` - Discontinued
|
|
- [Pixfalcon (FMUv2)](../flight_controller/autopilot_discontinued.md): `make px4_fmu-v2_default` - Discontinued
|
|
- [Dropix (FMUv2)](../flight_controller/autopilot_discontinued.md): `make px4_fmu-v2_default` - Discontinued
|
|
- [Pixhawk 1 (FMUv2)](../flight_controller/autopilot_discontinued.md): `make px4_fmu-v2_default` - Discontinued
|
|
|
|
:::warning
|
|
You **must** use a supported version of GCC to build this board (e.g. the `gcc-arm-none-eabi` package from the current Ubuntu LTS, which is the same toolchain used by CI) or remove modules from the build.
|
|
Building with an unsupported GCC may fail, as PX4 is close to the board's 1MB flash limit.
|
|
:::
|
|
|
|
- Pixhawk 1 with 2 MB flash: `make px4_fmu-v3_default`
|
|
|
|
Build commands for non-Pixhawk NuttX fight controllers (and for all other-boards) are provided in the documentation for the individual [flight controller boards](../flight_controller/index.md).
|
|
|
|
### Uploading Firmware (Flashing the board)
|
|
|
|
Append `upload` to the make commands to upload the compiled binary to the autopilot hardware via USB.
|
|
For example
|
|
|
|
```sh
|
|
make px4_fmu-v4_default upload
|
|
```
|
|
|
|
A successful run will end with this output:
|
|
|
|
```sh
|
|
Erase : [====================] 100.0%
|
|
Program: [====================] 100.0%
|
|
Verify : [====================] 100.0%
|
|
Rebooting.
|
|
|
|
[100%] Built target upload
|
|
```
|
|
|
|
::: tip
|
|
This is not supported when developing on WSL2.
|
|
See [ Windows Development Environment (WSL2-Based) > Flash a Control Board](../dev_setup/dev_env_windows_wsl.md#flash-a-flight-control-board).
|
|
:::
|
|
|
|
## Other Boards
|
|
|
|
Build commands for other boards are given the [board-specific flight controller pages](../flight_controller/index.md) (usually under a heading _Building Firmware_).
|
|
|
|
You can also list all configuration targets using the command:
|
|
|
|
```sh
|
|
make list_config_targets
|
|
```
|
|
|
|
## Submodules
|
|
|
|
PX4 pulls a number of libraries (NuttX, MAVLink, and others) in as git submodules.
|
|
Each build checks them once when it configures:
|
|
|
|
| Submodule state | Local build | CI (`CI=true`) |
|
|
| --------------------------------------- | ------------------------- | -------------------- |
|
|
| At the commit PX4 records | Builds | Builds |
|
|
| Missing | Fetched, then builds | Fetched, then builds |
|
|
| At another commit (e.g. you changed it) | Warns, builds it as it is | Fails |
|
|
|
|
A submodule at another commit is never reset, so you can develop and test changes to a submodule (for example a NuttX upgrade) in place.
|
|
The build warns about it every time, and you are responsible for keeping it in the state you want.
|
|
To check out the commits PX4 records (for example after switching branches), run:
|
|
|
|
```sh
|
|
git submodule sync --recursive && git submodule update --init --recursive
|
|
```
|
|
|
|
Set the CMake variable `PX4_GIT_SUBMODULES` to a list of submodule paths to check only those, for example when another project builds PX4 and uses only some of its libraries.
|
|
The configure step then stops if the build uses a submodule that is not checked out.
|
|
Set `GIT_SUBMODULES_ARE_EVIL=1` to skip the check entirely and manage submodules yourself.
|
|
|
|
## Compiling in a Graphical IDE
|
|
|
|
[VSCode](../dev_setup/vscode.md) is the officially supported (and recommended) IDE for PX4 development.
|
|
It is easy to set up and can be used to compile PX4 for both simulation and hardware environments.
|
|
|
|
## Troubleshooting
|
|
|
|
### General Build Errors
|
|
|
|
Many build problems are caused by either mismatching submodules or an incompletely cleaned-up build environment.
|
|
Updating the submodules and doing a `distclean` can fix these kinds of errors:
|
|
|
|
```sh
|
|
git submodule update --recursive
|
|
make distclean
|
|
```
|
|
|
|
### Flash overflowed by XXX bytes
|
|
|
|
The `region 'flash' overflowed by XXXX bytes` error indicates that the firmware is too large for the target hardware platform.
|
|
This is common for `make px4_fmu-v2_default` builds, where the flash size is limited to 1MB.
|
|
|
|
If you're building the _vanilla_ master branch, the most likely cause is using an unsupported version of GCC.
|
|
In this case, install the `gcc-arm-none-eabi` package from the current Ubuntu LTS as described in the [Developer Toolchain](../dev_setup/dev_env.md) instructions.
|
|
|
|
If building your own branch, it is possible that you have increased the firmware size over the 1MB limit.
|
|
In this case you will need to remove any drivers/modules that you don't need from the build.
|
|
|
|
### macOS: Too many open files error
|
|
|
|
MacOS allows a default maximum of 256 open files in all running processes.
|
|
The PX4 build system opens a large number of files, so you may exceed this number.
|
|
|
|
The build toolchain will then report `Too many open files` for many files, as shown below:
|
|
|
|
```sh
|
|
arm-none-eabi-ld: cannot find NuttX/nuttx/fs/libfs.a: Too many open files
|
|
```
|
|
|
|
The solution is to increase the maximum allowed number of open files (to 2048, matching the [macOS setup instructions](../dev_setup/dev_env_mac.md#prerequisites)).
|
|
You can do this in the macOS _Terminal_ for each session:
|
|
|
|
- Source this script [Tools/mac_set_ulimit.sh](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/mac_set_ulimit.sh) (it must be sourced, not executed, to affect your current shell):
|
|
|
|
```sh
|
|
source Tools/mac_set_ulimit.sh
|
|
```
|
|
|
|
- Or enter the command directly:
|
|
|
|
```sh
|
|
ulimit -S -n 2048
|
|
```
|
|
|
|
To apply it to every new terminal, add the `ulimit` line to `~/.zshrc` as described in the macOS setup.
|
|
|
|
### macOS Catalina: Problem running cmake
|
|
|
|
As of macOS Catalina 10.15.1 there may be problems when trying to build the simulator with _cmake_.
|
|
If you have build problems on this platform then try run the following command in your terminal:
|
|
|
|
```sh
|
|
xcode-select --install
|
|
sudo ln -s /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/* /usr/local/include/
|
|
```
|
|
|
|
### Failed to import Python packages
|
|
|
|
"Failed to import" errors when running the `make px4_sitl gz_x500` command indicates that some Python packages are not installed (where expected).
|
|
|
|
```sh
|
|
Failed to import jinja2: No module named 'jinja2'
|
|
You may need to install it using:
|
|
pip3 install --user jinja2
|
|
```
|
|
|
|
If you have already installed these dependencies this may be because there is more than one Python version on the computer (e.g. Python 2.7.16 and Python 3.8.3), and the module is not present in the version used by the build toolchain.
|
|
|
|
You should be able to fix this by installing the dependencies from the repository's requirements file:
|
|
|
|
```sh
|
|
pip3 install --user -r Tools/setup/requirements.txt
|
|
```
|
|
|
|
## PX4 Make Build Targets
|
|
|
|
The previous sections showed how you can call _make_ to build a number of different targets, start simulators, use IDEs etc.
|
|
This section shows how _make_ options are constructed and how to find the available choices.
|
|
|
|
The full syntax to call _make_ with a particular configuration and initialization file is:
|
|
|
|
```sh
|
|
make [VENDOR_][MODEL][_VARIANT] [VIEWER_MODEL_DEBUGGER_WORLD]
|
|
```
|
|
|
|
**VENDOR_MODEL_VARIANT**: (also known as `CONFIGURATION_TARGET`)
|
|
|
|
- **VENDOR:** The manufacturer of the board: `px4`, `aerotenna`, `airmind`, `atlflight`, `auav`, `beaglebone`, `intel`, `nxp`, etc.
|
|
The vendor name for Pixhawk series boards is `px4`.
|
|
- **MODEL:** The _board model_ "model": `sitl`, `fmu-v2`, `fmu-v3`, `fmu-v4`, `fmu-v5`, `navio2`, etc.
|
|
- **VARIANT:** Indicates particular configurations: e.g. `bootloader`, `cyphal`, `sih`, which add or remove components to/from the `default` configuration.
|
|
Most commonly this is `default`, and may be omitted.
|
|
|
|
:::tip
|
|
You can get a list of _all_ available `CONFIGURATION_TARGET` options using the command below:
|
|
|
|
```sh
|
|
make list_config_targets
|
|
```
|
|
|
|
:::
|
|
|
|
**VIEWER_MODEL_DEBUGGER_WORLD:**
|
|
|
|
- **VIEWER:** This is the simulator ("viewer") to launch and connect: `gz`, `gazebo`, `none` <!-- , ?airsim -->
|
|
|
|
:::tip
|
|
`none` can be used if you want to launch PX4 and wait for a simulator (Gazebo, Gazebo Classic, or some other simulator).
|
|
For example, `make px4_sitl none_iris` launches PX4 without a simulator (but with the iris airframe).
|
|
:::
|
|
|
|
- **MODEL:** The _vehicle_ model to use (e.g. `iris` (_default_), `rover`, `tailsitter`, etc), which will be loaded by the simulator.
|
|
The environment variable `PX4_SIM_MODEL` will be set to the selected model, which is then used in the [startup script](../simulation/index.md#startup-scripts) to select appropriate parameters.
|
|
- **DEBUGGER:** Debugger to use: `none` (_default_), `ide`, `gdb`, `lldb`, `ddd`, `valgrind`, `callgrind`.
|
|
For more information see [Simulation Debugging](../debug/simulation_debugging.md).
|
|
- **WORLD:** (Gazebo Classic only).
|
|
Set the world ([PX4-Autopilot/Tools/simulation/gazebo-classic/sitl_gazebo-classic/worlds](https://github.com/PX4/PX4-SITL_gazebo-classic/tree/main/worlds)) that is loaded.
|
|
Default is [empty.world](https://github.com/PX4/PX4-SITL_gazebo-classic/blob/main/worlds/empty.world).
|
|
For more information see [Gazebo Classic > Loading a Specific World](../sim_gazebo_classic/index.md#loading-a-specific-world).
|
|
|
|
::: info
|
|
|
|
- Most of the values in the `CONFIGURATION_TARGET` and `VIEWER_MODEL_DEBUGGER` have defaults, and are hence optional.
|
|
For example, `gazebo-classic` is equivalent to `gazebo-classic_iris` or `gazebo-classic_iris_none`.
|
|
- You can use three underscores if you want to specify a default value between two other settings.
|
|
For example, `gazebo-classic___gdb` is equivalent to `gazebo-classic_iris_gdb`.
|
|
- You can use a `none` value for `VIEWER_MODEL_DEBUGGER` to start PX4 and wait for a simulator.
|
|
For example start PX4 using `make px4_sitl_default none` and then start your simulator.
|
|
|
|
:::
|
|
|
|
The `VENDOR_MODEL_VARIANT` options map to particular _px4board_ configuration files in the PX4 source tree under the [/boards](https://github.com/PX4/PX4-Autopilot/tree/main/boards) directory.
|
|
Specifically `VENDOR_MODEL_VARIANT` maps to a configuration file **boards/VENDOR/MODEL/VARIANT.px4board**
|
|
(e.g. `px4_fmu-v5_default` corresponds to [boards/px4/fmu-v5/default.px4board](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v5/default.px4board)).
|
|
|
|
Additional make targets are discussed in relevant sections:
|
|
|
|
- `bloaty_compare_master`: [Binary Size Profiling](../debug/binary_size_profiling.md)
|
|
- ...
|
|
|
|
## Firmware Version & Git Tags
|
|
|
|
The _PX4 Firmware Version_ and _Custom Firmware Version_ are published using the MAVLink [AUTOPILOT_VERSION](https://mavlink.io/en/messages/common.html#AUTOPILOT_VERSION) message, and displayed in the _QGroundControl_ **Setup > Summary** airframe panel:
|
|
|
|

|
|
|
|
These are extracted at build time from the active _git tag_ for your repo tree.
|
|
The git tag should be formatted as `<PX4-version>-<vendor-version>` (e.g. the tag in the image above was set to `v1.8.1-2.22.1`).
|
|
|
|
:::warning
|
|
If you use a different git tag format, versions information may not be displayed properly.
|
|
:::
|