The waypoint protocol describes how waypoints are sent to and read from a MAV. The goal is to ensure a consistent state between sender and receiver. QGroundControl has an implementation of the Groundcontrol side of the protocol, every waypointplanner on a MAV implementing this protocol using MAVLINK can communicate with QGroundControl and exchange and update its waypoints.
The protocol consists of different transactions, each transaction is completed successfully or fails in a way that the previous state of the waypoint list on the receiving side is unchanged. A transaction can be initiated with a specific message only when no other transaction is active between the two communication parties. This means to initiate a transaction both communication parties have to be in state IDLE. If a transaction is started the state is changed, using a simple state machine in this way the protocol can be easily implemented.
After each sent message that excepts an answer the sending component starts a timer. If no response is received until a specified time has passed the request message is sent again. The resending is retried a number of times, if there is no answer after the last retry timed out the transaction is failed. The retrying mechanism means that all components have to be able to handle duplicate messages.
To retrieve a list of all waypoints from a component a
WAYPOINT_REQUEST_LIST message is sent. The targeted component will response with a
WAYPOINT_COUNT message stating the number of waypoints in its list.
The requesting component will now request every waypoint starting with sequence number 0 by sending a
WAYPOINT_REQUEST message and the targeted component answers every request with a corresponding
WAYPOINT message containing the waypoint data.
When the last waypoint was successfully received the requesting component sends a
WAYPOINT_ACK message to the targeted component. This finishes the transaction. Notice that the targeted component has to listen to
WAYPOINT_REQUEST messages of the last waypoint until it gets the
WAYPOINT_ACK or another message that starts a different transaction or a timeout happens.
To send a list of waypoints a
WAYPOINT_COUNT message containing the number waypoints in the list is sent to the targeted component. The component prepares itself for the reception and starts retrieving all the waypoints by sending
WAYPOINT_REQUEST starting with sequence number 0.
The component that is sending the waypoint list answers all the requests with a
When the last waypoint was successfully received by the targeted component, it sends a
WAYPOINT_ACK message to the sending component. This finishes the transaction.
If a waypoint planner component receives
WAYPOINT messages outside of transactions it answers with a
To clear the waypoint list of a component a
WAYPOINT_CLEAR_ALL message is sent. After having cleared the waypoint list the targeted component answers with a
To set a new current active waypoint for a component a
WAYPOINT_SET_CURRENT message is sent. After having changed the current waypoint the targeted component answers with a
WAYPOINT_CURRENT message with the new current sequence number.
If a waypoint planner on a MAV reaches a waypoint, it broadcasts a
WAYPOINT_REACHED message. As this is a broadcast no ack message has to be sent, but also no reception guarantees can be given.
If a waypoint planner on a MAV selects a waypoint as its new current target, it broadcasts a
WAYPOINT_CURRENT message. As this is a broadcast no ack message has to be sent, but also no reception guarantees can be given. It is recommended that this message is sent twice with a small delay to make sure it reaches all receivers with high probability.
Although not part of MAVLink, this is the recommended waypoint file format (currently used by QGroundControl and other implementations). Please note that the spaces between the numbers/fields are actually <tab> (Use “\t” in most programming languages):
QGC WPL <VERSION> <INDEX> <CURRENT WP> <COORD FRAME> <COMMAND> <PARAM1> <PARAM2> <PARAM3> <PARAM4> <PARAM5/X/LONGITUDE> <PARAM6/Y/LATITUDE> <PARAM7/Z/ALTITUDE> <AUTOCONTINUE>
QGC WPL 110 0 1 0 16 0.149999999999999994 0 0 0 8.54800000000000004 47.3759999999999977 550 1 1 0 0 16 0.149999999999999994 0 0 0 8.54800000000000004 47.3759999999999977 550 1 2 0 0 16 0.149999999999999994 0 0 0 8.54800000000000004 47.3759999999999977 550 1