UAV — UAV-related messages

A client sends this request to the server to ask one or more UAVs to calibrate one of its components accelerometer, pressure sensor, ESCs and so on).

The message specifies the name of the component to calibrate and an additional parameter object. The interpretation of the parameter object depends on the component itself. Right now the protocol supports baro, compass, esc, gyro and rc, although not all UAV types may implement all of these calibration types. As the component names are merely strings, the protocol can easily be extended in the future with additional component types. UAVs that do not know or do not support calibrating a specific component will return failures for the unsupported components.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the calibration was performed successfully on the UAV. The semantics of a successful response may vary from component to component; for instance, the calibration of a compass is a long process that requires a human operator to rotate the drone, so in this case the response may indicate success if the calibration has started. However, a pressure sensor is easily calibrated to a specific altitude without human intervention, so in this case the result indicates whether the calibration was successful.

Example request

Example response

A client sends this request to the server to ask a UAV to fly to a specific GPS coordinate and altitude. Note that it is possible to target multiple UAVs with the same command, in which case they will be asked to fly to the same coordinate. It is the responsibility of the software running on the UAVs to avoid collisions in such cases, so make sure that the UAVs can handle this.

The server responds with two lists: the first list contains the IDs of the UAVs where the command was accepted (which does not mean that the UAVs have reached the destination, only that the UAVs have started processing the command and act accordingly), and the second list contains the IDs where such an attempt was not started. (Possible reasons for failure could be: invalid UAV ID, UAV does not support flying to a specific waypoint, waypoint is outside the designated flying zone and so on). The server MAY decide to include more detailed information about failed attempts in the response.

The target is specified as a GPSCoordinate object. This object MUST contain a latitude and a longitude, but MAY omit both altitudes; in this case, the UAV SHOULD attempt flying to the target at the same altitude where it currently is.

Clients interested in whether the UAVs have reached their positions should keep an eye on UAV-INF messages.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, the result will indicate whether the request has been sent to the UAV.

Example request

Example response

A client sends this request to the server to initiate an immediate shutdown of an UAV in case of an emergency. Note that the UAV will not attempt to land - typically it will stop the rotors even in mid-air. Use this message only in emergencies.

The server responds with two lists: the first list contains the IDs of the UAVs where a shutdown attempt was started (in the sense that the UAV has been notified that they should shut down now), and the second list contains the IDs where such an attempt was not started. (Possible reasons for failure could be: invalid UAV ID, UAV does not support forced shutdown and so on). The server MAY decide to include more detailed information about failed attempts in the response.

Clients interested in whether the shutdown attempts have succeeded should keep an eye on UAV-INF messages.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, the result will indicate whether the request has been sent to the UAV.

Example request

Example response

A client sends this request to the server to request one or more UAVs to stop and hover in place in the air as soon as possible. Not applicable to fixed-wing UAVs that are not capable of hovering in place.

The server responds with two lists: the first list contains the IDs of the UAVs where the command to hover in place was sent, and the second list contains the IDs where such a command was not delivered successfully. (Possible reasons for failure could be: invalid UAV ID, UAV is a fixed-wing aircraft and so on). The server MAY decide to include more detailed information about failed attempts in the response.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, the result will indicate whether the request has been sent to the UAV.

Example request

Example response

A client sends this request to the server to obtain basic status information about one or more UAVs currently known to the server.

This message may also be broadcast as a notification by the server on its own volition to all connected Flockwave clients to notify them about a status change of one of the UAVs.

Request fields

Response and notification fields

All the UAV IDs that were specified in the request MUST appear either in the status list or in the error list. When this message is sent as a notification, only the status field SHOULD be present.

Example request

Example response

A client send this request to the server to initiate unsupervised landing on one or more UAVs. The server responds with two lists: the first list contains the IDs of the UAVs where an unsupervised landing attempt was started (in the sense that the UAV has been notified that they should land now), and the second list contains the IDs where such an attempt was not started. (Possible reasons for failure could be: invalid UAV ID, UAV does not support unsupervised landing and so on). The server MAY decide to include more detailed information about failed attempts in the response.

Clients interested in whether the landing attempts have succeeded should keep an eye on UAV-INF messages.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, the result will indicate whether the request has been sent to the UAV.

Example request

Example response

A client sends this request to the server to request the list of all UAVs currently known by the server. The semantics of ``knowing'' a UAV is left up to the server implementation and configuration; typically, the server will return an UAV ID in the response if it has received a status message from the given UAV recently, typically in the last few minutes.

This message is equivalent to sending an OBJ-LIST message with its filter set to uav; it exists solely for compatibility with legacy clients and will be deprecated in Flockwave 2.0.

Request fields

This request has no fields.

Response fields

Example request

Example response

A client sends this request to the server to request one or more of the UAVs to turn their motors on or off. Not all UAVs support this operation; UAVs that do not support turning on their motors without taking off should do nothing.

Typically, it is dangerous to turn off the motors while the UAV is airborne, and the default behaviour in such cases is to deny the operation. When the operator wants to stop the motors of the UAV even if it is airborne (in other words, to initiate an emergency stop without shutting down the software of the UAV), the command must be sent in "forced" mode.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, the result will indicate whether the request has been sent to the UAV.

Example request

Example response

A client sends this request to the server to obtain detailed information about the state of the onboard preflight checks on one or more UAVs currently known to the server.

Request fields

Response and notification fields

All the UAV IDs that were specified in the request MUST appear either in the status list or in the error list. When this message is sent as a notification, only the status field SHOULD be present.

Example request

Example response

