Ground Station Protocol

2016-06-24

This part is about Groundstation related functions(Waypoint, Hotpoint and Follow Me), which has been introduced briefly in the OPEN Protocol.

For the detailed function logic, please refer to the Ground Station Programming Guide.

Command Set and Command Id

CMD Set CMD Group CMD ID Description
0x03 Waypoint 0x10 upload waypoint mission settings
0x11 upload waypoint data
0x12 start/stop waypoint mission
0x13 pause/resume waypoint mission
0x14 read waypoint init status (available in upcoming 3.2 release)
0x15 read single waypoint status (available in upcoming 3.2 release)
0x16 set waypoint mission idle velocity
0x17 get waypoint mission idle velocity
Hotpoint 0x20 upload hotpoint data and start the mission
0x21 stop hotpoint mission
0x22 pause/resume hotpoint mission
0x23 set hotpoint mission idle velocity
0x24 set hotpoint mission radius
0x25 reset yaw of hotpoint mission
0x26 read hotpoint info from flight controller
0x27 enable auto-radius mode (not available)
Follow me 0x30 upload follow me data and start the mission
0x31 stop follow me mission
0x32 pause/resume follow me mission
0x33 update target position
0x02 Mission Status Push Info 0x03 current mission status
0x02 Waypoint Mission Event Push Info 0x04 mission event

Data Structure

Note: All reserved bytes in ground station structs should be set as 0, otherwise your commands may fail.


0x03, 0x10: Upload Waypoint Mission Settings

Request:

typedef struct {

uint8_t indexNumber; //Total number of waypoints
float32_t maxVelocity; //Maximum speed joystick input(2~15m)
float32_t idleVelocity; //Cruising Speed (without joystick input, no more than vel_cmd_range)
uint8_t finishAction; //Action on finish
//0: no action
//1: return to home
//2: auto landing
//3: return to point 0
//4: infinite mode, no exit
uint8_t executiveTimes;//Function execution times
//1: once
//2: twice
uint8_t yawMode; //Yaw mode
//0: auto mode(point to next waypoint)
//1: lock as an initial value
//2: controlled by RC
//3: use waypoint's yaw(tgt_yaw)
uint8_t traceMode; //Trace mode
//0: point to point, after reaching the target waypoint hover, complete waypoints
//action (if any), then fly to the next waypoint
//1: Coordinated turn mode, smooth transition between waypoints, no waypoints task
uint8_t RCLostAction; //Action on rc lost
//0: exit waypoint and failsafe
//1: continue the waypoint
uint8_t gimbalPitch; //Gimbal pitch mode
//0: free mode, no control on gimbal
//1: auto mode, Smooth transition between waypoints
float64_t latitude; //Focus latitude (radian)
float64_t longtitude; //Focus longitude (radian)
float32_t altitude; //Focus altitude (relative takeoff point height)
uint8_t reserved[16]; //Reserved, must be set to 0

} WayPointInitData;

ACK: uint8_t

Note: The ACK of task upload is always 0. Developers should check the task parameter by themselves, otherwise error code 0xEA will appear when trying to upload waypoints' data.

0x03, 0x11: Upload Waypoint Data

Request:

typedef struct {

uint8_t index; //Index to be uploaded
float64_t latitude; //Latitude (radian)
float64_t longitude; //Longitude (radian)
float32_t altitude; //Altitude (relative altitude from takeoff point)
float32_t damping; //Bend length (effective coordinated turn mode only)
int16_t yaw; //Yaw (degree)
int16_t gimbalPitch; //Gimbal pitch
uint8_t turnMode; //Turn mode
//0: clockwise
//1: counter-clockwise
uint8_t reserved[8]; //Reserved
uint8_t hasAction; //Action flag
//0: no action
//1: has action
uint16_t actionTimeLimit; //Action time limit
uint8_t actionNumber : 4; //Total number of actions
uint8_t actionReapeat : 4; //Total running times
uint8_t commandList[16]; //Command list
uint16_t commandParameter[16];//Command parameters

} WayPointData;

ACK:

typedef struct{

uint8_t ack;
uint8_t index;
WayPointData data;

} WayPointDataACK;

There are totally six kinds of actions as follows, which should be set in commandList.

Commands Commands value Command param Description
WP_ACTION_STAY 0 Hover time unit: millisecond Just hover
WP_ACTION_SIMPLE_SHOT 1 N/A Take a photo
WP_ACTION_VIDEO_START 2 N/A Start record
WP_ACTION_VIDEO_STOP 3 N/A Stop record
WP_ACTION_CRAFT_YAW 4 YAW (-180~180) Adjust the aircraft toward
WP_ACTION_GIMBAL_PITCH 5 PITCH Adjust gimbal pitch 0: head -90: look down

