Skip to content

Latest commit

 

History

History
943 lines (775 loc) · 18.2 KB

OPENProtocol.md

File metadata and controls

943 lines (775 loc) · 18.2 KB
Raw

Onboard SDK OPEN Protocol

Protocol Frame

The Protocal Frame is the smallest unit for transmission. It contains the Header, Data and the Tail as follows:

|<---------------------Header-------------------------->|<--Data-->|<--Tail-->|
|SOF|LEN|VER|SESSION|ACK|RES0|PADDING|ENC|RES1|SEQ|CRC16|   DATA   |  CRC32   |

Frame Format

Field Index (byte) Size (bit) Description
SOF 0 8 starting byte, fixed to be 0xAA
LEN 1 10 len of frame
VER 6 version of the frame header, set to be 0
SESSION 3 5 session ID
ACK 1 frame type
  • 0：CMD
  • 1：ACK
RES0 2 reserved, fixed to be 0
PADDING 4 5 len of padding data used by the Data encryption
ENC 3 encryption type
  • 0：no encryption
  • 1：AES encryption
RES1 5 24 reserved, fixed to be 0
SEQ 8 16 frame sequence num
CRC16 10 16 CRC16 frame header checksum
DATA 12 variable size frame data
CRC32 variable size 32 CRC32 whole frame checksum

Note: When encryption is enabled, the order of operation sequence should be encrypt DATA field -> update LEN and PADDING fields in frame header -> calculate CRC16 -> calculate CRC32

Note2: The byte content inside field is in LSB at left order. i.e. an 3th byte(SESSION+ACK+RES0) with value 0b01000000, the first 5 bits 01000 means value 2. Don't get lost when you're trying to print out the raw data of protocol.

Frame Type

There are two types of frames.

Frame Type Data Type Transmission Direction Content
CMD frame CMD frame data Onboard Device <=> N1 Autopilot flight control related CMDs
ACK frame ACK frame data N1 Autopilot <=> Onboard Device ACK related data

CMD frame data

|<------CMD frame data------>|
| CMD SET | CMD ID | CMD VAL |
Field Index (byte) Size (byte)
CMD SET 0 1
CMD ID 1 1
CMD VAL 2 vary by CMDs

ACK frame data

|<-ACK frame data->|
|      ACK VAL     |
Field Index (byte) Size (byte)
ACK VAL 0 vary by ACKs

SEQ field in ACK frame is the same as the one in corresponding CMD frame. Developers can use the SEQ field of the ACK frame to match the corresponding CMD frame.

Protocal Transmission Mechanism

Session

The session mechanism has been used in order to prevent the exceptions such as package loss. 3 kinds of session have been introduced:

Type SESSION Description
0 0 Sender doesn't need ACKs.
1 1 Sender needs ACKs but can be tolerated.
2 2-31 Sender needs ACKs.*

Note: Type 1 and Type 2 can ONLY be applied to the CMDs which have ACKs.

*Since type 2 is designed to be reliable. Developers should implement the package loss & resending mechinism based on the current SEQ and SESSION fields. When package loss is found from the sender, the sender can send the CMD frame again with the same SEQ and SESSION lost previously to retrieve back the ACK frame.

Encryption (optional)

DJI designs encryption interface in communication between Onboard Device and autopilot, considering it is possible that developer implement the communication with unsafe channel, for example various types of wireless transparent transmission module.

AES encrypting is designed only for data part of a frame. And developers can encrypt their own data with a key which is despatched when they register the APP ID, and encryption function in DJI_LIB.

Due to encryption process, data need to be aligned into blocks and each one contains 16 bytes. 'PADDING' in frame header is the length of additional data generated in this progress. Also 'LEN' need to be caclulated again, and 'ENC' need to be set to '1'. For more details about encryption algorithm, please refer to sdk_encrypt_interface in DJI_Pro_Codec.cpp .

On the other hand, there is no need to encrypt data, when developers use a serial cable to connect Onboard Device and autopilot. In this case, just set 'ENC' to '0'.

CMD Set & CMD ID

CMD Set

The CMDs have three different sets

CMD Set CMD ID Transmission Direction Description
Activation 0x00 Onboard Device ==> N1 Autopilot activation related CMDs
Flight Control 0x01 Onboard Device ==> N1 Autopilot flight control related CMDs
Push Data 0x02 N1 Autopilot ==> Onboard Device push data related CMDs

