Data types used in messages

This section describes the complex data types and structures that are used in Flockwave messages. These data types will be referenced later from the Known message types section.

Timestamps

Timestamps MUST always be expressed as the number of milliseconds elapsed since the Unix epoch (1970-01-01 00:00:00 UTC). Note that this means that timestamps expressed in local time MUST be converted to UTC before expressing them as milliseconds.

Dates and times as strings

The preferred date and time format of Flockwave

Dates, times and durations MUST always be expressed in UTC using an appropriate ISO 8601 format (see also RFC 3339, especially section 5.6 if you don’t like paywalls). Unless stated otherwise, the following formats should be used:

  • Dates should be expressed as YYYY-MM-DD (ISO 8601 extended format).

  • Times should be expressed as HH:mm:ss.sss (ISO 8601 extended format). The millisecond part may be omitted if not relevant.

  • Dates and times should be expressed as the date, followed by a literal T, followed by the time, followed by Z, where the T is the standard ISO 8601 separator between dates and times, and Z is the ISO 8601 marker for UTC (Zulu time).

Angles

Angles are always expressed in degrees because radians are for mathematicians. Depending on the context, angles may either be expressed in the half-open interval [0, 360), or in the half-open interval [-180, 180) or [-90, 90). For instance, latitudes, longitudes, roll and pitch are naturally expressed in an interval centered around zero, while heading and yaw information is typically presented as a non-negative number. When in doubt, look at the formal JSON schema specification for the allowed range of an angle.

Even though it is common in aviation to indicate 360 degrees instead of zero degree, we always transmit zero degree instead of 360 degrees in messages because it comes naturally from the way computers handle modulo arithmetics. The user interface may still opt to present zero degree as 360 degrees if the user prefers that.

However, when encoding an angle, it is first quantized in 1/10th of degrees and then encoded as a signed or unsigned integer in order to avoid floating point related inaccuracies and the accumulation of quantization errors (see discussion about floating-point inacccuracies). Therefore, the typical range of angles is [0, 3600) or [-1800, 1800), both of which are well versed to fit in a 16-bit integer.

Byte arrays

The JSON format does not support the transmission of raw byte arrays directly since the JSON string type is a sequence of Unicode characters and not a sequence of raw bytes. When a raw byte array has to be transmitted in JSON, the typical solution is to send a base64-encoded representation as a string (see RFC4648). This representation is approximately 33% longer than the corresponding raw byte array, but is still much shorter than the representation of the byte array as a JSON array of integers.

Temperatures

Temperatures are always expressed in kelvin because we do not want to take sides in the Celsius vs Fahrenheit debate. However, when encoding a temperature, it is first quantized in 1/10th of degrees kelvin and then encoded as an unsigned integer in order to avoid floating point related inaccuracies (see discussion about floating-point inacccuracies).

AntennaInformation

The AntennaInformation object holds information about the current RTK antenna.

Fields

Name Required? Type Description

stationId

no

integer

The station ID of the antenna, or null if not known

descriptor

no

string

The antenna descriptor, or null if not known

serialNumber

no

string

The serial number of the antenna, or null if not known

position

no

GPSCoordinate

The position of the RTK antenna, in GPS coordinates, or null if not known

positionECEF

no

ECEFCoordinate

The position of the RTK antenna, in ECEF coordinates, or null if not known

Example

{
    "stationId": "100",
    "descriptor": "ADVNULLANTENNA",
    "serialNumber": "12345678",
    "position": [519976597, -7406863, 93765],
    "positionECEF": [4120339623, 1418747456, 4641838123]
}

Attitude

An Attitude object describes the orientation of a UAV using the standard roll, pitch and yaw angles. See the section about angles for more information about how the angles are expressed.

The object is stored as a list with three mandatory items.

Items

Index Required? Type Description

0

yes

angle

the roll angle in 1/10th of degrees, in the range [-1800, 1800)

1

yes

angle

the pitch angle in 1/10th of degrees, in the range [-1800, 1800)

2

yes

angle

the yaw angle in 1/10th of degrees, in the range [0, 3600)

Example

[0, 0, 900]

BatteryInfo

A BatteryInfo object holds information about the state of an on-board battery on a UAV.

The object is stored as a list with one mandatory and two optional items.

Items

Index Required? Type Description

0

yes

integer

the battery voltage in one tenths of volts; zero if unknown

1

no

integer

the state-of-charge of the battery, expressed as a percentage in the range [0, 100]; omitted or negative if unknown

2

no

boolean

whether the battery is charging; defaults to false if omitted

Example

[124, 100, false]

BeaconBasicProperties

Monolithic object containing basic information about a single beacon that is unlikely to change over time.

Fields

Name Required? Type Description

id

yes

string

The unique identifier of the beacon

name

yes

string

The human-readable name of the beacon

Example

{
    "id": "base",
    "name": "Main base"
}

BeaconStatusInfo

Monolithic object containing general status information about a single beacon.

Fields

Name Required? Type Description

id

yes

string

The unique identifier of the beacon

