Skip to content

Latest commit

 

History

History
952 lines (777 loc) · 18.9 KB

开放协议.md

File metadata and controls

952 lines (777 loc) · 18.9 KB
Raw

#Onboard SDK 开放协议说明

协议帧

协议帧是本开放协议中信息传输的最小单位，由帧头，帧数据段及帧尾组成。以下为帧格式：

|<-----------------------帧头段------------------------->|<--帧数据段-->|<--帧尾段-->|
|SOF|LEN|VER|SESSION|ACK|RES0|PADDING|ENC|RES1|SEQ|CRC16|     DATA    |    CRC32   |

帧结构

字段 索引（byte） 大小（bit） 说明
SOF 0 8 帧起始标识，固定为0xAA
LEN 1 10 帧长度标识
VER 6 帧头格式版本，固定为0
SESSION 3 5 会话ID
ACK 1 帧标识
  • 0：命令帧
  • 1：应答帧
RES0 2 保留。固定值为0
PADDING 4 5 加密 帧数据段 时所需的附加数据长度
ENC 3 加密类型
  • 0：不加密
  • 1：AES加密
RES1 5 24 保留。固定值为0
SEQ 8 16 帧序列号
CRC16 10 16 帧头 CRC16 校验值
DATA 12 长度不定 帧数据段
CRC32 大小不定 32 整个帧的 CRC32 校验值

备注：如果协议帧需要AES加密，应先对数据段进行加密，该过程可能会产生附加的数据长度，需要更新帧头中PADDING字段及LEN字段。再对帧头部分进行CRC16校验，获得校验值后再对整个协议帧进行CRC32校验。

备注2：字段中的字节内容使用LSB（最低有效位）在左进行排列。例如当第三个byte内容（SESSION+ACK+RES0）为 0b01000000时，其中的01000为SESSION ID，值为2。用户在使用串口调试软件打印码流内容时请注意这一点。

帧类型

帧分为两类

帧类型 数据段类型 传输方向 传输内容
命令帧 命令数据段 机载设备<=>飞控 飞行器控制指令
应答帧 应答数据段 飞控<=>机载设备 控制指令的执行结果

命令帧数据段

|<-------帧数据段------->|
|CMD SET|CMD ID|CMD VALUE|
字段 索引（byte） 大小（byte） 说明
CMD SET 0 1 命令集
CMD ID 1 1 命令码
CMD VALUE 2 与命令码有关 命令值

应答帧数据段

|<--帧数据段-->|
|   ACK VALUE  |
字段 索引（byte） 大小（byte） 说明
ACK VALUE 0 大小可变 应答值

当接收到应答帧时，应答帧帧头部分中包含相应命令帧的帧序列号(SEQ)，开发者可通过此信息匹配应答帧与命令帧。

协议通信机制

会话机制

协议设计了会话机制，以保证命令数据和应答数据不会因为丢包而出现通信双方异常。通信双方在向对方发起通信会话时，可以根据需要通过设置在帧头部分的SESSION字段来选择会话类型。协议中设计了三种会话类型。

会话类型* SESSION 描述
类型0 0 发送端不需要接收端应答
类型1 1 发送端需要接收端应答值，但可容忍应答值丢包
类型2 2-31 发送端需要正确收到接收端的应答包*

备注：
*会话类型1及类型2仅适用于具有应答值的命令。
**发送端使用这些 SESSION 发送命令数据包时，应答帧中包含该命令帧中的帧序列号 (SEQ)和通信过程中的会话ID (SESSION)。如果在通信过程中，发送端没有正确收到应答包，可以重新发送包含相同SESSION和SEQ的命令帧。由于会话方式3是一种可靠会话方式，开发者在协议实现中应考虑并实现数据丢包发生时的重发机制等。

加密机制（可选）

考虑到机载设备与飞控之间的串口通讯可能采用不安全的方式，例如各类无线透传模块等。DJI为通讯提供了加密机制。加密仅对帧数据段进行AES加密，开发者可通过注册APP ID时获得的KEY，使用DJI提供的加密函数进行数据加密。由于加密是16字节对齐，加密后帧数据段长度会发生变化，因此需要在帧头”PADDING“字段写加密时产生的附加数据长度，同时需要重新计算帧的长度标识”LEN“，并将加密类型”ENC“段置1。具体的加密算法及实现请参考DJI_Pro_Codec.cpp文件中的sdk_encrypt_interface函数。

如果开发者采用飞机直接搭载机载设备，通过有线串口的方式连接机载设备与飞控。那么开发者也可以不采用加密方式通讯，此时仅需将加密类型”ENC“段置0。

