wsadexq DJI 上云 API
大疆上云 API 是基于大疆行业版无人机（机场、DJI Pilot 2、遥控器、负载）对外提供的云平台接入接口，采用"端-边-云"架构：无人机不能直接上云，必须通过网关设备（大疆机场或遥控器）间接接入。
- 网关设备（机场 / 遥控器）→ 第三方云平台，通信协议为 MQTT / HTTPS / WebSocket
- 网关注册登录时会上报飞机与负载的能力（物模型）
- 本技能只处理云平台侧接入与解析，不涉及飞控底层
何时使用
- 部署大疆上云服务端（MQTT 网关 / HTTPS / WebSocket / 对象存储）
- 解析设备上报的物模型数据（OSD 属性 / 事件 / 服务响应）
- 向设备下发指令（航线任务 / 直播 / 媒体 / 固件升级 / HMS 查询）
- 排查设备上下线、拓扑更新、订阅不到数据、错误码等问题
- 区分两种场景：Dock-to-Cloud（机场上云，无人值守）与 Pilot-to-Cloud（遥控器 + DJI Pilot 2 上云，有人操作）
基础架构
第三方云平台（你的服务端）
├── MQTT 网关 ← 设备长连接，收发属性/服务/事件/上下线（Broker）
├── HTTPS 服务 ← 短连接接口（航线管理/媒体管理/地图元素/态势感知）
├── WebSocket 服务 ← 服务端向 Pilot/Web 推送（地图元素/态势感知）
└── 对象存储 ← 航线文件/媒体文件存储
设备端
├── 大疆机场（Dock） → MQTT/HTTPS 上云（Dock-to-Cloud）
├── 遥控器 + DJI Pilot 2 → MQTT/HTTPS/WebSocket/JSBridge 上云（Pilot-to-Cloud）
└── 无人机/负载 → 不直接上云，由网关代理上报
通信协议速查
| 协议 | 用途 | 关键点 |
|---|---|---|
| MQTT | 设备长连接，属性/服务/事件/上下线/DRC | Topic 前缀 sys/（基础）与 thing/（物模型），消息含 tid/bid/method/data/timestamp |
| HTTPS | 业务短连接（航线/媒体/地图/态势） | https://{endpoint}/{module}/api/{v}/...，header 带 X-Auth-Token，响应 {code,message,data} |
| WebSocket | 服务端→Pilot/Web 推送 | 消息含 biz_code/version/timestamp/data |
| JSBridge | Pilot 内嵌 Webview 与原生双向通信 | Web 登录换取 Token/MQTT 地址后传给 Pilot |
硬性规则
- 无人机不能直接上云：必须经机场或遥控器网关代理，订阅/下发都走网关
sn - Topic 双层划分：
sys/product/{gateway_sn}/...（上下线/拓扑）与thing/product/{gateway_sn或device_sn}/...（物模型），不要混用 - osd 与 state 分离：
osd定频上报（pushmode=0），state事件性上报（pushmode=1） - tid/bid 必带：
tid事务 UUID（一次通信），bid业务 UUID（长流程，如点播/下载），服务端按 method 匹配回复 - 回复必须带
result：设备侧services_reply/events_reply/requests_reply/status_reply/property/set_reply的data.result非 0 即错误 - HTTPS 响应统一
{code,message,data}：code=0成功；message为错误描述 - 错误码 ABCDEF 格式：A 来源（3/5 设备端，4/6 Pilot）、BC 模块、DEF 自定义；HMS 错误需拼接文案 Key 查 hms.json（见 error-code.md）
- 物模型三要素：属性(Property)/服务(Service)/事件(Event)，属性用
accessMode=rw判断是否可写 - 机场型号差异：Dock1（如 M30 机场）与 Dock2（如 M3D 机场）的属性/服务主题可能不同，按机型查对应物模型
- 生成/解析后必须校验：字段命名、类型、取值范围对照官方物模型，禁止自造字段
安全与隐私边界（重要）
本技能涉及真实设备控制与云平台对接，以下边界必须严格执行，不能只依赖校验脚本：
- 高风险动作再次确认：远程开机、返航、起飞、指飞（DRC
fly_to_point/takeoff_to_point）、航线任务下发等动作，必须再次向用户确认目标坐标、高度与动作本身后才能执行 - 不写入用户真实数据：不得把用户设备 SN、真实坐标、航线、Token 写入示例文件或文档；示例必须使用占位符（
{sn}、虚构坐标、xxxxxxxx-...UUID） - 脱敏义务：坐标、设备 SN、Token、密钥、日志等敏感信息在输出前必须先脱敏；日志文件路径、设备序列号等一律占位化
- 校验通过 ≠ 控制安全：
validate_mqtt.py只校验公共信封字段与部分关键 method 参数，不代表设备端处理成功或飞行安全，也不代表符合当地法规 - 不主动提权/不改配置：未经用户明确要求，不得尝试连接生产环境、修改设备配置、拉取真实日志或进行任何网络操作
按需加载
- 要了解物模型/MQTT/HTTPS/WebSocket/JSBridge 基础概念 →
reference/basic-concepts.md - 要处理 MQTT 主题与消息结构（osd/state/services/events/requests/status/property/drc） →
reference/mqtt-topics.md - 要处理遥控器 + DJI Pilot 2 场景（Pilot 登录、地图元素、态势感知、直播、媒体、航线管理） →
reference/pilot-to-cloud.md - 要处理大疆机场场景（机场上下线、设备管理、直播、媒体、航线任务、HMS、固件升级、远程调试） →
reference/dock-to-cloud.md - 要了解功能集与适用机型 →
reference/feature-set.md - 要查错误码 / HMS 告警文案 →
reference/error-code.md - 要处理 PSDK/喊话器、AirSense、FlySafe 解禁、自定义飞行区、多机场蛙跳、Dock2 遥控器、PSDK/ESDK 透传 →
reference/extended-topics.md - 要搭建上云服务端（源码/Docker 部署）、Pilot 登录、MQTTX 调试、日志导出 →
reference/deploy-debug.md
脚本工具
scripts/build_mqtt.py：构造标准 MQTT 消息。读入模板 JSON，自动补齐tid/timestamp（+bid/gateway），输出带tid/bid/timestamp/gateway的完整消息python scripts/build_mqtt.py <template.json> [--gateway <sn>] [--bid] [-o <out.json>]scripts/validate_mqtt.py：校验 MQTT 消息合法性。检查公共字段、UUID 格式、13 位毫秒时间戳、method 必填性、回复类消息data.result规则python scripts/validate_mqtt.py <message.json> [--topic <topic>] [--strict]- 退出码：0 通过；1 不通过；2 参数错误
--topic显式指定 Topic（如thing/product/{sn}/services_reply）可更准确判断"回复类需data.result"
调试速查
| 症状 | 排查方向 |
|---|---|
| 设备不上线 | 检查 MQTT 认证（sn/密钥）、sys/product/{sn}/status 是否收到 update_topo |
| 订阅不到 OSD | 确认订阅的是 thing/product/{device_sn}/osd，且机型物模型存在该属性 |
| 下发指令无响应 | 确认 tid/bid 与 method 正确，检查 services_reply 的 result |
| 事件重复推送 | 检查 events 消息的 need_reply，按需回复 events_reply |
| HMS 告警看不懂 | 按 HMS 错误码拼接文案 Key，查 hms.json 获取文案（见 error-code.md） |
| 文件传不上去 | 检查临时凭证（HTTPS 获取 credentials）与对象存储权限 |