PX4 参数系统与 Kconfig（Commander 视角）

发表于 更新于 分类于 ， ， 阅读次数： 本文字数： 694 阅读时长 ≈ 2 分钟
解析 commander_params.c 中关键参数的含义与作用，说明 Kconfig 对 Commander 模块的编译控制，以及 PARAM_DEFINE_* 宏的本质。

一、PARAM_DEFINE_* 宏的本质

PARAM_DEFINE_* 是 PX4 参数系统的注册宏，将参数名和默认值写入参数表：

1
2
PARAM_DEFINE_FLOAT(参数名, 默认值);  // 浮点参数
PARAM_DEFINE_INT32(参数名, 默认值);  // 整型参数

参数系统特性：

  • 参数持久化存储在 SD 卡的 params 文件中，重启后保留
  • 通过 MAVLink 协议可被地面站（QGroundControl）读写
  • C++ 代码中通过 DEFINE_PARAMETERS 宏绑定到本地变量，updateParams() 同步最新值

相关前置：Commander 模块框架

二、关键参数详解

2.1 手动姿态输入

1
2
3
PARAM_DEFINE_FLOAT(TRIM_ROLL,  0.0f);
PARAM_DEFINE_FLOAT(TRIM_PITCH, 0.0f);
PARAM_DEFINE_FLOAT(TRIM_YAW,   0.0f);

控制杆量中心点补偿，归一化控制量。用于补偿机体重心偏置或机械安装误差导致的飞行偏斜。

2.2 数据链路监控

1
2
3
PARAM_DEFINE_INT32(COM_DL_LOSS_T,    10);
PARAM_DEFINE_INT32(COM_HLDL_LOSS_T, 120);
PARAM_DEFINE_INT32(COM_HLDL_REG_T,    0);
参数 含义
COM_DL_LOSS_T 普通地面站数据链路连续多少秒无数据后判定为 connection lost
COM_HLDL_LOSS_T 高延迟链路（卫星通信等）判丢的超时阈值（秒）
COM_HLDL_REG_T 从已丢失状态恢复为健康的去抖/回归时间

设置合理的超时阈值可避免链路短暂波动触发 failsafe，同时保证真实链路丢失时的响应速度。

2.3 RC/遥控器信号丢失

1
PARAM_DEFINE_FLOAT(COM_RC_LOSS_T, 0.5f);

RC 或摇杆 setpoint 超过 COM_RC_LOSS_T 秒没有更新，判定手动输入失效。

超时前系统继续执行最后一次输入，超时时间设置过长存在安全隐患：飞机可能持续执行旧杆量（持续倾斜、爬升或俯冲）。

2.4 Home 点策略

1
2
PARAM_DEFINE_INT32(COM_HOME_EN,     1);
PARAM_DEFINE_INT32(COM_HOME_IN_AIR, 0);
参数 含义
COM_HOME_EN 允许自动设置 Home 点（解锁时）
COM_HOME_IN_AIR 是否允许起飞后更新 Home 点（尝试回算真实起飞点）

COM_HOME_IN_AIR 默认关闭，更保守。若飞行过程中错误更新 Home，会导致 RTL 朝错误方向飞行。

与 HomePosition 管理的关联：参见 HomePosition 管理

2.5 RC 输入源选择

1
PARAM_DEFINE_INT32(COM_RC_IN_MODE, 3);

控制 RC 输入的来源模式（纯 RC、摇杆、两者兼容等）。

2.6 RC 解锁/锁定迟滞

1
PARAM_DEFINE_INT32(COM_RC_ARM_HYST, 1000);

通过摇杆组合（如油门最低+偏航最右）触发 ARM/DISARM，需要保持该动作至少 1000 ms 才生效。迟滞保护防止误触发解锁。

三、Kconfig 配置

1
2
3
4
5
6
7
8
menuconfig MODULES_COMMANDER
    bool "commander"
    default n

menuconfig USER_COMMANDER
    bool "commander running as userspace module"
    default y
    depends on BOARD_PROTECTED && MODULES_COMMANDER
配置项 含义
MODULES_COMMANDER 是否编译 Commander 模块。若板级未启用此项，Commander 不会进入固件，相关参数修改不会生效
USER_COMMANDER 在支持内存保护的板子上，是否将 Commander 放到 userspace 运行

注意：若板级的 .px4board 文件中未包含 CONFIG_MODULES_COMMANDER=y，则 Commander 模块不会被编译，修改任何 COM_* 参数都不会有实际效果。

四、参数在代码中的使用方式

Commander 继承 ModuleParams，通过 DEFINE_PARAMETERS 宏声明参数：

1
2
3
4
5
DEFINE_PARAMETERS(
    (ParamFloat<px4::params::COM_RC_LOSS_T>)  _param_rc_loss_t,
    (ParamInt<px4::params::COM_DL_LOSS_T>)    _param_dl_loss_t,
    (ParamInt<px4::params::COM_HOME_EN>)       _param_home_en
)

主循环中检测参数更新并同步：

1
2
3
4
5
if (_parameter_update_sub.updated()) {
    parameter_update_s param_update;
    _parameter_update_sub.copy(&param_update);
    updateParams();  // 将最新参数值同步到本地成员变量
}

随后直接使用本地变量（而不是每次都查表），保证高频主循环的参数读取效率。

上一篇：Commander 模块框架
下一篇：飞行模式编码与映射