1. 项目概述从源码到第一个“Hello PX4”如果你刚拿到PX4-AutoPilot的源码面对那庞大的代码仓库和复杂的构建系统感觉无从下手那么这篇教程就是为你准备的。我的目标很简单带你绕开那些繁琐的官方文档和抽象的概念直接动手从零开始在PX4固件源码框架内搭建起开发环境并成功编译、运行你的第一个应用程序模块。这个“应用程序”不是指地面站软件而是指能够被编译进PX4固件、在飞控硬件如Pixhawk系列或仿真环境如Gazebo中独立运行的一个功能模块。想象一下你写了一段代码控制了一个LED的闪烁或者通过串口打印了一句“Hello PX4”然后看着它在真实的飞控板或仿真模型上执行——这就是我们第一步要实现的。无论你是无人机领域的学生、嵌入式开发者还是对飞控底层感兴趣的研究者这篇手把手的实操指南都将帮你跨过最初也是最令人望而生畏的门槛。2. 开发环境搭建稳扎稳打的第一步在开始写代码之前一个稳定、配置正确的开发环境是成功的基石。PX4官方支持多种开发方式但对于深入源码和添加自定义应用在Ubuntu Linux系统下进行本地编译是最主流、也是最可控的选择。2.1 系统与基础依赖安装我强烈推荐使用Ubuntu 22.04 LTS作为开发系统。LTS版本提供了长期稳定的软件源和库支持能最大程度避免因系统版本过新或过旧导致的依赖库冲突问题。你可以在物理机安装也可以使用VMware或VirtualBox创建虚拟机。为虚拟机分配至少4核CPU、8GB内存和50GB磁盘空间能保证后续编译和仿真过程流畅。安装完系统后第一件事不是急着下载PX4源码而是安装一系列基础工具和依赖。打开终端依次执行以下命令sudo apt update sudo apt upgrade -y更新系统后安装编译PX4所需的各类开发工具、编译器、Python环境等sudo apt install -y \ git zip qtcreator cmake build-essential genromfs \ ninja-build exiftool ninja-build protobuf-compiler \ libxml2-utils libopencv-dev \ python3-pip python3-dev python3-wheel \ libgstreamer-plugins-base1.0-dev \ gstreamer1.0-plugins-bad gstreamer1.0-plugins-base \ gstreamer1.0-plugins-good gstreamer1.0-plugins-ugly \ gstreamer1.0-libav gstreamer1.0-tools \ libgstreamer-plugins-base1.0-dev \ libeigen3-dev这里安装的包涵盖了从代码管理git、构建系统cmake, ninja、编译器build-essential到图像处理libopencv-dev、消息序列化protobuf等方方面面。ninja-build是比传统make更快的构建工具PX4的构建系统已全面转向它。2.2 PX4-AutoPilot源码获取与工具链配置有了基础环境现在可以获取PX4的源代码。PX4项目托管在GitHub上我们使用git克隆注意要使用--recursive参数来同步所有子模块这是非常关键的一步因为PX4依赖许多外部库作为子模块。cd ~ git clone https://github.com/PX4/PX4-Autopilot.git --recursive cd PX4-Autopilot克隆完成后不要急于进入目录就开始编译。先检查一下是否在正确的分支上对于初学者使用main分支即可它包含了最新的稳定特性。接着运行PX4提供的环境准备脚本它会自动安装特定版本的交叉编译工具链如arm-none-eabi-gcc用于编译NuttX固件、Python依赖包等。# 切换到main分支通常克隆后默认就是 git checkout main # 更新子模块确保所有依赖都是最新的 git submodule sync --recursive git submodule update --init --recursive # 运行安装脚本安装工具链和Python依赖 bash ./Tools/setup/ubuntu.sh这个ubuntu.sh脚本会做大量工作检查系统依赖、安装缺失的包、下载并配置ARM GCC交叉编译器、安装pyulog、pyserial等Python工具。整个过程需要一定时间并且需要良好的网络环境。特别注意脚本执行过程中可能会提示你输入用户密码以进行sudo安装也可能需要你确认加入某些PPA软件源。请仔细阅读终端的提示信息。实操心得很多人在环境搭建这步就卡住了问题多出在网络或权限上。如果脚本中途失败可以尝试分段执行。例如先手动安装已知的依赖包或者使用国内镜像源替换脚本中某些下载链接。一个更稳妥的方法是查阅Tools/setup/ubuntu.sh脚本内容将其中的下载命令尤其是工具链的下载替换为速度更快的镜像地址。此外务必保证磁盘空间充足整个PX4源码及其工具链会占用超过10GB的空间。3. PX4应用模块架构深度解析成功搭建环境后我们有必要花点时间理解PX4的代码组织结构这样才能知道我们的应用程序应该放在哪里以及如何与系统其他部分交互。PX4采用了一种模块化的架构核心是uORB微对象请求代理中间件和基于NuttX RTOS的任务调度。3.1 源码目录结构速览进入PX4-Autopilot目录你会看到许多文件夹。对于应用开发者需要重点关注以下几个src/modules/:这是存放所有内置功能模块的核心目录。飞控的传感器驱动、姿态估计、位置控制、导航等核心功能都以独立模块的形式放在这里。我们创建的自定义应用程序最终也会放在这个目录下或者其子目录中。boards/: 包含了所有支持的飞控硬件如Pixhawk 4, Cube Orange等的板级定义、引脚映射和启动配置。msg/: 定义了所有uORB消息的格式。uORB是PX4模块间通信的基石任何模块间的数据交换如传感器数据、控制指令都通过发布/订阅特定格式的uORB消息来完成。platforms/: 区分了不同的构建平台如common通用、nuttx用于真实飞控的NuttX系统、posix用于Linux/macOS仿真。ROMFS/: 包含系统启动脚本和混合器Mixer定义等属于系统镜像的一部分。3.2 理解模块、uORB与任务一个PX4应用程序本质上就是一个模块Module。在代码中它通常体现为一个继承自ModuleBase的C类。这个模块可以被编译成一个独立的可执行文件在POSIX仿真环境下或者被链接进主固件在NuttX环境下。模块之间不直接调用函数而是通过uORB进行异步通信。例如sensors模块发布sensor_combined消息而attitude_estimator_q模块订阅这个消息。这种发布-订阅模式解耦了模块使得系统更灵活、易于扩展。每个模块通常运行在自己的任务Task中由NuttX调度。模块的run()方法就是任务的主循环。你需要在这个循环里处理业务逻辑同时注意不能长时间阻塞以免影响其他关键任务的执行。理解了这个架构我们就明白编写一个应用程序主要就是做三件事1) 创建一个模块类2) 定义或订阅所需的uORB消息3) 实现任务的主循环逻辑。4. 创建你的第一个应用程序模块理论说得再多不如动手写一行代码。我们现在就在src/modules/目录下创建一个最简单的模块它每隔一秒通过系统日志PX4_INFO打印一次 “Hello PX4!”。4.1 模块代码实现首先在src/modules/下创建一个新目录命名为hello_px4cd ~/PX4-Autopilot/src/modules mkdir hello_px4 cd hello_px4然后创建两个核心文件HelloPx4.hpp头文件和HelloPx4.cpp源文件。HelloPx4.hpp:#pragma once #include px4_platform_common/module.h #include px4_platform_common/module_params.h #include uORB/Publication.hpp #include uORB/topics/vehicle_status.h // 示例可以发布或订阅消息 #include lib/perf/perf_counter.h #include px4_platform_common/px4_work_queue/ScheduledWorkItem.hpp class HelloPx4 : public ModuleBaseHelloPx4, public ModuleParams, public px4::ScheduledWorkItem { public: HelloPx4(); ~HelloPx4() override; /** see ModuleBase */ static int task_spawn(int argc, char *argv[]); /** see ModuleBase */ static HelloPx4 *instantiate(int argc, char *argv[]); /** see ModuleBase */ static int custom_command(int argc, char *argv[]); /** see ModuleBase */ static int print_usage(const char *reason nullptr); /** see ModuleBase::run */ void Run() override; /** see ModuleBase::print_status */ int print_status() override; private: void update_params() override; // 性能计数器用于监控模块运行频率 perf_counter_t _loop_perf{perf_alloc(PC_ELAPSED, MODULE_NAME: cycle)}; // 示例一个uORB发布者可以发布vehicle_status消息非必需仅作演示 uORB::Publicationvehicle_status_s _vehicle_status_pub{ORB_ID(vehicle_status)}; // 模块参数示例可以在QGC中调整 DEFINE_PARAMETERS( (ParamIntpx4::params::SYS_AUTOSTART) _param_sys_autostart // 示例参数实际可按需定义 ) };HelloPx4.cpp:#include HelloPx4.hpp #include px4_platform_common/getopt.h #include px4_platform_common/log.h HelloPx4::HelloPx4() : ModuleParams(nullptr), ScheduledWorkItem(MODULE_NAME, px4::wq_configurations::lp_default) // 使用低优先级工作队列 { // 初始化参数 update_params(); // 立即调度第一次运行延迟1秒后执行 ScheduleDelayed(1000_ms); } HelloPx4::~HelloPx4() { perf_free(_loop_perf); } int HelloPx4::task_spawn(int argc, char *argv[]) { HelloPx4 *instance new HelloPx4(); if (instance) { _object.store(instance); _task_id task_id_is_work_queue; instance-ScheduleNow(); // 启动工作队列任务 return PX4_OK; } PX4_ERR(alloc failed); return PX4_ERROR; } HelloPx4 *HelloPx4::instantiate(int argc, char *argv[]) { return new HelloPx4(); } void HelloPx4::Run() { perf_begin(_loop_perf); // 这里是模块的主循环逻辑 PX4_INFO(Hello PX4!); // 示例发布一个vehicle_status消息可选 vehicle_status_s status{}; // ... 填充status数据 ... // _vehicle_status_pub.publish(status); // 更新参数 update_params(); perf_end(_loop_perf); // 再次调度自己1秒后再次运行 ScheduleDelayed(1000_ms); } int HelloPx4::print_status() { perf_print_counter(_loop_perf); return 0; } void HelloPx4::update_params() { ModuleParams::updateParams(); // 可以在这里读取并使用参数例如 // int autostart _param_sys_autostart.get(); } int HelloPx4::custom_command(int argc, char *argv[]) { // 可以在这里添加自定义命令 return print_usage(unknown command); } int HelloPx4::print_usage(const char *reason) { if (reason) { PX4_WARN(%s\n, reason); } PRINT_MODULE_DESCRIPTION( RDESCR_STR( ### 描述 这是一个简单的Hello World示例模块用于演示如何在PX4中创建自定义应用程序。 ### 示例 启动模块并打印信息 $ hello_px4 start 停止模块 $ hello_px4 stop 查看状态 $ hello_px4 status )DESCR_STR); PRINT_MODULE_USAGE_NAME(hello_px4, template); PRINT_MODULE_USAGE_COMMAND(start); PRINT_MODULE_USAGE_COMMAND_DESCR(stop, Stop the module); PRINT_MODULE_USAGE_COMMAND_DESCR(status, Print module status); PRINT_MODULE_USAGE_DEFAULT_COMMANDS(); return 0; } // 导出模块接口 extern C __EXPORT int hello_px4_main(int argc, char *argv[]) { return HelloPx4::main(argc, argv); }4.2 模块构建配置CMakeLists.txt为了让构建系统知道如何编译我们的模块需要在hello_px4目录下创建CMakeLists.txt文件px4_add_module( MODULE modules__hello_px4 MAIN hello_px4 SRCS HelloPx4.cpp DEPENDS platforms__common uORB )这个文件告诉CMake模块名为modules__hello_px4入口函数在hello_px4_main源文件是HelloPx4.cpp并且依赖platforms__common和uORB这两个组件。4.3 注册模块到构建系统最后我们需要在上一级目录的CMakeLists.txt中注册这个新模块。编辑src/modules/CMakeLists.txt文件在已有的模块列表中添加一行... add_subdirectory(hello_px4) # 添加这一行 add_subdirectory(airspeed_selector) ...5. 编译与运行在仿真中验证代码写好了接下来就是激动人心的编译和运行环节。我们首先在不需要真实硬器的仿真环境中进行测试。5.1 为仿真目标编译PX4支持多种仿真目标最常用的是px4_sitl_default软件在环仿真。在PX4-Autopilot根目录下执行make px4_sitl_default或者使用更快的ninjamake px4_sitl_default -j$(nproc) # -j 参数指定并行编译的线程数加快速度首次编译会花费较长时间可能10-30分钟因为它需要编译整个PX4固件、工具链以及Gazebo仿真模型。编译成功后你会在build/px4_sitl_default目录下看到生成的可执行文件。5.2 启动仿真并运行模块在一个终端中启动Gazebo仿真世界和PX4 SITLmake px4_sitl_default gazebo-classic等待Gazebo界面和PX4 shellpxh提示符启动完成。在另一个终端中我们可以通过px4_sitl_default的别名px4来操作仿真中的飞控。首先连接到仿真飞控的MAVLink shell./Tools/mavlink_shell.py /dev/ttyACM0 # 注意实际端口可能不同通常是 /tmp/ttyS0 或类似 # 或者更简单的方式在新的终端直接进入构建目录操作 cd build/px4_sitl_default ./bin/px4 -s etc/init.d-posix/rcS # 这种方式会启动一个包含shell的实例当出现pxh提示符后输入help可以看到所有可用的命令。你应该能在列表中看到hello_px4。现在启动我们的模块pxh hello_px4 start如果一切正常你会在终端中看到每秒输出一次的 “Hello PX4!” 信息。你可以使用hello_px4 status查看模块状态使用hello_px4 stop停止模块。注意事项在SITL仿真中日志输出可能会非常快容易被其他系统消息淹没。你可以使用dmesg -f 命令来过滤和持续查看特定来源的日志。另外确保你的模块没有以过高的频率运行比如不延迟地循环这可能会拖慢仿真速度。5.3 编译并刷写到真实硬件在仿真中测试无误后你可以尝试将固件刷写到真实的Pixhawk飞控上。首先确保飞控通过USB连接到电脑。然后针对你的具体硬件型号进行编译。例如对于常见的Pixhawk 4make px4_fmu-v5_default编译完成后使用make upload命令将固件刷写到飞控make px4_fmu-v5_default upload刷写过程中飞控上的LED会闪烁。完成后飞控会自动重启。要运行你的hello_px4模块你需要通过串口工具如screen,minicom或地面站的MAVLink控制台连接到飞控的NSHNuttX Shell。连接后输入hello_px4 start即可。在真实硬件上PX4_INFO的输出会显示在串口终端里。6. 进阶让应用程序更实用打印“Hello World”只是开始。一个有用的应用程序通常需要与系统交互。这里介绍两个最重要的交互方式使用uORB和定义参数。6.1 订阅与发布uORB消息假设我们希望应用程序读取飞机的姿态信息并做出反应。首先查看msg/目录下的.msg文件找到定义姿态的消息例如vehicle_attitude.msg。在我们的HelloPx4.hpp中添加一个订阅者#include uORB/Subscription.hpp #include uORB/topics/vehicle_attitude.h class HelloPx4 : ... { private: ... uORB::Subscription _attitude_sub{ORB_ID(vehicle_attitude)}; ... };在HelloPx4::Run()方法中我们可以检查是否有新的姿态数据void HelloPx4::Run() { vehicle_attitude_s att; if (_attitude_sub.update(att)) { // 成功获取到新的姿态数据 float roll att.roll; float pitch att.pitch; float yaw att.yaw; PX4_INFO(Roll: %.2f, Pitch: %.2f, Yaw: %.2f, (double)roll, (double)pitch, (double)yaw); } ... }同样你也可以发布消息来影响其他模块。例如发布一个vehicle_command来触发某个动作。6.2 定义与使用模块参数参数是PX4中用于配置模块行为的持久化变量可以通过地面站如QGroundControl动态修改。在HelloPx4.hpp的DEFINE_PARAMETERS宏内定义参数DEFINE_PARAMETERS( (ParamFloatpx4::params::HELLO_PX4_RATE) _param_rate, // 控制打印频率 (ParamIntpx4::params::HELLO_PX4_ENABLE) _param_enable // 使能开关 )注意px4::params::HELLO_PX4_RATE需要在参数元数据中声明。为此需要在模块目录下创建一个params.cmake文件# hello_px4/params.cmake px4_add_param(HELLO_PX4_RATE float 1.0 Hello message rate in Hz 0.1 10) px4_add_param(HELLO_PX4_ENABLE int32 1 Enable Hello module 0 1)然后在模块的CMakeLists.txt中引用它px4_add_module( ... PARAMETERS params.cmake ... )在代码中通过update_params()和_param_rate.get()来读取参数值并据此调整ScheduleDelayed的延迟时间。7. 调试技巧与常见问题排查开发过程中难免遇到问题掌握有效的调试方法至关重要。7.1 日志与输出PX4_INFO(): 用于输出一般信息。PX4_WARN(): 输出警告信息。PX4_ERR(): 输出错误信息。perf_counter: 如上例所示用于测量代码段执行时间通过hello_px4 status查看。在SITL中所有日志直接输出到终端。在真实硬件上需要通过串口查看或者通过MAVLink传输到地面站日志中。7.2 常见编译与运行问题问题现象可能原因排查与解决思路make编译失败提示缺少头文件或库1. 依赖未安装完全。2. 子模块未正确初始化。1. 重新运行ubuntu.sh脚本或根据错误信息手动安装缺失包。2. 执行git submodule update --init --recursive。模块编译成功但pxh中找不到命令1. 模块未正确注册到构建系统。2. 编译的目标不对。1. 检查src/modules/CMakeLists.txt是否添加了add_subdirectory(hello_px4)。2. 确保编译了对应的目标如px4_sitl_default并确认模块被包含在构建中查看编译输出。模块启动后立即崩溃或无输出1. 内存访问错误空指针、数组越界。2. 堆栈溢出。3. 工作队列配置错误。1. 使用printf或PX4_INFO在关键位置打印调试信息。2. 检查Run()函数中是否有死循环或未正确调度下一次运行。3. 确保在构造函数中正确调用了父类ScheduledWorkItem的构造函数并指定了工作队列。参数在地面站中不显示或无法修改1.params.cmake未正确链接。2. 参数未在代码中通过update_params()更新。3. 固件版本与地面站参数元数据不匹配。1. 检查模块CMakeLists.txt中的PARAMETERS部分。2. 确保在Run()中定期调用update_params()。3. 尝试在地面站中“刷新参数”或重新启动飞控。SITL仿真启动慢或Gazebo黑屏1. 网络问题导致模型下载失败。2. 显卡驱动或3D加速问题。1. 可以提前下载模型文件或使用--disable-gz-sensors等简化选项启动。2. 尝试在虚拟机设置中启用3D加速或使用HEADLESS1 make px4_sitl_default gazebo以无头模式运行。7.3 使用GDB调试SITL对于更复杂的问题可以使用GDB进行调试。首先确保编译时带有调试符号默认的debug构建方式已包含。然后这样启动仿真make px4_sitl_default gdb或者在启动后在另一个终端中找到PX4进程ID并用gdb附加gdb --pid $(pidof px4)在gdb中你可以设置断点break HelloPx4::Run、单步执行、查看变量是定位逻辑错误的利器。从一行“Hello PX4”开始你已经成功地将自己的代码嵌入了这个强大的飞控系统中。接下来你可以尝试订阅更多的传感器数据实现简单的控制算法或者通过uORB与其他模块协同工作。记住PX4社区和丰富的现有模块src/modules/下的所有内容是你最好的学习资料。多读代码多动手实验逐步构建出属于你自己的、功能强大的飞控应用程序。