命令集与命令码

命令集

命令分为三大命令集

命令集 命令集代码 传输方向 描述
激活验证类 0x00 机载设备==>飞控 查询飞控激活状态、完成激活的相关命令
命令控制类 0x01 机载设备==>飞控 控制对飞行器及云台等设备的相关命令
推送数据类 0x02 飞控==>机载设备 由飞控主动向机载设备的数据，如传感器数据、云台数据等

命令码

命令集包含一系列命令码，根据具体的命令码实现相应的功能。

命令需要在相应的权限级别下才能够被执行。当机载设备发出命令的所需权限级别高于飞控所处权限级别时，该命令将不被执行。处在较高权限级别下的飞控可以接受并执行来自机载设备的低级别权限命令。

权限级别 权限描述
0 激活命令相关
1 相机和云台控制命令相关
2 飞行控制命令相关

备注：权限级别可通过发送激活命令改变，飞行平台在激活前的默认权限级别默认为0。

功能索引

命令集 命令码 功能 所需权限级别
0x00
激活验证类 		0x00 获取通信协议版本 0
0x01 激活 0
0x01
控制命令类 		0x00 请求获取/释放控制权 2
0x01 切换飞行状态 2
0x02 查询飞行状态切换结果 2
0x03 姿态控制 2
0x1A 云台角速度控制 1
0x1B 云台角度控制 1
0x20 相机拍照 1
0x21 相机开始录像 1
0x22 相机停止录像 1
0x02
推送数据类		 0x00 飞行数据 0
0x01 失去控制权 0

命令数据说明

命令集 0x00 激活验证类

命令码 0x00 获取通信协议版本

数据类型 偏移（字节） 大小（字节） 描述
命令值 0 1 任意值
应答值 0 2 返回码
  • 0x0000：机载设备已激活
  • 0xFF01：机载设备未激活
2 4 通信协议版本号校验值
6 32 通信协议版本号

命令码 0x01 激活

数据类型 偏移（字节） 大小（字节） 描述
命令值 0 4 app_id, 应用唯一标识
4 4 api_level，权限级别
8 4 固定值，0x02030A00
12 32 固定字符串，"12345678901234567890123456789012"
应答值 0 2 返回码：
  • 0x0000：成功
  • 0x0001：参数非法
  • 0x0002：数据包加密，未能正确识别
  • 0x0003：新的APP，正在激活
  • 0x0004：DJI GO 没有响应
  • 0x0005：DJI GO 没有联网
  • 0x0006：服务器拒绝
  • 0x0007：权限级别不够
  • 0x0008：SDK版本错误

命令集 0x01 控制命令类

命令码 0x00 请求获取/释放控制权

请确认已满足以下条件

  • 在PC N1 assistant调参软件中，“启用API控制”勾选框已被勾选
  • 在DJI GO App中，IOC模式已被关闭
  • 遥控器的模式选择开关已置于F档 (请在飞机上电后，将模式选择开关先拨到A或P档后再拨到F档)
数据类型 偏移（字节） 大小（字节） 描述
命令值 0 1 0x01 ： 命令获得控制权
0x00 ： 命令释放控制权
应答值 0 2 返回码
  • 0x0000：拒绝获取控制权(未满足获取控制权条件)
  • 0x0001：成功释放控制权
  • 0x0002：成功获得控制权
  • 0x0003：正在获取控制权

命令码 0x01 切换飞行状态

数据类型 偏移（字节） 大小（字节） 描述
命令值 0 1 指令序列号*
1 1 0x01 ： 自动返航
0x04 ： 自动起飞
0x06 ： 自动降落
应答值 0 2 返回码
  • 0x0001：执行失败
  • 0x0002：开始执行

备注：开发者应实现状态切换命令的编号，以便查询飞行状态切换结果。

命令码 0x02 查询飞行状态切换结果

数据类型 偏移（字节） 大小（字节） 描述
命令值 0 1 指令序列号
应答值 0 2 返回码
  • 0x0001：指令序列号错误
  • 0x0003：指令正在执行
  • 0x0004：指令执行失败
  • 0x0005：指令执行成功

命令码 0x03 姿态控制

关于模式标志字节说明详情请参阅附录模式标志字节说明部分。

数据类型 偏移（字节） 大小（字节） 数据类型 描述
命令值 0 1 --- 模式标志字节
1 4 float32 Roll 轴或 X 轴控制量
5 4 float32 Pitch 轴或 Y 轴控制量
9 4 float32 Throttle 或 Z 轴控制量
13 4 float32 Yaw 轴控制量
应答值 --- --- --- 无应答值

