干无人机开发这一行的朋友应该都清楚PX4 作为开源飞控固件的事实标准早就不是一个“选不选”的问题而是绕不开的基本功。我自己是从 3.x 时代开始接触 PX4 的那时候编译环境还比较折腾踩坑踩到怀疑人生。后来陆陆续续给团队搭了不下十次开发机发现只要抓住 Ubuntu 版本、依赖工具链、编译顺序这几个关键点PX4 开发环境搭建并没有想象中那么可怕。今天这篇内容主线很明确在 Ubuntu 18.04 上完整搭建一套 PX4 开发环境把 QGC 地面站配好再让 Qt Creator 接进来做代码编辑和调试。文章会覆盖 PX4 固件编译、QGC 的安装连接、Qt Creator 的工程导入与调试技巧还会把所有我遇到过的经典报错和解决方案整理成速查表。不管你是刚开始接触 PX4 的新手还是已经编译过几次但总是被各种环境问题打断的老手这套流程基本都能直接照着抄。1. 为什么是 Ubuntu 18.04 QGC Qt Creator1.1 这套组合解决什么问题先理顺三个角色的分工。PX4 是跑在飞控硬件上或者仿真环境里的固件代码它的编译需要一套完整的交叉编译工具链QGCQGroundControl是地面站软件用来监控飞机状态、调参、看日志、执行任务规划。Qt Creator 则是我们用来看代码、改代码、单步调试的开发工具。这三样东西单独拎出来都能用但真正融入一条开发链路里才会产生质变。比如你在 PX4 的仿真环境Gazebo里跑一架无人机QGC 就能实时显示姿态、位置、电池电压这些状态你在 Qt Creator 里打断点检查某个控制算法的中间变量QGC 那边同步看到飞行数据的反馈。日常开发里 90% 的调试点都可以在这条链路里完成而不必频繁地烧固件、上真机。1.2 版本选择的取舍Ubuntu 18.04 这个版本在 PX4 官方文档里是很长一段时间的推荐 LTS 版本。原因是 PX4 的依赖库比如 Gazebo 9、ROS Melodic、Qt 5.9在这个系统版本上的兼容性最好官方工具链脚本ubuntu.sh、ubuntu_sim.sh 这些也几乎是为 18.04 量身定做的。当然你完全可以用 20.04 或者 22.04我后来也试过。但现实很骨感很多旧工具链脚本在 20.04 上会有 Python 2 依赖失效、OpenGL 库缺失这类问题。所以我给团队搭建环境时老实交代最后还是回到了 18.04省心。QGC 这边用官方发布的 AppImage 版本就可以。这个格式的好处是免安装、免依赖下载下来加个执行权限就能跑。Qt Creator 我用的版本比较保守5.9 到 5.12 之间都行不需要追求最新稳定优先。2. 环境准备从裸机到编译工具链2.1 系统安装与基础配置系统安装这一步不展开讲需要注意的是分区时给根目录至少留出 50GB 的空间因为 PX4 源码加上 Gazebo 模型、编译中间产物轻松吃掉十几个 GB。装完系统第一件事是更新软件源并且做一次系统升级sudo apt update sudo apt upgrade -y如果你在国内环境建议顺手把 apt 源换成国内镜像源这个操作会大幅缓解后续依赖安装的速度问题。换源有个细节Ubuntu 18.04 的源文件是 /etc/apt/sources.list修改前先备份不要整个覆盖只把 archive.ubuntu.com 和 security.ubuntu.com 替换成你选的镜像地址即可。2.2 安装 PX4 编译依赖PX4 官方提供的依赖安装脚本是最省事的方案。在普通用户下拉取源码然后进入 Tools/setup 目录执行cd ~ git clone https://github.com/PX4/PX4-Autopilot.git --recursive cd PX4-Autopilot/ bash ./Tools/setup/ubuntu.sh这个脚本会自动安装 cmake、ninja-build、python 依赖、arm-none-eabi 交叉编译器用于 NuttX 固件编译以及 Gazebo 仿真器。脚本运行时间比较长中间会要求你输入密码还会提示安装一些 ROS 相关组件这里你根据自己的需要选择。有一点我必须提醒脚本里的 git clone 步骤较多如果你那边的网络拉取 GitHub 很慢整个 setup 过程会卡在下载环节。我的做法是先把 PX4-Autopilot 仓库从国内镜像站整体 clone 下来再跑脚本——镜像地址我就不贴了gitee 上搜“PX4-Autopilot”就能找到不少同步仓库测一下哪个能 clone 通就用哪个。2.3 为什么推荐整个脚本跑而不是一条一条装有人习惯对着官方文档一条一条执行 apt install、pip install结果装完了编译还是报错。原因在于 PX4 依赖特定版本的 Python 包组合比如 empy、toml、numpy 这些版本不匹配直接会导致 px4_utils 模块导入失败。官方脚本会把版本锁定和顺序关系都处理好所以即使你看得懂每条命令是什么意思也建议整个脚本直接跑然后再针对报错单独修。安装完成后验证关键工具是否装好cmake --version python3 -c import empy; print(empy.__version__)如果这两条命令都能正常输出说明基础的编译环境基本就位了。接下来可以进入固件编译环节。3. 编译 PX4 固件目标选择与验证方法3.1 选择编译目标PX4 的编译目标非常多裸机固件有 px4_fmu-v5Pixhawk 4、px4_fmu-v3Pixhawk 1等等仿真目标则一般是 px4_sitl、px4_gazebo。开发调试阶段我强烈建议先从仿真目标开始。因为编译 SITLSoftware In The Loop目标不需要交叉编译器速度也比交叉编译快得多还能直接拉起 Gazebo 看到飞机模型。一条命令把仿真环境跑起来cd ~/PX4-Autopilot make px4_sitl gazebo第一次编译会比较久因为要把 uORB、参数系统、控制算法等全量代码都编一遍我的办公电脑大概需要 10 到 15 分钟。编完了会看到终端输出类似“SITL started”的日志紧接着一个 Gazebo 窗口弹出里面有一架四旋翼的 3D 模型。3.2 编译错误与恢复思路编译中间如果报错先不要慌。最常见的是资源竞争、权限问题、某个 Python 模块版本不匹配这三类。资源竞争指的是内存不够时 make 的并行编译全部卡死解决办法是限制并发数比如make px4_sitl gazebo -j2权限问题主要出现在下载依赖时没有写权限或者在 /opt 下执行了需要 root 的操作。这类问题看编译日志里的 Permission denied 就能定位。Python 模块版本不匹配是个重灾区。如果报错信息里出现“ModuleNotFoundError: No module named em”或者“while executing jinja generator”十有八九是 empy 没装好。恢复的方法是pip3 install empy3.3.4注意官方对 empy 版本有要求一般来说 3.3.x 都行不要随手装一个最新版否则生成的默认参数头文件可能会有不兼容的问题。3.3 验证编译产物的方法当你看到Build finished successfully编译产物默认在 build/px4_sitl_default/bin/ 目录下。验证方式有两种一是仿真起来后在 QGC 里看到无人机出现在地图上二是命令行里用 listener 查看 uORB 话题。例如在运行仿真的终端里输入listener vehicle_attitude能刷出 attitude 数据就说明消息系统在正常工作。这个手段在后续开发中也很常用因为它是确认某个算法模块是否在顶层调度里跑起来的最快方式。4. QGC 地面站安装与连接实战4.1 下载安装 QGCQGC 地面站安装几乎没有门槛。直接访问 QGC 的官方网站qgroundcontrol.com或者 GitHub releases 页面下载最新版 Linux AppImage 文件。下载后chmod x QGroundControl.AppImage ./QGroundControl.AppImage如果操作系统缺少必要的图形依赖会报错打不开先装一遍基础库sudo apt install libqt5gui5 libqt5waylandclient5 libqt5waylandcompositor5 wayland-protocols装完再启动 QGC。第一次打开会自动初始化地面站界面里勾选默认设置就行不需要额外改配置就能连接仿真。4.2 连接仿真环境与真机端口差异仿真环境下QGC 默认监听 UDP 14557 端口而 PX4 SITL 会在本机往这个端口发送 MAVLink 消息。所以你只要把 gazebo 仿真跑起来QGC 一般会自动识别到无人机。识别成功后左上角会有一个飞行器图标点击进去可以看到姿态、GPS、电池信息地图上也会出现飞机当前位置。如果是连接真机走 USB 线接到飞控的 USB 口即可。这时候有一个高频坑QGC 里显示 No connected vehicle。排查顺序是先用lsusb确认系统识别到硬件再检查 /dev/ttyACM0 是否存在注意可能不是 0可能是 ACM1然后确认用户是否在 dialout 组里不在的话执行sudo usermod -a -G dialout $USER后重新登录一次这一步操作完基本就能识别到了。真机连接时切勿直接插上飞控就飞先看右上角的固件版本和参数是否和当前源码版本一致避免 QGC 自动上传旧版本参数把设定值搞乱。4.3 QGC 的常用操作与调参技巧QGC 地面站不是只看状态的工具它还是个强大的调参器。常用的几个地方分别是飞行前检查页看传感器校准状态、参数页搜索并修改 PX4 参数、日志下载页拉取 ulog 飞行日志。这里分享一个调参经验改参数前先按一次 Reboot让飞控以新参数重新启动然后一次只改一个参数改完立刻在日志里看响应曲线。这样出了问题你才能精准知道是哪一项参数引起的。5. Qt Creator 环境配置与调试技巧5.1 安装 Qt Creator 与工具链配置Qt Creator 的安装方式有两种。最简单的是 apt 直接装sudo apt install qtcreator这个版本通常足够用。如果你偏爱新版界面可以到 Qt 官方下载页面拿 Qt Online Installer 只选择 Qt Creator 组件安装不用装一大堆无关模块。给团队做环境时我一般用 apt 版稳定、少折腾。安装完成后开启 Qt Creator进入“工具”-“选项”-“Kits”确认编译器一栏里有 gcc/gCMake 一栏里能自动检测到系统 cmake。如果 CMake 列表是空的点手动添加把路径填到 /usr/bin/cmake 即可。5.2 导入 PX4 工程的正确姿势打开 Qt Creator 后选择“打开文件或项目”定位到 PX4-Autopilot/CMakeLists.txt。导入时 Qt Creator 会让你选择构建目录和构建参数这一步不要默认一路下一步。PX4 的顶层 CMakeLists 会把各个模块统一组织起来但你如果不指定编译目标默认行为很可能无法编出可执行的 SITL 产物。我的做法是先不配置 Kit导入完成后在“项目”面板里点“Build Settings”把 CMake 参数改成-DCMAKE_BUILD_TYPERelWithDebInfo然后构建目录指到 build/qtcreator等 CMake 解析完成在“构建”菜单里选择“构建项目”就能看到编译输出。需要说明的是Qt Creator 直接对 PX4 全量构建的速度不如命令行 make 快因为中间层数太多。所以我的习惯是日常编辑用 Qt Creator编译和仿真用终端命令行只有需要打断点调试算法时才在 Qt Creator 里构建。这是一种比较舒服的分工。5.3 断点调试 PX4 进程Qt Creator 的调试功能对 SITL 仿真非常友好。先在“项目”面板的运行设置里把可执行程序路径指到仿真二进制文件例如~/PX4-Autopilot/build/px4_sitl_default/bin/px4然后在运行参数里加上启动参数标准的一组是-d ~/PX4-Autopilot/build/px4_sitl_default/etc -s sitl设置完成后启动调试会话在源码里打断点。比如想观察mc_pos_control_main.cpp里的位置控制输出直接跳转到那一行打个断点运行到断点时就可以查看局部变量的实时值。这个能力是纯命令行开发完全没法替代的特别是排查控制算法里“某个状态量异常跳变”这类问题时单步跟数据非常有帮助。5.4 在 Qt Creator 里写 QML 插件QGC 支持用 QML 写自定义分析工具和面板如果打算深度定制 QGCQt Creator 的 QML 查看器也值得一用。做法是在 Qt Creator 里直接打开你的 QML 文件它会自动进入 QML 调试模式可以实时查看组件树和属性值。QML 调试有个小坑如果 QGC 是自己编译的启动时要加-qmljsdebugger参数才能被 Qt Creator 识别否则只能编辑代码没法在线看效果。6. 仿真环境联动一条龙到多窗口调试6.1 完整跑一次 SITL QGC 代码调试三件套搭建好后我建议你完整跑一次联合调试流程因为这才是以后开发工作的常态。先把仿真启动起来cd ~/PX4-Autopilot make px4_sitl gazebo等 Gazebo 弹出飞机模型后启动 QGC这时 QGC 会自动发现仿真飞机。然后在 Qt Creator 里对你要调试的函数加断点再单独启动一个终端里的调试会话。注意这里有个顺序问题QGC 和 Qt Creator 的调试进程会同时占用同一套 MAVLink 消息流如果 QGC 连接正常而 Qt Creator 那边看不到飞机状态多半是因为端口被占用了。解决办法是在跑 Qt Creator 调试前先关掉 QGC 的某个连接视图或者调整仿真端的端口映射别让两边抢同一个端口。6.2 地图定位与航点任务的验证联合调试中最常见的一个场景是验证航点任务。在 QGC 里画一个航线例如一个矩形点击上传任务仿真飞机应该按照航点顺序依次飞。这个时候如果代码里面对任务状态机的处理有 bug飞机会出现“到了第一个点就悬停不动”的情况。排查步骤是先在 QGC 地图上看航点编号是否激活再到源码里 commander 模块和 navigator 模块处打日志看消息是否正常流转到导航模块。这么一套流程下来日常 80% 的逻辑调试都能解决。6.3 多机仿真与集群调试的思路如果你的开发工作涉及多机协同PX4 也支持多无人机 SITL。做法是启动多份仿真实例每个实例用不同的端口。QGC 默认只能连接一个 MAVLink 流需要额外加-mavlink-endpoint参数或者用 mavlink 转发工具。这个我还没有用到很深入但基本思路是给每架仿真飞机分配独立的端口再用 QGC 的“多个飞行器”视图同时监控。这一块如果后面有时间我打算单独写一篇。7. 高频问题与避坑速查表7.1 编译与启动阶段整理一下我在搭建环境和日常开发中踩得最频繁的坑方便你复制到笔记里备用。现象可能原因解决办法git clone 源码时卡住或超时网络访问 GitHub 不稳定换 gitee 镜像仓库或者手动下载 zip 包后解压ubuntu.sh 安装到一半退出某个依赖源不可达换成国内 apt 镜像后重跑已经装好的包会自动跳过编译报错 No module named emempy 未安装或版本不对pip3 install empy3.3.4编译占用内存过高导致死机make 默认并行度过高加 -j2 或 -j4 限制并发QGC 打开后黑屏缺 Qt5 图形库sudo apt install libqt5gui5 libqt5waylandclient5 libqt5waylandcompositor5仿真启动后 QGC 没飞机UDP 端口不匹配或 QGC 版本太旧确认启动参数升级到最新版 QGC7.2 硬件连接与调试阶段现象可能原因解决办法USB 连接飞控后 QGC 不识别当前用户不在 dialout 组sudo usermod -a -G dialout $USER重登/dev/ttyACM0 不存在驱动或线材问题换线材检查 udev 规则真机连接时固件版本异常QGC 自动上传了不匹配的参数断开重连刷入对应版本固件后再加载参数在 Qt Creator 里编译极慢CMake 缓存未配置好重复解析清空 build/qtcreator 目录后重新导入调试时报错 Could not connect to gdbserver调试启动器参数不对检查运行参数是否包含正确的二进制路径这里再补充一个经验如果你用虚拟机比如 VMware 或 VirtualBox装 Ubuntu 来做这个环境务必把虚拟机的“3D 加速”选项打开否则 Gazebo 和 QGC 的渲染经常有问题。另外虚拟机内存不要低于 6GB分辨率建议用 1920x1080 以上不然 QGC 界面在低分辨率下按钮会挤在一起操作体验很差。最后说几句实在话从装系统到可以正常跑仿真我第一次花了整整一个周末中间踩的坑比这篇文章里写的还要多。后来搭多了才发现这个环境的最大价值不是“能编译”而是“能调试”。有了 Qt Creator 的断点能力你才能看得见控制算法内部的数据流动有了 QGC 的地图与日志你才能把“飞机行为异常”和“代码逻辑里的哪一行”对应起来。给新手的最后建议是环境搭好以后别急着改代码先原样编译一次、仿真一次、在 Qt Creator 里打断点走一遍把整个流程的“手感”建立起来。这个过程越熟练后面查问题的时候就越快。还有一点源码目录尽量放在 home 下不要放中文路径下PX4 的构建脚本对非 ASCII 路径支持不是很好。这些都是我实打实摔出来的经验你照着做能少走不少弯路。
