DJI 无人机开发指南 — Part 1：DJI SDK 全体系详解

🚁 面向 ROS & Python/C++ 开发者（初学者友好）
💡 深入但实操：SDK 类型、使用场景、常用飞控与机型、授权/配套工具、快速上手示例、常见坑与排查思路
📅 最后更新：2025 年 11 月

---

📋 本章结构（便于查阅）

• 1. DJI SDK 总览（用途与选型）
• 2. 常见 DJI 平台、飞控与能力对照表
• 3. 各 SDK 详细说明（OSDK / MSDK / PSDK / Cloud API / RTK）
• 4. 与 ROS/ROS2 的集成路径与常见拓扑
• 5. 快速上手：典型开发环境与“Hello World”示例（OSDK + MAVROS 概览）
• 6. 权限、签名、固件与安全最佳实践
• 7. 常见问题（FAQ）与排查清单
• 8. 学习路线与推荐实验（为初学者设计）

---

1. DJI SDK 总览（用途与选型）

DJI 生态由多条 SDK 产品线组成，选择时按控制权限、运行位置（机载/手机/云）、外设能力来取舍。

选择要点（三问法）

1. 我需要在机载电脑运行算法，直接下发飞行指令吗？ → 选 Onboard SDK (OSDK)。
2. 我要做手机/平板端交互 App / 视觉回传给操作者吗？ → 选 Mobile SDK (MSDK)。
3. 我要开发挂载负载（相机/机械臂/传感器）并与无人机通信吗？ → 选 Payload SDK (PSDK)。
4. 我要做云端批量运维 / 集群调度 / 视频云转发？ → 选 Cloud API / HMS / 云端服务。
5. 需要厘米级定位？ → 关注 RTK / D-RTK 及其 SDK 接口。

---

2. 常见 DJI 平台、飞控与能力对照

平台 / 机型	典型飞控	支持 SDK	机载扩展	场景
Consumer（如 Mavic 系列）	集成飞控（闭源）	Mobile SDK（MSDK）	限制	消费级拍摄、航拍
Enterprise（Matrice 200/300/350 系列）	M300RTK 飞控	OSDK / PSDK / MSDK	丰富（PSDK 支持）	工业巡检、测绘、载荷
Inspire / Matrice	高级飞控	OSDK / MSDK / PSDK	支持机载电脑	专业影像、研发平台
Agras（农业机）	专用飞控	OSDK / Cloud	载药系统	农业喷洒
Matrice + D-RTK	支持 RTK	OSDK（RTK 接口）	精定位	精测绘、精确作业

注：不同机型具体支持的 SDK 版本与 API 会随固件更新变化，上线前务必核对厂商说明与兼容矩阵。

---

3. 各 SDK 详细说明（功能、适用与限制）

3.1 Onboard SDK（OSDK） — 机载控制首选

• 用途：在机载电脑（Jetson / NUC）上运行复杂算法（SLAM、导航、规避、视觉处理），并与飞控直接通信。
• 能力：获取传感器（IMU/GPS/状态）、发送位置/速度/姿态命令、读取/写入飞控参数、接收视频流、上传任务（航点）。
• 通信：串口（UART）、UDP（某些型号）或通过 mavlink-like 协议封装（由厂商提供）。
• 优点：能做闭环自动化控制、接入 ROS，适合研究/商用开发。
• 限制：某些消费机型不开放 OSDK；控制权限需飞控授权，且操作有风险（务必在测试场地）。

3.2 Mobile SDK（MSDK） — 手机/移动端交互

• 用途：开发遥控器或移动端应用（Android / iOS），实时视频、遥控、航点规划。
• 能力：视频回传、航点任务、相机控制、遥控通道、地理围栏设定。
• 优点：快速做 UI、演示与远程监控。
• 限制：不适合跑复杂本地算法（受移动端算力限制）。

3.3 Payload SDK（PSDK） — 定制负载

