协议帧是本开放协议中信息传输的最小单位,由帧头,帧数据段及帧尾组成。以下为帧格式:
|<-----------------------帧头段------------------------->|<--帧数据段-->|<--帧尾段-->|
|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 | 帧标识
|
|
RES0 | 2 | 保留。固定值为0 | |
PADDING | 4 | 5 | 加密 帧数据段 时所需的附加数据长度 |
ENC | 3 | 加密类型
|
|
RES1 | 5 | 24 | 保留。固定值为0 |
SEQ | 8 | 16 | 帧序列号 |
CRC16 | 10 | 16 | 帧头 CRC16 校验值 |
DATA | 12 | 长度不定 | 帧数据段 |
CRC32 | 大小不定 | 32 | 整个帧的 CRC32 校验值 |
帧分为两类
帧类型 | 数据段类型 | 传输方向 | 传输内容 |
---|---|---|---|
命令帧 | 命令数据段 | 机载设备<=>飞控 | 飞行器控制指令 |
应答帧 | 应答数据段 | 飞控<=>机载设备 | 控制指令的执行结果 |
|<-------帧数据段------->|
|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。
命令集包含一系列命令码,根据具体的命令码实现相应的功能。
命令需要在相应的权限级别下才能够被执行。当机载设备发出命令的所需权限级别高于飞控所处权限级别时,该命令将不被执行。处在较高权限级别下的飞控可以接受并执行来自机载设备的低级别权限命令。
权限级别 | 权限描述 |
---|---|
0 | 激活命令相关 |
1 | 相机和云台控制命令相关 |
2 | 飞行控制命令相关 |
备注:权限级别可通过发送激活命令改变,飞行平台在激活前的默认权限级别默认为0。
命令集 | 命令码 | 功能 | 所需权限级别 |
---|---|---|---|
0x00 初始化设置类 |
0x00 | 获取通信协议版本 | 0 |
0x01 | 激活 | 0 | |
0x10 | 设置推送数据频率 | 0 | |
0xFE | 数据透传:从Onboard SDK至Mobile SDK | 1 | |
0x01 控制命令类 |
0x00 | 请求获取/释放控制权 | 1 |
0x01 | 切换飞行状态 | 2 | |
0x02 | 查询飞行状态切换结果 | 2 | |
0x03 | 姿态控制 | 2 | |
0x05 | 解锁/锁定电机 | 2 | |
0x1A | 云台角速度控制 | 1 | |
0x1B | 云台角度控制 | 1 | |
0x20 | 相机拍照 | 1 | |
0x21 | 相机开始录像 | 1 | |
0x22 | 相机停止录像 | 1 | |
0x02 推送数据类 |
0x00 | 飞行数据 | 0 |
0x01 | 失去控制权 | 0 | |
0x02 | 数据透传:从Mobile SDK至Onboard SDK | 0 | |
0x03 | 地面站状态 | 0 | |
0x04 | 航点事件 | 0 | |
0x03 地面站功能类 航点部分 |
0x10 | 上传航点任务信息 | 2 |
0x11 | 上传航点 | 2 | |
0x12 | 启动/停止航点功能 | 2 | |
0x13 | 暂停/恢复航点功能 | 2 | |
0x14 | 下载航点任务信息 | 2 | |
0x15 | 下载航点信息 | 2 | |
0x16 | 设置巡航速度 | 2 | |
0x17 | 读取巡航速度 | 2 | |
0x03 地面站功能类 热点部分 |
0x20 | 启动热点功能 | 2 |
0x21 | 停止热点功能 | 2 | |
0x22 | 暂停/恢复热点功能 | 2 | |
0x23 | 设置巡航速度 | 2 | |
0x24 | 设置半径 | 2 | |
0x25 | 重置方向 | 2 | |
0x26 | 下载热点任务信息 | 2 | |
0x27 | 启动自动半径模式 | 2 | |
0x03 地面站功能类 跟随部分 |
0x30 | 启动跟随功能 | 2 |
0x31 | 停止跟随功能 | 2 | |
0x32 | 暂停/恢复跟随功能 | 2 | |
0x33 | 设置跟踪目标点位置 | 2 | |
0x04 同步信号类 |
0x00 | 设置同步信号输出频率 | 0 |
0x05 虚拟遥控类 |
0x00 | 虚拟遥控控制请求 | 2 |
0x01 | 虚拟遥控数据 | 2 |
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 | 任意值 |
应答值 | 0 | 2 | 返回码
|
2 | 4 | 通信协议版本号校验值 | |
6 | 32 | 通信协议版本号 |
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 4 | app_id, 应用唯一标识 |
8 | 4 | 固定值:
|
|
12 | 32 | 固定字符串,"12345678901234567890123456789012" | |
应答值 | 0 | 2 | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 | 时间戳 |
1 | 1 | 姿态四元数 | |
2 | 1 | 加速度 | |
3 | 1 | 速度 | |
4 | 1 | 角速度 | |
5 | 1 | GPS 位置, 海拔高度, 相对地面高度 | |
6 | 1 | 磁感计数值 | |
7 | 1 | 遥控器通道值 | |
8 | 1 | 云台姿态 | |
9 | 1 | 飞行状态 | |
10 | 1 | 剩余电池百分比 | |
11 | 1 | 控制设备 | |
12 | 4 | 保留 | |
应答值 | 0 | 2 | 返回码:
|
设置值 | 推送频率 |
---|---|
0 | 0Hz |
1 | 1Hz |
2 | 10Hz |
3 | 50Hz |
4 | 100Hz |
5 | 保持不变 |
请确认已满足以下条件
- 在PC assistant调参软件中,“启用API控制”勾选框已被勾选
- 遥控器的模式选择开关置于F档
由于飞控中的保护机制,所有的获取控制权与释放控制权指令需要发送两次才会生效,其中第一次会返回失败。故官方库文件中控制权获取和释放控制权的函数均发送了两次协议请求。
注意!在3.0及之后的固件中,若上电时遥控器模式开关已经处于F档,则默认进入F档逻辑。此处不同于2.3版本固件下的设定,无需将开关拨出F当后再次拨入。请从2.3版本升级的开发者一定注意!
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 |
0x01 : 命令获得控制权 0x00 : 命令释放控制权 |
应答值 | 0 | 2 | 返回码
|
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 | 指令序列号* |
1 | 1 |
0x01 : 自动返航 0x04 : 自动起飞 0x06 : 自动降落 |
|
应答值 | 0 | 2 | 返回码
|
备注:开发者应实现状态切换命令的编号,以便查询飞行状态切换结果。
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 | 指令序列号 |
应答值 | 0 | 2 | 返回码
|
关于模式标志字节说明详情请参阅附录模式标志字节说明部分。
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | --- | 模式标志字节 |
1 | 4 | float32 | Roll 轴或 X 轴控制量 | |
5 | 4 | float32 | Pitch 轴或 Y 轴控制量 | |
9 | 4 | float32 | Throttle 或 Z 轴控制量 | |
13 | 4 | float32 | Yaw 轴控制量 | |
应答值 | --- | --- | --- | 无应答值 |
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 |
0x01 : 解锁电机 0x00 : 锁定电机 |
应答值 | 0 | 2 | 返回码
|
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 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 |
|
|
|
应答值 | --- | --- | --- | 无应答值 |
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 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 | --- | 属性控制字节
|
|
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的读数会突变。
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 | 任意值 |
应答值 | --- | --- | 无应答值 |
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 | 任意值 |
应答值 | --- | --- | 无应答值 |
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 | 任意值 |
应答值 | --- | --- | 无应答值 |
飞控外发的状态数据包可以通过 DJI PC 调参软件配置。
更多详情请参阅飞行数据详细说明请访问附录飞行数据说明部分。
数据类型 | 偏移(字节)* | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 2 | 状态包存在标志位,标志位为 1 表示推送数据中存在该状态包
|
2 | 9 | 时间戳 | |
11 | 16 | 姿态四元数 | |
27 | 12 | 加速度 | |
39 | 13 | 速度 | |
52 | 12 | 角速度 | |
64 | 25 | GPS 位置, 海拔高度, 相对地面高度 | |
89 | 6 | 磁感计数值 | |
95 | 12 | 遥控器通道值 | |
107 | 13 | 云台姿态 | |
120 | 1 | 飞行状态 | |
121 | 1 | 剩余电池百分比 | |
122 | 2 | 控制设备 | |
应答值 | --- | --- | 无应答值 |
备注:
偏移(字节):表格中偏移(字节)为推送数据中存在所有状态包的情况。
实际数据在推送数据中的偏移需要根据标志位确定存在的状态包,然后根据各状态包大小计算出实际偏移大小。
机载设备的控制权优先级最低,其控制权可能在任何时候被夺去。
当机载设备失去控制权时该数据包会由飞控发送。
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 | 固定值,0x04 |
应答值 | --- | --- | 无应答值 |
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 6 | 地面站状态包 |
应答值 | --- | --- | 无应答值 |
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 6 | 航点事件包 |
应答值 | --- | --- | 无应答值 |
更多信息请参考地面站功能
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | * | waypoint_mission_info_comm_t | 任务信息 |
应答值 | 0 | 1 | uint8_t | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | 航点索引 |
1 | * | waypoint_comm_t | 航点信息 | |
应答值 | 0 | 1 | uint8_t | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 |
0x01 : 停止航点功能 0x00 : 启动航点功能 |
应答值 | 0 | 1 | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 |
0x01 : 恢复航点功能 0x00 : 暂停航点功能 |
应答值 | 0 | 1 | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | 任意值 |
应答值 | 0 | 1 | uint8_t | 返回码:
|
1 | * | waypoint_mission_info_comm_t | 任务信息 |
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | 航点索引号 |
应答值 | 0 | 1 | uint8_t | 返回码:
|
2 | 1 | uint8_t | 航点索引 | |
3 | * | waypoint_commt_t | 航点信息 |
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | * | float32 | 巡航速度 |
应答值 | 0 | 1 | uint8_t | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | 任意值 |
应答值 | 0 | 1 | uint8_t | 返回码:
|
1 | 2 | float32 | 巡航速度 |
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | * | hotpoint_mission_setting_t | 任务信息 |
应答值 | 0 | 1 | uint8_t | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | 任意值 |
应答值 | 0 | 1 | uint8_t | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 |
0x01 : 恢复热点功能 0x00 : 暂停热点功能 |
应答值 | 0 | 1 | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | 顺逆时针 |
1 | 4 | float32 | 巡航速度 | |
应答值 | --- | --- | --- | 无应答值 |
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 4 | float32 | 半径 |
应答值 | --- | --- | --- | 无应答值 |
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | 任意值 |
应答值 | --- | --- | --- | 无应答值 |
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | 任意值 |
应答值 | 0 | 1 | uint8_t | 返回码:
|
1 | * | hotpoint_mission_setting_t | 任务信息 |
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | enable(1为启动0为停止) |
1 | 1 | int8_t | rate(半径变化速度百分比) | |
应答值 | 0 | 1 | uint8_t | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | * | follow_me_mission_setting_t | 任务信息 |
应答值 | 0 | 1 | uint8_t | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | 任意值 |
应答值 | 0 | 1 | uint8_t | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 |
0x01 : 恢复跟随功能 0x00 : 暂停跟随功能 |
应答值 | 0 | 1 | 返回码:
|
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 1 | uint8_t | 任意值 |
应答值 | 0 | * | cmd_mission_follow_target_info | 目标点位置 |
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 4 | uint32_t | 0表示单次同步,其他数值表示同步频率单位hz |
应答值 | --- | --- | --- | 无应答值 |
更多信息请参考虚拟遥控
数据类型 | 偏移(字节) | 大小(字节) | 描述 |
---|---|---|---|
命令值 | 0 | 1 |
bit 0:
0 请求关闭
0 不切换,执行断线逻辑
|
应答值 | --- | --- | 无应答值 |
数据类型 | 偏移(字节) | 大小(字节) | 数据类型 | 描述 |
---|---|---|---|---|
命令值 | 0 | 4 * 16 | uint32_t[16] | 十六通道数值,范围[1024-660, 1024+660] |
应答值 | --- | --- | --- | 无应答值 |