Windows 开发环境（基于 WSL2）

以下说明将介绍如何在 Windows 10 或 11 系统上，借助 WSL2 运行的 Ubuntu Linux 来搭建 PX4 开发环境。

按照本文指示搭建的开发环境可用于编译以下内容：

• Pixhawk 及其他基于 NuttX 的硬件
• Gazebo 仿真环境
• Gazebo-Classic 仿真环境

TIP

此设置方案由 PX4 开发团队提供支持。理论上，该环境能够编译任何可在 Ubuntu 上编译的目标。上述列表中的目标是经过常规测试的。

综述

适用于 Linux 的 Windows 子系统（WSL2）允许用户在 Windows 上安装并运行 Ubuntu 开发环境，其使用体验几乎与在 Linux 计算机上运行无异。

借助此环境，开发者可以：

• 在 WSL 终端中编译 Ubuntu 开发环境 支持的任何模拟器或硬件目标（Ubuntu 是 PX4 开发平台中支持和测试最完善的系统）。
• 在运行于 Windows 的 Visual Studio Code 中调试代码。
• 使用在 WSL 中运行的 QGroundControl for Linux 监控仿真环境。Linux 版 QGC 会自动连接到仿真环境。

若有以下需求，则还需安装 QGroundControl for Windows：

• 更新真实飞行器的固件。
• 监控真实飞行器。需要注意的是，也可以使用它来监控仿真环境，但必须手动 连接到在 WSL 中运行的仿真环境。

INFO

WSL 不支持从内部连接 USB 设备，因此在命令行编译时无法使用 upload 选项更新固件，也不能通过 QGroundControl for Linux 更新固件。

INFO

这种方法与在自己的虚拟机中安装 PX4 类似，具体可参考 Windows 虚拟机托管工具链。WSL2 的优势在于其虚拟机与 Windows 深度集成，由系统管理，并且经过了性能优化。

安装

安装 WSL2

要在全新安装的 Windows 10 或 11 系统上安装带有 Ubuntu 的 WSL2，请按以下步骤操作：

1. 确保计算机 BIOS 中已启用虚拟化功能。该功能通常分别被称为 “虚拟化技术”、“Intel VT-x” 或 “AMD-V”。
2. 以管理员身份打开 cmd.exe。可以通过按下开始键，输入 cmd，右键单击 “命令提示符” 条目，然后选择 “以管理员身份运行” 来实现。
3. 执行以下命令来安装 WSL2 和特定版本的 Ubuntu：
   • 默认版本（Ubuntu 22.04）：

     wsl --install

   • Ubuntu 20.04（Gazebo-Classic 仿真环境）

     wsl --install -d Ubuntu-20.04

   • Ubuntu 22.04（Gazebo 仿真环境）

     wsl --install -d Ubuntu-22.04

   INFO

   你也可以从应用商店安装 Ubuntu 20.04 和 Ubuntu 22.04，这样就可以通过常规的 Windows 添加/删除程序设置来卸载应用程序。

::: 4. WSL 会提示你为 Ubuntu 安装设置用户名和密码。请记录这些凭据，因为后续可能会用到！

此时，命令提示符已变为新安装的 Ubuntu 环境中的终端。

打开 WSL 终端

所有安装和编译 PX4 的操作都必须在 WSL 终端中完成（可以使用安装 WSL2 时的终端，也可以打开一个新的终端）。

如果你使用的是 Windows 终端，可以按照图示打开已安装的 WSL 环境的终端，并通过关闭标签页退出。

若要使用命令提示符打开 WSL 终端，请按以下步骤操作：

1. 打开命令提示符：
   • 按下 Windows 开始 键。
   • 输入 cmd 并按下 Enter 键打开命令提示符。
2. 要启动 WSL 并进入 WSL 终端，请执行以下命令：

   wsl -d <发行版名称>

   例如：

   wsl -d Ubuntu

   wsl -d Ubuntu-20.04

   如果你只安装了一个版本的 Ubuntu，可以直接使用 wsl。