position

no

GPSCoordinate

The position of the beacon

heading

no

angle

The heading of the UAV, i.e. the direction the UAV is pointing, projected to the local tangent plane, if known.

active

no

boolean

Whether the beacon is active (operational). May be omitted for passive beacons or points of interest.

timestamp

yes

timestamp

Time when the last status update was received from the beacon

Example

{
    "id": "base",
    "position": [519976597, -7406863, 93765],
    "timestamp": 1449562661000,
    "heading": 290,
    "active": true
}

ChannelOperation

Enumeration type that describes the possible operations that may be performed on a channel of a device (real or virtual) on a UAV. See Objects, devices and channels for more information. Currently the following values are defined:

read

Represents the act of reading the current value of the channel.

write

Represents the act of writing a new value to the channel.

ChannelType

Enumeration type that describes the possible types of channels of a device (real or virtual) on a UAV. See UAV devices and channels for more information. Currently the following values are defined:

audio

A channel that provides a URL to an audio stream.

boolean

A channel that provides a single Boolean value

bytes

A channel that provides an array of raw bytes.

color

A channel that provides a color in 8-bit RGB, RGBA or RGBW format. The color is typically expressed as an array of three or four bytes, each byte ranging from 0 to 255.

duration

A channel that provides the duration of a time window, expressed as the number of seconds elapsed since the start of the time window. Fractional seconds are allowed.

number

A channel that provides a single double-precision floating-point number.

object

A channel that provides a complex JSON object.

string

A channel that provides a UTF-8 encoded string.

time

A channel that provides a time instant, expressed as the number of seconds elapsed since the UNIX epoch in UTC. Fractional seconds are allowed.

video

A channel that provides a URL to a video stream.

ClockEpoch

A ClockEpoch object describes the epoch of a clock or timer that the Flockwave server manages. It is either a datetime string or one of the following string values:

unix

The UNIX epoch, i.e. midnight on 1 Jan 1970 UTC.

ClockInfo

A ClockInfo object describes the current state of a clock or timer that the Flockwave server manages (e.g., a clock that reports the local time, the GPS time or a MIDI timecode coming from an external MIDI device connected to the server).

Fields

Name Required? Type Description

id

yes

string

the unique identifier of the clock

epoch

no

ClockEpoch

the epoch from which the current timestamp of the clock is to be measured, if that makes sense for the clock. When the epoch is omitted, the clock is assumed to be ticking since an unspecified instant in the past.

retrievedAt

yes

timestamp

the time according to the internal clock server when the state of the clock was retrieved. If the internal clock of the server and the client is synchronized, this can be used by the client to compensate for the time it takes for the server to transmit the clock status message to the client.

running

yes

boolean

whether the clock is running at the moment

ticksPerSecond

no

float

the number of clock ticks per second. Must be larger than zero. When omitted, it is assumed to be equal to 1.

ticks

yes

float

the number of ticks that have elapsed on the clock

Example

{
    "id": "mtc",
    "ticks": 4221,
    "retrievedAt": 1462890801000,
    "ticksPerSecond": 30,
    "running": true
}

ColorRGB565

A ColorRGB565 object is essentially a single integer in the range 0 to 65535 such that the most significant 5 bits encode the red component of an RGB color, the least significant 5 bits encode the blue component, and the remaining 6 bits in the middle encode the green component. This data type is used when some color information has to be transmitted in a way that does not occupy too much space in the message, assuming that the exact color is not too important as there is some quantization error when converting a 24-bit RGB color into RGB565 representation.

CommandExecutionStatus

A CommandExecutionStatus object describes the execution status of a command that was relayed from a client to a UAV by the server.

Fields

Name Required? Type Description

sent

yes

timestamp

time when the command request was sent to the UAV

acknowledged

no

timestamp

time when the UAV acknowledged the receipt of the request (explicitly or implicitly, i.e. by sending a status update or a response)

updated

no

timestamp

time when the UAV updated the progress of the request (explicitly or implicitly, i.e. by sending the completed response)

finished

no

timestamp

time when the final response was fully received by the server

progress

no

float

the progress of the execution of the command, expressed as an integer value between 0 and 100 (inclusive)

status

no

string

optional status text message

Example

{
    "sent": 1459670842000,
    "acknowledged": 1459670842471,
    "updated": 1459670842811,
    "progress": 80,
    "status": "Almost ready :)"
}

CommandResponse

A CommandResponse object stores the response given by a particular UAV to a command sent to it using an OBJ-CMD request, along with a type annotation that tells the receiver how the response should be interpreted.

Currently the protocol defines the following response types:

plain

Plain text response that should be formatted on the receiver side as is. The receiver side is allowed to use a variable-width font and it can also perform additional formatting or word wrapping on the text if needed.

preformatted

Preformatted response that should be printed on the receiver end with a fixed-width font. Newlines and tabulation should also be preserved on the receiver end if possible.

markdown

Markdown-formatted text response that should be interpreted by a Markdown processor before it is displayed to the user.

