Mission Protocol

The mission sub-protocol allows a GCS or developer API to exchange mission (flight plan), geofence and safe point information with a drone/component.

The protocol covers:

• Operations to upload, download and clear missions, set/get the current mission item number, and get notification when the current mission item has changed.
• Message type(s) and enumerations for exchanging mission items.
• Mission Items ("MAVLink commands") that are common to most systems.

The protocol supports re-request of messages that have not arrived, which allows missions to be reliably transferred over a lossy link.

Mission Types

MAVLink 2 supports three types of "missions": flight plans, geofences and rally/safe points. The protocol uses the same sequence of operations for all types (albeit with different types of Mission Items). The mission types must be stored and handled separately/independently.

Mission protocol messages include the type of associated mission in the mission_type field (a MAVLink 2 message extension). The field takes one of the MAV_MISSION_TYPE enum values: MAV_MISSION_TYPE_MISSION, MAV_MISSION_TYPE_FENCE, MAV_MISSION_TYPE_RALLY.

MAVLink 1 supports only "regular" flight-plan missions (this is implied/not explicitly set).

Mission Items (MAVLink Commands)

Mission items for all the mission types are defined in the MAV_CMD enum.

MAV_CMD is used to define commands that can be used in missions ("mission items") and commands that can be sent outside of a mission context (using the Command Protocol). Some MAV_CMD can be used with both mission and command protocols. Not all commands/mission items are supported on all systems (or for all flight modes).

The items for the different types of mission are identified using a simple name prefix convention:

• Flight plans:
  • NAV commands (MAV_CMD_NAV_*) for navigation/movement (e.g. MAV_CMD_NAV_WAYPOINT, MAV_CMD_NAV_LAND)
  • DO commands (MAV_CMD_DO_*) for immediate actions like changing speed or activating a servo (e.g. MAV_CMD_DO_CHANGE_SPEED).
  • CONDITION commands (MAV_CMD_CONDITION_*) for changing the execution of the mission based on a condition - e.g. pausing the mission for a time before executing next command (MAV_CMD_CONDITION_DELAY).
• Geofence mission items:
  • Prefixed with MAV_CMD_NAV_FENCE_ (e.g. MAV_CMD_NAV_FENCE_RETURN_POINT).
• Rally point mission items:
  • There is just one rally point MAV_CMD: MAV_CMD_NAV_RALLY_POINT.

The commands are transmitted/encoded in MISSION_ITEM or MISSION_ITEM_INT messages. These messages include fields to identify the particular mission item (command id) and up to 7 command-specific optional parameters.

The first four parameters (shown above) can be used for any purpose - this depends on the particular command. The last three parameters (x, y, z) are used for positional information in MAV_CMD_NAV_* commands, but can be used for any purpose in other commands.

The remaining message fields are used for addressing, defining the mission type, specifying the reference frame used for x, y, z in MAV_CMD_NAV_* messages, etc.:

MISSION_ITEM_INT vs MISSION_ITEM

MISSION_ITEM and MISSION_ITEM_INT are used to exchange individual mission items between systems. MISSION_ITEM messages encode all mission item parameters into float parameters fields (single precision IEEE754) for transmission. MISSION_ITEM_INT is exactly the same except that param5 and param6 are Int32 fields.

Protocol implementations must allow both message types in supported operations (along with the corresponding MISSION_REQUEST and MISSION_REQUEST_INT message types).

MAVLink users should always prefer MISSION_ITEM_INT because it allows latitude/longitude to be encoded without the loss of precision that can come from using MISSION_ITEM.

Message/Enum Summary

The following messages and enums are used by the service.

Operations

This section defines all the protocol operations.

Upload a Mission to the Vehicle

The diagram below shows the communication sequence to upload a mission to a drone (assuming all operations succeed).

Mission update must be robust! A new mission should be fully uploaded and accepted before the old mission is replaced/removed.

In more detail, the sequence of operations is:

1. GCS sends MISSION_COUNT including the number of mission items to be uploaded (count).
   • A timeout must be started for the GCS to wait on the response from Drone (MISSION_REQUEST_INT).
2. Drone receives message and responds with MISSION_REQUEST_INT requesting the first mission item (seq==0).
   • A timeout must be started for the Drone to wait on the MISSION_ITEM_INT response from GCS.
3. GCS receives MISSION_REQUEST_INT and responds with the requested mission item in a MISSION_ITEM_INT message.
4. Drone and GCS repeat the MISSION_REQUEST_INT/MISSION_ITEM_INT cycle, iterating seq until all items are uploaded (seq==count-1).
5. After receiving the last mission item the drone responds with MISSION_ACK with the type of MAV_MISSION_ACCEPTED indicating mission upload completion/success.
   • The drone should set the new mission to be the current mission, discarding the original data.
   • The drone considers the upload complete.
