To use the SDK, please update your SplashDrone 4 to the following firmware

 

Introduction

Flight Control Communication Protocol is an open set of control protocols used for:

• Extend aircraft capabilities to your needs.
• Third-party software/application development.
• Integration of aircraft to your own system.

By using this protocol, you are able to obtain flight status, video feed; automate flight; and control gimbal, camera, payload release, etc.

Diagram

Video Feed

The video feed uses the standard RTSP protocol. After establishing the connection to the remote controller, access the address “RTSP://192.168.2.220:554” to receive the video stream.

Control Link

Control link uses a dedicated protocol to communicate with the external devices. After establishing the connection to the remote controller, all the signal and data are communicated by accessing the TCP:192.168.2.1:2022 socket.

Packet Format

All packets are packed and parsed using the following format.

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	1 byte	1 byte	1 byte	N byte	1 byte

• Start Flag: Every packet starts with 0xa6.
• PackLength: Length of the packet, including start and end flags.
• SRC: Source, the device which sends the packet.
• DEST: Destination, the device which receives the packet.
• MSGID: Message ID.
• CheckSum: check any errors that occur from MSGID to PAYLOAD. (Refer to “UMBUS.CHECKSUM.C” file for CheckSum algorithm)

Source Device and Destination Device

A complete system consists of multiple devices. To identify the recipient when sending the packet, you need to enter the right destination device code.

• SRC: Source, the device which sends the packet.
• DEST: Destination, the device which receives the packet.

Device Code	Device
0x01	Flight Control
0x02	Remote Controller
0x03	Gimbal
0x04	App/Ground Station
0xff	Report - all devices will receive and forward the message
0x00	Share code, the device will recognize as its own device.

For your own defined external devices, Device Code can be set to any code between 0xc8 to 0xfe.

Flight Status Report

Aircraft will report flight status periodically. One can get aircraft flight status by receiving and parsing the Flight Status Report message.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x1d	0x01	0xff	N byte	1 byte

SRC - Flight Control

DEST - Report

Data structure in PAYLOAD

Byte Index	Symbol	Length	Description
0	FLY_REPORT_V1	Sizeof(FLY_REPORT_V1)	Flight Status Report

 

Flight Mission Control

Flight Control has a mission control system used to receive and execute commands. The system allows you to operate take-off, land, return-to-home, payload release, waypoints, etc. You can also send a chain of commands to the mission control system to execute in sequence. For example, send a chain of commands to the aircraft to let it fly to a certain location and take a picture.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - the device which sends the message

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	Mission type
3	TASK.DATA (n byte)	Mission data, length not fixed

Mission OPCODE Definition

#define FC_TASK_OC_TRAN_STR	0x01	Start sending
#define FC_TASK_OC_ADD	0x03	Add mission to queue
#define FC_TASK_OC_READ	0x04	Read mission on queue
#define FC_TASK_OC_START	0x05	Execute mission from the assigned location
#define FC_TASK_OC_STOP	0x06	Stop the current mission immediately
#define FC_TASK_OC_ERROR	0xfb	Error Message
#define FC_TASK_OC_ACK	0xfc	Acknowledge
#define FC_TASK_OC_ACTION	0xfd	Execute the received mission immediately
#define FC_TASK_OC_CLEAR	0xfe	Clear mission queue
#define FC_TASK_OC_TRAN_END	0xff	Sending ends

Mission Type (TASK.TYPE) Definition

#define FC_TSK_Null	0	/
#define FC_TSK_TakeOff	1	Take Off
#define FC_TSK_Land	2	Land
#define FC_TSK_RTH	3	Return to Home
#define FC_TSK_SetHome	4	Set Home Point
#define FC_TSK_SetPOI	5	Set Point-of-Interest
#define FC_TSK_DelPOI	6	Delete Point-of Interest
#define FC_TSK_MOVE	7	Control Movement in 3D
#define FC_TSK_Gimbal	8	Control Gimbal Angle
#define FC_TSK_SetEXTIO	9	Control External IO (Payload Release, arm lights, strobe light)
#define FC_TSK_WayPoint	10	Add Waypoint
#define FC_TSK_SetSpeed	11	Set Flight Speed
#define FC_TSK_SetALT	12	Set Flight Altitude
#define FC_TSK_WAIT_MS	15	Set Hover Time
#define FC_TSK_REPLAY	16	Set Times of Repetition
#define FC_TSK_CAMERA	17	Control Camera
#define FC_TSK_RESERVE	18	Reserve
#define FC_TSK_CIRCLE	19	Orbit Flight

Acknowledge Packet

After receiving each message from the source device, Flight Control will send an acknowledge packet to the source device to acknowledge the message. The packet includes opcode FC_TASK_OC_ACK, mission ID, and other information. The source device needs to use the acknowledge packet to check if each message is sent successfully.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	xxx	N byte	1 byte

SRC - The device sends the acknowledge packet

DEST - The device which sends the message.

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_ACK
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	Mission type
3-6	(UINT32) CODE	The return mission data

 

