124 lines
4.2 KiB
Markdown
124 lines
4.2 KiB
Markdown
# 客户端上报：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` 片段）
|
||
|
||
```json
|
||
{
|
||
"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](https://mavlink.io/en/messages/common.html#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 为准。
|