Additional response types may be defined by the user as needed.

Example

{
    "type": "markdown",
    "data": "# Heading\n\nHello world!"
}

ConnectionInfo

A ConnectionInfo object describes the purpose and current state of a connection that the Flockwave server manages (e.g., a radio link or a DGPS stream).

Fields

Name Required? Type Description

id

yes

string

the unique identifier of the connection

purpose

yes

ConnectionPurpose

the purpose of the connection (i.e. what sort of data it provides)

description

no

string

human-readable description of the connection

status

yes

ConnectionStatus

the current status of the connection

timestamp

no

timestamp

time when the last packet was received from the connection, or if it is not available, the time when the connection changed status the last time

Example

{
    "id": "xbee",
    "purpose": "uavRadioLink",
    "description": "Upstream XBee radio link",
    "status": "connected",
    "timestamp": 1449562061000
}

ConnectionPurpose

Enumeration type that describes the purpose of a connection. Currently the following values are defined:

debug

A connection that is meant for debugging purposes only.

dgps

A connection whose purpose is to receive DGPS or RTK correction packets from an external stream (e.g., an NTRIP data source or a serial link to an RTK base station).

dock

A connection that provides information about the status of a docking station.

gps

A connection that receives data from a GPS device.

mocap

A connection to a motion capture system.

time

A connection whose purpose is to connect to a service or device that provides time-related information. Examples are connections to an NTP server or a MIDI timecode provider.

uavRadioLink

A connection whose purpose is to receive status information from UAVs and/or send commands to them.

other

A connection whose purpose does not fit into the above categories. It is advised to use a human-readable description for these connections.

ConnectionStatus

Enumeration type that describes the possible states of a connection. A connection may be in exactly one of the following five states at any time:

disconnected

The connection is not alive and no connection attempt is currently in progress.

connecting

The connection is not alive yet, but a connection or reconnection attempt is currently in progress.

connected

The connection is alive.

disconnecting

The connection is not alive any more, but it has not been properly shut down yet.

unknown

The status of the connection is unknown (typically because we have received no status information from the connection yet).

The value of a field of type ConnectionStatus is always a string with one of the five values above.

DeviceClass

Enumeration type that describes the possible classes (i.e. types) of devices in a device tree. Device classes may be used by user interfaces talking to a Flockwave server to provide some feedback to the user about the type of a device (e.g., it could show batteries with a different icon). Currently the following values are registered:

accelerometer

The device is an accelerometer.

actuator

The device is a generic actuator that cannot be categorised more precisely into any of the other classes.

altimeter

The device is an altimeter (e.g., pressure sensor, radar altimeter, sonic altimeter).

battery

The device is a battery.

camera

The device is a camera (consumer-grade, infrared, security camera or anything else).

cpu

The device is the CPU on the UAV (or on its companion computer).

cpuCore

The device is one particular CPU core of the CPU of a UAV.

gps

The device is a GPS receiver.

group

The device represents a logical grouping of other devices. For instance, the rotors of a UAV may be grouped in a rotor group.

gyroscope

The device is a gyroscope.

led

The device is a single LED or a LED strip.

magnetometer

The device is a magnetometer.

microphone

The device is a microphone.

misc

The device does not fall into any of the predefined device classes.

pyro

The device is a pyrotechnic device (e.g., firework launcher board).

radio

The device is a radio receiver or transmitter (e.g., an XBee radio).

rc

The device is an RC receiver.

rotor

The device is a rotor.

sensor

The device is a generic sensor that cannot be categorised more precisely into any of the other classes.

speaker

The device is a speaker.

DeviceTreeNode

This type represents a single node of the device tree. The node may represent a UAV or any other top-level object that has a unique ID, an onboard (real or virtual) device of an object, or a channel of a device. (See Objects, devices and channels for more details).

Fields

Name Required? Type Description

type

yes

DeviceTreeNodeType

The type of the node

subType

no

ChannelType

The type of the channel if the node is a channel node. This field is required for channel nodes and forbidden for other types of nodes.

class

no

DeviceClass

The type of the device that this node represents. This field is optional for device nodes and forbidden for other types of nodes. Its value may be used by Flockwave clients to represent the device in a different way on the UI or to hide certain types of devices.

children

no

object of DeviceTreeNode

Object mapping names of child nodes to their descriptions

operations

no

list of ChannelOperation

The list of operations supported by the channel. This field is required for channel nodes and forbidden for other types of nodes.

unit

no

string

The unit in which the value of the channel is represented. This field is optional for channel nodes (typically makes sense for numeric channels) and forbidden for other types of nodes.

DeviceTreeNodeType

