PX4 Autopilot 参数参考手册完全解读:从 3103 个参数到源码级调参实践

原创2026-09-22 20:13:581,361 阅读
文章标签:无人机机器人RTOS嵌入式固件传感器驱动硬件开发ROS自动驾驶系统编程

PX4 Autopilot 参数参考手册完全解读:从 3103 个参数到源码级调参实践

PX4 飞行控制固件的所有可调行为——从传感器噪声模型、EKF2 状态估计融合开关,到电机/舵机输出函数、RC 通道映射与各类 failsafe 阈值——都由统一参数系统(Parameter System)驱动。本文以仓库内自动生成的 参数参考文档 为骨架,逐层拆解其组织结构、字段语义与阅读方法,并结合 module.yaml 等参数定义源文件和 参数存储实现 源码,帮助你在 QGroundControl 中精准定位、理解并安全修改任意一个 PX4 参数。

文档性质:由源码自动生成的"参数总索引"

docs/en/advanced_config/parameter_reference.md 不是手工维护的文档,而是一份从固件源码自动生成的完整参数索引,全文件共 50692 行,覆盖 3103 个参数,按 100+ 个功能分组(## 章节)组织。文档头部明确标注了其生成方式:

This documentation was auto-generated from the source code for this PX4 version (using make parameters_metadata).

生成链路在仓库中清晰可查:

因此,该文档与当前固件版本严格同步:文档里看到的每一个默认值、取值范围、单位,都是编译进固件的真实数值。这也意味着如果你使用的固件版本较旧,或构建时裁剪了某些模块,文档中个别参数可能并不存在于你的固件中——对应处理方式参见后文"参数缺失"一节。

文档的宏观结构:分组、锚点与命名规律

参数参考文档采用"分组(H2)→ 参数条目(H3)"两级结构。分组名即功能域,例如:

分组 覆盖内容
ADC 片上/外部 ADC(如 ADS7128、ADS7953、TLA2528)参考电压配置
ADSB ADS-B 收发信机的呼号、ICAO ID、应急状态、机体尺寸等广播参数
Actuator Outputs 执行机构输出通道(Hiwonder EMM、PCA9685 等)的 Disarmed/Failsafe/函数映射
Airspeed Validator 空速传感器有效性检查与失效切换(ASPD_* 系列)
EKF2 扩展卡尔曼滤波器全部状态估计与融合参数
FW / Multicopter 固定翼 / 多旋翼的姿态、速率、位置控制增益
RC / Radio Calibration 遥控输入、摇杆校准、开关功能分配
Return Mode / Geofence 返航、地理围栏行为
System / Sensors / Serial 系统级、传感器选择、串口外设服务分配

每个参数条目带有一个锚点(如 {#EKF2_ACC_NOISE}),方便文档内跳转与精确引用。参数命名遵循**"模块前缀 + 下划线 + 语义名"**的强规律,例如:

  • EKF2_ACC_NOISE:EKF2 模块的加速度计噪声参数;
  • ASPD_FS_INNOV:空速校验的失效创新阈值;
  • COM_PREARM_MODE:Commander(飞行管理)的预解锁模式;
  • SYS_AUTOCFG_CAL:系统自动配置复位中的传感器校准开关。

看到前缀即可判断参数归属模块,这是快速定位参数的第一把钥匙。

逐字段读懂一个参数条目

文档中每个参数条目由"短描述 + 长描述 + 取值说明 + 元数据表"组成。以 EKF2_ACC_NOISE(加速度计噪声,用于协方差预测)为例:

### EKF2_ACC_NOISE (FLOAT) {#EKF2_ACC_NOISE}

Accelerometer noise for covariance prediction.

| Reboot | minValue | maxValue | increment | default | unit  | Read-Only |
| ------ | -------- | -------- | --------- | ------- | ----- | --------- |
|   | 0.01     | 1.0      |           | 0.35    | m/s^2 |      |

其元数据表的七个字段含义如下:

字段 含义
Reboot 显示 ✓ 表示修改该参数后必须重启飞控才生效;空白表示热更新即可生效
minValue / maxValue 参数的合法取值范围,超出范围的值会被拒绝或截断
increment 允许的步进增量,留空表示连续可调
default 固件内置默认值;布尔型会同时显示语义标签,如 Disabled (0)
unit 物理单位(V、m/s^2、s、ms、rad/s、m 等),用于换算
Read-Only 显示 ✓ 表示该参数由固件计算生成、不可写

对应地,参数在模块定义源文件中的原始形态是这样的(见 src/modules/ekf2/module.yaml):

EKF2_ACC_NOISE:
  description:
    short: Accelerometer noise for covariance prediction
  type: float
  default: 0.35
  min: 0.01
  max: 1.0
  unit: m/s^2
  decimal: 2

可以看到,short 描述、type、default、min、max、unit 一一对应地渲染进最终文档;decimal 字段则被生成器注释掉("intended for GCS not people"),说明文档刻意面向人类阅读而非地面站程序。

枚举型参数(Values)

当参数取值为离散枚举时,文档会列出完整取值表。以 ADSB-Out 的应急状态参数 ADSB_EMERGC 为例:

**Values:**
- `0`: NoEmergency
- `1`: General
- `2`: Medical
- `3`: LowFuel
- `4`: NoCommunications
- `5`: Interference
- `6`: Downed

这类枚举在生成器中由 param.GetEnumCodes() 收集并按键值排序输出(见 markdownout.py)。布尔型参数(如 ADC_ADS7953_EN)则统一渲染为 0: Disabled / 1: Enabled,默认值同时显示语义标签,如 Disabled (0)。

位掩码型参数(Bitmask)

一类特殊参数用位掩码组合多个独立开关,文档以 Bitmask 块列出每个比特位的含义。例如空速校验参数 ASPD_DO_CHECKS:

**Bitmask:**
- `0`: Only data missing check (triggers if more than 1s no data)
- `1`: Data stuck (triggers if data is exactly constant for 2s in FW mode)
- `2`: Innovation check (see ASPD_FS_INNOV)
- `3`: Load factor check (triggers if measurement is below stall speed)
- `4`: First principle check (airspeed change vs. throttle and pitch)

| Reboot | minValue | maxValue | ... | default | ... |
|   | 0        | 31       | ... | 7       | ... |

默认值 7 = 二进制 00111,即默认启用第 0、1、2 位检查;maxValue 31 = 全部 5 位。这类参数的取值需按二进制位组合理解,文档的 Bitmask 列表是唯一的权威解释。另一个典型例子是 EMM_REV(Hiwonder EMM 四通道输出范围反转),其 maxValue 15 = 4 个比特位全部置位。

阅读"板级专属"参数:Badge 标注的含义

文档部分条目带有 <Badge type="warning" text="This parameter is only present on some boards." /> 标注。生成器对 Actuator Outputs 分组内的所有参数强制添加该标注(见 markdownout.py 中的 BOARD_SPECIFIC_GROUPS 列表),因为该分组的输出通道数量、计时器映射因板卡而异。典型如 PCA9685_CENT1(PCA9685 PWM 扩展板 1 号通道舵机中位值)与 EMM_FUNC1(Hiwonder EMM 通道 1 输出函数)。

此外,生成器对 PWM 主/辅定时器参数(PWM_MAIN_TIM0、PWM_AUX_TIM0 等)会附加 The exact output numbers where this timer applies are board-specific 的信息标注(PARAM_IS_OUTPUT_TIMER 列表,见 markdownout.py)。看到这些 Badge 时应意识到:该参数在你的板卡上可能根本不存在,移植配置时切勿照搬。

从文档走向源码:三组代表性参数的底层逻辑

EKF2 噪声与状态估计参数

EKF2 分组(从 23054 行起)是文档中最大的参数族之一,覆盖 IMU 偏置学习、协方差预测、辅助传感器融合等。除 EKF2_ACC_NOISE 外,同族的 EKF2_ABL_ACCLIM(允许 IMU 偏置学习的最大加速度幅值,默认 25.0 m/s²)和 EKF2_AGP0_CTRL(辅助全球位置传感器融合开关,位掩码)都遵循"短描述解释用途、元数据表约束范围"的统一范式。这些参数在运行时由 EKF2.hpp 通过 ParamExtFloat<px4::params::EKF2_ACC_NOISE> 模板实例化读取,即固件启动时从参数系统加载并缓存。

空速校验与失效切换(ASPD_*)

Airspeed Validator 分组展示了一组联动的失效保护参数如何协同工作:

  • ASPD_DO_CHECKS(默认 7)决定启用哪些数据有效性检查;
  • ASPD_FS_INNOV(默认 5.0 m/s,范围 0.5–10.0)是触发失效的"预测空速 vs 实测空速"创新阈值,值越大越不敏感;
  • ASPD_FS_INTEG(默认 10.0 m)对超过阈值的创新量做时间积分,防止瞬时尖峰误触发;
  • ASPD_FS_T_STOP(默认 1.0 s)与 ASPD_FS_T_START(默认 -1.0 s,负值表示飞行中不自动恢复)控制传感器"判坏停用"与"判好恢复"的延迟。

阅读这类参数时,建议按"检测(DO_CHECKS)→ 阈值(INNOV)→ 积分确认(INTEG)→ 切换延迟(T_STOP/T_START)→ 主源选择(ASPD_PRIMARY)"的链路整体理解,而不是孤立地改单个值。

系统级开关(SYS_* / COM_* / RPM_*)

System 分组包含大量布尔/枚举型系统开关,例如 RPM_CAP_ENABLE(PWM 引脚 RPM 捕获使能)与 RPM_PULS_PER_REV(每转脉冲数,1–50,默认 1)需成对配置;SYS_AUTOCFG_CAL(SYS_AUTOCONFIG 复位是否覆盖传感器标定)则与出厂校准策略相关。这些参数的共同点是修改后通常需要重启(元数据表 Reboot 列为 &check;),因为它们在模块初始化阶段即被加载。

参数不在固件里怎么办

文档提示(原文档 tip 块)指出:若某个列出的参数在固件中缺失,请参考 参数查找与更新指南。常见原因有二:

  1. 条件参数:参数依赖另一个未被启用的参数,因此在参数界面被隐藏——串口服务分配类参数(SER_*)是最典型的条件参数;
  2. 固件裁剪:FMUv2 固件为塞进 1MB Flash 裁掉了大量模块,其参数自然不存在;解决方式是升级 FMUv3 引导加载程序,或通过 make px4_fmuv2_default boardconfig 重新配置模块后重建固件。

在 QGroundControl 中查找与修改参数

参数参考文档是"纸质索引",日常调参则在 QGroundControl 的 Parameters 界面进行(详见 参数查找与更新指南):

  • 搜索:在 Search 框输入子串,可同时匹配参数名与描述;勾选 Show modified only 过滤未改动参数;
  • 分组浏览:左侧按类型/分组(如 DShot、EKF2、Multicopter Position Control)折叠浏览;底部 Component X 分组对应已连接的 DroneCAN 外设参数;
  • 修改:点击参数行弹出侧边对话框,可查看详细信息(含是否需要重启)并修改;点 Save 后自动静默上传到飞控;
  • 工具菜单:提供 Refresh、Reset all to firmware defaults、Reset to vehicle's configuration defaults、Load/Save to file、Clear all RC to Param、Reboot Vehicle 等批量操作。

务必注意文档警告:除特别说明外,不应在飞行中修改参数;需要重启的参数在修改后飞控不会自动重启,须手动执行 Reboot Vehicle 或断电重启。

参数系统的底层实现与持久化

参数修改后如何保存?答案在 src/lib/parameters 目录:

这解释了三个实际现象:Reset all to firmware defaults 本质是擦除 Flash 中的参数覆盖区;只有被修改过的参数才占 Flash 空间(默认值不落盘);Flash 写满或损坏时飞控可能回退到全部默认值。

如何重新生成这份参考文档

文档本身也由仓库工具链产出。生成器 markdownout.py 的 Save() 方法以 UTF-8 写出最终 Markdown;配套的 jsonout.py 与 xmlout.py 则输出 JSON/XML 格式,供地面站(如 QGroundControl)动态加载。在完整 PX4 构建环境中执行:

make parameters_metadata

即可基于当前源码重新生成参数文档。由于参数定义散落在各模块 module.yaml,新增或修改参数后必须重新生成,文档才能与固件保持一致——这也再次说明:这份 50692 行的参数参考,本质上是整个 PX4 可配置性的一面镜子,读懂它,就拿到了从"改参数"到"懂固件"的完整地图。

登录后查看全文
PX4-Autopilot