PX4 参数协议

PX4 参数读写不是普通 MAV_CMD flow，而是 MAVLink parameter microservice。开放平台将它们纳入统一 command lifecycle：创建命令时仍调用 POST /api/v1/open/downlink/commands，查询结果时仍使用 GET /api/v1/open/downlink/commands/{commandId}。

能力总览

能力	数量	command_type	底层 MAVLink	响应
参数读取	1	`px4.parameter.read`	`PARAM_REQUEST_READ` (`20`)	`PARAM_VALUE` / `PARAM_ERROR`
参数写入	1873	`px4.parameter.<px4_param_name_lower>.set`	`PARAM_SET` (`23`)	`PARAM_VALUE` / `PARAM_ERROR`

选择入口

读取参数

读取任意 PX4 parameter id，例如 COM_RC_IN_MODE

写入参数

了解 PX4 参数写入的请求、校验和安全策略

全量 set 目录

查看 1873 个 named set command 和基础元数据

按 PX4 组查找

按 Commander、EKF2、MAVLink、Sensors 等 group 定位参数

参数目录来源

当前 catalog 来自 PX4 构建产物 parameters.json/xml，并与 PX4 MAVLink parameter 代码一起作为 evidence。目录规模：

分类	数量	说明
全部 writable named set	1873	每个参数一个固定 command type
`FLOAT`	1310	用浮点值写入
`INT32`	563	用整数、枚举、布尔或 bitmask 写入
`Standard`	1455	常规运行参数
`System`	411	系统/驱动/校准相关参数
`Developer`	7	circuit breaker 等开发/调试参数
`volatile`	101	飞控运行期 volatile 参数

写入模型

参数写入不允许调用方自己拼 PARAM_SET 的 param_id、param_value、param_type。每个参数都有自己的 named command：

px4.parameter.<px4_param_name_lower>.set

例如 CBRK_USB_CHK 的 command type 是：

px4.parameter.cbrk_usb_chk.set

通用 catalog-backed 请求使用 payload.value：

{
  "vendor": "px4",
  "device_id": "px4-real-1",
  "command_type": "px4.parameter.cbrk_usb_chk.set",
  "payload": {
    "value": 0
  },
  "idempotency_key": "req-px4-param-CBRK_USB_CHK-001",
  "timeout_seconds": 30
}

重点参数详情页会解释 payload.value 的业务含义、枚举值和安全限制，但 agent 协议字段仍固定为 payload.value。例如 COM_RC_IN_MODE 的 value 是手动控制输入来源枚举。

完成语义

PX4 响应	command.completed 结果	查询状态
`PARAM_VALUE` 且 `param_id`、类型和值匹配	`parameter_value_confirmed`	`SUCCEEDED`
`PARAM_ERROR`	`parameter_error`	`FAILED`
`PARAM_VALUE` 但不是本次请求的参数或值	`parameter_mismatch`	`UNKNOWN`
超时未收到匹配响应	`parameter_timeout`	`TIMED_OUT`
transport 发送失败	`transport_failed`	`FAILED`
agent 本地拒绝	`rejected_by_agent`	`FAILED`

安全策略

PX4_COMMAND_MODE=disabled 是默认值；disabled 模式不向真实飞控发送 parameter frame。
真实读取和写入都需要 guarded 模式、ready transport 和 operator guard。
写入还要求 PX4_PARAMETER_WRITE_ALLOWLIST 包含 named command 固定绑定的 PX4 参数 ID。
payload 不允许提供 param_id、value_type 或 generic param1..param7。
MAV_CMD_DO_SET_PARAMETER 不作为普通 command flow 开放；写参数必须使用 named parameter set。

重点参数详情页

以下页面提供更面向业务的中文解释和 typed payload。它们不是全部 set 命令；完整列表见全量 set 目录。

参数	command_type	说明
`COM_RC_IN_MODE`	`px4.parameter.com_rc_in_mode.set`	手动控制输入来源
`MPC_XY_VEL_MAX`	`px4.parameter.mpc_xy_vel_max.set`	最大水平速度
`CBRK_USB_CHK`	`px4.parameter.cbrk_usb_chk.set`	USB 连接检查 circuit breaker
`EKF2_GPS_CTRL`	`px4.parameter.ekf2_gps_ctrl.set`	GNSS 融合 bitmask
`MPC_Z_VEL_MAX_UP`	`px4.parameter.mpc_z_vel_max_up.set`	最大上升速度

​PX4 参数协议

​能力总览

​选择入口