Enumeration type that describes the type of a device tree node (see DeviceTreeNode. Currently the following values are defined:

root

This is the root node of the device tree. The node has no parent by definition. The children of the root node must be nodes of type object.

object

This is a tree node that represents an object that is identified by its ID in the server. The parent of an object node is always a root node. The children of the object nodes must be nodes of type device.

device

This is a tree node that represents a device of an object, or a sub-device of another device. The parent of a device node is either a uav node or another device node.

channel

This is a tree node that represents a channel of a device. The parent of a channel node is always a device node.

DockStatusInfo

Monolithic object containing general status information about a single docking station.

Fields

Name Required? Type Description

id

yes

string

The unique identifier of the docking station

position

no

GPSCoordinate

The position of the docking station

timestamp

yes

timestamp

Time when the last status update was received from the docking station

Example

{
    "id": "base",
    "position": [519976597, -7406863, 93765],
    "timestamp": 1449562661000
}

DroneLightsConfiguration

LED light related configuration object for drone shows. The object is used by the SHOW-LIGHTS and the SHOW-SETLIGHTS commands to get or set the configuration for the LED lights on drones.

Fields

Name Required? Type Description

effect

no

string

Type of the light effect. Can be either off (GCS is not controlling the LED lights on the drones) or solid (GCS is asking the drones to use a solid LED light).

color

no

list of integers

Color of the light effect in RGB notations. Values in the array must be between 0 and 255, inclusive.

Example

{
    "effect": "solid",
    "color": [0, 18, 255],
}

DroneShowConfiguration

Configuration object for the drone show. It is used by the SHOW-CFG and the SHOW-SETCFG commands to get or set the configuration for the drone show.

Fields

Name Required? Type Description

start

no

StartConditions

Object that contains the conditions regarding the start of the show

mapping

no

list of strings

Mapping of show-specific indices to the corresponding UAV IDs, if known. Not mandatory.

duration

no

float

The total duration of the show, in seconds. Not mandatory.

Example

{
    "start": {
        "authorized": false,
        "time": 1581881192,
        "method": "auto",
        "uavIds": ["01", "42"]
    },
    "mapping": ["01", "02", null, "05", "42"],
    "duration": 294
}

ECEFCoordinate

This type represents a coordinate given by a GPS in the Earth-centered, Earth-fixed coordinate frame, where:

  • The origin is the center of mass of the Earth.

  • The X axis is in the plane of the equator, passing through the origin and extending from 180° longitude (negative) to the prime meridian (positive);

  • The Y axis is also in the plane of the equator, passing through extending from 90°W longitude (negative) to 90°E longitude (positive)

  • The Z axis is the line between the North and South Poles, with positive values increasing northward.

All three coordinates (X, Y, and Z) are stored in millimeters.

The object is stored as a list with three items.

Items

Index Required? Type Description

0

yes

float

The X coordinate in millimeters

1

yes

float

The Y coordinate in millimeters

2

yes

float

The Z coordinate in millimeters

Example

[4120339, 1418747, 4641838]

ErrorList

This type is simply an array of numbers, where each number represents a possible error condition. See Error codes for a detailed listing of all the error codes that are currently defined in the Flockwave protocol.

ExtensionInfo

This type contains detailed information about an extension. It is used by the server’s response to the EXT-INF client request.

Fields

Name Required? Type Description

id

yes

string

Identifier of a single extension.

loaded

yes

boolean

Identifies whether the extension is loaded or not.

name

yes

string

The name of the extension.

description

no

string

Description of the extension.

Example

{
    "id": "ssdp",
    "loaded": true,
    "name": "Simple Service Discovery Protocol",
    "description" : "Used for advertisement and discovery of network services."
}

FlightMode

Enumeration type that describes the typical flight modes of a UAV. The list of values presented here are not exhaustive; UAVs may use additional flight mode constants if none of the modes below are suitable to describe the flight mode. Currently the following values have pre-defined meanings, mostly modelled after the common flight modes in ArduPilot:

acro

Acro mode; the pilot is controlling the attitude of the UAV directly and there is no self-leveling.

alt

Altitude hold mode; in the absence of any input, the UAV attempts to hold its altitude and self-levels the roll and pitch angles.

auto

Automatic mode; the UAV is executing an unspecified autonomous control algorithm that requires no human intervention.

circle

The UAV is circling around a pre-defined point of interest.

flow

The UAV is attempting to hold its position using an optical flow sensor.

follow

The UAV is following another device.

guided

The UAV is controlled by an external companion computer.

land

The UAV is attempting an unsupervised landing.

loiter

The UAV holds its altitude and position, using GPS for movements. The pilot controls the velocities along the axes.

mission

The UAV is following a preprogrammed mission.

other

The UAV is in a control mode that cannot be covered by any of the modes outlined here.

pos

The UAV holds its altitude and position, using GPS for movements. THe pilot controls the roll and pitch angles when the sticks are not centered.

precland

The UAV is executing a precision landing maneuver, typically aided by an external beacon, sensor or other guidance method.

rth

The UAV is returning to its home position autonomously, optinally landing when the home position is reached.

simple

The UAV is in a simplified control mode.

stab

Stabilization mode; roll and pitch axes are self-leveled, but the altitude is not controlled.

takeoff

The UAV is executing an autonomous takeoff algorithm.

unknown

The UAV is in an unknown control mode.

FirmwareUpdateTarget

This type represents an abstract component (sofrware or hardware) of an object that can be targeted with a firmware update operation. Firmware update targets can be registered and unregistered in the server and each object can report the list of firmware targets that it supports. An object may have multiple firmware update targets or may have none; for instance, a UAV consisting of an autopilot and a telemetry module can provide two firmware update targets if the firmware can be updated on both components remotely.

The firmware of a component of an object may be updated by sending a firmware update request to the server, indicating the object, the firmware update target and the firmware itself; the server will then take care of orchestrating the replacement of the firmware on the object.

Items

Name Required? Type Description

id

yes

string

The unique identifier of the firmware update target

name

yes

string

A human-readable name of the firmware update target

Example

{
    "id": "io.skybrush.server.virtual_uav.firmware",
    "name": "Firmware for virtual UAVs"
}

GPSCoordinate

This type represents a coordinate given by a GPS in the usual "latitude, longitude, altitude above mean sea level" format using the WGS84 reference system. Additionally, it supports the storage of corresponding relative altitudes, namely, "altitude above home" and "altitude above ground".

Latitude and longitude should be specified with at least seven digits' precision if possible. (More than seven digits is usually not necessary because consumer GPS receivers are not that accurate). To avoid floating point inaccuracies, latitudes and longitudes are stored in 10-7 degrees, and all altitudes are stored in millimeters as integers.

The object is stored as a list with five items. The third, fourth and fifth items (AMSL, AHL and AGL, respectively) may be null if they are not known. Trailing nulls may be omitted.

Items

Index Required? Type Description

0

yes

integer

The latitude, in 10-7 degrees, in the range [-90 × 107, 90 × 107)

1

yes

integer

The longitude, in 10-7 degrees, in the range [-180 × 107,180 × 107)

2

no

integer

The altitude, in millimeters, above mean sea level

3

no

integer

The altitude, in millimeters, above home level

4

no

integer

The altitude, in millimeters, above ground level

Example

[519976597, -7406863, 93765]

GPSFix

This type represents a short summary of the current GPS fix achieved by a UAV. The value is a list consisting of one or more (up to four) items. The first item of the list represents the type of the GPS fix according to the following table:

Value Description

0

The UAV does not have a GPS.

1

The UAV has a GPS but there is no GPS fix yet.

2

2D GPS fix.

3

3D GPS fix.

4

3D GPS fix augmented with DGPS/SBAS or similar.

5

3D RTK float solution.

6

3D RTK fixed solution.

7

Static position, known in advance.

The second item of the list is optional and it may contain the number of GPS satellites that were used in the calculation.

The third and fourth items of the list are optional and they may contain the horizontal and vertical accuracy, respectively, in millimeters.

LogMessage

This type represents a single log message that is sent from the server to the client, intended for human consumption.

The log message may originate from the server itself, or it may be relayed by the server from one of the objects (UAVs, docks, weather stations etc) that the server manages.

Items

Name Required? Type Description

severity

no

Severity

The severity level of the message; defaults to "info"

sender

no

string

The ID of the object that sent the message if the server is relaying it; omitted if the server generated the message on its own

message

yes

string

The message to send to the client

timestamp

no

timestamp

Time when the message was generated or received by the server; may be omitted if not relevant

Example

{
    "severity": "info",
    "message": "Free cookies in the lobby!"
}

MagneticVector

This type represents a magnetic vector; typically the vector of Earth’s magnetic field at a given location. The vector is represented in a North-East-Down coordinate system (positive axes point North, East and down, respectively), in nanoteslas.

The object is stored as a list with three items.

ObjectType

Enumeration type that describes the possible object types that the server knows about. See Objects, devices and channels for more information.

Currently the following values are defined:

beacon

A beacon on the ground or in the air. May also be used for waypoints that do not have a physical presence.

dock

A docking station.

other

Other object type, not listed here.

uav

An unmanned aerial vehicle.

weatherStation

A weather station.

Values not listed here should also be accepted by the server. If the server does not know a particular object type, it should simply return an empty list when the user queries about objects of an unknown type. This allows server extensions to register custom object types later on.

MessageObservations

The MessageObservations object contains statistical information about RTK messages broadcast by the RTK base station.

The object is indexed by the message types sent by the RTK base.

Items

Index Required? Type Description

0

yes

int

The age of the last observation, in integer milliseconds

1

yes

int

The average bitrate of the message stream in the last 10 seconds, in bits per second

Example

{
    "rtcm3/1007": [123, 456],
    "rtcm3/1019": [1234, 5678]
}

PositionXYZ

This type represents the position of an airborne object (typically a UAV) in a local (flat-Earth) right-handed XYZ coordinate system. The origin of the coordinate system and the orientation of its X axis is typically specific to the UAV. The Z axis points upwards.

The object is stored as a list with three mandatory items.

Items

Index Required? Type Description

0

yes

number

The X component of the position vector, in mm

1

yes

number

The Y component of the position vector, in mm

2

yes

number

The Z component of the position vector, in mm

Example

[2000, 2000, 1000]

PreflightCheckInfo

Monolithic object containing information about the preflight checklist of a UAV.

Fields

Name Required? Type Description

result

yes

PreflightCheckResult

The result of the preflight check

items

yes

array of PreflightCheckItem

List of preflight check items, containing information about the individual checks that were performed onboard and the corresponding results.

message

no

string

Custom message to show next to the result of the preflight check, containing even more details (if applicable).

Example

{
    "message": "Compass inconsistency",
    "result": "failure",
    "items": [{
        "id": "compass",
        "label": "Compass",
        "result": "failure",
        "message": "Compass inconsistency detected"
    }, {
        "id": "imu",
        "label": "IMU",
        "result": "pass",
        "message": "IMU subsystem healthy"
    }, {
        "id": "gps",
        "label": "GPS",
        "result": "pass",
        "message": "3D GPS fix"
    }, {
        "id": "Home",
        "label": "Home position",
        "result": "warning",
        "message": "Home position not set yet"
    }]
}

PreflightCheckItem

Object containing information about a single item in a preflight checklist.

Fields

Name Required? Type Description

id

yes

string

The unique identifier of the preflight check item

label

no

string

A custom label to show next to the preflight check item on user interfaces showing the checklist

result

yes

PreflightCheckResult

The result of the preflight checklist item

message

no

string

Custom message to show next to the result of the preflight check item, containing more details (if applicable).

Example

{
    "id": "compass",
    "label": "Compass",
    "result": "failure",
    "message": "Compass inconsistency detected"
}

PreflightCheckResult

Enumeration type that describes the possible results of an item on a preflight checklist, or the preflight check as a whole. Currently the following values are defined:

off

The preflight check is disabled.

pass

The preflight check passed.

warning

There were some issues during the preflight checks; this does not prevent a takeoff but should be investigated later. It may also indicate a temporary issue that is likely to resolve itself on its own.

running

The preflight check is in progress and there is no conclusive result yet.

softFailure

The preflight check failed, but it is likely that it will pass soon without any further operator intervention.

failure

The preflight check failed and it will not pass soon without operator intervention.

error

There was an error during the preflight check that prevented the check from reaching a conclusive result. This is usually indicative of a failure in the code or firmware of the UAV.

Progress

A Progress object stores the progress of an asynchronous operation that is being performed on the server or a remote object (such as a UAV) managed by the server. It is typically used in ASYNC-ST messages.

The progress object consists of a percentage value (null if unknown or indeterminate), a human-readable message (null if not specified) and an optional machine-readable object that can be used for arbitrary purposes if there is a common understanding of the semantics of this object between the server and the client. For instance, a long-running RC calibration operation on a UAV may use this object to report the minimum and maximum values seen for each RC channel so far during the calibration process, which can be used by the client to provide visual feedback to the user.

Fields

Name Required? Type Description

percentage

no

integer

Progress of the operation expressed as a percentage, between 0 and 100 (inclusive).

message

no

string

Human-readable status message that can be used on the UI to provide feedback to the user.

object

no

object

Arbitrary machine-readable object that can be used to transmit additional information to the client about the progress of the operation in a structured manner.

Example

{
    "percentage": 80,
    "message": "Almost ready, stay tuned..."
}

RSSI

An RSSI object is an array of integers, each holding the received signal strength indicator from a single channel of the UAV that it is accessible on. Most UAVs are accessible on a single channel or a primary and a redundant secondary channel only, so this object typically holds one or two integers.

Received signal strength is expressed on an abstract, unitless scale from 0 to 100. Percentages may be used directly if the UAV can provide an RSSI reading that is already mapped into a percent scale. -1 is also a valid value, interpreted as "no RSSI reading available".

RTKConfigurationPreset

An RTKConfigurationPreset object holds an RTK configuration preset consisting of one or more RTK data sources and an optional packet filter to be executed on every received packet.

RTK configuration presets may be of one of three types:

  • Built-in presets are supplied by the configuration of the server and may not be modified or removed by the user.

  • Dynamic presets are created by the server automatically based on the hardware configuration. For instance, USB serial ports may have one corresponding preset that assumes that an RTK base station is attached to the port. These presets may not be modified or removed by the user either.

  • User presets are created by the user manually and may be modified, added or removed on-demand.

Fields

Name Required? Type Description

title

yes

string

A human-readable title of the preset

type

no

string

Type of the RTK preset (built-in, dynamic, user)

format

yes

string

Format of the GPS messages arriving in this configuration (supported formats: "rtcm2", "rtcm3", "ubx", and "auto" for auto detection)

sources

yes

list of string

List of source connections where this preset collects messages from

Example

{
    "title": "My RTK base (COM3) (115200 baud)",
    "format": "auto",
    "sources": ["serial:COM3?baud=115200"]
}

RTKSurveySettings

The RTKSurveySettings object contains status of the current RTK base station self-survey procedure.

Fields

Name Required? Type Description

duration

yes

float

The minimum duration of the survey to perform

accuracy

yes

float

The accuracy of the survey in meters

messageSet

yes

string

The message set to use / used ('msm4' or 'msm7')

position

no

ECEFCoordinate

The RTK base station antenna position in ECEF coordinates

gnssTypes

no

list of GNSSType

The GNSS types to use (choose from "gps", "glonass", "galileo", "sbas", "qzss", "beidou", "irnss")

Example

{
    "duration": 60,
    "accuracy": 0.99,
    "messageSet": "msm7",
    "position": [4120339623, 1418747456, 4641838123],
    "gnssTypes": ["gps", "glonass"]
}

Severity

Enumeration type that describes the severity level of a human-readable message that the server sends to the client.

Currently the following values are defined:

debug

Debug messages that are of interest to developers only.

info

Informational messages.

warning

Warning messages.

error

Error messages.

critical

Critical errors that require immediate attention.

StartConditions

Object that contains the conditions regarding the start of the show.

It is a field of DroneShowConfiguration, and the data type is therefore used by the SHOW-CFG and SHOW-SETCFG commands.

Fields

Name Required? Type Description

authorized

no

boolean

Whether the server has received authorization from a human operator to start the show

clock

no

string or null

Identifier of the clock that the start time refers to; null means that the start time is a UNIX timestamp

time

no

timestamp

Timestamp when the drone show should start

method

no

StartMethod

Method of starting the show. Can be either rc or auto.

uavIds

no

list of strings

Array containing the IDs of the UAVs that should be started automatically.

Example

{
    "authorized": true,
    "clock": null,
    "time": 1449562661000,
    "method": "rc",
    "uavIds": ["1","17","31"]
}

StartMethod

Enumeration type that describes the method of how the drone show should be started.

rc

Remote controlled. This means that the human operator starts the show manually.

auto

The drone show is started automatically.

SurveyStatus

The SurveyStatus object contains status of the current RTK base station self-survey procedure.

Fields

Name Required? Type Description

accuracy

yes

float

Accuracy of the antenna position during the survey in meters

flags

yes

integer

RTK survey status flags:

0

unknwon

1

supported

2

active

4

valid

Example

{
    "accuracy": 0.99,
    "flags": 7
}

TransportOptions

Object describing how a particular message should be delivered to a target UAV if multiple communication channels are available.

This data type is supported by some of the UAV-…​ commands to allow the sender to specify its preference about how the message should be delivered to the UAVs. In particular, the transport options let the server know which communication channel the server should use if the UAVs are reachable over multiple communication channels (primary and secondary ones), and whether the server is allowed to use a broadcast message instead of addressing all the targeted UAVs one by one. The broadcasting option should be used only if the sender is certain that it is safe to target all UAVs with the particular UAV-…​ message.

UAVs MAY NOT respect the transport options specified by the sender, but implementations should try to satisfy the preferences of the caller on a best-effort basis.

Fields

Name Required? Type Description

channel

no

integer

Index of the communication channel to use if there are multiple channels over which the UAV can be reached. Zero means the primary channel, 1 means the first backup channel and so on. Defaults to zero if omitted.

broadcast

no

boolean

Whether the sender allows the server to use a broadcast message to reach all UAVs in range. Defaults to false if omitted.

ignoreIds

no

boolean

Whether to ignore the explicitly defined UAV IDs in the command in broadcast mode. See below for more details.

Example

{
    "channel": 1,
    "broadcast": true
}

The example above means that the first backup channel should be used and that broadcasting is allowed.

Handling of broadcast, ignoreIds and UAV ID lists

The interplay between the broadcast and the ignoreIds field in this object and a uavIds field in the corresponding command deserves a more detailed explanation. We assume that UAVs are typically reachable via one or more communication networks, and the server knows which network to use to reach a particular UAV. The rules are as follows:

  • When broadcast is missing or set to false, the messages sent by the server will be targeted to the UAVs explicitly listed in the uavIds field, and each such message will be unicast. Sending a command with an empty uavIds field thus generates no messages at all.

  • When broadcast is set to true and ignoreIds is false or missing, the server MUST go through the list of UAV IDs and find all the communication networks that contain at least one of the mentioned UAVs. The server MUST then send one broadcast message per network. It MUST NOT send broadcast or unicast messages into communication networks that do not contain any of the UAVs in the uavIds field. Sending a command with an empty uavIds field thus generates no messages either.

  • When broadcast is set to true and ignoreIds is also set to true, the server MUST send one broadcast message into all the communication networks that it uses to manage UAVs, irrespectively of whether it is aware of any UAVs in that network or not. Sending a command with an empty uavIds field will still generate one broadcast message per network. This can be used for remote power-on requests when the server does not know in advance how many UAVs there will be in each network.

UAVStatusInfo

Monolithic object containing general status information about a single UAV.

Fields

Name Required? Type Description

id

yes

string

The unique identifier of the UAV

mode

no

string

The flight mode of the UAV. Several values have pre-defined meanings; see FlightMode for these pre-defined values.

position

no

GPSCoordinate

The position of the UAV, in GPS coordinates

positionXYZ

no

PositionXYZ

The position of the UAV, in a local right-handed flat Earth coordinate system

gps

no

GPSFix

Basic information about the GPS fix of the UAV

heading

no

angle

The heading of the UAV, i.e. the direction the UAV is pointing, projected to the local tangent plane, if known.

attitude

no

Attitude

The attitude of the UAV.

velocity

no

VelocityNED

The velocity of the UAV, expressed in the NED (North, East, Down) coordinate system.

velocityXYZ

no

VelocityXYZ

The velocity of the UAV, in a local right-handed flat Earth coordinate system

timestamp

yes

timestamp

Time when the last status update was received from the UAV

battery

no

BatteryInfo

Information about the state of the battery on the UAV.

light

no

ColorRGB565

Information about the color of the light attached to the UAV, assuming that it has a primary light.

rssi

no

RSSI

The received signal strength from the UAV, for each of the communication channels it is accessible on.

errors

no

ErrorList

The list of error codes currently applicable for the UAV. When omitted, it means that there are no errors.

debug

no

byte array

Debug information provided by the algorithm running on the UAV (if applicable).

Example

{
    "id": "17",
    "mode": "pos",
    "position": [519976597, -7406863, 93765],
    "positionXYZ": [0, 0, 0],
    "gps": [3, 17],
    "heading": 900,
    "attitude": [0, 0, 900],
    "velocity": [2000, 2000, -1000],
    "velocityXYZ": [2000, 2000, 1000],
    "timestamp": 1449562661000,
    "battery": [118, 69, false],
    "light": 2016,
    "rssi": [80],
    "errors": [42],
    "debug": "MEJBRENBRkU="
}

The debug information in the above example is then decoded to 0BADCAFE using base64.

VelocityNED

This type represents the velocity of an airborne object (typically a UAV) in the NED coordinate system (also called local tangent plane). The default unit for the components is mm/s (millimeters per second). For instance, a UAV moving northeast with ~2.82 m/s (2.82 = sqrt(8)) while ascending with 1 m/s is expressed by a velocity vector where north=2000, east=2000 and down=-1000.

The object is stored as a list with three mandatory items.

Fields

Index Required? Type Description

0

yes

number

The "north" component of the velocity vector, in mm/s

1

yes

number

The "east" component of the velocity vector, in mm/s

2

yes

number

The "down" component of the velocity vector, in mm/s

Example

[2000, 2000, -1000]

VelocityXYZ

This type represents the velocity of an airborne object (typically a UAV) in a local (flat-Earth) right-handed XYZ coordinate system. The origin of the coordinate system and the orientation of its X axis is typically specific to the UAV. The Z axis points upwards.

The object is stored as a list with three mandatory items.

Fields

Index Required? Type Description

0

yes

number

The X component of the velocity vector, in mm/s

1

yes

number

The Y component of the velocity vector, in mm/s

2

yes

number

The Z component of the velocity vector, in mm/s

Example

[2000, 2000, 1000]

Weather

This type encapsulates information about the weather at a given time and geographical coordinate. Objects of this type are typically provided by weather stations or external weather APIs.

The structure of this object is heavily influenced by the OpenWeatherMap one-call API response. Almost all of the fields are optional to account for use-cases when a weather station cannot provide one or more of the response fields; only the position and the timestamp are mandatory.

Fields

Name Required? Type Description

position

yes

GPSCoordinate

GPS coordinate that the weather object refers to

timestamp

yes

timestamp

Time that the weather object refers to

code

no

integer

OpenWeatherMap weather condition code

sunrise

no

timestamp

Time of sunrise; negative if the Sun does not rise on the given day

sunset

no

timestamp

Time of sunset; negative if the Sun does not set on the given day

temperature

no

temperature

Temperature

feelsLike

no

temperature

Temperature, adjusted for human perception

pressure

no

integer

Atmospheric pressure, in Pa

humidity

no

integer

Humidity, in %

dewPoint

no

temperature

Dew point

uvIndex

no

integer

UV index, multiplied by 100 (e.g., 89 means 0.89)

kpIndex

no

integer

Planetary K-index

magneticVector

no

MagneticVector

Earth’s magnetic field, in nanoteslas

clouds

no

integer

Cloudiness, in %

visibility

no

integer

Visibility, in metres

windDirection

no

angle

Meteorological wind direction (i.e. where the wind blows from)

windSpeed

no

integer

Wind speed, in millimetres per second

windGust

no

integer

Wind gust, in millimetres per second

Example

{
    "position": [519976597, -7406863],
    "timestamp": 1628607017000,
    "code": 500,
    "sunrise": 1628609700000,
    "sunset": 1628618640000,
    "temperature": 2840,
    "feelsLike": 2828,
    "pressure": 101900,
    "humidity": 62,
    "dewPoint": 2771,
    "uvIndex": 89,
    "clouds": 0,
    "visibility": 10000,
    "windSpeed": 6000,
    "windDirection": 3000,
    "magneticField": [21451, 1989, 43823]
}