From 5b7fb1d0fc5e559b011fa95f7d4ec27b2f725806 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 29 Feb 2024 12:42:27 +1100 Subject: [PATCH 1/8] Add section on mission execution --- en/services/mission.md | 45 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/en/services/mission.md b/en/services/mission.md index 162c84788..0138aa0e9 100644 --- a/en/services/mission.md +++ b/en/services/mission.md @@ -379,6 +379,51 @@ Note: - [timeouts](#timeout) are not considered errors. - Out-of-sequence messages in mission upload/download are recoverable, and are not treated as errors. +## Executing Missions + +Following mission upload, or vehicle restart, or mission reset, all jump counter loops are set to their initial values. +Unless a mission has just been uploaded that explicitly sets the current mission item, the current mission item is set to 1. + +The mission is executed when the vehicle is armed and in the flight stack's mission mode. +While executing, the vehicle will progress sequentially through the mission items, looping and jumping in response to jump commands. + +The mission can be paused by changing to another flight mode, such as Hold/loiter, and restarted by changing back to mission mode (when armed). +On restart the vehicle will _generally_ continue towards the same waypoint item as when it was paused. +In some cases flight stacks may start from the preceding waypoint, for example, a paused camera survey may restart on the previous waypoint to ensure the whole paused leg is captured. +Note that there is no concept of "stopping" a mission independent of pausing it. + +On completion of all mission items the mission will "complete". +At this point some flight stacks will loiter within the mission mode, while others will transition to some other mode (such as "Hold") and not allow you to return to mission mode. +In either case, the mission cannot be restarted unless it is [reset](#resetting-missions) (which usually happens after the vehicle lands and disarms). + +While the mission is executing the current mission item can be changed via MAVLink ([MAV_CMD_DO_SET_MISSION_CURRENT](#MAV_CMD_DO_SET_MISSION_CURRENT)). +Note however that this does not reset the jump counters, and if the mission is complete, will not restart the mission. + +### Starting Missions + +A flight stack will usually run mission checks before allowing a vehicle to enter the mission executing mode (typically checks are run when first executing a mission, but some flight stacks might also check before continuing a paused mission). + +Provided the checks pass, you can start a mission by either switching to mission mode and arming, or arming and switching to mission mode. +With mavlink we can change the mode using [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) to set the mode and ARM using[MAV_CMD_COMPONENT_ARM_DISARM](../messages/common.md#MAV_CMD_COMPONENT_ARM_DISARM). + +If supported the [MAV_CMD_MISSION_START](../messages/common.md#MAV_CMD_MISSION_START) command will both arm the vehicle (if necessary) and switch to the mission mode. +This command also allows you to specify a particular start and end item in the mission. + +### Pausing/Stopping Missions + +Pause and stop missions by changing mode. +In MAVLink this can be done using [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) (generally a vehicle will also support changing modes via an RC controller/joystick too). + +### Resetting Missions + +Once a mission has started it will iterate through the mission items, jumping and looping as indicated by jump mission items, until it completes. +While the mission is running you can change the current mission item, but this does not reset the jump counters used for loops, and once the mission is complete, changing the current mission item will not restart it. + +The mission will reset after you land and the vehicle disarms. +It is also reset following a vehicle reboot. + +[MAV_CMD_DO_SET_MISSION_CURRENT.param2](../messages/common.md#MAV_CMD_DO_SET_MISSION_CURRENT) can also be used to reset the mission, if supported on the flight stack. + ## Mission File Formats The _defacto_ standard file format for exchanging missions/plans is discussed in: [File Formats > Mission Plain-Text File Format](../file_formats/README.md#mission_plain_text_file). From 0dafb8b64dfc1ec6b1c23b3c7f4f9857447e40fc Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Mar 2024 09:28:59 +1100 Subject: [PATCH 2/8] Apply suggestions from code review --- en/services/mission.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/en/services/mission.md b/en/services/mission.md index 0138aa0e9..b3ac86bb2 100644 --- a/en/services/mission.md +++ b/en/services/mission.md @@ -381,8 +381,9 @@ Note: ## Executing Missions -Following mission upload, or vehicle restart, or mission reset, all jump counter loops are set to their initial values. -Unless a mission has just been uploaded that explicitly sets the current mission item, the current mission item is set to 1. +Following full mission upload, or vehicle restart, or mission reset, all jump counter loops are set to their initial values. +The current mission item is normally reset to one on mission reset or vehicle restart, or on mission upload when the vehicle is landed. +The current mission item may retain its current value if a mission is uploaded in-air or it may be set to the mission item that has `current` set in a mission item (this field is ignored in ArduPilot but respected by PX4). The mission is executed when the vehicle is armed and in the flight stack's mission mode. While executing, the vehicle will progress sequentially through the mission items, looping and jumping in response to jump commands. From b3cedb1ad541df64a3d1cdf40c796af1ce2d501a Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Mar 2024 09:29:11 +1100 Subject: [PATCH 3/8] Update en/services/mission.md --- en/services/mission.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/services/mission.md b/en/services/mission.md index b3ac86bb2..ad2122303 100644 --- a/en/services/mission.md +++ b/en/services/mission.md @@ -418,7 +418,7 @@ In MAVLink this can be done using [MAV_CMD_DO_SET_MODE](../messages/common.md#MA ### Resetting Missions Once a mission has started it will iterate through the mission items, jumping and looping as indicated by jump mission items, until it completes. -While the mission is running you can change the current mission item, but this does not reset the jump counters used for loops, and once the mission is complete, changing the current mission item will not restart it. +While the mission is running you can change the current mission item, but this does not by reset the jump counters used for loops, and once the mission is complete, changing the current mission item will not restart it (with an exception outlined below). The mission will reset after you land and the vehicle disarms. It is also reset following a vehicle reboot. From 8de8ed04667620fb796881355eeff73a60ef858b Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Mar 2024 09:34:41 +1100 Subject: [PATCH 4/8] Update en/services/mission.md --- en/services/mission.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/en/services/mission.md b/en/services/mission.md index ad2122303..8348cd937 100644 --- a/en/services/mission.md +++ b/en/services/mission.md @@ -385,7 +385,10 @@ Following full mission upload, or vehicle restart, or mission reset, all jump co The current mission item is normally reset to one on mission reset or vehicle restart, or on mission upload when the vehicle is landed. The current mission item may retain its current value if a mission is uploaded in-air or it may be set to the mission item that has `current` set in a mission item (this field is ignored in ArduPilot but respected by PX4). -The mission is executed when the vehicle is armed and in the flight stack's mission mode. +For a mission to be executed the vehicle must be armed and in the flight stack's mission mode. +There may (or may not) be further requirements to start a mission. +For example PX4 will start as soon as you arm in mission mode, while ArduCopter in its default configuration requires that the throttle is raised. +Similarly, planes that are configured for throttle/hand launch may require a minimum acceleration before the mission is executed. While executing, the vehicle will progress sequentially through the mission items, looping and jumping in response to jump commands. The mission can be paused by changing to another flight mode, such as Hold/loiter, and restarted by changing back to mission mode (when armed). From 48126d8dc1c2a61f1df6f067fcf10c998fa35f3b Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Mar 2024 09:35:39 +1100 Subject: [PATCH 5/8] Update en/services/mission.md --- en/services/mission.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/services/mission.md b/en/services/mission.md index 8348cd937..cd92f0602 100644 --- a/en/services/mission.md +++ b/en/services/mission.md @@ -398,7 +398,7 @@ Note that there is no concept of "stopping" a mission independent of pausing it. On completion of all mission items the mission will "complete". At this point some flight stacks will loiter within the mission mode, while others will transition to some other mode (such as "Hold") and not allow you to return to mission mode. -In either case, the mission cannot be restarted unless it is [reset](#resetting-missions) (which usually happens after the vehicle lands and disarms). +In either case, the mission cannot be restarted unless it is [reset](#resetting-missions). While the mission is executing the current mission item can be changed via MAVLink ([MAV_CMD_DO_SET_MISSION_CURRENT](#MAV_CMD_DO_SET_MISSION_CURRENT)). Note however that this does not reset the jump counters, and if the mission is complete, will not restart the mission. From 7dd38c15bbfacae8081c8d29f0f81f6933fcca3f Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Mar 2024 09:39:48 +1100 Subject: [PATCH 6/8] Apply suggestions from code review --- en/services/mission.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/services/mission.md b/en/services/mission.md index cd92f0602..4a9f719d0 100644 --- a/en/services/mission.md +++ b/en/services/mission.md @@ -401,7 +401,7 @@ At this point some flight stacks will loiter within the mission mode, while othe In either case, the mission cannot be restarted unless it is [reset](#resetting-missions). While the mission is executing the current mission item can be changed via MAVLink ([MAV_CMD_DO_SET_MISSION_CURRENT](#MAV_CMD_DO_SET_MISSION_CURRENT)). -Note however that this does not reset the jump counters, and if the mission is complete, will not restart the mission. +Note however that unless the command [resets the mission](#resetting-missions), this does not reset the jump counters, and if the mission is complete, will not restart the mission. ### Starting Missions From 89ef2e28b77a89917cef69ca5fac03f2101e88a1 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Mar 2024 11:59:54 +1100 Subject: [PATCH 7/8] Restructure so exceptions on resetting can be grouped --- en/services/mission.md | 186 +++++++++++++++++++++++++---------------- 1 file changed, 113 insertions(+), 73 deletions(-) diff --git a/en/services/mission.md b/en/services/mission.md index 4a9f719d0..d8838bdd2 100644 --- a/en/services/mission.md +++ b/en/services/mission.md @@ -1,19 +1,23 @@ # 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 mission protocol allows a GCS or developer API to exchange _mission_ (flight plan), _geofence_ and _safe point_ information with a drone/component, and to control [mission execution](#executing-missions). 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. +- Operations to upload, download and clear missions and other [plan types](#mission_types) +- Operations to start, pause, and continue a mission, to set/get the current mission item number, and to get notification about the current mission state. - 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 {#mission_types} +## Plan Types {#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](#mavlink_commands)). +MAVLink 2 supports three types of "plans" within the mission protocol: flight plans ("missions"), geofence definitions, and rally/safe points. +Mission plans are autonomously executed flight plans that are primarily executed in a "mission mode", with the main exception being mission-defined landing patterns, which are may also be used for fixed wing landings in return mode (RTL). +Geofence definitions apply to all modes when enabled, and rally/safe points are generally used to provide safe alternative destinations in return mode (RTL). + +The mission protocol uses the same sequence of operations to upload and download all these types (albeit with different types of [Mission Items](#mavlink_commands)). 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). @@ -24,6 +28,7 @@ The field takes one of the [MAV_MISSION_TYPE](../messages/common.md#MAV_MISSION_ ## Mission Items (MAVLink Commands) {#mavlink_commands} +Mission items define the waypoints and other operations in a mission, and the definitions of rally (safety) points and geofences. Mission items for all the [mission types](#mission_types) are defined in the [MAV_CMD](../messages/common.md#mav_commands) enum. > **Note** [MAV_CMD](../messages/common.md#mav_commands) 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](../services/command.md)). @@ -70,9 +75,7 @@ The remaining message fields are used for addressing, defining the mission type, | current | uint8_t | false:0, true:1 | When downloading, whether the item is the current mission item. | | autocontinue | uint8_t | | Autocontinue to next waypoint when the command completes. | -## Message/Enum Summary - -The following messages and enums are used by the service. +## Message/Enum Summary (Plan Upload/Download) | Message | Description | | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -81,15 +84,7 @@ The following messages and enums are used by the service. | [MISSION_REQUEST_INT](../messages/common.md#MISSION_REQUEST_INT) | Request mission item data for a specific sequence number be sent by the recipient using a [MISSION_ITEM_INT](#MISSION_ITEM_INT) message. Used for mission [upload](#uploading_mission) and [download](#download_mission). | | [MISSION_ITEM_INT](../messages/common.md#MISSION_ITEM_INT) | Message encoding a [mission item/command](#mavlink_commands) (defined in a [MAV_CMD](#MAV_CMD)). Used for mission [upload](#uploading_mission) and [download](#download_mission). | | [MISSION_ACK](../messages/common.md#MISSION_ACK) | Acknowledgment message when a system completes a [mission operation](#operations) (e.g. sent by autopilot after it has uploaded all mission items). The message includes a [MAV_MISSION_RESULT](#MAV_MISSION_RESULT) indicating either success or the type of failure. | -| [MISSION_CURRENT](../messages/common.md#MISSION_CURRENT) | Message containing the current mission item sequence number, mission status, current mission ids, and other information. This is streamed and also emitted when the [current mission item is set/changed](#current_mission_item). | -| [MISSION_SET_CURRENT](../messages/common.md#MISSION_SET_CURRENT) | [Set the current mission item](#current_mission_item) by sequence number (continue to this item on the shortest path). | -| [STATUSTEXT](../messages/common.md#STATUSTEXT) | Sent to notify systems when a request to [set the current mission item](#current_mission_item) fails. | | [MISSION_CLEAR_ALL](../messages/common.md#MISSION_CLEAR_ALL) | Message sent to [clear/delete all mission items](#clear_mission) stored on a system. | -| [MISSION_ITEM_REACHED](../messages/common.md#MISSION_ITEM_REACHED) | Message emitted by system whenever it reaches a new waypoint. Used to [monitor progress](#monitor_progress). | - -| Command | Description | -| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| [MAV_CMD_DO_SET_MISSION_CURRENT](../messages/common.md#MAV_CMD_DO_SET_MISSION_CURRENT) | Set current mission item and optionally reset mission counter. Supersedes [MISSION_SET_CURRENT](#MISSION_SET_CURRENT). | | Enum | Description | | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -98,12 +93,34 @@ The following messages and enums are used by the service. | [MAV_FRAME](../messages/common.md#MAV_FRAME) | Co-ordinate frame for position/velocity/acceleration data in the message. | | [MAV_CMD](../messages/common.md#mav_commands) | [Mission Items](#mavlink_commands) (and MAVLink commands) sent in [MISSION_ITEM_INT](#MISSION_ITEM_INT). | -## Deprecated Types: MISSION_ITEM {#command_message_type} +## Message/Enum Summary (Mission Execution) + +The following are generally used for controlling [mission execution](#executing-missions). + +| Message | Description | +| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [MISSION_CURRENT](../messages/common.md#MISSION_CURRENT) | Message containing the current mission item sequence number, mission status, current mission ids, and other information. This is streamed and also emitted when the [current mission item is set/changed](#current_mission_item). | +| [STATUSTEXT](../messages/common.md#STATUSTEXT) | Sent to notify systems when a request to [set the current mission item](#current_mission_item) fails. | +| [MISSION_ITEM_REACHED](../messages/common.md#MISSION_ITEM_REACHED) | Message emitted by system whenever it reaches a new waypoint. Used to [monitor progress](#monitor_progress). | + +| Command | Description | +| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| [MAV_CMD_DO_PAUSE_CONTINUE](../messages/common.md#MAV_CMD_DO_PAUSE_CONTINUE) | Pause and restart a mission. | +| [MAV_CMD_DO_SET_MISSION_CURRENT](../messages/common.md#MAV_CMD_DO_SET_MISSION_CURRENT) | Set current mission item and optionally reset mission counter. Supersedes [MISSION_SET_CURRENT](#MISSION_SET_CURRENT). | -The legacy version of the protocol also supported [MISSION_REQUEST](../messages/common.md#MISSION_REQUEST) for requesting that a mission be sent as a sequence of [MISSION_ITEM](../messages/common.md#MISSION_ITEM) messages. +## Deprecated Types + +### MISSION_ITEM {#command_message_type} + +The legacy version of the protocol supported [MISSION_REQUEST](../messages/common.md#MISSION_REQUEST) for requesting that a mission be sent as a sequence of [MISSION_ITEM](../messages/common.md#MISSION_ITEM) messages. Both `MISSION_REQUEST` and `MISSION_ITEM` messages are now deprecated, and should no longer be sent. -If `MISSION_REQUEST` is recieved the system should instead respond with [MISSION_ITEM_INT](#MISSION_ITEM_INT) items (as though it received [MISSION_REQUEST_INT](#MISSION_REQUEST_INT)). +If `MISSION_REQUEST` is received the system should instead respond with [MISSION_ITEM_INT](#MISSION_ITEM_INT) items (as though it received [MISSION_REQUEST_INT](#MISSION_REQUEST_INT)). + +### MISSION_SET_CURRENT + +The [MISSION_SET_CURRENT](../messages/common.md#MISSION_SET_CURRENT) message is deprecated. +The command [MAV_CMD_DO_SET_MISSION_CURRENT](#MAV_CMD_DO_SET_MISSION_CURRENT) should be used instead. ## Frames & Positional Information @@ -151,9 +168,9 @@ In this case the [MISSION_ITEM_INT.frame](#MISSION_ITEM_INT) should be set to [M As param5 and param6 are sent in _integer_ fields, generally you should design mission items/MAV_CMDs such that these only include integer data (and are sent as-is/unscaled). If these must be used for real numbers and scaling is required, then this must be noted in the mission item itself. -## Operations {#operations} +## Plan Upload/Download {#operations} -This section defines all the protocol operations. +This section defines protocol operations for exchanging mission plans between a drone and ground station. ### Detecting Mission/Plan Changes @@ -273,43 +290,6 @@ Note: - The sequence above shows the [mission items](#mavlink_commands) packaged in [MISSION_ITEM_INT](../messages/common.md#MISSION_ITEM_INT) messages. Protocol implementations must also support [MISSION_ITEM](../messages/common.md#MISSION_ITEM) and [MISSION_REQUEST](../messages/common.md#MISSION_REQUEST) in the same way. -### Set Current Mission Item {#current_mission_item} - -The diagram below shows the communication sequence to set the current mission item. - -[![Mermaid Diagram: Set mission item](https://mermaid.ink/img/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtO1xuICAgIHBhcnRpY2lwYW50IEdDU1xuICAgIHBhcnRpY2lwYW50IERyb25lXG4gICAgR0NTLT4-RHJvbmU6IE1JU1NJT05fU0VUX0NVUlJFTlRcbiAgICBEcm9uZS0tPj5HQ1M6IE1JU1NJT05fQ1VSUkVOVCIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtO1xuICAgIHBhcnRpY2lwYW50IEdDU1xuICAgIHBhcnRpY2lwYW50IERyb25lXG4gICAgR0NTLT4-RHJvbmU6IE1JU1NJT05fU0VUX0NVUlJFTlRcbiAgICBEcm9uZS0tPj5HQ1M6IE1JU1NJT05fQ1VSUkVOVCIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9) - - - -In more detail, the sequence of operations is: - -1. GCS/App sends [MAV_CMD_DO_SET_MISSION_CURRENT](#MAV_CMD_DO_SET_MISSION_CURRENT) (or [MISSION_SET_CURRENT](#MISSION_SET_CURRENT)), specifying the new sequence number (`seq`). -1. Drone receives message and attempts to update the current mission sequence number. - - On success, the Drone must _broadcast_ a [MISSION_CURRENT](../messages/common.md#MISSION_CURRENT) message containing the current sequence number (`seq`). - - On failure, the Drone must _broadcast_ a [STATUSTEXT](../messages/common.md#STATUSTEXT) with a [MAV_SEVERITY](../messages/common.md#MAV_SEVERITY) and a string stating the problem. - This may be displayed in the UI of receiving systems. - -Notes: - -- There is no specific [timeout](#timeout) on `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](#errors) in other operations. - This approach is used because the success/failure is relevant to all mission-handling clients. - -### Monitor Mission Progress {#monitor_progress} - -GCS/developer API can monitor progress by handling the appropriate messages sent by the drone: - -- The vehicle must broadcast a [MISSION_ITEM_REACHED](../messages/common.md#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](../messages/common.md#MISSION_CURRENT) message if the [current mission item](#current_mission_item) is changed. - ### Clear Missions {#clear_mission} The diagram below shows the communication sequence to clear the mission from a drone (assuming all operations succeed). @@ -381,17 +361,19 @@ Note: ## Executing Missions -Following full mission upload, or vehicle restart, or mission reset, all jump counter loops are set to their initial values. -The current mission item is normally reset to one on mission reset or vehicle restart, or on mission upload when the vehicle is landed. -The current mission item may retain its current value if a mission is uploaded in-air or it may be set to the mission item that has `current` set in a mission item (this field is ignored in ArduPilot but respected by PX4). +Following a [mission reset](#resetting-missions), for example after rebooting the vehicle, all jump counter loops are set to their initial values and the current mission item is set to 1. For a mission to be executed the vehicle must be armed and in the flight stack's mission mode. There may (or may not) be further requirements to start a mission. -For example PX4 will start as soon as you arm in mission mode, while ArduCopter in its default configuration requires that the throttle is raised. -Similarly, planes that are configured for throttle/hand launch may require a minimum acceleration before the mission is executed. +For example PX4 will start as soon as you arm in mission mode, while ArduCopter (in its default configuration) requires that the throttle is raised. +Similarly, planes that are configured for throttle/hand launch may require a minimum acceleration before the mission execution starts. While executing, the vehicle will progress sequentially through the mission items, looping and jumping in response to jump commands. -The mission can be paused by changing to another flight mode, such as Hold/loiter, and restarted by changing back to mission mode (when armed). +A mission can be paused and restarted by calling [MAV_CMD_DO_PAUSE_CONTINUE](#MAV_CMD_DO_PAUSE_CONTINUE). +Pausing a mission causes fixed wing vehicles (planes) to loiter in a circular flight pattern, while hovering vehicles will loiter/hold in place. +Note that pausing may be implemented by forcing a mode change, such as to Hold/Loiter mode, or by pausing within the mission mode context. + +A mission may also be paused by changing to another flight mode, such as Hold/loiter, and restarted by changing back to mission mode (when armed). On restart the vehicle will _generally_ continue towards the same waypoint item as when it was paused. In some cases flight stacks may start from the preceding waypoint, for example, a paused camera survey may restart on the previous waypoint to ensure the whole paused leg is captured. Note that there is no concept of "stopping" a mission independent of pausing it. @@ -407,26 +389,84 @@ Note however that unless the command [resets the mission](#resetting-missions), A flight stack will usually run mission checks before allowing a vehicle to enter the mission executing mode (typically checks are run when first executing a mission, but some flight stacks might also check before continuing a paused mission). -Provided the checks pass, you can start a mission by either switching to mission mode and arming, or arming and switching to mission mode. -With mavlink we can change the mode using [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) to set the mode and ARM using[MAV_CMD_COMPONENT_ARM_DISARM](../messages/common.md#MAV_CMD_COMPONENT_ARM_DISARM). +Provided the checks pass, you can start a mission by switching to mission mode and arming (or arming and switching to mission mode). +Depending on the vehicle type you may also need to provide an additional trigger, such as increasing throttle, or a hand/catapult launch. -If supported the [MAV_CMD_MISSION_START](../messages/common.md#MAV_CMD_MISSION_START) command will both arm the vehicle (if necessary) and switch to the mission mode. +You can use the [MAV_CMD_MISSION_START](../messages/common.md#MAV_CMD_MISSION_START) command to both arm the vehicle (if necessary) and switch to the mission mode - but not to provide any additional trigger, if required. This command also allows you to specify a particular start and end item in the mission. +The arm/mode change operation can also be done using [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) and [MAV_CMD_COMPONENT_ARM_DISARM](../messages/common.md#MAV_CMD_COMPONENT_ARM_DISARM). + ### Pausing/Stopping Missions -Pause and stop missions by changing mode. -In MAVLink this can be done using [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) (generally a vehicle will also support changing modes via an RC controller/joystick too). +To pause/restart a mission call [MAV_CMD_DO_PAUSE_CONTINUE](#MAV_CMD_DO_PAUSE_CONTINUE). +Pausing a mission causes vehicles to loiter (forward-flying vehicles fly in a circle, vehicle that can hold position do so). + +You can also pause/restart a mission by switching between mission mode and any other mode. +This can be done, for example, using [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) (generally a vehicle will also support changing modes via an RC controller/joystick too). ### Resetting Missions Once a mission has started it will iterate through the mission items, jumping and looping as indicated by jump mission items, until it completes. -While the mission is running you can change the current mission item, but this does not by reset the jump counters used for loops, and once the mission is complete, changing the current mission item will not restart it (with an exception outlined below). +Once complete the mission must be _reset_ before it can be restarted. +Resetting removes the "complete" flag so the mission can execute. +It should also set the current mission item to 0 and reset the loop counters used to track how many times each JUMP command in the mission has looped. + +A mission will reset when: + +- The vehicle is rebooted (on all flight stacks). +- A full mission is uploaded. A partial upload may not reset jump counters/mission execution. +- On disarming for **some vehicles** and configurations. + This depends on whether the vehicle needs to continue a mission after landing/disarming. +- When [MAV_CMD_DO_SET_MISSION_CURRENT](#current_mission_item) is used to set the mission current to `0`. + Note that PX4 clears the complete flag and sets the mission item to zero, but does not reset jump counters. + + +### Set Current Mission Item {#current_mission_item} -The mission will reset after you land and the vehicle disarms. -It is also reset following a vehicle reboot. +The [MAV_CMD_DO_SET_MISSION_CURRENT](#MAV_CMD_DO_SET_MISSION_CURRENT) command can be used to change the current mission item, and hence the target waypoint for either a running or paused mission. +Note that setting a non-zero positive mission item number will not reset mission jump counters, or restart a completed mission (even though the current mission item would change). +If the mission item is set to `0` the mission will be [reset](#resetting-missions) (on PX4 jump counters are not reset). -[MAV_CMD_DO_SET_MISSION_CURRENT.param2](../messages/common.md#MAV_CMD_DO_SET_MISSION_CURRENT) can also be used to reset the mission, if supported on the flight stack. +> **Note** The current mission item may also be set on mission upload by applying the `current` field on one mission item. +> The field is not needed because you can aways set the current mission item after upload. +> This field is ignored in ArduPilot but respected by PX4. + +The diagram below shows the communication sequence to set the current mission item. + +[![Mermaid Diagram: Set mission item](https://mermaid.ink/img/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtO1xuICAgIHBhcnRpY2lwYW50IEdDU1xuICAgIHBhcnRpY2lwYW50IERyb25lXG4gICAgR0NTLT4-RHJvbmU6IE1JU1NJT05fU0VUX0NVUlJFTlRcbiAgICBEcm9uZS0tPj5HQ1M6IE1JU1NJT05fQ1VSUkVOVCIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtO1xuICAgIHBhcnRpY2lwYW50IEdDU1xuICAgIHBhcnRpY2lwYW50IERyb25lXG4gICAgR0NTLT4-RHJvbmU6IE1JU1NJT05fU0VUX0NVUlJFTlRcbiAgICBEcm9uZS0tPj5HQ1M6IE1JU1NJT05fQ1VSUkVOVCIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9) + + + +In more detail, the sequence of operations is: + +1. GCS/App sends [MAV_CMD_DO_SET_MISSION_CURRENT](#MAV_CMD_DO_SET_MISSION_CURRENT). +1. Drone receives message and attempts to update the current mission sequence number. + - On success, the Drone must _broadcast_ a [MISSION_CURRENT](../messages/common.md#MISSION_CURRENT) message containing the current sequence number (`seq`). + - On failure, the Drone must _broadcast_ a [STATUSTEXT](../messages/common.md#STATUSTEXT) with a [MAV_SEVERITY](../messages/common.md#MAV_SEVERITY) and a string stating the problem. + This may be displayed in the UI of receiving systems. + +Notes: + +- There is no specific [timeout](#timeout) on `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](#errors) in other operations. + This approach is used because the success/failure is relevant to all mission-handling clients. + +### Monitor Mission Progress {#monitor_progress} + +GCS/developer API can monitor progress by handling the appropriate messages sent by the drone: + +- The vehicle must broadcast a [MISSION_ITEM_REACHED](../messages/common.md#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 stream a [MISSION_CURRENT](../messages/common.md#MISSION_CURRENT) message and also emit it if the [current mission item](#current_mission_item) is changed. + This includes the current mission item, the state of the mission (paused, etc.), and unique ids for the current plan types (these can be used to detect when a plan has changed). ## Mission File Formats From 39df0b244495c55e9b1f95ce204d8e6eac25f8aa Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 6 Mar 2024 12:24:12 +1100 Subject: [PATCH 8/8] Simplify introduction --- en/services/mission.md | 78 ++++++++++++++++++------------------------ 1 file changed, 34 insertions(+), 44 deletions(-) diff --git a/en/services/mission.md b/en/services/mission.md index d8838bdd2..3fbecffec 100644 --- a/en/services/mission.md +++ b/en/services/mission.md @@ -361,37 +361,22 @@ Note: ## Executing Missions -Following a [mission reset](#resetting-missions), for example after rebooting the vehicle, all jump counter loops are set to their initial values and the current mission item is set to 1. - -For a mission to be executed the vehicle must be armed and in the flight stack's mission mode. -There may (or may not) be further requirements to start a mission. -For example PX4 will start as soon as you arm in mission mode, while ArduCopter (in its default configuration) requires that the throttle is raised. -Similarly, planes that are configured for throttle/hand launch may require a minimum acceleration before the mission execution starts. -While executing, the vehicle will progress sequentially through the mission items, looping and jumping in response to jump commands. - -A mission can be paused and restarted by calling [MAV_CMD_DO_PAUSE_CONTINUE](#MAV_CMD_DO_PAUSE_CONTINUE). -Pausing a mission causes fixed wing vehicles (planes) to loiter in a circular flight pattern, while hovering vehicles will loiter/hold in place. -Note that pausing may be implemented by forcing a mode change, such as to Hold/Loiter mode, or by pausing within the mission mode context. - -A mission may also be paused by changing to another flight mode, such as Hold/loiter, and restarted by changing back to mission mode (when armed). -On restart the vehicle will _generally_ continue towards the same waypoint item as when it was paused. -In some cases flight stacks may start from the preceding waypoint, for example, a paused camera survey may restart on the previous waypoint to ensure the whole paused leg is captured. -Note that there is no concept of "stopping" a mission independent of pausing it. +Once the mission is started it will progress sequentially through the mission items, looping and jumping in response to jump commands. +It can be paused and restarted, and the current mission item can be changed. On completion of all mission items the mission will "complete". -At this point some flight stacks will loiter within the mission mode, while others will transition to some other mode (such as "Hold") and not allow you to return to mission mode. +At this point some flight stacks will loiter within the mission mode, while others will transition to some other mode (such as "Hold" or "Return") and not allow you to return to mission mode. In either case, the mission cannot be restarted unless it is [reset](#resetting-missions). -While the mission is executing the current mission item can be changed via MAVLink ([MAV_CMD_DO_SET_MISSION_CURRENT](#MAV_CMD_DO_SET_MISSION_CURRENT)). -Note however that unless the command [resets the mission](#resetting-missions), this does not reset the jump counters, and if the mission is complete, will not restart the mission. - ### Starting Missions -A flight stack will usually run mission checks before allowing a vehicle to enter the mission executing mode (typically checks are run when first executing a mission, but some flight stacks might also check before continuing a paused mission). - -Provided the checks pass, you can start a mission by switching to mission mode and arming (or arming and switching to mission mode). -Depending on the vehicle type you may also need to provide an additional trigger, such as increasing throttle, or a hand/catapult launch. +For a mission to be executed the vehicle must be armed and in the flight stack's mission mode: +- A flight stack will usually run mission checks before allowing a vehicle to enter the mission executing mode (typically checks are run when first executing a mission, but some flight stacks might also check before continuing a paused mission). +- There may (or may not) be further requirements to start a mission depending on flight stack, vehicle type, and configuration. + For example PX4 multicopter will start as soon as you arm in mission mode, while ArduCopter (in its default configuration) requires that the throttle is raised. + Similarly, planes that are configured for throttle/hand launch may require a minimum acceleration before the mission execution starts. + You can use the [MAV_CMD_MISSION_START](../messages/common.md#MAV_CMD_MISSION_START) command to both arm the vehicle (if necessary) and switch to the mission mode - but not to provide any additional trigger, if required. This command also allows you to specify a particular start and end item in the mission. @@ -399,28 +384,16 @@ The arm/mode change operation can also be done using [MAV_CMD_DO_SET_MODE](../me ### Pausing/Stopping Missions -To pause/restart a mission call [MAV_CMD_DO_PAUSE_CONTINUE](#MAV_CMD_DO_PAUSE_CONTINUE). -Pausing a mission causes vehicles to loiter (forward-flying vehicles fly in a circle, vehicle that can hold position do so). - -You can also pause/restart a mission by switching between mission mode and any other mode. -This can be done, for example, using [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) (generally a vehicle will also support changing modes via an RC controller/joystick too). - -### Resetting Missions - -Once a mission has started it will iterate through the mission items, jumping and looping as indicated by jump mission items, until it completes. -Once complete the mission must be _reset_ before it can be restarted. -Resetting removes the "complete" flag so the mission can execute. -It should also set the current mission item to 0 and reset the loop counters used to track how many times each JUMP command in the mission has looped. +To pause/restart a mission call [MAV_CMD_DO_PAUSE_CONTINUE](#MAV_CMD_DO_PAUSE_CONTINUE) (there is no concept of "stopping" a mission independent of pausing it). -A mission will reset when: +Pausing a mission causes vehicles to loiter (forward-flying vehicles fly in a circle, vehicles that can hold position do so). +Note that pausing may be implemented by forcing a mode change, such as to Hold/Loiter mode, or by pausing within the mission mode context. +On restart the vehicle will _generally_ continue towards the same waypoint item as when it was paused. +In some cases flight stacks may start from the preceding waypoint, for example, a paused camera survey may restart on the previous waypoint to ensure the whole paused leg is captured. -- The vehicle is rebooted (on all flight stacks). -- A full mission is uploaded. A partial upload may not reset jump counters/mission execution. -- On disarming for **some vehicles** and configurations. - This depends on whether the vehicle needs to continue a mission after landing/disarming. -- When [MAV_CMD_DO_SET_MISSION_CURRENT](#current_mission_item) is used to set the mission current to `0`. - Note that PX4 clears the complete flag and sets the mission item to zero, but does not reset jump counters. - +A mission may also be paused by changing to another flight mode, such as Hold/loiter, and restarted by changing back to mission mode (when armed). +This can be done, for example, using [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) (generally a vehicle will also support changing modes via an RC controller/joystick too). +Note that if you change to modes that use mission functionality, such as a fixed wing return mode that uses a mission-defined landing mode, the vehicle may switch back to mission mode for the implementation. ### Set Current Mission Item {#current_mission_item} @@ -459,6 +432,23 @@ Notes: This differs from [error handling](#errors) in other operations. This approach is used because the success/failure is relevant to all mission-handling clients. +### Resetting Missions + +Once a mission has started it will iterate through the mission items, jumping and looping as indicated by jump mission items, until it completes. +Once complete the mission must be _reset_ before it can be restarted. +Resetting removes the "complete" flag so the mission can execute. +It should also set the current mission item to 0 and reset the loop counters used to track how many times each JUMP command in the mission has looped. + +A mission will reset when: + +- The vehicle is rebooted (on all flight stacks). +- A full mission is uploaded. A partial upload may not reset jump counters/mission execution. +- On disarming for **some vehicles** and configurations. + This depends on whether the vehicle needs to continue a mission after landing/disarming. +- When [MAV_CMD_DO_SET_MISSION_CURRENT](#current_mission_item) is used to set the mission current to `0`. + Note that PX4 clears the complete flag and sets the mission item to zero, but does not reset jump counters. + + ### Monitor Mission Progress {#monitor_progress} GCS/developer API can monitor progress by handling the appropriate messages sent by the drone: