---
name: dji-cloud-api
description: 处理大疆上云 API（DJI Cloud API）的接入、解析、调试与问题定位。当用户提到"大疆上云""Cloud API""云平台对接""大疆机场上云""Pilot 上云""MQTT 设备接入""物模型""HMS 告警""机场直播""OSD 数据""DRC 指飞""航线任务下发""设备拓扑""固件升级"等涉及大疆行业设备（机场/DJI Pilot 2/遥控器/无人机）与第三方云平台通信的场景时使用。
---

# 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 |

## 硬性规则

1. **无人机不能直接上云**：必须经机场或遥控器网关代理，订阅/下发都走网关 `sn`
2. **Topic 双层划分**：`sys/product/{gateway_sn}/...`（上下线/拓扑）与 `thing/product/{gateway_sn或device_sn}/...`（物模型），不要混用
3. **osd 与 state 分离**：`osd` 定频上报（pushmode=0），`state` 事件性上报（pushmode=1）
4. **tid/bid 必带**：`tid` 事务 UUID（一次通信），`bid` 业务 UUID（长流程，如点播/下载），服务端按 method 匹配回复
5. **回复必须带 `result`**：设备侧 `services_reply`/`events_reply`/`requests_reply`/`status_reply`/`property/set_reply` 的 `data.result` 非 0 即错误
6. **HTTPS 响应统一 `{code,message,data}`**：`code=0` 成功；`message` 为错误描述
7. **错误码 ABCDEF 格式**：A 来源（3/5 设备端，4/6 Pilot）、BC 模块、DEF 自定义；HMS 错误需拼接文案 Key 查 hms.json（见 error-code.md）
8. **物模型三要素**：属性(Property)/服务(Service)/事件(Event)，属性用 `accessMode=rw` 判断是否可写
9. **机场型号差异**：Dock1（如 M30 机场）与 Dock2（如 M3D 机场）的属性/服务主题可能不同，按机型查对应物模型
10. **生成/解析后必须校验**：字段命名、类型、取值范围对照官方物模型，禁止自造字段

## 按需加载

- **要了解物模型/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`

## 调试速查

| 症状 | 排查方向 |
|---|---|
| 设备不上线 | 检查 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）与对象存储权限 |