6. GCS receives MISSION_ACK containing MAV_MISSION_ACCEPTED to indicate the operation is complete.

Note:

• A timeout is set for every message that requires a response (e.g. MISSION_REQUEST_INT). If the timeout expires without a response being received then the request must be resent.
• Mission items must be received in order. If an item is received out-of-sequence the expected item should be re-requested by the vehicle (the out-of-sequence item is dropped).
• An error can be signaled in response to any request using a MISSION_ACK message containing an error code. This must cancel the operation and restore the mission to its previous state. For example, the drone might respond to the MISSION_COUNT request with a MAV_MISSION_NO_SPACE if there isn't enough space to upload the mission.
• The sequence above shows the mission items packaged in MISSION_ITEM_INT messages. Protocol implementations must also support MISSION_ITEM and MISSION_REQUEST in the same way.
• Uploading an empty mission (MISSION_COUNT is 0) has the same effect as clearing the mission.

Download a Mission from the Vehicle

The diagram below shows the communication sequence to download a mission from a drone (assuming all operations succeed).

The sequence is similar to that for uploading a mission. The main difference is that the client (e.g. GCS) sends MISSION_REQUEST_LIST, which triggers the autopilot to respond with the current count of items. This starts a cycle where the GCS requests mission items, and the drone supplies them.

Note:

• A timeout is set for every message that requires a response (e.g. MISSION_REQUEST_INT). If the timeout expires without a response being received then the request must be resent.
• Mission items must be received in order. If an item is received out-of-sequence the expected item should be re-requested by the GCS (the out-of-sequence item is dropped).
• An error can be signaled in response to any request using a MISSION_ACK message containing an error code. This must cancel the operation.
• The sequence above shows the mission items packaged in MISSION_ITEM_INT messages. Protocol implementations must also support MISSION_ITEM and MISSION_REQUEST in the same way.

Set Current Mission Item

The diagram below shows the communication sequence to set the current mission item.

In more detail, the sequence of operations is:

1. GCS/App sends MISSION_SET_CURRENT, specifying the new sequence number (seq).
2. Drone receives message and attempts to update the current mission sequence number.
   • On success, the Drone must broadcast a MISSION_CURRENT message containing the current sequence number (seq).
   • On failure, the Drone must broadcast a STATUSTEXT with a MAV_SEVERITY and a string stating the problem. This may be displayed in the UI of receiving systems.

Notes:

• There is no specific timeout on the MISSION_SET_CURRENT message.
• The acknowledgment of the message is via broadcast of mission/system status, which is not associated with the original message. This differs from error handling in other operations. This approach is used because the success/failure is relevant to all mission-handling clients.

Monitor Mission Progress

GCS/developer API can monitor progress by handling the appropriate messages sent by the drone:

• The vehicle must broadcast a MISSION_ITEM_REACHED message whenever a new mission item is reached. The message contains the seq number of the current mission item.
• The vehicle must also broadcast a MISSION_CURRENT message if the current mission item is changed.

Clear Missions

The diagram below shows the communication sequence to clear the mission from a drone (assuming all operations succeed).

In more detail, the sequence of operations is:

1. GCS/API sends MISSION_CLEAR_ALL
   • A timeout is started for the GCS to wait on MISSION_ACK from Drone.
2. Drone receives the message, and clears the mission from storage.
3. Drone responds with MISSION_ACK with result type of MAV_MISSION_ACCEPTEDMAV_MISSION_RESULT.
4. GCS receives MISSION_ACK and clears its own stored information about the mission. The operation is now complete.

Note:

• A timeout is set for every message that requires a response (e.g. MISSION_CLEAR_ALL). If the timeout expires without a response being received then the request must be resent.
• An error can be signaled in response to any request (in this case, just MISSION_CLEAR_ALL) using a MISSION_ACK message containing an error code. This must cancel the operation. The GCS record of the mission (if any) should be retained.

Canceling Operations

The above mission operations may be canceled by responding to any request (e.g. MISSION_REQUEST_INT) with a MISSION_ACK message containing the MAV_MISSION_OPERATION_CANCELLED error.

Both systems should then return themselves to the idle state (if the system does not receive the cancellation message it will resend the request; the recipient will then be in the idle state and may respond with an appropriate error for that state).

Operation Exceptions

Timeouts and Retries

