DroneMind/voicellmcloud/docs/PX4_CLIENT_CONTEXT.md

客户端上报：PX4 载具上下文（session.start.client.px4）

云端 LLM 需要知道你在控哪一类 PX4 载具、当前能力边界，才能把口语「往前十米、返航、降落」消歧成稳定的高层 flight_intent，避免把固定翼/VTL 按多旋翼瞎猜。

本字段全部可选；不传则 vehicle_class 在模型侧按 unknown 处理，summary 里会更保守。建议在机端能取到的情况下至少上报 vehicle_class，其次 mav_type。

---

1. 建议优先级

优先级	字段	说明
P0	vehicle_class	粗粒度机型，见 §3
P1	mav_type	HEARTBEAT.mav_type，与机载一致
P2	home_position_valid、rtl_available	影响「返航」是否可信
P2	offboard_capable	影响含 Offboard/机载接管的语义
P3	current_nav_state	当前 NAV_STATE / 可读模式名，消解「继续飞」等
P3	default_setpoint_frame	goto 默认用 local_ned 还是 body_ned 等
P4	px4_version、airframe_id、cruise_alt_m_agl、extras	排障、高度尺度、自定义

---

2. JSON 示例（session.start 片段）

{
  "type": "session.start",
  "proto_version": "1.0",
  "transport_profile": "text_uplink",
  "session_id": "...",
  "auth_token": "...",
  "client": {
    "device_id": "drone-01",
    "locale": "zh-CN",
    "capabilities": {
      "playback_sample_rate_hz": 24000,
      "prefer_tts_codec": "pcm_s16le"
    },
    "px4": {
      "vehicle_class": "multicopter",
      "mav_type": 2,
      "px4_version": "1.14.3",
      "airframe_id": "px4_generic_quad",
      "default_setpoint_frame": "local_ned",
      "offboard_capable": true,
      "mission_capable": true,
      "rtl_available": true,
      "home_position_valid": true,
      "current_nav_state": "POSITION",
      "cruise_alt_m_agl": 30.0,
      "extras": {
        "gps_ok": true,
        "ekf_ok": true
      }
    }
  }
}

服务端在 session.ready.server_caps 中带 accepts_px4_vehicle_profile: true 表示会消费该块并注入系统提示词。

---

3. vehicle_class 枚举（字符串）

与 PX4 常见机架大类对齐，客户端任选其一（小写 + 下划线）：

值	典型 PX4 / MAV 场景
multicopter	四旋翼、六旋翼等
fixed_wing	固定翼
vtol_standard	标准尾座/倾转等 VTOL
vtol_tailsitter	尾座 VTOL
rover	地面车
boat	水面艇
submarine	水下（若业务用到）
other	其它或少见构型
unknown	未知（默认）

---

4. mav_type（可选，整数）

可直接填 MAVLink HEARTBEAT 的 mav_type 原值，便于与 QGC / MAVSDK 对齐。常见示例（完整表见 MAV_TYPE）：

值	含义
1	固定翼
2	四旋翼（quad）
3	六旋翼
10	地面车
11	水面船
19	双足/仿人（少见）
20	尾座 VTOL
21	六旋翼同轴等
22	三旋翼

若同时提供 vehicle_class 与 mav_type，模型以二者一致性强为前提；明显冲突时以 mav_type 为准（可在 extras 里注明数据来源）。

---

5. default_setpoint_frame

口语「前/右/上」在未说明坐标系时，云端生成 goto 会优先用此字段：

• local_ned（默认）：北东地局部系，与多数 Offboard 位置设定一致。
• body_ned / body：机体系前右下 —— 仅当机端确实按体轴解析相对位移时填写。

---

6. extras

任意 JSON 对象，原样进入 LLM 上下文（控制「电池低」「室内无 GPS」「仅限 mission」等）。建议键名短、值可机器生成。

---

7. 与 MAVROS / ROS2 的对应关系（实现提示）

• mav_type、current_nav_state：可由 MAVROS /mavros/state 或 px4_msgs 等价话题映射得到。
• home_position_valid：HOME_POSITION 已设置或与 RTL 可用逻辑一致即可。
• offboard_capable： companion 侧已验证能 ≥2Hz 维持 Offboard 再置 true（见 PX4 Offboard 文档）。

本文不规定机端如何执行 JSON；执行栈仍以贵方 MAVROS / 自研 bridge 为准。