输入以下命令先关闭 WSL 终端，然后关闭 WSL：

exit
wsl -d <发行版名称> --shutdown

或者，输入 exit 后直接关闭命令提示符。

安装 PX4 工具链

接下来，我们在 WSL2 环境中下载 PX4 源代码，并使用常规的 Ubuntu 安装脚本 来设置开发环境。这将安装用于 Gazebo Classic 仿真和 Pixhawk/NuttX 硬件的工具链。

要安装开发工具链，请按以下步骤操作：

1. 打开 WSL2 终端（如果之前的终端仍处于打开状态，可以继续使用）。
2. 执行命令 cd ~ 切换到 WSL 的主文件夹，以便进行后续步骤。

   WARNING

   这一步非常重要！如果在 WSL 文件系统之外的位置进行操作，可能会遇到执行速度极慢以及访问权限错误等问题。

::: 3. 使用 git（WSL2 中已预装）下载 PX4 源代码： sh git clone https://github.com/PX4/PX4-Autopilot.git --recursive ::: info 源代码中的环境设置脚本通常适用于较新的 PX4 版本。如果使用的是较旧版本的 PX4，可能需要 获取特定版本的源代码。 ::: 4. 运行 ubuntu.sh 安装脚本，并在脚本执行过程中确认所有提示信息： sh bash ./PX4-Autopilot/Tools/setup/ubuntu.sh ::: info 此脚本将安装用于编译 Pixhawk 以及 Gazebo 或 Gazebo Classic 目标的工具： - 可以使用 --no-nuttx 和 --no-sim-tools 选项省略 NuttX 和/或仿真工具的安装。 - 其他 Linux 编译目标未经测试（你可以尝试将 Ubuntu 开发环境 中的相应命令输入到 WSL 终端中）。 ::: 5. 脚本执行完成后，重启 “WSL 计算机”（退出终端，关闭 WSL，然后重新启动 WSL）： sh exit wsl --shutdown wsl 6. 切换到 WSL 主文件夹中的 PX4 仓库： sh cd ~/PX4-Autopilot 7. 编译 PX4 SITL 目标并测试环境： sh make px4_sitl 更多编译选项请参考 构建 PX4 软件。

Visual Studio Code 集成

运行于 Windows 的 VS Code 与 WSL 集成度很高。

要设置集成，请按以下步骤操作：

1. 在 Windows 上 下载 并安装 Visual Studio Code（VS Code）。
2. 打开 VS Code。
3. 安装名为 Remote - WSL 的扩展（应用市场）。
4. 打开 WSL 终端。
5. 在 WSL 终端中，切换到 PX4 文件夹：

   cd ~/PX4-Autopilot

6. 在 WSL 终端中，启动 VS Code：

   code .

这将打开一个与 WSL 终端完全集成的 IDE。请确保始终以远程 WSL 模式打开 PX4 仓库。 7. 下次需要在 WSL2 中进行开发时，可以通过选择 “打开最近的项目”（如下所示）非常方便地以远程 WSL 模式再次打开。这将为你启动 WSL。

不过需要注意的是，WSL 虚拟机的 IP 地址会发生变化，因此无法使用 Windows 版 QGC 监控仿真环境（仍然可以使用 Linux 版 QGC 进行监控）。

QGroundControl

你可以在 WSL 或 Windows 中运行 QGroundControl 来连接正在运行的仿真环境。如果你需要 为飞行控制板刷入新固件，则只能使用 Windows 版的 QGroundControl。

WSL 中的 QGroundControl

设置和使用 QGroundControl 最简单的方法是将 Linux 版本下载到你的 WSL 中。

你可以在 WSL 终端中完成此操作。

