企业官网建设流程全解析

• 嵌入式
• 物联网
• 机器人
• 自动驾驶
• 智能硬件

本文围绕 docs/en/releases/main.md（PX4 官方main分支发布说明）展开，系统梳理 PX4-Autopilot 在 v1.18 beta 之后、面向 v2.0 方向落地的主要变更：六旋翼电机故障恢复、双天线 GNSS 航向重构、GNSS 主题/参数全面重命名、安全与故障注入增强等。读完本文，你将掌握这些变更的影响范围、参数迁移路径与升级时的具体操作步骤，并能结合仓库源码理解底层实现逻辑。文中所有参数定义均可在 src/modules/control_allocator/module.yaml 与 src/modules/commander/commander_params.yaml 中查到权威出处。

一、版本背景：什么是 main 分支发布说明

main分支发布说明记录的是已经合入 PX4main分支、但**尚未进入下一个正式发布版本（PX4 v1.18）**的变更内容。也就是说，这份文档是 PX4 v1.18（beta 测试中）之后的"下一个版本"（v2.0 或更晚）的功能预告与升级警告合集，包括：

• Major Changes：进入main的显著性功能变更；
• Upgrade Guide：升级前必须阅读并处理的破坏性变更（参数改名、功能移除、行为变化）；
• Other changes：按模块分类的常规改进（硬件支持、控制、安全、估计、传感器、仿真、通信等）。

文末带TBD占位的章节（Debug & Logging、Ethernet、MAVLink、RC、Multi-Rotor、VTOL、Fixed-wing、Rover、ROS 2）表示对应模块的变更尚未最终确定，后续会持续更新。因此本文适合开发者当作"升级路线图"来跟踪，而非最终版本说明。

二、重大变更：六旋翼单电机故障恢复（Motor Failure Recovery）

本次发布最核心的新功能是六旋翼（hexarotor）的单电机故障恢复。其原理是：当检测到单个电机故障时，控制分配器（control allocator）将该故障电机从分配矩阵中移除，同时针对六旋翼的特殊几何布局，额外处理与故障电机几何对侧的电机，以恢复因此损失的偏航（yaw）控制权限。

2.1 行为模式：CA_FAILURE_MODE

通过参数 CA_FAILURE_MODE 选择处理方式，在 src/modules/control_allocator/module.yaml 中定义如下：

模式1与2均适用于六旋翼；对六旋翼以外的机架，无论取值如何，都只会移除故障电机本身，行为不变。该功能默认关闭（CA_FAILURE_MODE=0），需要用户按需开启。

2.2 反向推力建模：CA_REV_THR_FRAC

模式2（反转对侧电机）要求对侧电机的 ESC支持反转（reverse-capable ESC），并且需要在分配器中建模"正桨在反转时只能产生部分推力"这一物理事实。这正是新参数 CA_REV_THR_FRAC 的作用：它表示可逆电机反转时能产生的正向推力比例，该值主要取决于螺旋桨特性。在 src/modules/control_allocator/module.yaml 中其定义为：

• 类型：float，默认值0.4（即反转时产生 40% 正向推力），取值范围0.1 ~ 1.0；
• 配套参数CA_R_REV（bitmask）用于将对应电机（Motor 1~12）标记为双向/可逆电机，同时要求输出驱动支持双向输出。

从源码结构看（src/modules/control_allocator/ControlAllocator.cpp），故障恢复在控制分配层面完成：检测到故障后更新有效电机集合，并依据CA_REV_THR_FRAC修正对侧电机反向输出时的推力/力矩模型。另外，DroneCAN 上可逆电机的输出现在以有符号的RawCommand值发送（负值表示反转），这是本次发布的配套硬件协议变更（见 src/drivers/dronecan 相关实现）。

实现来源：PX4-Autopilot#28078。

三、升级指南：升级前必须处理的破坏性变更

以下是升级到main（未来 v2.0）时必须逐条核对的行为变化，原文已给出明确迁移路径。

3.1 交通避让参数改名：COM_ARM_TRAFF → COM_TRAFF_AVOID

旧参数COM_ARM_TRAFF已被 COM_TRAFF_AVOID 取代。参数在 src/modules/commander/commander_params.yaml 中的定义如下：

迁移要点：旧的COM_ARM_TRAFF=3（"仅任务模式强制执行"）会自动迁移为COM_TRAFF_AVOID=2，而新值2的语义是在所有模式下阻止解锁，不再局限于任务模式。因此，如果你依赖"检测到交通时仍可手动解锁"，升级后需要手动将COM_TRAFF_AVOID改为1（仅告警），以恢复旧行为。