Send Mission to the Aircraft

If you want the aircraft to execute the mission immediately, send the Opcode FC_TASK_OC_ACTION to execute the mission.

If you want to use the mission queue:

1. Send opcode FC_TASK_OC_CLEAR to Flight Control.
2. Flight Control clear the mission queue and return opcode FC_TASK_OC_ACK.
3. Send opcode FC_TASK_OC_TRAN_STR to start sending the mission.
4. Flight Control return FC_TASK_OC_ACK to confirm the sending.
5. Use opcode FC_TASK_OC_ADD to add the mission to the mission queue.
6. Each time Flight Control receive the mission, it will return opcode FC_TASK_OC_ACK to confirm the sending is successful.
7. When sending is completed, send opcode FC_TASK_OC_TRAN_END to end the mission sending.
8. Flight Control return FC_TASK_OC_ACK to confirm the sending is completed.

Clear Mission Queue

Using the opcode FC_TASK_OC_CLEAR will clear all the mission in the mission queue and stop the current mission.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_CLEAR
1	TASK.ID (1 byte)	0x00

 

End the Sending to Mission Queue

When sending is completed, send opcode FC_TASK_OC_TRAN_END to end the mission sending.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_TRAN_END
1	TASK.ID (1 byte)	0xFF

 

Execute Mission

After sending the mission to Flight Control, send opcode FC_TASK_OC_START to command Flight Control to execute the mission. Flight Control return acknowledge packet and start executing the mission.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_START
1	TASK.ID (1 byte)	Mission ID

TASK.ID = 0xff indicates Flight Control executes the mission from the previous stopping location.

TASK.ID = 0x00 indicates Flight Control executes the mission from the first one.

Stop Execution

After the mission is executed, at any time, send opcode FC_TASK_OC_STOP to stop the current execution and put the aircraft to hover. Flight Control return acknowledge packet and confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_STOP
1	TASK.ID (1 byte)	0x00

 

Aircraft Basic Control

Here is how to use the mission control system to proceed with aircraft basic control.

Take off

Send mission FC_TSK_TakeOff to unlock and take off the aircraft to the designated altitude. Flight Control return acknowledge packet to confirm receiving the command.

If the designated altitude is set < 50 cm, the aircraft only unlocks and does not take off.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	FC_TSK_TakeOff
3-4	ALTITUDE (2 byte)	Take-off altitude: 0 - 65535 cm

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

Land

Send mission FC_TSK_Land, the aircraft will land in the current position and then lock the motors. Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	FC_TSK_Land

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

Return-to-Home

Send mission FC_TSK_RTH, the aircraft will proceed to return to home point. Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	FC_TSK_RTH

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

Set the Home Point

Send mission FC_TSK_SetHome to reset the home point. (Default home point is the take-off location) Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	FC_TSK_SetHome
3-6	LATITUDE (4 byte)	Latitude: ± 1800000000
7-10	LONGITUDE (4 byte)	Longitude: ± 1800000000

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

Set Point-of-interest (POI)

⌛ Point-of-interest (POI) is currently not supported. It will be coming in the future firmware updates.

Send mission FC_TSK_SetPOI to set a point of interest to let the aircraft head always point to the POI. Moving the control stick will disengage the POI command. Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	FC_TSK_SetPOI
3-6	LATITUDE (4 byte)	Latitude: ± 1800000000
7-10	LONGITUDE (4 byte)	Longitude: ± 1800000000

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

Delete Point-of-interest (POI)

Send mission FC_TSK_DelPOI to delete the point of interest. The aircraft head will stop locking to POI direction. Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Type	Description
0	OPCODE (1 byte)	BYTE	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	BYTE	Mission ID
2	TASK.TYPE (1 byte)	BYTE	FC_TSK_DelPOI

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

 

Aircraft Movement in 3D

Send mission FC_TSK_MOVE to command the aircraft to execute the movement in three dimensions. Send the parameter in 3 dimensions, the aircraft will move to the set 3D parameters relative the hover point. Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message.

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Type	Description
0	OPCODE (1 byte)	BYTE	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	BYTE	Mission ID
2	TASK.TYPE (1 byte)	BYTE	FC_TSK_MOVE
3-4	X (2 byte)	INT16	Front and back dimension relative to the aircraft: ± 32767 cm
5-6	Y (2 byte)	INT16	Left and right dimension relative to the aircraft: ± 32767 cm
7-8	Z (2 byte)	INT16	Up and down dimension relative to the aircraft: ± 32767 cm
9	HSPEED (1 byte)	BYTE	Horizontal flight speed: 0 -250 = 0 -25 m/s
10	VSPEED (1 byte)	SBYTE	Vertical flight speed: ± 40 = ± 4.0 m/s

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

 

Gimbal and External Device Control

Set the designated mission to the Flight Control to control gimbal angle, payload release, and aircraft LED light. You can also combine the gimbal and external device control with the aircraft flight control to perform a series of auto operations. For example, let the aircraft fly to a certain location to drop the attached payload.

Gimbal Position Broadcast