• 用途：实现与无人机集成的外挂设备通信（例如工业相机、LiDAR、机械臂）。
• 能力：电源管理、串口通信、GPIO、专用 API（数据上报、控制），可以与飞控共享信息。
• 优点：为第三方设备提供“官方级”挂载支持与安全交互方式。
• 限制：PSDK API 与硬件映射依机型而异，需要厂商认证/许可（部分机型需申请 PSDK 许可）。

3.4 Cloud API / HMS / Web Services

• 用途：远程运维、数据中心处理、大规模调度、存储视频/飞行日志。
• 能力：设备注册、任务下发、日志回传、视频推流服务。
• 优点：便于 Fleet 管理与远程分析。
• 限制：网络依赖强，实时性与安全性需额外设计（TLS、鉴权、SBOM）。

3.5 RTK 与高精度定位接口

• 用途：厘米级定位需求（测绘、精准作业）。
• 能力：提供差分修正数据或直接接入 D-RTK 基站数据。
• 限制：需要额外硬件（D-RTK）与合规操作（地面基站部署、频谱许可）。

---

4. 与 ROS/ROS2 的集成路径与常见拓扑

4.1 两种主流拓扑

1. 直接机载 ROS（机载 SBC） + OSDK

   Jetson/NUC (ROS2) <--> OSDK <--> 飞控
   ROS nodes: perception, planner, mavros_bridge (optional)
   

   优点：低延迟，本地闭环；缺点：机载算力/重量受限。

2. 地面站/云端 + MSDK/Cloud + 轻量机载控制

   地面/云 (ROS2) <--> MSDK/Cloud <--> 遥测/视频 <--> 轻量飞控
   

   优点：算力集中，可用云推理；缺点：依赖链路稳定性，不适合低延迟闭环控制。

4.2 MAVROS / mavlink 桥接

• 对于想把 DJI 飞控的数据抽象为 ROS Topic/Service 的场景，可以使用厂商提供的桥接包（或第三方 mavros-like 包）。MAVROS（原生为 PX4/ArduPilot）在某些 DJI 平台上需要适配层，但 OSDK-ROS 官方包通常已封装了必要功能。
• 常见 Topic：/dji/state、/dji/odometry、/dji/image_raw、service: takeoff, land, upload_mission。

---

5. 快速上手：典型开发环境与“Hello World”示例

5.1 开发先决条件（机载开发最小清单）

• 支持 OSDK 的 DJI 飞行器（例如 M300RTK、Matrice 系列；确认具体机型）
• 机载电脑（Jetson Orin / Xavier / NUC）运行 Ubuntu 20.04/22.04
• 串口线 / CAN / 以太网（视机型）连接到飞控
• DJI 开发者账号（用于获取 SDK 许可/Key 与文档）
• ROS2（Humble 或 later）——若要在 ROS2 上开发

---

5.2 OSDK “Hello World”：获取飞行器状态（C++ 伪示例）

#include <dji_vehicle.hpp>
using namespace DJI::OSDK;

int main() {
  Vehicle* vehicle = new Vehicle("/dev/ttyUSB0", 230400, 0);
  if (!vehicle->protocolLayer) {
    std::cerr << "Connect failed\n";
    return -1;
  }
  Telemetry::Status status = vehicle->broadcast->getStatus();
  std::cout << "Battery: " << status.battery << "%\n";
  delete vehicle;
  return 0;
}

注意：实际 API 名称会因 SDK 版本而变化，以上为示意。请以 SDK 文档示例为准。

---

5.3 ROS2 + OSDK 的最小启动流程（概要）

1. 在机载电脑上安装 OSDK 与 OSDK-ROS 套件（源码或 deb）。

2. 启动 OSDK 节点（会创建 ROS topic/publisher）：

   ros2 launch dji_osdk_ros dji_sdk.launch.py
   