3.2 PCA9685 参数合并：PCA9685_SCHD_HZ 移除

PCA9685_SCHD_HZ已移除。现在 PCA9685_PWM_FREQ 同时决定 PCA9685 的 PWM 频率以及向芯片推送输出值的速率。迁移方式：

• 若你之前将PCA9685_SCHD_HZ设为非默认值，升级后把它设置到PCA9685_PWM_FREQ即可；
• 注意限制：超过 400 Hz 的频率（此前仅在占空比模式下可用）不再支持。

3.3 飞控固件不再内嵌 CAN 节点固件

飞控固件不再携带 CAN 节点（DroneCAN 外设）的固件。具体来说：

• 旧构建px4_fmu-v5_uavcanv0periph及其背后的板级选项CONFIG_BOARD_UAVCAN_PERIPHERALS已被移除。该构建原本在 ROMFS 中携带 CUAV CAN GPS v1 固件，使飞控可以直接通过 DroneCAN 更新 GPS 固件；
• 迁移方式：改用标准px4_fmu-v5_default固件，并从发布包中获取cuav_can-gps-v1_default.uavcan.bin，通过 SD 卡完成 GPS 固件更新，详见 DroneCAN 固件更新。

实现来源：PX4-Autopilot#28870。

3.4 jMAVSim 移除与替代方案

jMAVSim 已从项目中完全移除：

• make px4_sitl jmavsim命令不再存在；
• 10017_jmavsim_iris机架（SYS_AUTOSTART=10017）已删除；
• 环境搭建脚本不再安装 Java 和ant。

推荐替代方案：

• 使用 SIH（Software In The Loop） 配合 Hawkeye 可视化器，命令为make px4_sitl_sih sihsim_quadx；
• 或使用 Gazebo 仿真。

3.5 六旋翼电机故障处理行为复核

结合 2.1 节：CA_FAILURE_MODE=1的语义已变化——在六旋翼上，除了移除故障电机，还会停止其对侧电机（此前只移除故障电机本身）。其他机架不受影响，默认值CA_FAILURE_MODE=0行为不变。升级前请复核你的故障处理配置是否符合预期，详见 电机故障恢复。

3.6 双天线 GNSS 航向必须重新配置（重要）

这是一项影响较大的破坏性变更，涉及参数移除、新的航向源配置流程与数据来源收窄：

被移除且不自动迁移的参数（包括 DroneCAN GNSS 节点上的同名参数）：

新配置流程：

1. 在飞控上为提供航向的接收机设置 SENS_GNSSn_HDG，GNSS 航向才会被使用；
2. 基线由天线位置参数确定：移动基准站使用两个接收机的SENS_GNSSn_OFFX/Y/Z；双天线接收机还需第二个天线的SENS_GNSSn_AUXX/Y/Z；
3. 基线校验：报告的基线若与计算基线偏差超过 20%，该航向样本会被拒绝。

航向数据来源收窄：航向现在只从sensor_gnss_relative主题获取（u-blox、Unicore UM982、Septentrio、DroneCANRelPosHeading）。以下来源不再使用：

• Trimble MB-Two、Femtomes、NMEAHDT、SBG、MicroStrain 的航向；
• DroneCANFix2消息中的航向；
• sensor_gps消息中的heading、heading_offset、heading_accuracy字段（这三个字段已被移除）。

DroneCAN 兼容提示：运行旧固件的 DroneCAN 节点仍会自行减去其GPS_YAW_OFFSET，请将该节点参数设为0，避免双重修正。

3.7 GNSS 主题、消息与参数全面重命名（影响面最大）

这是本次升级中波及面最广的变更，影响 uORB 主题、MAVLink 消息、ROS 2 接口与参数：

主题与消息：

vehicle_gnss的嵌套结构可在 msg/VehicleGnss.msg 中看到：顶层为timestamp与timestamp_sample，receiver内嵌所选接收机的sensor_gnss样本，并新增修正后的timestamp_sample与antenna_offset字段，访问方式如vehicle_gnss.receiver.latitude。

字段重命名对照：

ROS 2 应用适配：订阅主题从/fmu/out/vehicle_gps_position（px4_msgs/msg/SensorGps）改为/fmu/out/vehicle_gnss（px4_msgs/msg/VehicleGnss）。时间戳读取注意：只有顶层timestamp与timestamp_sample会被转换为 ROS 时间，receiver.timestamp与receiver.timestamp_sample仍为 PX4 启动时钟；且timestamp现在是 sensors 模块发布样本的时刻，测量时刻应使用timestamp_sample。