命令码 0x1A 云台角速度控制

数据类型 偏移（字节） 大小（字节） 数据类型 描述
命令值 0 2 int16_t Yaw轴角速度
单位0.1º/s，输入范围[-1800, 1800]
2 2 int16_t Roll轴角速度
单位0.1º/s，输入范围[-1800, 1800]
4 2 int16_t Pitch轴角速度
单位0.1º/s，输入范围[-1800, 1800]
6 1 --- 固定值，0x80
应答值 --- --- --- 无应答值

命令码 0x1B 云台角度控制

数据类型 偏移（字节） 大小（字节） 数据类型 描述
命令值 0 2 int16_t Yaw轴角度*
单位0.1º，输入范围 [-3200, 3200]
2 2 int16_t Roll轴角度
单位0.1º，输入范围 [-350, 350]
4 2 int16_t Pitch轴角度
单位0.1º，输入范围 [-900, 300]
6 1 --- 属性控制字节
  • bit 0：控制模式选择位
      • 0 ： 增量控制，角度基准为当前云台所处位置
      1 ： 绝对控制，角度基准与手机DJI Go App设置有关*
  • bit 1：Yaw轴命令控制失效位
      0 ： 云台Yaw角度运动到命令位置
      1 ： 云台Yaw将维持上一时刻状态
  • bit 2：Roll轴命令控制失效位，同bit1描述
  • bit 3：Pitch轴命令控制失效位，同bit1描述
  • bit 4:7：保留，设置为0
7 1 uint8_t 命令完成时间
单位0.1s，例如20代表云台在2s内匀速转动至命令位置
建议开发者控制速度不超过400º/秒
应答值 --- --- --- 无应答值

绝对控制模式下角度基准与手机DJI Go App中云台工作模式关系

云台工作模式 Roll Pitch Yaw 云台方向是否跟随机头
跟随模式 Ground Ground Body 是
FPV模式 不可控 Ground 不可控 是
自由模式 Ground Ground Ground 否

注意：将pitch旋转90度后会触发万向锁问题，此时roll与yaw的读数会突变。

命令码 0x20 相机拍照

数据类型 偏移（字节） 大小（字节） 描述
命令值 0 1 任意值
应答值 --- --- 无应答值

命令码 0x21 相机开始录像

数据类型 偏移（字节） 大小（字节） 描述
命令值 0 1 任意值
应答值 --- --- 无应答值

命令码 0x22 相机停止录像

数据类型 偏移（字节） 大小（字节） 描述
命令值 0 1 任意值
应答值 --- --- 无应答值

命令集 0x02 推送数据类

命令码 0x00 飞行数据

飞控外发的状态数据包可以通过 DJI N1 PC 调参软件配置。
更多详情请参阅飞行数据详细说明请访问附录飞行数据说明部分。

数据类型 偏移（字节）* 大小（字节） 描述
命令值 0 2 状态包存在标志位，标志位为 1 表示推送数据中存在该状态包
  • bit 0：时间戳存在标志
  • bit 1：姿态四元数存在标志
  • bit 2：加速度存在标志
  • bit 3：速度存在标志
  • bit 4：角速度存在标志
  • bit 5：GPS 位置、海拔（气压计数值）、相对地面高度、健康度存在标志
  • bit 6：磁感计数值存在标志
  • bit 7：遥控器通道值存在标志
  • bit 8：云台 roll、pitch、yaw 数据存在标志
  • bit 9：飞行状态存在标志
  • bit 10：剩余电池百分比存在标志
  • bit 11：控制设备存在标志
  • bit 12:15：保留
2 4 时间戳
6 16 姿态四元数
22 12 加速度
34 13 速度
47 12 角速度
59 24 GPS 位置, 海拔高度, 相对地面高度
83 12 磁感计数值
95 10 遥控器通道值
105 12 云台姿态
117 1 飞行状态
118 1 剩余电池百分比
119 1 控制设备
应答值 --- --- 无应答值

备注：
偏移（字节）：表格中偏移（字节）为推送数据中存在所有状态包的情况。
实际数据在推送数据中的偏移需要根据标志位确定存在的状态包，然后根据各状态包大小计算出实际偏移大小。

命令码 0x01 失去控制权

机载设备的控制权优先级最低，其控制权可能在任何时候被夺去。
当机载设备失去控制权时该数据包会由飞控发送。

数据类型 偏移（字节） 大小（字节） 描述
命令值 0 1 固定值，0x04
应答值 --- --- 无应答值