PX4 云端接入
PX4 是 UTMOS 的一等厂商适配器，和 DJI 平级。PX4 不属于 DJI 兼容层，也不会写入 DJI command catalog。
真实 PX4 下行默认关闭。PX4 edge agent 必须保持 PX4_COMMAND_MODE=disabled，除非 guarded downlink 显式授权并完成安全验收。
命令方向
command.accepted 只表示云端已经鉴权、授权、幂等校验并持久化命令，不表示 PX4 已执行命令。
PX4 命令覆盖
| 命令族 | 数量 | 响应模型 | 页面 |
|---|
| generated MAV_CMD flow | 178 | COMMAND_ACK | PX4 命令目录 |
| parameter read | 1 | PARAM_VALUE / PARAM_ERROR | px4.parameter.read |
| named parameter set | 1873 | PARAM_VALUE / PARAM_ERROR | 参数 set 全量目录 |
不开放的 MAV_CMD_DO_SET_PARAMETER | 1 | 不适用 | 由 named parameter set commands 替代 |
云端后端与 Console 接入边界
PX4 agent 只负责 utmos-px4-agent <-> NATS <-> PX4 MAVLink 边界。Open Platform API、Console 后端和 Console 前端必须把 agent 输出的 named catalog 当作能力合同消费，不应重新发明 PX4 MAV_CMD 或 PARAM_SET payload。
| 层级 | 新增或改动方式 | 不允许 |
|---|
| Open Platform 后端 | 从 PX4 vendor catalog 同步 command_type、请求 schema、结果状态和 evidence；受理后发布 command.accepted；查询时聚合 command.completed。 | 在业务后端暴露 generic mav_cmd、param1..param7、px4.parameter.set 或自定义 PX4 参数名字段。 |
| Console 后端 | 给浏览器返回已授权设备的可用 command catalog、参数 schema、allowlist、guard 状态、transport readiness 和最近完成结果。 | 让浏览器直接拼 NATS subject、MAVLink frame、PARAM_SET 或读取 agent 私有配置。 |
| Console 前端 | 按 catalog 渲染表单：枚举用下拉，bitmask 用具名开关，boolean 用开关，number/integer 用范围输入；按 PX4 group、命令域和搜索过滤。 | 显示 param1..param7、要求用户猜 enum 数字、把 1873 个参数平铺成一级导航、把 disabled 状态伪装成可发送。 |
| 文档 UX | 保持 commands、parameters/read、parameters/set、parameters/set/catalog、parameters/set/groups 分层；重点参数单独写中文解释。 | 为每个 generated parameter 建一级 sidebar 项，或只给英文 PX4 原文不解释业务含义。 |
command_id 和生命周期状态，不把 NATS 内部 subject 当作用户操作对象。
command.accepted 事件
Subject:
tenant.<tenant_id>.command.accepted
{
"event_id": "uuid",
"event_type": "command.accepted",
"command_id": "uuid",
"tenant_id": "tenant_local",
"client_id": "client_001",
"vendor": "px4",
"device_id": "px4-real-1",
"command_type": "nav_takeoff",
"timeout_seconds": 30,
"accepted_at": "2026-06-08T10:15:30Z",
"request_id": "req_001",
"payload": {
"latitude": 473566000,
"longitude": 85432100,
"altitude": 30
}
}
command.completed 事件
Subject:
tenant.<tenant_id>.command.completed
| PX4 status | adapter_status | public_status |
|---|
rejected_by_agent | REJECTED_BY_ADAPTER | FAILED |
sent_to_px4 | SENT_TO_DEVICE | DELIVERED |
ack_accepted | SENT_TO_DEVICE | SUCCEEDED |
ack_temporarily_rejected | SENT_TO_DEVICE | FAILED |
ack_denied | SENT_TO_DEVICE | FAILED |
ack_unsupported | SENT_TO_DEVICE | UNSUPPORTED |
ack_timeout | RESPONSE_TIMEOUT | TIMED_OUT |
parameter_value_confirmed | SENT_TO_DEVICE | SUCCEEDED |
parameter_error | SENT_TO_DEVICE | FAILED |
parameter_response_mismatch | RECEIVED | UNKNOWN |
parameter_timeout | RESPONSE_TIMEOUT | TIMED_OUT |
transport_failed | TRANSPORT_FAILED | FAILED |
| 字段 | 说明 |
|---|
human_summary | 中文优先的可读结果，例如 PX4 已确认 COM_RC_IN_MODE 设置为 MAVLink only。 |
hardware_response | PX4 硬件响应的 typed payload，例如 COMMAND_ACK、PARAM_VALUE、PARAM_ERROR、MISSION_ACK、FILE_TRANSFER_PROTOCOL、TIMESYNC。 |
source_evidence | 定义该响应语义的 PX4/MAVLink 本地源码证据。 |
COMMAND_ACK.result、PARAM_VALUE.param_type、PARAM_ERROR.error 或 delegated protocol ACK/NACK payload。
command.problem 事件
Subject:
tenant.<tenant_id>.command.problem
command.completed 时发布该事件，例如 accepted-command JSON 格式错误。UTMOS 会把原始 problem payload 投影到 PX4 设备最近事件视图，Console 可展开查看 problem_code、problem、detail 和 source_subject。
上行方向
PX4 edge agent 发布：
iot.uplink.px4.telemetry.observed
iot.uplink.px4.state.vehicle
| 数据 | 策略 |
|---|
| 高频 telemetry | 不写 PostgreSQL 主事实表 |
| latest state | 写入可重建当前态投影 |
| 历史分析 | 后续由 ClickHouse telemetry-history 特性承接 |
| 运行指标 | 暴露 Prometheus 指标 |