CMD ID

Each CMD Set contains some CMD IDs for different operations.

The execution of different CMDs needs an corresponding Authorization Level. A CMD will not be executed when the current Authorization Level granted is lower.

Levels Description
0 Activation related
1 Gimbal and Camera control related
2 Flight Control related

Note: The Authorization Level of the N1 Autopilot can be changed by the 'Activation' CMD. The init level is set to be 0.

Function Index

CMD Set CMD ID Function Level Required
0x00
Activation CMD Set		 0x00 Get Protocal Version 0
0x01 Activation 0
0x01
Control CMD Set		 0x00 Obtain/Release Control Authorization 2
0x01 Switch Flight Mode 2
0x02 Request Switch Result 2
0x03 Movement Control 2
0x1A Gimbal Control in Rate 1
0x1B Gimbal Control in Position 1
0x20 Take Photo 1
0x21 Start Recording Video 1
0x22 Stop Recording Video 1
0x02
Push Data CMD Set		 0x00 Flight Data 0
0x01 Lost of Flight Control 0

CMD Val & ACK Val

Activation CMD Set: 0x00

CMD ID 0x00: Get Protocal Version

Data Type Offset (byte) Size (byte) Description
CMD Val 0 1 arbitrary num
ACK Val 0 2 Return Code
  • 0x0000：N1 Autopilot is activated
  • 0xFF01：N1 Autopilot is NOT activated
2 4 The CRC val of the protocal version
6 32 protocal version

CMD ID 0x01: Activation

Data Type Offset (byte) Size (byte) Description
CMD Val 0 4 app_id, app unique identifer
4 4 api_level, authorization level
8 4 Fixed value, 0x02030A00
12 32 Fixed string, "12345678901234567890123456789012"
ACK Val 0 2 Return Code：
  • 0x0000：Success
  • 0x0001：Invalid parameters
  • 0x0002：Cannot recognize the encrypted package
  • 0x0003：New APP ID, activation in progress
  • 0x0004：No response from DJI GO APP
  • 0x0005：No Internet from DJI GO APP
  • 0x0006：Server rejected
  • 0x0007：Authorization level insufficient
  • 0x0008：Wrong SDK version

CMD Set 0x01 Control CMDs

CMD ID 0x00: Obtain/Release Control Authorization

Please make sure the following conditions have been met:

  • The 'enable API control' box is checked in the N1 assistant software.
  • The IOC mode inside the DJI GO APP is off.
  • The mode selection bar of the remote controller is placed at the F position. (After aircraft powered-up, switch the mode selector to A or P and then turn to F )
Data Type Offset (byte) Size (byte) Description
CMD Val 0 1 0x01：request to obtain control authorization
0x00：request to release control authorization
ACK Val 0 2 Return Code
  • 0x0000:refuse to obtaine control authorization(conditions are not met)
  • 0x0001:successfully released control authorization
  • 0x0002:successfully obtained control authorization
  • 0x0003:in progress

CMD ID 0x01 Switch Flight Mode

Data Type Offset (byte) Size (byte) Description
CMD Val 0 1 CMD Sequence Number
1 1 0x01 ： return to home(RTH)
0x04 ： auto take off
0x06 ： auto landing
ACK Val 0 2 Return Code
  • 0x0001：execution fail
  • 0x0002：start executing

CMD ID 0x02 Request Switch Result

Data Type Offset (byte) Size (byte) Description
CMD Val 0 1 CMD Sequence Number
ACK Val 0 2 Return Code
  • 0x0001：wrong CMD Sequence Number
  • 0x0003：switching in progress
  • 0x0004：switching failed
  • 0x0005：switching succeed

CMD ID 0x03 Movement Control

For more info about Movement Control, please refer to Control mode byte part in Appendix.

Data Type Offset (byte) Size (byte) Data Type Description
CMD Val 0 1 --- Control mode byte
1 4 float32 Roll or X-axis control value
5 4 float32 Pitch or Y-axis control value
9 4 float32 Throttle or Z-axis control value
13 4 float32 Yaw control value
ACK Val --- --- --- N/A

CMD ID 0x1A Gimbal Control in Rate