1. 在网页浏览器中，访问 QGC 的 Ubuntu 下载页面。
2. 右键单击 QGroundControl.AppImage 链接，然后选择 “复制链接地址”。链接地址可能类似于 _https://d176td9ibe4jno.cloudfront.net/builds/master/QGroundControl.AppImage_。
3. 打开 WSL 终端，并输入以下命令下载 AppImage 文件并使其可执行（请将 <复制的 AppImage URL> 替换为实际的链接地址）：

   cd ~
   wget <复制的 AppImage URL>
   chmod +x QGroundControl.AppImage

4. 运行 QGroundControl：

   ./QGroundControl.AppImage

QGroundControl 将启动并自动连接到正在运行的仿真环境，允许你监控和控制飞行器。

由于 WSL 不允许访问串行设备，因此无法使用它来安装 PX4 固件。

Windows 上的 QGroundControl

如果你想使用 PX4 中创建的固件更新硬件，请在 Windows 上安装 QGroundControl。

以下步骤介绍了如何连接到在 WSL 中运行的仿真环境：

1. 打开 WSL 终端。
2. 运行命令 ip addr | grep eth0 检查 WSL 虚拟机的 IP 地址：

   $ ip addr | grep eth0
   
   6: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
       inet 172.18.46.131/20 brd 172.18.47.255 scope global eth0

将 eth0 接口 inet 地址的第一部分复制到剪贴板。在本例中为：172.18.46.131。 3. 在 QGC 中，转到 Q > 应用程序设置 > 通信链接。 4. 添加一个名为 “WSL” 的 UDP 链接，指向上面复制的 IP 地址的 18570 端口。 5. 保存设置并连接。

INFO

每次 WSL 重启后，都需要更新 QGC 中的 WSL 通信链接（因为它会获取动态 IP 地址）。

刷写飞行控制板

必须使用 Windows 版 QGroundControl 来刷写自定义编译的 PX4 二进制文件。

INFO

WSL2 本身不提供对连接到计算机的串行/USB 设备（如 Pixhawk 飞行控制器）的直接访问。这意味着你无法将运行在 WSL2 内的 QGC 连接到飞行控制器以安装固件，也不能使用 upload 命令 在编译时上传固件。相反，你需要将 Windows 版 QGroundControl 连接到在 WSL2 中运行的 PX4 以及飞行控制器，以便上传固件。

要刷写在 WSL 中编译的自定义二进制文件，请执行以下步骤：

1. 如果你还没有在 WSL 中编译二进制文件，可以使用 WSL 终端 并运行以下命令：

   cd ~/PX4-Autopilot
   make px4_fmu-v5

   TIP

   请为你的飞行控制板使用正确的 make 目标。px4_fmu-v5 可用于 Pixhawk 4 飞行控制板。

::: 2. 如果 Pixhawk 板已通过 USB 连接到计算机，请先断开 USB 电缆。 3. 打开 QGC 并导航到 Q > 飞行器设置 > 固件。 4. 通过 USB 连接你的 Pixhawk 板。 5. 连接成功后，选择 “PX4 飞行栈”，勾选 “高级设置”，然后从下方的下拉菜单中选择 “自定义固件文件 ...”。 6. 继续操作并选择你刚刚在 WSL 中编译的固件二进制文件。 在打开的对话框中，在左侧窗格中查找带有企鹅图标的 “Linux” 位置。该位置通常在最底部。选择路径为 Ubuntu\home\{你的 WSL 用户名}\PX4-Autopilot\build\{你的编译目标}\{你的编译目标}.px4 的文件。 ::: info 你可以将该文件夹添加到收藏夹，以便下次快速访问。 ::: 7. 开始刷写。 更多信息请参考 安装 PX4 主版本、测试版或自定义固件（加载固件）。

故障处理

如果你在设置过程中遇到任何问题，请查看当前的 Microsoft WSL 安装文档。

我们还建议你安装最新的 Windows GPU 驱动程序，并在 Ubuntu 环境中安装较新版本的 kisak mesa，以便模拟大多数 OpenGL 功能：

sudo add-apt-repository ppa:kisak/kisak-mesa
sudo apt update
sudo apt upgrade