Custom packets
This page documents the custom packets used by the Skybrush firmware to transmit drone show related status information to the ground station in a compact fashion.
Most of the custom packets used by the firmware are embedded in a MAVLink
DATA16, DATA32, DATA64 or DATA96 message. These packets are used
interchangeably; feel free to use the packet which fits the size of the payload
that you are trying to send as both the firmware and the ground station will
have a common handler registered to all of these packets. From now on, we will
refer to these as DATA packets and the appropriate size of the packet is
implied.
Some MAVLink packets with unspecified semantics (such as LED_CONTROL) are
also used by the Skybrush firmware in a specific manner. These will also be
documented here.
Multi-byte values are in little-endian order unless specified otherwise.
Drone to GCS
DATA packets sent from the drone to the ground station have their type field
set to 0x5b or 0x5d. Type 0x5b is a standard status packet. For packets
with type 0x5d, the real type of the packet is encoded in the first
byte of the payload.
Drone show status
This packet is used to convey status information related to the drone show
context to the ground station. It is meant to be used in conjunction with
standard MAVLink HEARTBEAT, GLOBAL_POSITION_INT, GPS_RAW_INT and
SYS_STATUS packets.
The packet is a MAVLink DATA16 packet with the type set to 0x5b. The
structure of the payload is as follows:
where:
- Start time
-
The scheduled start time of the show in GPS time-of-week, in seconds, encoded as a 32-bit signed integer; -1 if the start time is not set on the drone yet.
- Color
-
The current color of the LED of the drone, in RGB565 encoding (i.e. 5 bits for the red channel, 6 bits for the green channel, 5 bits for the blue channel), encoded as a 16-bit unsigned integer.
- Flags
-
See below.
- Flags 2
-
See below.
- GPS
-
Most significant 5 bits: number of GPS satellites seen by the drone, capped at 31. Least significant 3 bits: GPS fix status (0 = no GPS connected, 1 = no fix, 2 = 2D fix, 3 = 3D fix, 4 = DGPS, 5 = RTK float, 6 = RTK fixed, 7 = surveyed station).
- Flags 3
-
See below.
- Elapsed time
-
Number of seconds elapsed since the start of the show (negative if waiting for the start time of the show), in seconds, encoded as a 16-bit signed integer.
- RTCM counters
-
Number of RTCM messages received in the last five seconds by the drone plus one, encoded as 8-bit unsigned integers per RTCM channel (first byte: primary channel, second byte: backup channel). Zero means that no RTCM messages have been observed on the telemetry channel since boot.
The flags in the Flags, Flags 2 and Flags 3 bytes have a convoluted encoding due to backward compatibility purposes. From LSB to MSB, the individual bits in Flags are as follows:
-
Fence breached
-
Drone uses GPS time to start the show and the start time is not valid yet
-
Authorization granted (0 = not granted, 1 = granted; superseded by authorization scopes in Flags 3).
-
Fence enabled
-
Show orientation set
-
Show origin set
-
Scheduled start time set
-
Show data loaded successfully
From LSB to MSB, the individual bits in Flags 2 are as follows:
-
Current show execution stage (4 bits, 0 = off, 1 = initializing, 2 = waiting for start time, 3 = taking off, 4 = performing, 5 = returning to launch site, 6 = position hold, 7 = landing, 8 = landed, 9 = error, 10 = testing lights)
-
Next 3 bits unspecified, must be set to 0.
-
MSB is set to 1 if the drone is not at its expected takeoff position, 0 otherwise.
From LSB to MSB, the individual bits in Flags 3 are as follows:
-
Boot count modulo 4, in 2 bits.
-
Authorization scope, in 2 bits.
-
Next 3 bits reserved, must be set to 0.
-
MSB is set to 1 if the drone drifted from its expected position, 0 otherwise.
GCS to drone
DATA packets sent from the ground station to the drone have their type field
set to 0x5c. The real type of the packet is encoded in the first byte of the
payload.
LED control packet
LED control commands are conveyed in MAVLink LED_CONTROL messages where the
instance and the pattern fields are both set to decimal 42. The payload of
the message contains the command itself.
The general semantics of the message is primarily decided by the length of the payload.
- Payload of length 0
-
Instructs the drone to flash its LED five times to attract attention.
- Payload of length 1
-
Instructs the drone to flash its LED five times to attract attention if its configured group (in the
SHOW_GROUPparameter) matches the group mask in the first byte of the payload. Bit 0 (LSB) of the payload belongs to group 0, bit 1 belongs to group 1 and so on. - Payload of length 3
-
Set the LED to a specific color for 5 seconds. the desired color is encoded in the payload in RGB order (one byte per channel).
- Payload of length 5
-
Set the LED to a specific color for a given duration. The desired color is encoded in the payload in RGB order (one byte per channel) in the first three bytes, followed by a 16-bit duration in milliseconds as an unsigned integer.
- Payload of length 6
-
Same as a payload of length 5, extended by a byte that encodes an effect with which the light intensity will be modulated (0 = off, 1 = solid, 2 = blinking, 3 = "breathing", i.e. slowly fading in and out).
- Payload of length 7
-
Same as a payload of length 6, extended by a group mask. The drone will execute the command if its configured group (in the
SHOW_GROUPparameter) matches the group mask.
Start time configuration
Implemented with a DATA packet with the type set to 0x5c and the first byte
of the payload set to 0x01.
where:
- Start time
-
Start time to set on the drone, in GPS time of week (sec), encoded as a 32-bit signed integer. Anything larger than 604799 means not to touch the start time that is currently set. Negative number means that the start time must be cleared.
- Auth
-
The authorization scope. TODO: explain this!
- Countdown
-
Number of milliseconds left until the start of the show, used to implement starting the show with a countdown, encoded as a 32-bit signed integer. Positive numbers mean that there is still some time left until the start of the show. The
SHOW_SYNC_MODEparameter must be set to 1 for this argument to take effect, otherwise it is ignored by the drone.
Collective return to launch
Implemented with a DATA packet with the type set to 0x5c and the first byte
of the payload set to 0x02.
The next two bytes of the payload encode the start time of the collective return-to-launch (RTL) operation, in seconds since the start of the show, encoded as a 16-bit unsigned integer. Zero is a special value, it clears any scheduled collective RTL for the future if the drone has not started the operation yet.
This packet is currently unused as the corresponding feature has not been tested thoroughly yet.