A timeout should be set for all messages that require a response. If the expected response is not received before the timeout then the message must be resent. If no response is received after a number of retries then the client must cancel the operation and return to an idle state.

The recommended timeout values before resending, and the number of retries are:

• Timeout (default): 1500 ms
• Timeout (mission items): 250 ms.
• Retries (max): 5

Errors/Completion

All operations complete with a MISSION_ACK message containing the result of the operation (MAV_MISSION_RESULT) in the type field.

On successful completion, the message must contain type of MAV_MISSION_ACCEPTED; this is sent by the system that is receiving the command/data (e.g. the drone for mission upload or the GCS for mission download).

An operation may also complete with an error - MISSION_ACK.type set to MAV_MISSION_ERROR or some other error code in MAV_MISSION_RESULT. This can occur in response to any message/anywhere in the sequence.

Errors are considered unrecoverable. In an error is sent, both ends of the system should reset themselves to the idle state and the current state of the mission on the vehicle should be unaltered.

Note:

• timeouts are not considered errors.
• Out-of-sequence messages in mission upload/download are recoverable, and are not treated as errors.

Mission File Formats

The defacto standard file format for exchanging missions/plans is discussed in: File Formats > Mission Plain-Text File Format.

Implementations

PX4

The protocol has been implemented in C.

Source code:

• src/modules/mavlink/mavlink_mission.cpp

The implementation status is (at time of writing):

• Flight plan missions:
  • upload, download, clearing missions, and monitoring progress are supported as defined in this specification.
• Geofence missions" are supported as defined in this specification.
• Rally point "missions" are not supported on PX4.

Mission operation cancellation works for mission download (sets system to idle). Mission operation cancellation does not work for mission uploading; PX4 resends MISSION_REQUEST_INT until the operation times out.

Source code:

• src/modules/mavlink/mavlink_mission.cpp

QGroundControl

The protocol has been implemented in C++.

Source code:

• src/MissionManager/PlanManager.cc

ArduPilot

ArduPilot implements the mission protocol in C++.

ArduPilot uses the same messages and message flow described in this specification. There are (anecdotally) some implementation differences that affect compatibility. These are documented below.

Source:

• /libraries/GCS_MAVLink/GCS_Common.cpp

Flight Plan Missions

Mission upload, download, clearing missions, and monitoring progress are supported.

ArduPilot implements also partial mission upload using MISSION_WRITE_PARTIAL_LIST, but not partial mission download (MISSION_REQUEST_PARTIAL_LIST). Partial mission upload/download is not an official/standardised part of the mission service.

ArduPilot's implementation differs from this specification (non-exhaustively):

• The first mission sequence number (seq==0) is populated with the home position of the vehicle instead of the first mission item.
• Mission uploads are not "atomic". An upload that fails (or is canceled) part-way through will not match the pre-update state. Instead it may be a mix of the original and new mission.
• Even if upload is successful, the vehicle mission may not match the version on the uploading system (and if the mission is then downloaded it will differ from the original).
  • There is rounding on some fields (and in some cases internal maximum possible values due to available storage space). Failures can occur if you do a straight comparison of the float params before/after upload.
• A MISSION_ACK returning an error value (NACK) does not terminate the upload (i.e. it is not considered an unrecoverable error). As long as ArduPilot has not yet timed-out a system can retry the current mission item upload.
• A mission cannot be cleared while it is being executed (i.e. while in Auto mode). Note that a new mission can be uploaded (even a zero-size mission - which is equivalent to clearing).
• Explicit cancellation of operations is not supported. If one end stops communicating the other end will eventually timeout and reset itself to an idle/ready state.

The following behaviour is not defined by the specification (but is still of interest):

• ArduPilot performs some validation of fields when mission items are submitted. The validation code is common to all vehicles; mission items that are not understood by the vehicle type are accepted on upload but skipped during mission execution.
• ArduPilot preforms some vehicle-specific validation at mission runtime (e.g. of jump targets).
• A new mission can be uploaded while a mission is being executed. In this case the current waypoint will be executed to completion even if the waypoint sequence is different in the new mission (to get the new item you would need to reset the sequence or switch in/out of auto mode).
• ArduPilot missions are not stored in an SD card and therefore have a vehicle/board-specific maximum mission size (as a benefit, on ArduPilot, missions can survive SD card failure in flight).

Geofence & Rally Point Plans

ArduPilot supports Geofence and Rally points on Copter Rover and Sub using this protocol (for MAVLink 2 connections).

ArduPlane supports rally points and missions. Geofence support for ArduPlane is in development (May 2020).

MAVSDK

TBD

DroneKit

TBD