Gimbal will broadcast its position periodically to inform the tilt/pan/roll angle of the gimbal. Receive the gimbal position broadcast message will get the information.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x30	0x01	0xff	N byte	1 byte

SRC - Flight Control

DEST - Broadcast

Data structure in PAYLOAD

Byte index	Symbol	Type	Description
0	IDX (1 byte)	BYTE	0x07 (fixed value)
1-4	ROLL (4 byte)	FLOAT	Gimbal tilt angle: ±90°
5-8	PITCH (4 byte)	FLOAT	Gimbal roll angle: ±45°
9-12	YAW (4 byte)	FLOAT	Gimbal pan angle: ±45°

 

Gimbal Control

Send mission FC_TSK_SetGimbal to set the gimbal angle.

Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x03	N byte	1 byte

SRC - The device which sends the message

DEST - Gimbal

Data structure in PAYLOAD

Byte index	Symbol	Type	Description
0	OPCODE (1 byte)	BYTE	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	BYTE	Mission ID
2	TASK.TYPE (1 byte)	BYTE	FC_TSK_SetGimbal
3-4	PITCH (2 byte)	FLOAT	Gimbal tilt angle: ±90°
5-6	ROLL (2 byte)	FLOAT	Gimbal roll angle: ±45°
7-8	YAW (2 byte)	FLOAT	Gimbal pan angle: ±45°

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

Payload Release and Lights Control

Send FC_TSK_SetEXTIO to turn ON/OFF the payload release, arm lights, and strobe light.

Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	FC_TSK_SetEXTIO
3-6	IO_SELECT (4 byte)	Select the IO to operate
7-10	ON_OFF (2 byte)	Set 1 to turn ON the selected IO, 0 to turn OFF

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

Use IO_SELECT to select the IO for operation, and set the according BIT for the IO to 1 to select the IO. You can select a total of 32 IO at max.

BIT0	Payload Release #1	BIT4	Strobe Light
BIT1	Payload Release #2 (Not in use)	BIT5	Arm Lights
BIT2		BIT6
BIT3		BIT7

 

Waypoint Mission

Waypoint mission is an autonomous flight operation. It sets the aircraft to fly to the set locations autonomously and allows for repetitive operations.

To use the waypoint mission, you must set the flight speed, altitude, and the set of locations.

Flight Speed Setting

Send FC_TSK_SetSpeed to set the flight speed. If flight speed hasn’t been set for the waypoint mission, the aircraft is going to fly at the default speed of 6m/s or at the speed set previously.

Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	FC_TSK_SetSpeed
3-4	SPEED (2 byte)	Flight Speed: 0-65535 = 0-655.35 m/s.

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

Altitude Setting

Send FC_TSK_SetALT to set flight altitude. If flight altitude hasn’t been set for the waypoint mission, the aircraft is going to fly at the current altitude.

Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	FC_TSK_SetALT
3-4	ALTITUDE (2 byte)	Flight Altitude: 0-65535 = 0-655.35 meter (relative to take-off altitude)

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

Add Waypoint

Send FC_TSK_WayPoint to add a waypoint to the waypoint mission.

To use the waypoint mission, you must set flight speed and flight altitude.

Flight Control return acknowledge packet to confirm receiving the command.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x34	xxx	0x01	N byte	1 byte

SRC - The device which sends the message

DEST - Flight Control

Data structure in PAYLOAD

Byte index	Symbol	Description
0	OPCODE (1 byte)	Mission opcode: FC_TASK_OC_ADD or FC_TASK_OC_ACTION
1	TASK.ID (1 byte)	Mission ID
2	TASK.TYPE (1 byte)	FC_TSK_WayPoint
3-4	HoverTime (2 byte)	Hover time for the waypoint: 0-65535 second
5-8	LATITUDE(4 byte)	Latitude: ± 1800000000
9-12	LONGITUDE(4 byte)	Longitude: ± 1800000000

If hover time is set to 0, the aircraft is going to fly to the next waypoint without slowing down.

If hover time is not set to 0, the aircraft is going to hover at the waypoint for the set time and then fly to the next waypoint.

If the opcode is FC_TASK_OC_ACTION, the mission will be executed immediately.

 

Send Waypoint Mission to Aircraft

To send waypoint mission to the aircraft, refer to Send Mission to the Aircraft.

To execute or stop the execution, refer to Execute Mission/Stop Execution.

 

Waypoint Mission Status Report

Aircraft will report flight status periodically during the waypoint mission. One can get aircraft flight status by receiving and parsing the Flight Status Report message.

Packet Format

START FLAG	PackLength	MSGID	SRC	DEST	PAYLOAD	CHECKSUM
0xa6	1 byte	0x31	0x01	0xff	N byte	1 byte

SRC - Flight Control

DEST - Report

Data structure in PAYLOAD

Byte Index	Symbol	Length	Description
0	FLY_STAT_NAV	1 byte	0x02 (fixed value)
1-N	Struct WP_NAV_STATE	Sizeof(WP_NAV_STATE)	Flight Status Report