参数重命名：

• SENS_GPS_MASK、SENS_GPS_TAU、SENS_GPS_PRIME→SENS_GNSS_*；
• SENS_GPSn_ID/OFFX/OFFY/OFFZ/DELAY→SENS_GNSSn_*；
• 驱动层GPS_*与EKF2_*参数保持不变；
• 已保存参数会自动迁移，但加载旧的 QGC 参数文件不会恢复旧名称参数，旧参数文件需手动更新；
• 仓库内的日志分析脚本同时兼容新旧名称；
• uORB-over-Cyphal 寄存器由uorb.sensor_gps更名为uorb.sensor_gnss（对应uavcan.sub.uorb.sensor_gnss.0.id、uavcan.pub.uorb.sensor_gnss.0.id），而UCAN1_UORB_GPS与UCAN1_UORB_GPS_P不变。

实现来源：PX4-Autopilot#24399。

四、其他变更：按模块逐项解读

4.1 任务与导航（Mission / Return）

• 快速任务返航跳过循环：快速任务返航模式（RTL_TYPE =2与4）沿任务路径返航时，现在会跳过DO_JUMP（循环）指令，避免返航路径被循环指令卡住。对应实现在 src/modules/navigator/rtl.cpp（RTL_TYPE_MISSION_FAST、RTL_TYPE_MISSION_FAST_OR_REVERSE常量，见该文件第 59-64 行）。
• 新增 RTL_TYPE=6（电池感知的家/安全点返航）：
  • 若估算的返航飞行时间在剩余电池时间内，则直接返航回家（home）；
  • 否则返航到最近的集结点（rally point）；
  • 若电池剩余时间不可用，则回退到最近的安全点（home 或 rally）。
  • 源码中对应常量RTL_TYPE_HOME_OR_SAFE_POINT_DIRECT = 6（src/modules/navigator/rtl.cpp），测试用例见 src/modules/navigator/test/test_RTL.cpp。

4.2 硬件支持（Hardware Support）

• DroneCAN ESC 无需再设置UAVCAN_PUB_ARM：只要UAVCAN_ENABLE=3（ESC 输出使能），ArmingStatus消息就会自动发布，ESC 无需手动配置该参数。（PX4-Autopilot#28364，详见 DroneCAN ESCs）

4.3 公共库（Common）

• macOS 构建与测试：单元与功能测试套件现在可以在 macOS 上完整构建、链接并运行（make tests）；同时修复了px4_poll()在 macOS 上的超时行为——现在会等待完整时长而非立即返回；
• GPS 时间戳精度修复：混合（blended）GPS 时间戳改为以 double 累计、最后一次性舍入，替代此前对每个加权项分别截断的做法；
• AlphaFilter 接口变更：采样间隔与时间常数参数现在以微秒为单位，以秒为单位的 float 重载已被移除。这意味着"单位传错"的代码将直接编译失败而非运行时出错。仓库外的代码若以秒构造该滤波器，需要同步更新（PX4-Autopilot#28421，实现见 src/lib 下滤波器相关源码）。

4.4 控制（Control）

• 增益压缩（Gain Compression）扩展到多旋翼：此前仅固定翼可用的增益压缩，现在通过 MC_GC_EN 对多旋翼开放。原理：当在扭矩设定点上检测到振荡时，速率环增益被动态降低（无需手动重新整定），振荡停止后增益恢复至 1.0。增益下限由 MC_GC_GAIN_MIN 设定，默认0.3（范围0.0 ~ 1.0），功能默认关闭。参数与实现见 src/lib/rate_control/gain_compression_params.yaml、src/lib/rate_control/gain_compression.cpp，并已在多旋翼速率控制模块中接入（src/modules/mc_rate_control/MulticopterRateControl.cpp）。

4.5 安全（Safety）

• 地理围栏感知返航（Geofence Aware Return）：返航模式新增地理围栏感知能力，详见 Return 模式文档（PX4-Autopilot#27145、#28001）；
• 飞行终止可作为备用失效保护：在需要降落伞着陆的无驾驶员的飞行器上，飞行终止 现在可以作为 Descend（下降）模式的替代后备失效保护动作，以实现更安全的着陆。对应的两个新配置入口：
  • 电池电量失效保护：通过 COM_LOW_BAT_ACT 新增取值4（critical 时 Return、emergency 时 Terminate）；
  • 位置丢失失效保护动作：新增 COM_POS_FS_ACT（0= Descend 模式，1= Terminate）。
  • 两参数的权威定义均见 src/modules/commander/commander_params.yaml（COM_LOW_BAT_ACT第 144-156 行、COM_POS_FS_ACT第 360-371 行）。