3. 在另一个终端订阅状态：

   ros2 topic echo /dji_sdk/battery_state
   

4. 通过 ROS service 发起起飞命令（需在安全环境）：

   ros2 service call /dji_sdk/takeoff std_srvs/srv/Trigger
   

---

6. 权限、签名、固件与安全最佳实践

6.1 控制权限与“控制权获取”

• OSDK 发起控制前必须获得飞控授权（obtainCtrlAuthority()），避免与遥控器冲突。开发时务必在安全空场并能立刻接管遥控。

6.2 固件与 SDK 兼容性

• 固件更新可能导致 API 变更或功能受限：

  • 在生产部署中采用固件冻结策略：确保在一段时间内仅使用经过验证的固件版本。
  • 所有升级先在 SITL/HITL 或测试机上验证。

6.3 安全与签名（OTA、镜像）

• SDK 密钥、token 不要硬编码在仓库中；使用 CI Secrets / Vault 管理。
• OTA 镜像/固件使用签名与校验，设备端校验签名后才应用更新。
• 对 RPC/HTTP 接口启用 TLS 并强制认证。

---

7. 常见问题（FAQ）与排查清单

Q1：我的 OSDK 无法连接到飞控，报串口打开失败

排查：

• 检查串口权限（ls -l /dev/ttyUSB*，dialout 组）
• 确认波特率与线缆型号（某些机型使用 CAN/ETH 而非 UART）
• 飞控是否占用了串口（其他进程/地面站软件）

Q2：通过 ROS 发起起飞没反应

排查：

• 是否获得了控制权限（查看 /dji_sdk/controller/control_authority）
• 飞行器是否处于可起飞状态（GPS/IMU 校准/电量）
• 是否处于禁飞区或地理围栏限制

Q3：图传延迟高或丢帧

排查：

• 检查带宽与 Wi-Fi 干扰（切换频段或使用有线回传）
• 降低分辨率/码率或在机载进行轻量预处理

Q4：机载电脑性能瓶颈（推理卡顿）

排查：

• 使用 TensorRT / ONNX Runtime 加速推理
• 将部分推理任务移到边缘服务器或云端（注意时延）

---

8. 学习路线与推荐实验（为初学者设计）

周期：4–8 周（入门到能跑基本任务）

Week 1 — 环境与基础

• 熟悉机型与硬件；搭建机载电脑环境（Ubuntu + ROS2 + OSDK）；学会串口与日志查看。
• 实验：ros2 topic echo /dji_sdk/state、读电量、读 GPS。

Week 2 — 控制与任务

• 学习起飞/降落/航点任务；理解控制权限。
• 实验：实现安全模式下的自动起飞 → 悬停 → 降落（仿真优先）。

Week 3 — 感知接入

• 接入 RealSense 或 ZED；把深度/点云发布为 ROS Topic。
• 实验：实现简单的前向障碍检测并在发现障碍时停止前进。

Week 4 — ROS 集成与闭环

• 使用 VIO（VINS-Fusion）或视觉里程计发布 /odom，尝试位置控制。
• 实验：实现基于视觉定位的自动返回起点。

扩展（Week 5–8）

• 集成 PSDK 载荷、实现拍照点位任务；做 SITL 与现场小规模飞行测试。
• 学习 RTK 接入与精度测试（若需厘米级）。

---

写在最后（风险提示与下一步建议）

• 安全第一：任何涉及起飞/控制的代码在实际飞行前都必须在仿真或空旷场地多次验证，并且团队中要有人能够随时接管遥控器。
• 合规：不同国家/地区对无人机有严格法规（飞行高度、禁飞区、隐私采集等），开展现场测试前务必确认合规。
• 版本管理：把 SDK 版本、飞控固件、参数文件、标定数据都纳入版本化管理，保证可回滚。

---

🎉祝你天天开心，我将更新更多有意思的内容，欢迎关注！

最后更新：2025年11月
作者：Echo