diff --git a/en/SUMMARY.md b/en/SUMMARY.md
index dd794e89..9c1fa76d 100644
--- a/en/SUMMARY.md
+++ b/en/SUMMARY.md
@@ -80,7 +80,7 @@
* [Payload Protocols](services/payload.md)
* [Traffic Management (UTM/ADS-B)](services/traffic_management.md)
* [Events Interface (WIP)](services/events.md)
- * [Standard Flight Modes](services/standard_modes.md)
+ * [Standard Flight Modes (WIP)](services/standard_modes.md)
* [Time Synchronization](services/timesync.md)
* [Contributing](contributing/contributing.md)
* [Support](about/support.md)
diff --git a/en/services/README.md b/en/services/README.md
index b3ab8a4d..6eb83f1f 100644
--- a/en/services/README.md
+++ b/en/services/README.md
@@ -40,6 +40,6 @@ The main microservices are shown in the sidebar (most are listed below):
- [Payload Protocol](../services/payload.md)
- [Traffic Management (UTM/ADS-B)](../services/traffic_management.md)
- [Events Interface (WIP)](../services/events.md)
-- [Standard Flight Modes](../services/standard_modes.md)
+- [Standard Flight Modes (WIP)](../services/standard_modes.md)
- [Time Synchronization](../services/timesync.md)
- [Illuminator Protocol](../services/illuminator.md)
diff --git a/en/services/standard_modes.md b/en/services/standard_modes.md
index 936eaa96..6b3d0033 100644
--- a/en/services/standard_modes.md
+++ b/en/services/standard_modes.md
@@ -1,4 +1,7 @@
-# Standard Modes Protocol
+# Standard Modes Protocol (WIP)
+
+> **Warning** This protocol is a work in progress and may change.
+> It has an initial implementation in PX4 and QGroundControl (daily).
The MAVLink standard modes protocol allows a GCS to construct a UI allowing selection and display of available flight modes without prior knowledge of the connected flight stack.
@@ -8,18 +11,19 @@ The protocol provides:
These are modes that behave similarly enough across flight stacks that users can select and control them in the same way.
For example, modes for taking off and landing, executing missions, holding position, and so on.
- Enumeration of all flight modes supported by the flight stack, both standard and custom.
- This includes includes information about whether particular modes can be selected or just displayed, and if they are displayed, whether they are advanced.
- For custom modes it includes a name string that can be used in the UI.
-- Notification of the current mode
+
+ The provided flight mode information includes:
+
+ - Flags indicating whether particular custom modes can be selected or just displayed, and if they are displayed, whether they are advanced.
+ - A name/metadata string that can either be used to fetch metadata for the mode (such as a name and description), or directly as the name for custom modes.
+
+- Notification of the current mode.
- A command to set a standard mode.
There are additional optional messages/features to allow:
-- Modes to be enabled and disabled dynamically
-- Overriding of mode metadata (provide a metadata key)
-
-A GCS can use this service to create a UI that only uses (well understood) standard modes.
-It can also choose to expose custom modes, though in this case the only information that a user can infer is the name of the mode.
+- Modes to be enabled and disabled dynamically.
+- Overriding of mode metadata (provide a metadata key).
## Background
@@ -27,7 +31,7 @@ MAVLink previously only standardized very high level _base modes_ (defined in [M
More specific flight behaviour/modes are defined in _custom modes_, which are specific to each flight stack.
Mechanisms are provided to set the base and custom modes ([MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE)), and the `HEARTBEAT` contains the current/active `base_mode` and `custom_mode`.
-However, prior to the addition of this service, there were no mechanisms query the available custom modes.
+However, prior to the addition of this service, there were no mechanisms query the available custom modes, so a GCS would have to know about a flight stack in advance in order to construct its mode display and setting UI.
Most autopilots implement a set of custom flight modes that have very similar behaviour or intent, for example: position-hold mode, altitude-hold mode, mission mode, safety return/RTL.
However because these are all identified by different custom mode identifiers on different flight stacks, there is no way to be sure what these "mean" without pre-existing knowledge.
@@ -41,11 +45,11 @@ For more information see [MAVLink RFC0016 Standard modes](https://github.com/mav
### Messages
-| Message | Description |
-| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [CURRENT_MODE](../messages/development.md#CURRENT_MODE) | . |
-| [AVAILABLE_MODES](../messages/development.md#AVAILABLE_MODES) | Get information about all available modes (both standard and custom) allowing generation of a UI and setting of modes. Requested using [MAV_CMD_REQUEST_MESSAGE](`MAV_CMD_REQUEST_MESSAGE`) (set param2=0 for all modes). |
-| [AVAILABLE_MODES_MONITOR](../messages/development.md#AVAILABLE_MODES_MONITOR) | Provides a sequence number that allows clients to determine if the set of available modes has changed, and hence whether the [AVAILABLE_MODES](#AVAILABLE_MODES) must be re-requested. |
+| Message | Description |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [CURRENT_MODE](../messages/development.md#CURRENT_MODE) | Get information about the current active mode, including both its standard and custom mode identifiers (if defined). Also "the intended mode", to indicate the case where setting a mode failed. |
+| [AVAILABLE_MODES](../messages/development.md#AVAILABLE_MODES) | Get information about all available modes (both standard and custom) allowing generation of a UI and setting of modes. Requested using [MAV_CMD_REQUEST_MESSAGE](`MAV_CMD_REQUEST_MESSAGE`) (set param2=0 for all modes). |
+| [AVAILABLE_MODES_MONITOR](../messages/development.md#AVAILABLE_MODES_MONITOR) | Provides a sequence number that allows clients to determine if the set of available modes has changed, and hence whether the [AVAILABLE_MODES](#AVAILABLE_MODES) must be re-requested. Sent on first mode change and subsequently streamed at low rate. |
### Enums
@@ -57,18 +61,17 @@ For more information see [MAVLink RFC0016 Standard modes](https://github.com/mav
### Commands
-| Command | Description |
-| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| [MAV_CMD_DO_SET_STANDARD_MODE](../messages/development.md#MAV_CMD_DO_SET_STANDARD_MODE) | Enable the specified standard MAVLink mode ([MAV_STANDARD_MODE] |
-| (#MAV_STANDARD_MODE)). ACK with MAV_RESULT_FAILED if the mode is not supported by the vehicle. |
-| [MAV_CMD_REQUEST_MESSAGE](../messages/common.md#MAV_CMD_REQUEST_MESSAGE) | Used to request [AVAILABLE_MODES](#AVAILABLE_MODES) message |
+| Command | Description |
+| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [MAV_CMD_DO_SET_STANDARD_MODE](../messages/development.md#MAV_CMD_DO_SET_STANDARD_MODE) | Enable the specified standard MAVLink mode ([MAV_STANDARD_MODE](#MAV_STANDARD_MODE)). ACK with [MAV_RESULT_FAILED](../messages/development.md#MAV_RESULT_FAILED) if the mode is not supported by the vehicle. |
+| [MAV_CMD_REQUEST_MESSAGE](../messages/common.md#MAV_CMD_REQUEST_MESSAGE) | Used to request [AVAILABLE_MODES](#AVAILABLE_MODES) message |
## Operations
### Getting Available Modes
-All available modes can be enumerated by using [MAV_CMD_REQUEST_MESSAGE](#MAV_CMD_REQUEST_MESSAGE) to request the [AVAILABLE_MODES](#AVAILABLE_MODES) message, where `MAV_CMD_REQUEST_MESSAGE.param2` is set to `0`.
-Each `AVAILABLE_MODES` message includes the total number of modes and the index of the current mode, so a GCS can query for all modes, and then individually query for any `AVAILABLE_MODES` message that it missed by specifying their index in `MAV_CMD_REQUEST_MESSAGE.param2`.
+All available modes can be enumerated by using [MAV_CMD_REQUEST_MESSAGE](#MAV_CMD_REQUEST_MESSAGE) to request the [AVAILABLE_MODES (435)](#AVAILABLE_MODES) message.
+Each `AVAILABLE_MODES` message includes the total number of modes and the index of the current mode, so a GCS should first query for all modes (`MAV_CMD_REQUEST_MESSAGE.param2=0`), and then individually query for any `AVAILABLE_MODES` message that it missed (`MAV_CMD_REQUEST_MESSAGE.param2="missing index number"`).
Notes:
@@ -81,6 +84,8 @@ Notes:
- The modes that are emitted depend on the current vehicle type.
For example, "takeoff" would not be emitted for a rover type, but would for a copter.
+The sequence for requesting all modes is shown below:
+
[](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNqllF9L5DAUxb_KJU8t1EGd9aVSobZBZKf-mY4-FUpsb8dAk8wmKbsifnfTzIzuuLusOH0o4XLuOT-SmzyTRrVIYmLwx4CywZyzpWbitJLgvhXTljd8xaSFi6z8s5hrJXFdvlIWQfPlowXVjeoY5qOpscD6HoTLMRCk9-nlLD2f0bq4zmkZrnud-uDszJvFUKT3dVbk9Zze3tFyURe0LNMLGrhcJo6Sb9OTCPz6ODnc6feZpXV4YLlANdjfyHrsPNgmJM2-g97iyRYMut8HOOiUfmdfe_n2bVZ2XRTpVV47s0CjGXqbjPBzWt7NFq6a0ZsFzf_FGPRKLlGHu7A7AR-AAjmIB9S150kqIisSebiayxZ_JUfh_h7Hf_OYTCb7O8vwv4NiVtjwjjebaeGdO5snENwYLpcQPGCvfkbg7WBakRD2G5_pp8bn60e-z26NbCQiArVgvHU39Hn0rIh9RIEVid2yxY45gIpU8sVJh1XLLNKWW6VJ3LHeYETYYFX5JBsSWz3gVrS55W8q9E3F-inwL8LLK_5wSuk)