Note: The controller will valid all waypoints' data together after the last one uploaded, which means if there exist at least one invalid waypoint information, the waypoint upload ACK of the last one will be with a error code.

0x03, 0x12: Start/Stop Waypoint Mission

Request:

uint8_t start;//0-> start, 1-> cancel

ACK: uint8_t

0x03, 0x13: Pause/Resume Waypoint Mission

Request:

uint8_t pause;//0-> pause, 1-> resume

ACK: uint8_t

0x03, 0x14: Read Waypoint Init Status (Available in upcoming 3.2 Release)

Request:

uint8_t with arbitrary value.

ACK:

typedef struct{

uint8_t ack;
WayPointInitData data;

} WayPointInitACK;

0x03, 0x15: Read Single Waypoint Status (Available in upcoming 3.2 Release)

Request:

uint8_t index;

ACK:

typedef struct{

uint8_t ack;
uint8_t index;
WayPointData data;

} WayPointDataACK;

0x03, 0x16: Set Idle Velocity

Request:

float32_t idleVeloctity;

ACK:

typedef struct{

uint8_t ack;
float32_t idleVelocity;

} WayPointVelocityACK;

0x03, 0x17: Get Idle Velocity

Request:

uint8_t with arbitrary value

ACK:

typedef struct{

uint8_t ack;
float32_t idleVelocity;

} WayPointVelocityACK;

0x03, 0x20: Upload And Start Hotpoint Mission

Request:

typedef struct{

uint8_t version; //Reserved, kept as 0
float64_t latitude; //Latitude (radian)
float64_t longitude; //Longitude (radian)
float64_t altitude; //Altitude (relative altitude from takeoff point
float64_t radius; //Radius (5m~500m)
float32_t yawRate; //Angle rate (0~30°/s)
uint8_t clockwise; // 0->fly in counter-clockwise direction, 1->clockwise direction
uint8_t startPoint; //Start point position
//0: north to the hot point
//1: south to the hot point
//2: west to the hot point
//3: east to the hot point
//4: from current position to nearest point on the hot point
uint8_t yawMode; //Yaw mode
//0: point to velocity direction
//1: face inside
//2: face ouside
//3: controlled by RC
//4: same as the starting yaw
uint8_t reserved[11];//Reserved

} HotPointData;

ACK:

typedef struct{

uint8_t ack;
float32_t maxRadius;

} HotPointStartACK;

0x03, 0x21: Stop Hotpoint Mission

Request:

uint8_t with arbitrary value

ACK: uint8_t

0x03, 0x22: Pause Hotpoint Mission

Request:

uint8_t pause; //0->pause, 1->resume

ACK: uint8_t

0x03, 0x23: Set Hotpoint Idle Velocity

typedef struct{

uint8_t clockwise;
float32_t yawRate;

} YawRate;

ACK: uint8_t

0x03, 0x24: Set Hotpoint Radius

Request:

float32_t radius;

ACK: uint8_t

0x03, 0x25: Reset Hotpoint Yaw

Requset:

uint8_t with arbitrary value

ACK: uint8_t

0x03, 0x26: Read Hotpoint Task Info From Flight Controller

Request:

uint8_t with arbitrary value

ACK:

typedef struct{

uint8_t ack;
HotPointData data;

} HotPointReadACK;

0x03, 0x27:Enable Auto-Radius Mode

Request:

struct hotpoint_auto_radius {
uint8_t on_off; //1->enable, 0->disable
int8_t rate;//radius change rate
};

ACK: uint8_t

0x03, 0x30: Upload And Start Follow Me Mission

Request:

typedef struct{

uint8_t mode; //Follow mode(reserved), set as 0
uint8_t yaw; //Yaw mode
//1: point to target
//0: controlled by RC
TargetData target; //Target
uint8_t sensitivity;//reserved, set as 0

} FollowData;
typedef struct TargetData{

float64_t latitude; //Initial position latitude (radian)
float64_t longitude;//Initial position longitude (radian)
uint16_t height; //Initial position altitude
uint16_t angle; //Reserved

} TargetData;

ACK: uint8_t

0x03, 0x31: Stop Follow Me Mission

Request:

uint8_t with arbitrary value

ACK: uint8_t

0x03, 0x32: Pause/Resume Follow Me Mission

Request:

uint8_t pause; //0->pause, 1->resume

ACK: uint8_t

0x03, 0x33: Update Target Position

Request:

typedef struct TargetData{

float64_t latitude; //Initial position latitude (radian)
float64_t longitude;//Initial position longitude (radian)
uint16_t height; //Initial position altitude
uint16_t angle; //Reserved

} TargetData;

NO ACK


The following CMD SET/ID are not API but broadcast data protocol, by which developers can check the current mission status and events like how flight data works.

Note: Developers should select the Ground Station Status checkbox in DJI Assistant.

0x02, 0x03 Current Mission Status Push Information

