​
PX4 参数写入

PX4 参数写入统一使用 MAVLink PARAM_SET，但 Open Platform 不暴露 generic px4.parameter.set。每个可写参数都有自己的 named command、请求结构、响应结构和 PX4 catalog evidence，调用者只填写 payload.value 和可选 target override。 当前 PX4 catalog 来自 parameters.json/xml，共有 1873 个 QGroundControl 同款 named 参数，其中 FLOAT 1310 个、INT32 563 个、volatile 101 个。平台为每个参数生成固定 command type： 
px4.parameter.<px4_param_name_lower>.set
例如 CBRK_USB_CHK 对应 px4.parameter.cbrk_usb_chk.set。调用者不能在 payload 中传 param_id，参数名永远由 command type 固定绑定。

​
查找参数

全量 set 目录

一张完整索引表，包含 1873 个 named set command

按 PX4 组查找

按 Commander、EKF2、MAVLink、Sensors 等 group 进入分组页面

读取参数

先读当前值，再决定是否写入

参数协议总览

查看 response、allowlist 和完成语义

​
Payload 模型

catalog-backed 参数写入使用固定字段： 
{
  "value": 0
}
对于 enum、boolean、bitmask、float、int32，agent 会按 PX4 catalog 校验：
PX4 形态payload 写法校验
FLOATnumber类型、最小值、最大值
INT32integer类型、最小值、最大值
enumstring必须命中 catalog values
booleanboolean转成 PX4 INT32
bitmask{ "bits": integer }必须只设置 catalog bits
重点参数详情页会解释 payload.value 的业务含义。例如 COM_RC_IN_MODE 的 value 是手动控制输入来源枚举，MPC_XY_VEL_MAX 的 value 是水平最大速度。详情页只是重点参数说明，不代表 catalog 只有这几个命令。

​
请求示例

{
  "vendor": "px4",
  "device_id": "px4-real-1",
  "command_type": "px4.parameter.mpc_z_vel_max_up.set",
  "payload": {
    "value": 3.5
  },
  "idempotency_key": "req-px4-param-MPC_Z_VEL_MAX_UP-001",
  "timeout_seconds": 30
}

​
重点参数详情页

参数command_type说明
COM_RC_IN_MODEpx4.parameter.com_rc_in_mode.set手动控制输入来源
MPC_XY_VEL_MAXpx4.parameter.mpc_xy_vel_max.set最大水平速度
CBRK_USB_CHKpx4.parameter.cbrk_usb_chk.setUSB 连接检查 circuit breaker
EKF2_GPS_CTRLpx4.parameter.ekf2_gps_ctrl.setGNSS 融合 bitmask
MPC_Z_VEL_MAX_UPpx4.parameter.mpc_z_vel_max_up.set最大上升速度

​
安全规则

  • 不允许发送 command_type=px4.parameter.set。
  • 不允许在 payload 中提供 param_id、value_type、param1 到 param7。
  • enum、boolean、bitmask、float、int32 都必须按 PX4 catalog 校验。
  • 真实写入需要 PX4_COMMAND_MODE=guarded、显式授权、ready transport 和 operator guard。
  • PX4_PARAMETER_WRITE_ALLOWLIST 必须包含该 named command 固定映射的 PX4 参数 ID。
  • PX4_COMMAND_MODE=disabled 是默认值；此时所有参数写入都会在 agent 本地拒绝，不会向飞控发送 PARAM_SET。

​
底层映射

层级说明
Cloud command每个参数一个 named command type
Request model每个参数一个 named request struct
MAVLink framePARAM_SET (23)
PX4 responsePARAM_VALUE 或 PARAM_ERROR
Completionparameter_value_confirmed / parameter_error / parameter_response_mismatch / parameter_timeout