A client sends this request to the server to initiate the reboot of the entire UAV or some subsystem of it. Note that this is a potentially dangerous operation; this message only if the UAV is on the ground or if you are sure that the rebooted subsystem does not affect the normal operation of the UAV during flight.

The server responds with two lists: the first list contains the IDs of the UAVs where a reboot attempt was started (in the sense that the UAV has been notified that they should reboot), and the second list contains the IDs where such an attempt was not started. (Possible reasons for failure could be: invalid UAV ID, UAV does not support rebooting and so on). The server MAY decide to include more detailed information about failed attempts in the response.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, the result will indicate whether the request has been sent to the UAV.

Example request

Example response

A client send this request to the server to request some of the UAVs to return to their home positions.

The server responds with two lists: the first list contains the IDs of the UAVs where an unsupervised landing attempt was started (in the sense that the UAV has been notified that they should return to their home positions now), and the second list contains the IDs where such an attempt was not started. (Possible reasons for failure could be: invalid UAV ID, UAV does not know the concept of a home position and so on). The server MAY decide to include more detailed information about failed attempts in the response.

Clients interested in whether the targeted UAVs have returned to their home positions should keep an eye on UAV-INF messages and watch the GPS coordinates of the UAVs.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, the result will indicate whether the request has been sent to the UAV.

Example request

Example response

A client sends this request to the server to ask one or more UAVs to emit a light or audio signal in order to attract attention. This is useful if you are trying to find a lost drone in the field or if you want to identify a drone needing battery replacement in a drone swarm, given its ID.

The message specifies what sort of signal should be emitted; right now the protocol supports light and sound signals, but more signal types may be added in the future. As the signal types are merely strings, the protocol can easily be extended in the future with additional signal types, and UAVs that do not know or do not support a specific signal type should simply ignore the unknown ones.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, the result will indicate whether the request has been sent to the UAV.

Example request

Example response

A client sends this request to the server to request one or more UAVs to switch to a low-power state where most of the components are powered down, except the ones responsible for maintaining a connection with the GCS. This allows the operator to suspend a UAV remotely and wake it up later. UAVs that do not support low-power states MUST NOT treat this command as a poweroff command as it becomes impossible to recover from the powered-down state without physically restarting the UAV.

The server responds with two lists: the first list contains the IDs of the UAVs where the command was acknowledged, and the second list contains the IDs where such an acknowledgment was not received. (Note that the UAV may have still entered a low-power state even if the acknowledgment was not received; this may happen if the UAV is constructed in a way that it does not have time to send the acknowledgment before it powers down).

Clients interested in whether the low-power state switch attempts have succeeded should keep an eye on UAV-INF messages.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, and the server knows that no acknowledgment should be expected, the result may indicate whether the request has been sent to the UAV instead.

Example request

Example response

A client sends this request to the server to initiate unsupervised take-off on one or more UAVs. The server responds with two lists: the first list contains the IDs of the UAVs where an unsupervised take-off was started (in the sense that the UAV has been notified that they should take off now), and the second list contains the IDs where such an attempt was not started. (Possible reasons for failure could be: invalid UAV ID, UAV does not support unsupervised take-off and so on). The server MAY decide to include more detailed information about failed attempts in the response.

Clients interested in whether the take-off attempts have succeeded should keep an eye on UAV-INF messages and watch the status flags of the UAVs.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, the result will indicate whether the request has been sent to the UAV.

Example request

Example response

A client sends this request to the server to ask one or more UAVs to perform a self-test on one of its components.

The message specifies the name of the component to test and an additional parameter object. The interpretation of the parameter object depends on the component itself. Right now the protocol supports motor and led as the component names, but more component types may be added in the future. As the component names are merely strings, the protocol can easily be extended in the future with additional component types. UAVs that do not know or do not support testing a specific component will return failures for the unsupported components.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the self-test was performed successfully on the UAV. The semantics of a successful response may vary from component to component; for instance, the self-test of a LED light requires a human operator to observe whether the LED light works correctly, so in this case the response will indicate success if the test has started. Similarly, a motor test might be handled by a particular UAV in a way that a human operator has to observe the motors to check whether they are spinning in the right direction.

Example request

Example response

A client sends this request to the server to retrieve the version numbers of the essential components of one or more UAVs.

It is up to the UAVs to decide which components can report version numbers and how these version numbers should be presented to the user. A simple non-autonomous UAV may report only the version number of the hardware and the firmware, while a more complex autonomous UAV may report several version numbers for various software components.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to another object mapping component names to version numbers.

Example request

Example response

A client sends this request to the server to request one or more UAVs to switch back to normal operational state from a low-power state. This allows the operator to wake up a UAV that was suspended earlier with UAV-SLEEP.

The server responds with two lists: the first list contains the IDs of the UAVs where the command was acknowledged, and the second list contains the IDs where such an acknowledgment was not received. (Note that the UAV may have still started recovering to a normal operational state even if the acknowledgment was not received; this may happen if the UAV is constructed in a way that it does not respond to wakeup calls because the power management subsystem is too low-level to engage in communication).

Clients interested in whether the wakeup calls have succeeded should keep an eye on UAV-INF messages.

Request fields

Response fields

The response is a multi-object async response; each UAV is mapped to a boolean denoting whether the operation was sent successfully to the UAV. If the UAV supports acknowledgments for this operation, the result will indicate whether the UAV has acknowledged the operation. If the UAV does not support acknowledgments for this type of operation, and the server knows that no acknowledgment should be expected, the result may indicate whether the request has been sent to the UAV instead.

Example request

Example response