• 故障注入（Failure Injection）显著扩展（PX4-Autopilot#27572、#27832、#27950）：
  • 现在可作用于真实硬件，不再局限于仿真器（注入钩子位于共享传感器驱动中）；
  • 命令处理集中到专门的故障注入管理模块；
  • 可通过位掩码同时使多个传感器实例失效，并支持从 RC 开关触发故障；
  • 电池的注入 WRONG 故障默认行为变更：发布错误的电量值，而不是停止发布。
  • 详见 故障注入文档（SYS_FAILURE_EN）。
• 六旋翼电机故障恢复：同第 2 节，同时支持停止（模式1）与反转（模式2）对侧电机两种恢复策略。
• RTL_TYPE=6：见 4.1 节。

4.6 估计（Estimation）

• EKF2 双天线 GNSS 航向融合重构（PX4-Autopilot#27102）：
  • EKF2 现在从独立主题vehicle_gnss_heading融合双天线 GNSS 航向，按航向自身的速率与测量时间融合，而非跟随每个位置样本；
  • GNSS 航向融合的门控条件基于航向本身（基线检查，以及提供航向的接收机在 EKF2_GPS_CHECK 下的欺骗/干扰状态，与位置融合一致），而非位置检查；即使位置与速度融合停止，航向融合仍可继续运行；
  • GPS_RAW_INT与GPS2_RAW现在报告提供航向的接收机的机体坐标系航向。
• GNSS 位置丢失原因事件上报：飞行中因 GNSS 丢失本地位置估计时，commander 现在会以事件形式报告原因——是接收机检查失败，还是接收机停止发送数据。地面站与日志会在"GNSS data fusion stopped"消息之前显示具体原因（PX4-Autopilot#28873）。

4.7 传感器（Sensors）

• u-blox u-center 诊断：车辆 GPS 正常运行的同时，可启用 u-blox Diagnostics with u-center 进行在线诊断（PX4-Autopilot#28280）；
• 磁力计选择改进：运行中禁用当前选中的磁力计（将其 CAL_MAGn_PRIO 设为0）时，会直接切换给下一个磁力计，而不再产生传感器失效报告；启动时被禁用的磁力计也不会再阻止其后磁力计被选中（PX4-Autopilot#28750）。

4.8 仿真（Simulation）

• jMAVSim 移除：见 3.4 节，替代方案为 SIH + Hawkeye 或 Gazebo；
• Gazebo GNSS 故障注入对齐：failure gps off、stuck、wrong命令现在作用于 gz bridge 发布的 NavSat 数据，与其他仿真路径行为一致（PX4-Autopilot#28398）。

4.9 uXRCE-DDS / Zenoh / ROS 2

• SITL 多机自动命名空间前缀统一：自动命名空间前缀改为uav_{px4_instance}，与UXRCE_DDS_NS_IDX的行为对齐（PX4-Autopilot#28338）。ROS 2 应用若依赖旧前缀命名，需要同步调整。

五、升级后的验证与排查建议

结合上文变更，升级到main后建议按以下顺序自查：

1. 参数迁移核查：用param show或 QGC 检查COM_TRAFF_AVOID、PCA9685_PWM_FREQ、SENS_GNSSn_*系列参数是否已按预期迁移；旧 QGC 参数文件中的旧名称参数不会被恢复，需要手工更新；
2. GNSS 航向验证：确认提供航向的接收机已设置SENS_GNSSn_HDG，天线偏移参数（SENS_GNSSn_OFFX/Y/Z、SENS_GNSSn_AUXX/Y/Z）配置正确，观察vehicle_gnss中航向是否持续有效；
3. 电机故障恢复测试：在仿真或地面测试中开启CA_FAILURE_MODE，结合 故障注入 模拟电机失效，验证六旋翼的偏航权限恢复行为；
4. 仿真链路：确认启动命令已从 jMAVSim 迁移到make px4_sitl_sih sihsim_quadx或 Gazebo。

完整参数说明可查阅 Parameter Reference，该文档由仓库内 Tools/module_config/generate_params.py 从各模块的*.yaml参数定义自动生成；本发布说明对应的上一个版本说明见 PX4 v1.18 Release Notes。

• 嵌入式
• 物联网
• 机器人
• 自动驾驶
• 智能硬件