Waypoint Protocol

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.

Communication / State Machine

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.

Read MAV Waypoint list

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.


Write MAV Waypoint list

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 WAYPOINT message

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 WAYPOINT_ACK message.


Clear MAV Waypoint list

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 WAYPOINT_ACK message.



Set new current MAV Waypoint

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.



Waypoint reached Status message from MAV

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.

Current Waypoint changed Status message from MAV

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.



Waypoint File Format

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):

Format
QGC WPL <VERSION>
<INDEX> <CURRENT WP> <COORD FRAME> <COMMAND> <PARAM1> <PARAM2> <PARAM3> <PARAM4> <PARAM5/X/LONGITUDE> <PARAM6/Y/LATITUDE> <PARAM7/Z/ALTITUDE> <AUTOCONTINUE>
Example
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