Data Type Offset (byte) Size (byte) Data Type Description
CMD Val 0 2 int16_t Yaw in rate
unit 0.1º/s, input range[-1800,1800]
2 2 int16_t Roll in rate
unit 0.1º/s, input range[-1800,1800]
4 2 int16_t Pitch in rate
unit 0.1º/s, input range[-1800,1800]
6 1 --- Fixed value, 0x80
ACK Val --- --- --- N/A

CMD ID 0x1B Gimbal Control in Position

Data Type Offset (byte) Size (byte) Data Type Description
CMD Val 0 2 int16_t Yaw angle
unit 0.1º, input range [-3200,3200]
2 2 int16_t Roll angle
unit 0.1º, input range [-350,350]
4 2 int16_t Pitch angle
unit 0.1º, input range [-900,300]
6 1 --- control flag byte
  • bit 0：mode flag bit
      • 0 ： Incremental control, the angle reference is the current Gimbal location
      1 ： Absolute control, the angle reference is related to configuration in DJI Go App
  • bit 1：Yaw invaild bit
      0 ： Gimbal will follow the command in Yaw
      1 ： Gimbal will maintain position in Yaw
  • bit 2：Roll invaild bit, the same as bit[1]
  • bit 3：Pitch invaild bit, the same as bit[1]
  • bit [4:7]：reserved, set to be 0
7 1 uint8_t Command completion time
unit 0.1s, for example 20 means gimbal will reach the commended postition in 2 seconds
rotate rate beyond 400º/s is not recommand
ACK Val --- --- --- N/A

The relationship bewteen the angle reference in absolute control mode and gimbal mode configuration in DJI Go App

Gimbal Mode Roll Pitch Yaw Gimbal Follow UAV's nose
Follow Ground Ground Body Y
FPV N/A Ground N/A Y
Free Ground Ground Ground N

Note: Rotating 90 degree in pitch direction will cause gimbal lock problem, in which the value of roll and yaw are not reliable.

CMD ID 0x20 Take Photo

Data Type Offset (byte) Size (byte) Description
CMD Val 0 1 arbitrary number
ACK Val --- --- N/A

CMD ID 0x21 Start Video Recording

Data Type Offset (byte) Size (byte) Description
CMD Val 0 1 arbitrary number
ACK Val --- --- N/A

CMD ID 0x22 Stop Video Recording

Data Type Offset (byte) Size (byte) Description
CMD Val 0 1 arbitrary number
ACK Val --- --- N/A

CMD Set 0x02 Push Data CMD Set

CMD ID 0x00 Flight Data

The flight data from the N1 Autopilot can be configured by the DJI N1 assistant software.

More info about Flight Data, please refer to Flight Data part in Appendix .

Data Type Offset (byte)* Size (byte) Description
CMD Val 0 2 item presence byte, Bit with value 1 means this flight data contains corresponding data item
  • bit 0：flag of time stamp
  • bit 1：flag of attitude quaternion
  • bit 2：flag of linear acceleration
  • bit 3：flag of linear velocity
  • bit 4：flag of angular velocity
  • bit 5：flag of GPS location, altitude and healthiness
  • bit 6：flag of magnetometer
  • bit 7：flag of remote controller data
  • bit 8：flag of roll,pitch and yaw of gimbal
  • bit 9：flag of flight status
  • bit 10：flag of battery info
  • bit 11：flag of control device
  • bit [12:15]：reserved
2 4 Time stamp
6 16 Attitude quaternion
22 12 Linear acceleration
34 13 Linear velocity
47 12 Angular velocity
59 24 GPS position, altitude, height and healthiness
83 12 Magnetometer data
95 10 Remote controller channels
105 12 Roll, pitch and yaw of Gimbal
117 1 Flight status
118 1 Battery percentage
119 1 Control device
ACK Val --- --- N/A

Note: The offset in the above table is with the assumption that all data items exist. The actual offset of data item in the flight data should be calculated by the flags of 'item presence byte'.

CMD ID 0x01 Lost of Flight Control

Onboard Device has the lowerest control priority. Its control authorization can be taken over by remote controller and Mobile Device. Once the flight control is lost from the Onboard Device, a push data will be sent by the N1 Autopilot.

Data Type Offset (byte) Size (byte) Description
CMD Val 0 1 Fixed value, set to be 0x04
ACK Val --- --- N/A