构建 PX4 软件

无论对于模拟器还是硬件目标设备，PX4固件可以在控制台或者IDE中从源码构建

You need to build PX4 in order to use simulators, 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 using QGroundControl (there is no need to follow these instructions).

INFO

Before following these instructions you must first install the Developer Toolchain for your host operating system and target hardware. If you have any problems after following these steps see the Troubleshooting section below.

下载 PX4 源代码

The PX4 source code is stored on Github in the PX4/PX4-Autopilot repository.

To get the very latest (main branch) version onto your computer, enter the following command into a terminal:

git clone https://github.com/PX4/PX4-Autopilot.git --recursive

Note that you may already have done this when installing the Developer Toolchain

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. GIT Examples provides a lot more information working with releases and contributing to PX4.

初次构建（使用模拟器）

首先我们要用控制台环境来构建一个模拟器目标 这使我们能够在转移到真正的硬件和 IDE 之前验证系统设置。

Navigate into the PX4-Autopilot directory. Depending on your operating system you will have installed either Gazebo SITL or Gazebo Classic SITL (if you don't know which you can try both).

Start Gazebo SITL using the following command:

make px4_sitl gz_x500

Start Gazebo SITL using the following command:

make px4_sitl gazebo-classic

这将显示 PX4 控制台：

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.

可以通过键入以下命令（如上方控制台中所示）来控制飞行器。

pxh> commander takeoff

该机体将起飞，您将在模拟器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).

与地面站一起飞模拟器更接近飞机的实际运行。 在飞机飞行时（Takeoff飞行模式），单击地图上的某个位置并启用滑块。 这将重新定位飞机。

基于NuttX / Pixhawk 的飞控板

为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 hardware you could use the following command:

cd PX4-Autopilot
make px4_fmu-v5_default

运行成功后将输出类似结果：

-- 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 boards:

• Holybro Pixhawk 6X-RT (FMUv6X): make px4_fmu-v6xrt_default

• Holybro Pixhawk 6X (FMUv6X): make px4_fmu-v6x_default

• Holybro Pixhawk 6C (FMUv6C): make px4_fmu-v6c_default

• Holybro Pixhawk 6C Mini (FMUv6C): make px4_fmu-v6c_default

• Holybro Pix32 v6 (FMUv6C): make px4_fmu-v6c_default

• Holybro Pixhawk 5X (FMUv5X): make px4_fmu-v5x_default

• Pixhawk 4 (FMUv5): make px4_fmu-v5_default

• Pixhawk 4 Mini (FMUv5): make px4_fmu-v5_default

• CUAV V5+ (FMUv5): make px4_fmu-v5_default

• CUAV V5 nano (FMUv5): make px4_fmu-v5_default

• Pixracer (FMUv4): make px4_fmu-v4_default

• Pixhawk 3 Pro: make px4_fmu-v4pro_default

• Pixhawk Mini: make px4_fmu-v3_default

• Pixhawk 2 (Cube Black) (FMUv3): make px4_fmu-v3_default

• mRo Pixhawk (FMUv3): make px4_fmu-v3_default (supports 2MB Flash)

• Holybro pix32 (FMUv2): make px4_fmu-v2_default

• Pixfalcon (FMUv2): make px4_fmu-v2_default

• Dropix (FMUv2): make px4_fmu-v2_default

• Pixhawk 1 (FMUv2): make px4_fmu-v2_default

  WARNING

  You must use a supported version of GCC to build this board (e.g. the same as used by CI/docker) 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.

将固件烧录到飞控板

Append upload to the make commands to upload the compiled binary to the autopilot hardware via USB. 例如

make px4_fmu-v4_default upload

运行成功后将有以下输出：

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.

其他飞控板

Build commands for other boards are given the board-specific flight controller pages (usually under a heading Building Firmware).

您还可以使用以下命令列出所有配置目标：

make list_config_targets

用图形界面 IDE 编译

VSCode 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.

故障处理

常规构建错误

许多构建问题是由不匹配的子模块或未完全清理的构建环境引起的。 Updating the submodules and doing a distclean can fix these kinds of errors:

git submodule update --recursive
make distclean

闪存溢出了 XXX 字节

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 version specified in the Developer Toolchain instructions.

如果在构建自己的分支，您可能已将固件大小增加到超过1MB的限制。 在这种情况下，您需要从构建中删除您不需要的任何驱动程序/模块。

macOS：打开文件过多错误

MacOS 默认允许在所有正在运行的进程中最多打开256个文件。 PX4构建系统打开大量文件，因此您可能会超出此数量。

The build toolchain will then report Too many open files for many files, as shown below:

/usr/local/Cellar/gcc-arm-none-eabi/20171218/bin/../lib/gcc/arm-none-eabi/7.2.1/../../../../arm-none-eabi/bin/ld: cannot find NuttX/nuttx/fs/libfs.a: Too many open files

解决方案是增加允许打开文件的最大数量（例如增加到300）。 You can do this in the macOS Terminal for each session:

• Run this script Tools/mac_set_ulimit.sh, or

• 运行这个命令:

  ulimit -S -n 300

macOS Catalina：运行cmake时出现问题

As of macOS Catalina 10.15.1 there may be problems when trying to build the simulator with cmake. 如果您在这个平台上遇到构建问题，请尝试在终端中运行以下命令：

xcode-select --install
sudo ln -s /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/* /usr/local/include/

Ubuntu 18.04：涉及arm_none_eabi_gcc的编译错误

Build issues related to arm_none_eabi_gccmay be due to a broken g++ toolchain installation. 您可以通过检查缺少的依赖项来验证这一点：

arm-none-eabi-gcc --version
arm-none-eabi-g++ --version
arm-none-eabi-gdb --version
arm-none-eabi-size --version

缺少依赖项的 bash 输出示例：

arm-none-eabi-gdb --version
arm-none-eabi-gdb: command not found

This can be resolved by removing and reinstalling the compiler.

Ubuntu 18.04：Visual Studio Code 无法监视此大型工作区中的文件更改

See Visual Studio Code IDE (VSCode) > Troubleshooting.

导入Python软件包失败

"Failed to import" errors when running the make px4_sitl jmavsim command indicates that some Python packages are not installed (where expected).

Failed to import jinja2: No module named 'jinja2'
您可能需要使用以下方式进行安装:
    pip3 install --user jinja2

如果您已经安装了这些依赖关系，这可能是因为计算机上存在多个 Python 版本（例如 Python 2.7.16 和 Python 3.8.3），并且该模块不存在于构建工具链使用的版本中。

您应该能够按照所示明确安装依赖项来解决此问题。

pip3 install --user pyserial empty toml numpy pandas jinja2 pyyaml pyros-genmsg packaging

PX4 创建生成目标

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:

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, which contain components that are not present in 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:

make list_config_targets

VIEWER_MODEL_DEBUGGER_WORLD:

• VIEWER: This is the simulator ("viewer") to launch and connect: gz, gazebo, jmavsim, none

  TIP

  none can be used if you want to launch PX4 and wait for a simulator (jmavsim, 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 to select appropriate parameters.

• DEBUGGER: Debugger to use: none (default), ide, gdb, lldb, ddd, valgrind, callgrind. For more information see Simulation Debugging.

• WORLD: (Gazebo Classic only). Set the world (PX4-Autopilot/Tools/simulation/gazebo-classic/sitl_gazebo-classic/worlds) that is loaded. Default is empty.world. For more information see Gazebo Classic > Loading a Specific World.

TIP

You can get a list of all available VIEWER_MODEL_DEBUGGER_WORLD options using the command below:

make px4_sitl list_vmd_make_targets

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.
• 如果要在其他两个设置之间指定默认值，可以使用三个下划线。 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 jMAVSim using ./Tools/simulation/jmavsim/jmavsim_run.sh -l.

The VENDOR_MODEL_VARIANT options map to particular px4board configuration files in the PX4 source tree under the /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).

其他 make 目标在相关章节中讨论：

• bloaty_compare_master: Binary Size Profiling
• ...

Firmware Version & Git Tags

The PX4 Firmware Version and Custom Firmware Version are published using the MAVLink 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.