PX4 Guide (main)

中文 (Chinese)

English

中文 (Chinese)

English

Appearance

构建 PX4 软件 ​

无论对于模拟器还是硬件目标设备，PX4 固件都可以在控制台或者集成开发环境（IDE）中从源码进行构建。

若你想使用 模拟器，或者想要修改 PX4 并创建自定义构建版本，就需要对 PX4 进行构建。如果你只是想在真实硬件上试用 PX4，那么可以使用 QGroundControl 加载预构建的二进制文件（无需遵循以下说明）。

INFO

在遵循这些说明之前，你必须先为你的主机操作系统和目标硬件安装 开发工具链。如果在按照这些步骤操作后遇到任何问题，请参阅下面的故障排除部分。

下载 PX4 源代码 ​

PX4 源代码存储在 Github 的 [PX4/PX4 - Autopilot](https://github.com/PX4/PX4 - Autopilot) 仓库中。

要将最新的（main 分支）版本下载到你的计算机上，请在终端中输入以下命令：

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

请注意，你在安装 开发工具链 时可能已经执行过此操作。

INFO

若要获取最新代码，执行上述操作即可。如果需要，你还可以获取特定版本的源代码。GIT 示例 提供了更多关于处理版本和为 PX4 做贡献的信息。

初次构建（使用模拟器） ​

首先，我们要在控制台环境中构建一个模拟器目标。这能让我们在转向真正的硬件和 IDE 之前，验证系统设置是否正确。

进入 PX4 - Autopilot 目录。根据你的操作系统，你应该已经安装了 Gazebo SITL 或者 Gazebo Classic SITL（如果你不确定安装了哪个，可以都尝试一下）。

这将显示 PX4 控制台：

PX4 控制台

INFO

在继续操作之前，你可能需要启动 QGroundControl，因为默认的 PX4 配置要求在起飞前建立与地面站的连接。你可以[从这里下载](https://docs.qgroundcontrol.com/master/en/qgc - user - guide/getting_started/download_and_install.html)。

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

sh
pxh> commander takeoff

飞行器将起飞，你将在模拟器用户界面（UI）中看到相应画面：

可以通过键入 commander land 让无人机降落，通过按 CTRL + C（或者输入 shutdown）来停止整个仿真。

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

QGroundControl 前往功能

基于 NuttX / Pixhawk 的飞控板 ​

为 NuttX 构建 ​

若要为基于 NuttX 或 Pixhawk 的飞控板进行构建，先进入 PX4 - Autopilot 目录，然后使用适合你飞控板的构建目标调用 make 命令。

例如，要为 Pixhawk 4 硬件进行构建，可以使用以下命令：

sh
cd PX4 - Autopilot
make px4_fmu - v5_default

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

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

构建目标的第一部分 px4_fmu - v4 表示固件的目标飞行控制器硬件。后缀（在本例中为 _default）表示固件的一种 配置，例如支持或省略特定功能。

INFO

_default 后缀是可选的。例如，make px4_fmu - v5 和 px4_fmu - v5_default 会生成相同的固件。

以下列表展示了 Pixhawk 标准 飞控板的构建命令：

:::

  • 配备 2MB 闪存的 Pixhawk 1：make px4_fmu - v3_default

非 Pixhawk 的 NuttX 飞控板（以及所有其他飞控板）的构建命令在各个 飞控板文档 中提供。

将固件烧录到飞控板 ​

在 make 命令后追加 upload，即可通过 USB 将编译好的二进制文件上传到自动驾驶仪硬件。例如：

sh
make px4_fmu - v4_default upload

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

sh
Erase  : [====================] 100.0%
Program: [====================] 100.0%
Verify : [====================] 100.0%
Rebooting.

[100%] Built target upload

TIP

在 WSL2 上进行开发时不支持此操作。请参阅 基于 WSL2 的 Windows 开发环境 > 烧录飞控板。

其他飞控板 ​

其他飞控板的构建命令在 特定飞控板页面 中给出（通常在“构建固件”标题下）。

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

sh
make list_config_targets

用图形界面 IDE 编译 ​

VSCode 是 PX4 开发官方支持（并推荐）的 IDE。它易于设置，可用于为仿真和硬件环境编译 PX4。

故障处理 ​

常规构建错误 ​

许多构建问题是由不匹配的子模块或未完全清理的构建环境引起的。更新子模块并执行 distclean 可以解决这类错误：

sh
git submodule update --recursive
make distclean

闪存溢出了 XXX 字节 ​

region 'flash' overflowed by XXXX bytes 错误表明固件对于目标硬件平台来说太大了。这在 make px4_fmu - v2_default 构建中很常见，因为该飞控板的闪存大小限制为 1MB。

如果你正在构建 原版 的主分支，最可能的原因是使用了不受支持的 GCC 版本。在这种情况下，请安装 开发工具链 说明中指定的版本。

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

macOS：打开文件过多错误 ​

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

构建工具链随后会针对许多文件报告 Too many open files 错误，如下所示：

sh
/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）。你可以在 macOS 终端 中为每个会话执行以下操作：

  • 运行这个脚本 [Tools/mac_set_ulimit.sh](https://github.com/PX4/PX4 - Autopilot/blob/main/Tools/mac_set_ulimit.sh)，或者

  • 运行这个命令：

    sh
    ulimit -S -n 300

macOS Catalina：运行 cmake 时出现问题 ​

从 macOS Catalina 10.15.1 版本开始，尝试使用 cmake 构建模拟器时可能会出现问题。如果你在这个平台上遇到构建问题，请尝试在终端中运行以下命令：

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

Ubuntu 18.04：涉及 arm_none_eabi_gcc 的编译错误 ​

与 arm_none_eabi_gcc 相关的构建问题可能是由于 g++ 工具链安装损坏导致的。你可以通过检查缺少的依赖项来验证这一点：

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

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

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

可以通过删除并 [重新安装编译器](https://askubuntu.com/questions/1243252/how - to - install - arm - none - eabi - gdb - on - ubuntu - 20 - 04 - lts - focal - fossa) 来解决这个问题。

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

请参阅 Visual Studio Code IDE (VSCode) > 故障处理。

导入 Python 软件包失败 ​

运行 make px4_sitl jmavsim 命令时出现 “Failed to import” 错误，表明某些 Python 包未按预期安装。

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

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

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

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

PX4 创建生成目标 ​

前面的章节展示了如何调用 make 来构建多个不同的目标、启动模拟器、使用 IDE 等。本节将展示 make 选项是如何构建的，以及如何查找可用的选项。

使用特定配置和初始化文件调用 make 的完整语法如下：

sh
make [VENDOR_][MODEL][_VARIANT] [VIEWER_MODEL_DEBUGGER_WORLD]

VENDOR_MODEL_VARIANT：（也称为 CONFIGURATION_TARGET）

  • VENDOR：飞控板的制造商，例如 px4、aerotenna、airmind、atlflight、auav、beaglebone、intel、nxp 等。Pixhawk 系列飞控板的制造商名称为 px4。
  • MODEL：飞控板的 型号，例如 sitl、fmu - v2、fmu - v3、fmu - v4、fmu - v5、navio2 等。
  • VARIANT：表示特定的配置，例如 bootloader、cyphal，这些配置包含 default 配置中不存在的组件。最常见的是 default，并且可以省略。

TIP

你可以使用以下命令获取所有可用的 CONFIGURATION_TARGET 选项列表：

sh
make list_config_targets

VIEWER_MODEL_DEBUGGER_WORLD：

  • VIEWER：这是要启动并连接的模拟器（“查看器”），例如 gz、gazebo、jmavsim、none

    TIP

    如果你想启动 PX4 并等待模拟器（jmavsim、Gazebo、Gazebo Classic 或其他模拟器），可以使用 none。例如，make px4_sitl none_iris 会在不启动模拟器的情况下启动 PX4（但会加载 iris 机型）。

:::

  • MODEL：要使用的 飞行器 模型（例如 iris（默认值）、rover、tailsitter 等），模拟器将加载该模型。环境变量 PX4_SIM_MODEL 将被设置为所选模型，然后在 [启动脚本](../simulation/index.md#startup - scripts) 中用于选择合适的参数。
  • DEBUGGER：要使用的调试器，例如 none（默认值）、ide、gdb、lldb、ddd、valgrind、callgrind。更多信息请参阅 [仿真调试](../