There are four kinds of mission status with the same struct size.

Developers can separate them by their first bytes, i.e. mission_type.

The 'mission_type' is defined with the following enum.

typedef enum
{
NAVI_MODE_ATTI,
NAVI_MISSION_WAYPOINT,
NAVI_MISSION_HOTPOINT,
NAVI_MISSION_FOLLOWME,
NAVI_MISSION_IOC,
}navi_type;

waypoint mission push information

typedef struct{
uint8_t mission_type; //mission type, should be NAVI_MISSION_WAYPOINT
uint8_t target_waypoint; //current target waypoint index
uint8_t current_status;//current status
uint8_t error_notification;//error notification
uint16_t reserved;//reserved

} cmd_mission_waypoint_status_push_t;

hotpoint mission push information

typedef struct{
uint8_t mission_type;// mission type, should be NAVI_MISSION_HOTPOINT
uint8_t mission_status;//mission status
//0:init
//1:running
//2:paused
uint16_t hp_exec_radius; //distance to the hotpoint: cm
uint8_t reason;
uint8_t hp_exec_vel;//angular velocity in ground frame, degree * 10
} cmd_mission_hotpoint_status_push_t;

follow me mission push information

typedef struct{
uint8_t mission_type;// mission type, should be NAVI_MISSION_FOLLOWM
uint8_t reserved_1;
uint16_t reserved_2;
uint16_t reserved_3;
}cmd_mission_folowme_status_push_t;

the other two status(NAVI_MODE_ATTI & NAVI_MISSION_IOC)

typedef struct{
uint8_t mission_type;
uint8_t last_mission_type;
uint8_t is_broken :1;
uint8_t reserved_1 :7;
uint8_t reason;
uint8_t reserved_2;
uint8_t reserved_3;
}cmd_mission_default_status_push_t;

0x02, 0x04 Mission Event Push Information

There are three kinds of waypoint mission events with the same struct size.

Developers can separate them by their first bytes, i.e. incident_type.

The 'incident_type' is defined with the following enum.

typedef enum
{
NAVI_UPLOAD_FINISH,
NAVI_MISSION_FINISH;
NAVI_MISSION_WP_REACH_POINT,
}incident_type;

waypoint mission upload event push information

typedef struct{
uint8_t incident_type;
uint8_t is_mission_valid;
uint16_t estimated_run_time;
uint16_t reserved;
}cmd_mission_wp_upload_incident_t;

waypoint mission finish event push information

typedef struct{
uint8_t incident_type;
uint8_t repeat;
uint16_t reserved_1;
uint16_t reserved_2;
}cmd_mission_wp_finish_incident_t;

waypoint reached event push information

typedef struct{
uint8_t incident_type;
uint8_t waypoint_index;
uint8_t current_status;
uint8_t reserved_1;
uint8_t reserved_2;
}cmd_mission_wp_reached_incident_t;

ACK Code

Common ACK
0x00 Success 0xD0 mode bar not in F
0xD1 not in Navi Mode 0xD2 IOC enabled
0xD3 mission not init 0xD4 mission not running
0xD5 mission running 0xD6 flight duration not satisfied
0xD7 mission with higher priority is running 0xD8 GPS health not satisfied
0xD9 low battery 0xDA drone not in air when init
0xDB invalid mission parameter 0xDC execution condition not satisfied
0xDD mission will fly through no-fly zone 0xDE HOME point not recorded
0xDF drone in no-fly zone 0xC0 altitude higher than max
0xC1 altitude lower than min 0xC7 too far
0xC8 drone does not support groundstation functions 0xC9 too far from the hotpoint/first waypoint
0xCA drone in beginner mode 0xF0 drone is taking off
0xF1 drone is landing 0xF2 drone is coming back to home
0xF3 drone is arming 0xF4 invalid command
0xFF unknown command/td>
Follow me ACK
0xB0 drone too far from mobile 0xB1 disconnect time too long
0xB2 gimbal pitch too large
Hotpoint ACK
0xC2 invalid radius 0xC3 velocity too large
0xC4 invalid start point 0xC5 invalid yaw mode
0xC6 too far to go back to route 0xA2 invalid float number
0xA3 invalid latitude/longitude 0xA6 invalid direction
0xA9 hotpoint already paused 0xAA hotpoint not paused
Waypoint ACK
0xE0 invalid mission data 0xE1 invalid waypoint data
0xE2 planned route too long 0xE3 flight route too long
0xE4 index larger than max number 0xE5 neighboring waypoints too close
0xE6 neighboring waypoints too far 0xE7 damping checking failed
0xE8 invalid action parameter 0xE9 waypoint upload not finished
0xEA waypoint task not uploaded 0xEB not all waypoint uploaded
0xEC request is running 0xED cannot pause because not running
IOC ACK
0xA0 too close to HOME point 0xA1 IOC type error