mirror of
https://github.com/mavlink/mavlink-devguide.git
synced 2026-06-19 07:36:26 +00:00
Add WIP and clarifications
This commit is contained in:
Hamish Willee
+1
-1
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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 |
|
||||
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <a id="CURRENT_MODE"></a>[CURRENT_MODE](../messages/development.md#CURRENT_MODE) | . |
|
||||
| <a id="AVAILABLE_MODES"></a>[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). |
|
||||
| <a id="AVAILABLE_MODES_MONITOR"></a>[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 |
|
||||
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <a id="CURRENT_MODE"></a>[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. |
|
||||
| <a id="AVAILABLE_MODES"></a>[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). |
|
||||
| <a id="AVAILABLE_MODES_MONITOR"></a>[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 |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
|
||||
| <a id="MAV_CMD_DO_SET_STANDARD_MODE"></a>[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. |
|
||||
| <a id="MAV_CMD_REQUEST_MESSAGE"></a>[MAV_CMD_REQUEST_MESSAGE](../messages/common.md#MAV_CMD_REQUEST_MESSAGE) | Used to request [AVAILABLE_MODES](#AVAILABLE_MODES) message |
|
||||
| Command | Description |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <a id="MAV_CMD_DO_SET_STANDARD_MODE"></a>[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. |
|
||||
| <a id="MAV_CMD_REQUEST_MESSAGE"></a>[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)
|
||||
|
||||
<!--
|
||||
@@ -109,12 +114,12 @@ sequenceDiagram;
|
||||
In addition to the fields for enumerating the available modes, `AVAILABLE_MODES` has the following fields:
|
||||
|
||||
- `standard_mode`: The standard mode represented by this `AVAILABLE_MODES` ([MAV_STANDARD_MODE](#MAV_STANDARD_MODE)). `0` for a custom mode that is not also a standard mode (`MAV_STANDARD_MODE_NON_STANDARD`).
|
||||
- `custom_mode`: The id of the custom mode represented by this `AVAILABLE_MODES`.
|
||||
- `properties`: Flags indicatig the UI properties of this mode.
|
||||
- `custom_mode`: The id of the custom mode represented by this `AVAILABLE_MODES` (if any).
|
||||
- `properties`: Flags indicating the UI properties of this mode.
|
||||
These provide hints about where the mode can/should appear in the UI.
|
||||
For example, `MAV_MODE_PROPERTY_NOT_USER_SELECTABLE` indicates that the mode should not appear in selection lists, while `MAV_MODE_PROPERTY_ADVANCED` indicates a mode that is harder to fly, and might be separated from other modes in the UI.
|
||||
- `mode_name`: Mode name, with null termination character.
|
||||
- The field can act as both a key for determining mode metadata, or as a fallback string if the GCS has no metadata for the mode.
|
||||
For example, `MAV_MODE_PROPERTY_NOT_USER_SELECTABLE` indicates that the mode should not be set by a user, and hence should not appear in selection lists, while `MAV_MODE_PROPERTY_ADVANCED` indicates a mode that is harder to fly, and might be visually separated from other modes in the UI.
|
||||
- `mode_name`: Mode metadata key or name, with null termination character.
|
||||
- The field can act as both a key for determining metadata associated with the mode, or as a fallback name to use for the mode if the GCS has no metadata.
|
||||
- It can be used to override metadata on existing modes, for example to enhance standard metadata with additional information about autopilot-specific behaviour, or can provide metadata for any other static or dynamic mode.
|
||||
- The field must be human readable and autopilot-unique.
|
||||
- Generally does not have to be set for standard modes, where the ground station might be expected to already have metadata (but if it is, it will be used as a metadata key).
|
||||
@@ -146,8 +151,11 @@ Note that the current custom mode is also published in the [HEARTBEAT](https://m
|
||||
|
||||
The [AVAILABLE_MODES_MONITOR](#AVAILABLE_MODES_MONITOR) is an optional part of the protocol that allows a MAVLink system to dynamically change the set of modes it supports at runtime (for example, using Lua or other onboard scripting languages, or offboard from a companion computer).
|
||||
|
||||
The message has a sequence number field that that should be iterated sequentially whenever the set of available modes change.
|
||||
It should be streamed at low rate (nominally 0.1 Hz) and when the set of available modes change.
|
||||
The message sequence number field is iterated sequentially whenever the set of available modes change.
|
||||
A GCS can detect this change and re-request the set of [AVAILABLE_MODES](#AVAILABLE_MODES).
|
||||
|
||||
The message should be emitted when the set of available modes changes.
|
||||
After the set of modes changes the first time, it should also be streamed at low rate (nominally 0.1 Hz).
|
||||
|
||||
## Mode Metadata
|
||||
|
||||
@@ -174,4 +182,7 @@ Note that the `mode_name` must be human readable and unique for the autopilot.
|
||||
## Implementations
|
||||
|
||||
PX4 v1.15 and later supports this service, including the optional part (`AVAILABLE_MODES_MONITOR`) (this allows ROS2 modes added using the [PX4 ROS 2 Interface Library](https://docs.px4.io/main/en/ros2/px4_ros2_interface_lib.html) to be dynamically updated in a GCS).
|
||||
QGC also supports this feature.
|
||||
At time of writing it only exposes the standard modes that are common to all vehicles as standard modes, such as takeoff and landing, and missions.
|
||||
|
||||
QGC also uses this service to build the mode display/setting UI, when supported by the autopilot.
|
||||
This feature is supported in daily builds (at time of writing).
|
||||
|
||||
Reference in New Issue
Block a user