mirror/mavlink-devguide
1
0
Fork 0
mirror of https://github.com/mavlink/mavlink-devguide.git synced 2026-06-19 07:36:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Use native asides (#576)

Browse Source 
* Use vitepress native asides - prettier screws up githu

* minor clean

* prettier_output
This commit is contained in:
Hamish Willee
2024-11-28 10:09:22 +11:00
committed by GitHub
parent 356c5efd14
commit 63a111f366
49 changed files with 1062 additions and 833 deletions
Download Patch File Download Diff File Expand all files Collapse all files
en/about/overview.md
+4 -3
View File
@@ -28,9 +28,10 @@ uint16_t checksum; ///< CRC-16/MCRF4XX
uint8_t signature[13]; ///< Signature which allows ensuring that the link is tamper-proof (optional)
```
> [!NOTE]
> The [MAVLink 1 packet format](../guide/serialization.md#v1_packet_format) is similar, but omits `incompat_flags`, `compat_flags` and `signature`, and only has a single byte for the message address.
> For more information see [Serialization > Packet Format](../guide/serialization.md#packet_format).
::: info
The [MAVLink 1 packet format](../guide/serialization.md#v1_packet_format) is similar, but omits `incompat_flags`, `compat_flags` and `signature`, and only has a single byte for the message address.
For more information see [Serialization > Packet Format](../guide/serialization.md#packet_format).
:::
## Serialization
en/about/support.md
+4 -3
View File
@@ -14,9 +14,10 @@ If directed by the development team, issues may be raised on [Github here](https
MAVLink developers, adopting companies and the surrounding community of users meet regularly to help define the direction of the project, discuss RFCs, Issues and have a Q&A session.
> [!TIP]
> The call is open to anyone who wants to contribute to the ongoing development of the project (not just the dev team).
> This is a great opportunity to meet the team.
::: tip
The call is open to anyone who wants to contribute to the ongoing development of the project (not just the dev team).
This is a great opportunity to meet the team.
:::
#### Who should attend: {#who-should-attend}
en/contributing/contributing.md
+3 -2
View File
@@ -61,8 +61,9 @@ Primarily this means that the team developing the generator must provide suffici
git checkout -b mydescriptivebranchname
```
> [!NOTE]
> _Always_ branch off master for new features.
::: info
_Always_ branch off master for new features.
:::
3. Commit your changes with a descriptive commit message.
en/file_formats/index.md
+7 -5
View File
@@ -5,9 +5,10 @@ Often the information is defined on one system and used on another (e.g. logs fr
There is a _defacto_ standard used in many GCS systems and developer APIs for storing _mission_ information: [plain-text file format](#mission_plain_text_file).
> [!NOTE]
> At time of writing there are no MAVLink standards (defacto or otherwise) for: geofence, rally points, parameters etc.
> There is a discussion about standardising file formats in [Issue #989](https://github.com/mavlink/mavlink/issues/989).
::: info
At time of writing there are no MAVLink standards (defacto or otherwise) for: geofence, rally points, parameters etc.
There is a discussion about standardising file formats in [Issue #989](https://github.com/mavlink/mavlink/issues/989).
:::
## Mission Plain-Text File Format {#mission_plain_text_file}
@@ -22,8 +23,9 @@ QGC WPL <VERSION>
<INDEX> <CURRENT WP> <COORD FRAME> <COMMAND> <PARAM1> <PARAM2> <PARAM3> <PARAM4> <PARAM5/X/LATITUDE> <PARAM6/Y/LONGITUDE> <PARAM7/Z/ALTITUDE> <AUTOCONTINUE>
```
> [!NOTE]
> The spaces between the numbers/fields above are `<tab>` (i.e. `\t` in most programming languages).
::: info
The spaces between the numbers/fields above are `<tab>` (i.e. `\t` in most programming languages).
:::
For example:
en/getting_started/generate_libraries.md
+29 -20
View File
@@ -7,28 +7,33 @@ This page shows how to use the following two code generators provided with the M
- GUI tool: [mavgenerate](#mavgenerate)
- Command line tool: [mavgen](#mavgen), which is the backend tool used also by mavgenerate
> [!NOTE]
> These generators can build MAVLink 2 and MAVLink 1 libraries for the following programming languages: C, C++11, Python, Typescript, Java, and WLua. The following programming languages are supported for MAVLink 1 libraries only: C#, JavaScript, ObjC, Swift.
::: info
These generators can build MAVLink 2 and MAVLink 1 libraries for the following programming languages: C, C++11, Python, Typescript, Java, and WLua.
The following programming languages are supported for MAVLink 1 libraries only: C#, JavaScript, ObjC, Swift.
:::
> [!TIP]
> Generators for other programming languages are supported and documented in independent projects.
> For more information see [Supported Languages](../index.md#supported_languages).
::: tip
Generators for other programming languages are supported and documented in independent projects.
For more information see [Supported Languages](../index.md#supported_languages).
:::
## Pre-requisites
1. You must already have [Installed the MAVLink toolchain](../getting_started/installation.md), which includes the mavgenerate and mavgen tools used below as well as the [XML Message Definitions](../messages/index.md).
1. If you are generating messages for a [custom dialect](../messages/index.md#dialects), copy the dialect [XML definition file(s)](../messages/index.md#xml-definition-files--dialects) into the directory [message_definitions/v1.0/](https://github.com/mavlink/mavlink/tree/master/message_definitions/v1.0).
> [!NOTE]
> _mavgen_ can handle dialects that have relative paths for included XML files (e.g typically [common.xml](../messages/common.md)), but other generators may not.
> We recommend putting custom dialects in the same folder as the ones that come with the [mavlink/mavlink](https://github.com/mavlink/mavlink) repository.
::: info
_mavgen_ can handle dialects that have relative paths for included XML files (e.g typically [common.xml](../messages/common.md)), but other generators may not.
We recommend putting custom dialects in the same folder as the ones that come with the [mavlink/mavlink](https://github.com/mavlink/mavlink) repository.
:::
## Building MAVLink libraries using the Mavgenerate GUI {#mavgenerate}
**mavgenerate.py** is GUI code generator for MAVLink, written in Python.
> [!NOTE]
> _Mavgenerate_ provides a GUI front end to the [mavgen](#mavgen) command line code generator, and supports the same [options](#mavgen_options).
::: info
_Mavgenerate_ provides a GUI front end to the [mavgen](#mavgen) command line code generator, and supports the same [options](#mavgen_options).
:::
The GUI can be launched from anywhere using Python's `-m` argument:
@@ -42,8 +47,9 @@ Steps for generating the MAVLink library code:
1. Choose the target XML file (typically in [mavlink/message_definitions/1.0](https://github.com/mavlink/mavlink/tree/master/message_definitions/v1.0)).
> [!NOTE]
> If using a custom dialect, first copy it into the above directory (if the dialect is dependent on **common.xml** it must be located in the same directory).
::: info
If using a custom dialect, first copy it into the above directory (if the dialect is dependent on **common.xml** it must be located in the same directory).
:::
1. Choose an output directory (e.g. **mavlink/include**).
1. Select the target output programming language.
@@ -58,10 +64,11 @@ Steps for generating the MAVLink library code:
1. Select the target MAVLink protocol version. Ideally use 2.0 if the generator supports it.
> **Caution** Generation will fail if the protocol is not [supported](../index.md#supported_languages) by the selected programming language.
::: warning
Generation will fail if the protocol is not [supported](../index.md#supported_languages) by the selected programming language.
:::
1. Optionally check _Validate_ and/or _Validate Units_, which validates XML specifications.
1. Click **Generate** to create the source files for the MAVLink library and the chosen dialect.
## Building MAVLink libraries using the Mavgen Command Line Tool {#mavgen}
@@ -69,9 +76,10 @@ Steps for generating the MAVLink library code:
**mavgen.py** is a command line tool for generating MAVLink libraries for various programming languages.
You can run mavgen from the `mavlink` directory. However, if you are outside of the mavlink directory, you need to add the `mavlink` directory to the `PYTHONPATH` environment variable.
> [!TIP]
> Mavgen is the backend used by [mavgenerate](#mavgenerate).
> The documentation below explains all the options for both tools.
::: tip
Mavgen is the backend used by [mavgenerate](#mavgenerate).
The documentation below explains all the options for both tools.
:::
Below is an example for how to generate _MAVLink 2_ libraries for the C programming language using a dialect named **your_custom_dialect.xml**:
@@ -79,12 +87,13 @@ Below is an example for how to generate _MAVLink 2_ libraries for the C programm
python3 -m pymavlink.tools.mavgen --lang=C --wire-protocol=2.0 --output=generated/include/mavlink/v2.0 message_definitions/v1.0/your_custom_dialect.xml
```
> [!NOTE]
> The syntax for for generating Python modules is the same, except that the `--output` specifies a _filename_ rather than a directory.
::: info
The syntax for for generating Python modules is the same, except that the `--output` specifies a _filename_ rather than a directory.
:::
<!-- https://github.com/ArduPilot/pymavlink/issues/203 -->
<span id="mavgen_options"></span>
<a id="mavgen_options"></a>
The full syntax and options can be output by running `mavgen.py -h` flag, which is reproduced below:
```
en/getting_started/installation.md
+4 -3
View File
@@ -2,9 +2,10 @@
This topic explains how to install the [MAVLink toolchain](https://github.com/mavlink/mavlink). The toolchain includes the [XML message definitions](../messages/index.md) as well as the the GUI/command line tools that use the definitions to [Generate MAVLink Source Files](../getting_started/generate_libraries.md).
> [!TIP]
> You do not need to install or generate the source files if you are using the C programming language and a standard [dialect](../messages/index.md#dialects).
> Just get the [prebuilt libraries](../index.md#prebuilt_libraries) and then jump to [Using C Libraries](../mavgen_c/index.md).
::: tip
You do not need to install or generate the source files if you are using the C programming language and a standard [dialect](../messages/index.md#dialects).
Just get the [prebuilt libraries](../index.md#prebuilt_libraries) and then jump to [Using C Libraries](../mavgen_c/index.md).
:::
## Prerequisites
en/getting_started/use_libraries.md
+4 -3
View File
@@ -2,9 +2,10 @@
The linked documents explain how to use the MAVLink libraries for different programming languages (and from different code generators).
> [!NOTE]
> Not all of the libraries are documented.
> If you have experience with the other libraries, please help us update those sections!
::: info
Not all of the libraries are documented.
If you have experience with the other libraries, please help us update those sections!
:::
- Mavgen
en/guide/crc.md
+7 -5
View File
@@ -2,12 +2,14 @@
MAVLink services that need to use a Cyclic Redundancy Check (CRC) should choose the CRC32 algorithm described below.
> [!NOTE]
> Using the same CRC implementation for all cases means that only one implementation is required.
> Do not introduce another unless there without a compelling technical reason.
::: info
Using the same CRC implementation for all cases means that only one implementation is required.
Do not introduce another unless there without a compelling technical reason.
:::
> [!NOTE]
> This CRC is [used for higher level services](#implementations) (it is not related to the CRC16 used for the checksum in [MAVLink serialization](serialization.md#checksum)).
::: info
This CRC is [used for higher level services](#implementations) (it is not related to the CRC16 used for the checksum in [MAVLink serialization](serialization.md#checksum)).
:::
## CRC32 Algorithm
en/guide/define_xml_element.md
+96 -74
View File
@@ -4,11 +4,13 @@ MAVLink enums, messages, commands, and other elements are [defined within XML fi
This topic provides practical guidance for defining and extending MAVLink XML elements, including conventions and best-practice.
> [!NOTE]
> For detailed information about the file format see [MAVLink XML Schema](../guide/xml_schema.md) (you can also inspect [common.xml](https://github.com/mavlink/mavlink/tree/master/message_definitions/v1.0/common.xml) and other dialect files).
::: info
For detailed information about the file format see [MAVLink XML Schema](../guide/xml_schema.md) (you can also inspect [common.xml](https://github.com/mavlink/mavlink/tree/master/message_definitions/v1.0/common.xml) and other dialect files).
:::
> [!TIP]
> Before submitting a pull request for a change to a [dialect xml file](../messages/index.md), you should first [regenerate the dialect library](../getting_started/generate_libraries.md) _with validation enabled_, and then run the [./scripts/format_xml.sh](https://github.com/mavlink/mavlink/blob/master/scripts/format_xml.sh) script.
::: tip
Before submitting a pull request for a change to a [dialect xml file](../messages/index.md), you should first [regenerate the dialect library](../getting_started/generate_libraries.md) _with validation enabled_, and then run the [./scripts/format_xml.sh](https://github.com/mavlink/mavlink/blob/master/scripts/format_xml.sh) script.
:::
## Messages vs Commands
@@ -44,12 +46,14 @@ The "official" project XML files are stored in the Github repo [mavlink/mavlink]
MAVLink systems typically fork and maintain a copy of this repo (e.g. [ArduPilot/mavlink](https://github.com/ArduPilot/mavlink)). The downstream repo should pull **common.xml** changes (see next section) down from the main repo and push dialect-specific changes back to it.
> [!TIP]
> The official repo is forked and/or cloned into your environment when you [Install MAVLink](../getting_started/installation.md).
::: tip
The official repo is forked and/or cloned into your environment when you [Install MAVLink](../getting_started/installation.md).
:::
> [!NOTE]
> A project/dialect doesn't _have to_ push changes back to MAVLink.
> However this makes sense if you want to publish your messages more widely, and potentially get them moved into the **common.xml** message set.
::: info
A project/dialect doesn't _have to_ push changes back to MAVLink.
However this makes sense if you want to publish your messages more widely, and potentially get them moved into the **common.xml** message set.
:::
## Where Should MAVLink Elements be Created?
@@ -57,9 +61,10 @@ The enums and messages that are generally useful for many flight stacks and grou
The MAVLink elements supported by a particular autopilot system or protocol are referred to as _dialects_.
The _dialects_ are stored in separate XML files, which typically `include` (import) **common.xml** and define just the elements needed for system-specific functionality.
> [!NOTE]
> When a MAVLink library is generated from a dialect file, code is created for all messages in both the dialect and any included files (e.g. **common.xml**), and entries for a particular enum are merged.
> The generator reports errors if there are name or id clashes between imported messages or enum entries.
::: info
When a MAVLink library is generated from a dialect file, code is created for all messages in both the dialect and any included files (e.g. **common.xml**), and entries for a particular enum are merged.
The generator reports errors if there are name or id clashes between imported messages or enum entries.
:::
Where you define an element depends on whether it is common or a dialect, and whether the project is public or private.
@@ -86,44 +91,48 @@ To create a new dialect file:
1. Create a dialect file named after your MAVLink system (e.g. flight stack) in **message_definitions/v1.0/**
1. Copy the following text into the new file.
```xml
<?xml version="1.0"?>
<mavlink>
```xml
<?xml version="1.0"?>
<mavlink>
<include>common.xml</include>
<!-- <version>9</version> -->
<dialect>8</dialect>
<include>common.xml</include>
<!-- <version>9</version> -->
<dialect>8</dialect>
<enums>
<!-- Enums are defined here (optional) -->
</enums>
<enums>
<!-- Enums are defined here (optional) -->
</enums>
<messages>
<!-- Messages are defined here (optional) -->
</messages>
<messages>
<!-- Messages are defined here (optional) -->
</messages>
</mavlink>
```
</mavlink>
```
The template assumes that your dialect:
The template assumes that your dialect:
- imports **common.xml** (`<include>common.xml</include>`)
- takes its version from **common.xml** (which is why the `version` tags are commented out).
- imports **common.xml** (`<include>common.xml</include>`)
- takes its version from **common.xml** (which is why the `version` tags are commented out).
1. Update the `include`(s):
- if the dialect is not based on **common.xml** remove the existing `include` line
- Add additional `<include> </include>` elements to import additional files/dialects.
> [!NOTE]
> Includes in nested files are ignored.
- if the dialect is not based on **common.xml** remove the existing `include` line
- Add additional `<include> </include>` elements to import additional files/dialects.
::: info
Includes in nested files are ignored.
:::
1. Update the `version`:
- Most dialects should leave the version commented out (i.e. all dialects that include **common.xml**).
- Dialects that are _not_ based on **common.xml** can uncomment the `<version>6</version>` line and use whatever version is desired.
> [!NOTE]
> The `version` specified in the top level file is used by default, if present.
> If it is not present in the file, then a `version` from an included file is used.
- Most dialects should leave the version commented out (i.e. all dialects that include **common.xml**).
- Dialects that are _not_ based on **common.xml** can uncomment the `<version>6</version>` line and use whatever version is desired.
::: info
The `version` specified in the top level file is used by default, if present.
If it is not present in the file, then a `version` from an included file is used.
:::
1. Update the `<dialect>8</dialect>` line to replace `8` with the next-largest unused dialect number (based on the other files in the folder).
1. Optionally remove the `enums` or `messages` sections if you don't plan on declaring any elements of these types.
@@ -161,8 +170,9 @@ A typical message ([SAFETY_SET_ALLOWED_AREA](../messages/common.md#SAFETY_SET_AL
Messages must be declared between the `<messages></messages>` tags in either **common.xml** or _dialect_ files.
Each message is defined using `<message id="" name="LIBRARY_UNIQUE_NAME"> ... </message>` tags (with unique `id` and `name` attributes).
> [!TIP]
> The only only difference between messages defined in **common.xml** or _dialect_ files is they they must use different `id` ranges in order to ensure that the `ids` are unique. See [Message Id Ranges](#message_id_ranges) for more information.
::: tip
The only only difference between messages defined in **common.xml** or _dialect_ files is they they must use different `id` ranges in order to ensure that the `ids` are unique. See [Message Id Ranges](#message_id_ranges) for more information.
:::
The main rules for messages are:
@@ -183,11 +193,12 @@ The main rules for messages are:
Each field should only have **one** or no units.
- _should_ use the `enum` attribute where possible results are finite/well understood.
> [!WARNING]
> You cannot rely on generators to fully test for compliance with the above rules.
> The _mavgen_ code generator tests for duplicate message ids, duplicate field names, messages with no fields, and messages with more than 64 fields.
> It does not check for other issues (e.g. duplicate names, or over-size payloads).
> Other generators may provide better validation
::: warning
You cannot rely on generators to fully test for compliance with the above rules.
The _mavgen_ code generator tests for duplicate message ids, duplicate field names, messages with no fields, and messages with more than 64 fields.
It does not check for other issues (e.g. duplicate names, or over-size payloads).
Other generators may provide better validation
:::
#### Message Id Ranges {#message_id_ranges}
@@ -208,8 +219,9 @@ Allocated ranges are listed below (a more complete list is provided in the comme
| ArduPilotMega.xml | 11000 - 11999 |
| icarous.xml | 42000 - 42999 |
> [!TIP]
> If you are creating a new public dialect, [create an issue](https://github.com/mavlink/mavlink/issues/new) to request your own message id range. For private dialects, you can use whatever range you like.
::: tip
If you are creating a new public dialect, [create an issue](https://github.com/mavlink/mavlink/issues/new) to request your own message id range. For private dialects, you can use whatever range you like.
:::
You should not create messages with ids in the "MAVLink 1" range (MAVLink v1 only has 8 bit message IDs, and hence can only support messages with ids 0 - 255).
@@ -221,8 +233,9 @@ Changing the name or id of a message will make it incompatible with older versio
Adding or removing a field, or changing the name or type of a field, will make a message incompatible with older versions of the generated library (the generated message decoding method is hard coded with the field number, [order](../guide/serialization.md#crc_extra), type and position at build time - if these change, decoding will fail).
> [!TIP]
> [Message Extensions](#message_extensions) (see below) allow you to add new fields to a MAVLink 2 message without breaking compatibility for a receiver that has not been updated. Note that you can only add messages, not modify or delete them using this mechanism.
::: tip
[Message Extensions](#message_extensions) (see below) allow you to add new fields to a MAVLink 2 message without breaking compatibility for a receiver that has not been updated. Note that you can only add messages, not modify or delete them using this mechanism.
:::
If a message needs to be changed in these ways then there are several options:
@@ -236,8 +249,9 @@ For a message in **common.xml** either change requires the agreement of major st
- Create a PR and discuss in the MAVLink developer meeting.
> [!TIP]
> Before proposing changes to **common.xml** check the codebase of major stakeholder to confirm impact.
::: tip
Before proposing changes to **common.xml** check the codebase of major stakeholder to confirm impact.
:::
It is possible to change the message and field descriptions without breaking binary compatibility.
Care should still be taken to ensure that any changes that alter the way that the field is interpreted are agreed by stakeholders, and handled with proper version control.
@@ -339,8 +353,9 @@ A typical enum ([LANDING_TARGET_TYPE](../messages/common.md#LANDING_TARGET_TYPE)
Enums must be declared between the `<enums></enums>` tags in **common.xml** and/or _dialect_ files.
Each enum is defined using `<enum name="SOME_NAME"> ... </enum>` tags (with a `name` attribute).
> [!TIP]
> There is no difference between enums defined in **common.xml** or _dialect_ files (other than management of the namespace).
::: tip
There is no difference between enums defined in **common.xml** or _dialect_ files (other than management of the namespace).
:::
The main rules for enums are:
@@ -351,22 +366,25 @@ The main rules for enums are:
- Enums _may_ be marked as deprecated.
- Enums _must_ have at least one enum entry.
- Entries:
- _must_ have a `name` attribute.
- The `name` must be unique across all entries in the enum.
- By _convention_, the `name` should be prefixed with the enum name (e.g. enum `LANDING_TARGET_TYPE` has entry `LANDING_TARGET_TYPE_LIGHT_BEACON`).
- _should_ have a `value` attribute, and if assigned this must be unique within the (merged) enum.
Missing values will automatically be sequentially assigned (starting from 1, if the first value is not assigned).
> [!TIP]
> We recommend you assign values because then new entries can be added within the range without breaking compatibility.
::: tip
We recommend you assign values because then new entries can be added within the range without breaking compatibility.
:::
- _should_ (very highly recommended) include a `description` element.
- may represent bitmasks, in which case values will increase by a power of 2.
- _may_ be marked as deprecated.
> [!WARNING]
> You cannot rely on specific generators to fully test for compliance with the above rules.
> _mavgen_ tests for duplicate names in enums, duplicate names for (merged) enum entries, duplicate values for enum entries.
::: warning
You cannot rely on specific generators to fully test for compliance with the above rules.
_mavgen_ tests for duplicate names in enums, duplicate names for (merged) enum entries, duplicate values for enum entries.
:::
### Modifying an Enum
@@ -386,8 +404,9 @@ If an enum needs to be changed then there are several options:
For either case, all users of the enum will need to be updated with new generated libraries.
> [!TIP]
> Before proposing changes to **common.xml** check the codebase of major stakeholder to confirm impact.
::: tip
Before proposing changes to **common.xml** check the codebase of major stakeholder to confirm impact.
:::
For an enum in **common.xml** either change requires the agreement of major stakeholders
@@ -403,8 +422,9 @@ Enums are very rarely deleted, as this may break compatibility with legacy MAVLi
MAVLink commands are defined as entries in the [MAV_CMD](../messages/common.md#mav_commands) enum.
They are used to define operations used in autonomous missions (see [Mission Protocol](../services/mission.md)) or to send commands in any mode (see [Command Protocol](../services/command.md)).
> [!TIP]
> The schema for commands is documented [here](../guide/xml_schema.md#MAV_CMD).
::: tip
The schema for commands is documented [here](../guide/xml_schema.md#MAV_CMD).
:::
A typical mission command is ([MAV_CMD_NAV_WAYPOINT](../messages/common.md#MAV_CMD_NAV_WAYPOINT)) is shown below:
@@ -446,10 +466,10 @@ The allocated ranges are listed below (a more complete list is provided in the c
| Common.xml | 0 - 39999 |
| asluav.xml | 40001 - 41999 |
| ArduPilotMega.xml | 42000 - 42999 |
| slugs.xml | 10001 - 11999 |
> [!TIP]
> If you are creating a new public dialect, [create an issue](https://github.com/mavlink/mavlink/issues/new) to request your own command id range. For private dialects, you can use whatever range you like.
::: tip
If you are creating a new public dialect, [create an issue](https://github.com/mavlink/mavlink/issues/new) to request your own command id range. For private dialects, you can use whatever range you like.
:::
There are a number of common and ArduPilot commands that are outside the ranges (e.g. 16, 200, etc.).
Generally you would only use these these ranges in order to give a new command an id that is close to related to that of related commands.
@@ -465,9 +485,10 @@ In addition, there are some other "standard" prefixes which are used for common
- `MAV_CMD_CONDITION_`: `CONDITION_` commands are used to define conditions before the mission state machine will move to the next item (e.g. a time after reaching a waypoint before taking a picture).
- `MAV_CMD_REQUEST_`: For requesting information from a system.
> [!TIP]
> The rules for the above prefixes are flexible; some DO commands might reasonably be NAV commands.
> Ins some cases a request for information might be a `MAV_CMD_REQUEST_` and in others it might be a stand alone message.
::: tip
The rules for the above prefixes are flexible; some DO commands might reasonably be NAV commands.
In some cases a request for information might be a `MAV_CMD_REQUEST_` and in others it might be a stand alone message.
:::
### Parameters (param) {#param}
@@ -491,7 +512,6 @@ ASLUAV : 40001,40002
Autoquad 1,2,4
Common - 16 - 34, 80-85, 92 - 95, 112-115, 159, 176 - 186, 189 - 252, 300, 400, 410, 500, 510, 530, 2000-2003, 2500, scattered up to 5000 then 30001-31014 (scattered
matrixpilot : 0
Slugs - 10001 - 10015
-->
#### Reserved/Undefined Parameters {#reserved}
@@ -502,9 +522,10 @@ These unused parameters can be treated as _reserved_, allowing them to be reused
A reserved `param` **must** always be sent with a (default) value of _either_ `0` or `NaN` (which will be interpreted by recipient as "no action" or "not supported").
If the param is reused the original default value must still mean "no action", so that an updated system can still interact with a system that has not been updated.
> [!NOTE]
> Unfortunately this means that a reserved `param` must have its default value decided when the command is declared!
> The default value cannot later be changed from `NaN` to `0` (or visa versa) without potential compatibility issues.
::: info
Unfortunately this means that a reserved `param` must have its default value decided when the command is declared!
The default value cannot later be changed from `NaN` to `0` (or visa versa) without potential compatibility issues.
:::
To declare a `param` as `reserved` with `default` value of `NaN` you should use the following syntax.
@@ -512,8 +533,9 @@ To declare a `param` as `reserved` with `default` value of `NaN` you should use
<param index="3" reserved="true" default="NaN" />
```
> [!WARNING]
> Params with index values `5` and `6` should not be given a `default` of `NaN` , because if these are sent in a `COMMAND_INT` or `MISSION_INT` these parameters are integers (and hence there is no way to represent an `NaN`).
::: warning
Params with index values `5` and `6` should not be given a `default` of `NaN` , because if these are sent in a `COMMAND_INT` or `MISSION_INT` these parameters are integers (and hence there is no way to represent an `NaN`).
:::
To declare a param as `reserved` with `default` value of `0` simply omit the `param` from the definition. This is the default - it is equivalent to:
en/guide/mavlink_2.md
+3 -2
View File
@@ -15,8 +15,9 @@ The key new features of _MAVLink 2_ are:
- [Empty-byte payload truncation](../guide/serialization.md#payload_truncation) - Empty (zero-filled) bytes at the end of the serialized payload must be removed before sending (All bytes were sent in _MAVLink 1_, regardless of content).
- [Compatibility Flags](../guide/serialization.md#compat_flags)/[Incompatibility Flags](../guide/serialization.md#incompat_flags) - Allow for backwards compatible evolution of the protocol by indicating frames that must be handled in a special/non-standard way (packets with compatibility flags can still be handled in the standard way, while packets with incompatibility flags must be dropped if the flage is not supported).
> [!TIP]
> The _MAVLink 2_ [design document](https://docs.google.com/document/d/1XtbD0ORNkhZ8eKrsbSIZNLyg9sFRXMXbsR2mp37KbIg/edit?usp=sharing) provides additional background information about the changes.
::: tip
The _MAVLink 2_ [design document](https://docs.google.com/document/d/1XtbD0ORNkhZ8eKrsbSIZNLyg9sFRXMXbsR2mp37KbIg/edit?usp=sharing) provides additional background information about the changes.
:::
## Upgrading to MAVLink 2
en/guide/mavlink_version.md
+15 -11
View File
@@ -8,10 +8,11 @@ MAVLink has been deployed in a number of versions:
The _MAVLink 2.0_ C/C++ and Python libraries are backwards compatible with MAVLink 1.0 (support both protocols).
[Version Handshaking](#version_handshaking) and [Negotiating Versions](#negotiating_versions) explain how to choose which version is used.
> [!NOTE]
> _MAVLink v0.9_ is a pre-release version that is no longer supported.
> The associated message set deleted in August 2018.
> Legacy code may be present in generator and test code.
::: info
_MAVLink v0.9_ is a pre-release version that is no longer supported.
The associated message set deleted in August 2018.
Legacy code may be present in generator and test code.
:::
## Determining Protocol/Message Version
@@ -26,12 +27,14 @@ A library's MAVLink support can be determined in a number of ways:
- MAVLink 1: `0xFE`
- MAVLink 2: `0xFD`
> [!NOTE]
> A MAVLink library that does not support a protocol version will not recognise the protocol start marker;
> so no messages will even be detected (see [Serialization](../guide/serialization.md)).
::: info
A MAVLink library that does not support a protocol version will not recognise the protocol start marker;
so no messages will even be detected (see [Serialization](../guide/serialization.md)).
:::
> [!TIP]
> While messages do not contain version information, an extra CRC is used to ensure that a library will only process compatible messages (see [Serialization > CRC_EXTRA](../guide/serialization.md)).
::: tip
While messages do not contain version information, an extra CRC is used to ensure that a library will only process compatible messages (see [Serialization > CRC_EXTRA](../guide/serialization.md)).
:::
## Version Handshaking {#version_handshaking}
@@ -74,8 +77,9 @@ The supported MAVLink library implementations enable different MAVLink versions
As a result, all [connections](../services/heartbeat.md) to other components over a particular channel must share the same MAVLink version. If a system is using signing, then all connections via the same channel must also be signing messages with the same key.
> [!NOTE]
> A system cannot use a single channel to connect to signed MAVLink 2 systems, unsigned MAVLink 2 systems, and/or MAVLink 1 components.
::: info
A system cannot use a single channel to connect to signed MAVLink 2 systems, unsigned MAVLink 2 systems, and/or MAVLink 1 components.
:::
Currently most MAVLink networks are configured to use unsigned MAVLink 2 messages.
MAVLink 1 is primarily used to allow autopilots to connect to legacy MAVLink peripherals, and this is done via a separate channel.
en/guide/message_signing.md
+36 -27
View File
@@ -18,10 +18,11 @@ The signed packet format is shown below.
![MAVLink 2 Signed](../../assets/packets/packet_mavlink_v2_signing.png)
> [!NOTE]
> The [incompatibility flags](../guide/mavlink_2.md#incompat_flags) in the packet header are used to indicate that the MAVLink library must reject the packet if it does not understand or cannot handle the flag.
> In other words, a MAVLink library that does not support signing must drop signed packets.
> The C library uses [MAVLINK_IFLAG_SIGNED](../guide/mavlink_2.md#MAVLINK_IFLAG_SIGNED) to represent the "supports message signing" bit.
::: info
The [incompatibility flags](../guide/mavlink_2.md#incompat_flags) in the packet header are used to indicate that the MAVLink library must reject the packet if it does not understand or cannot handle the flag.
In other words, a MAVLink library that does not support signing must drop signed packets.
The C library uses [MAVLINK_IFLAG_SIGNED](../guide/mavlink_2.md#MAVLINK_IFLAG_SIGNED) to represent the "supports message signing" bit.
:::
The 13 bytes of the signature are:
@@ -44,8 +45,9 @@ The monotonically increasing [timestamp](#timestamp) rule is applied separately
(SystemID,ComponentID,LinkID)
```
> [!NOTE]
> For more information see [C Message Signing > Handling Link IDs](../mavgen_c/message_signing_c.md#handling_link_ids).
::: info
For more information see [C Message Signing > Handling Link IDs](../mavgen_c/message_signing_c.md#handling_link_ids).
:::
### Signature {#signature}
@@ -62,8 +64,9 @@ signature = sha256_48(secret_key + header + payload + CRC + link-ID + timestamp)
The timestamp is a 48 bit number with units of 10 microseconds since 1st January 2015 GMT. For systems where the time since 1/1/1970 is available (the unix epoch) you can use an offset in seconds of 1420070400.
> [!NOTE]
> This is a loose definition, as the various update mechanisms detailed below may result in the timestamp being significantly different from actual GMT time.
::: info
This is a loose definition, as the various update mechanisms detailed below may result in the timestamp being significantly different from actual GMT time.
:::
All timestamps generated must be at least 1 more than the previous timestamp sent in the same session for the same link/`(SystemID, ComponentID, LinkID)` tuple.
The timestamp may get ahead of GMT time if there is a burst of packets at a rate of more than 100 thousand packets per second.
@@ -78,15 +81,17 @@ Systems should implement the following rules to obtain a reliable timestamp:
- The timestamp should be incremented by one on each message sent from a particular link.
- When a correctly signed message is decoded the timestamp should be replaced by the timestamp of the incoming message if that timestamp is greater than the current timestamp.
> [!NOTE]
> The link timestamp must never be updated with the timestamp from an incorrectly signed packet (even if these are being [accepted](#accepting_incorrectly_signed_packets)).
::: info
The link timestamp must never be updated with the timestamp from an incorrectly signed packet (even if these are being [accepted](#accepting_incorrectly_signed_packets)).
:::
- The timestamp on incoming signed messages should be checked against the previous timestamp for the incoming `(linkID,srcSystem,SrcComponent)` tuple and the message rejected if it is smaller.
- If there is no previous message with the given `(linkID,srcSystem,SrcComponent)` then the timestamp should be accepted if it not more than 6 million (one minute) behind the current timestamp.
> [!TIP]
> For devices that store the timestamp in persistent storage, implementations can prevent race conditions by storing two timestamp values.
> On write the smaller of the two values should be updated. On read the larger of the two values should be used.
::: tip
For devices that store the timestamp in persistent storage, implementations can prevent race conditions by storing two timestamp values.
On write the smaller of the two values should be updated. On read the larger of the two values should be used.
:::
## Accepting Signed Packets {#accept_signed_packets}
@@ -102,9 +107,9 @@ MAVLink libraries should provide a mechanism that allows a system to conditional
The rules for accepting these packets will be implementation specific, but could be based on a combination of a parameter setting, transport type, message type, (in)compatibility flags etc.
> [!NOTE]
> All packets that do not meet the system-specific unsigned packet acceptance rules must be rejected
> (otherwise there is no benefit gained from signing/authentication).
::: info
All packets that do not meet the system-specific unsigned packet acceptance rules must be rejected (otherwise there is no benefit gained from signing/authentication).
:::
Some suggestions for when to accept unsigned packets:
@@ -120,8 +125,9 @@ MAVLink libraries should provide a mechanism that allows a system to conditional
This feature might be useful for finding a lost vehicle with a corrupted secret key (the GCS could choose to still display position information, albeit ideally with a different "untrusted" icon).
> [!NOTE]
> A system that is accepting incorrectly signed packets should provide a highly conspicuous indication that the connection is _unsafe_/_insecure_. Malformed signed packets indicate a bad configuration, transport failure, protocol failure, or hostile manipulation.
::: info
A system that is accepting incorrectly signed packets should provide a highly conspicuous indication that the connection is _unsafe_/_insecure_. Malformed signed packets indicate a bad configuration, transport failure, protocol failure, or hostile manipulation.
:::
## Secret Key Management {#secret_key}
@@ -129,10 +135,11 @@ A secret key is 32 bytes of binary data that are used to create message signatur
The key should be created on one system in the network (often a GCS) and shared to other trusted devices via secure channels.
Systems must have a shared key in order to be able to communicate.
> [!NOTE]
> The _mavgen_ [C](../mavgen_c/message_signing_c.md) and [Python](../mavgen_python/index.md#message_signing) libraries support only one key per link.
> This is a choice of the library and not a limit/requirement of the protocol.
> An implementation might instead store a pool of keys, and/or manage keys on a per-connection basis.
::: info
The _mavgen_ [C](../mavgen_c/message_signing_c.md) and [Python](../mavgen_python/index.md#message_signing) libraries support only one key per link.
This is a choice of the library and not a limit/requirement of the protocol.
An implementation might instead store a pool of keys, and/or manage keys on a per-connection basis.
:::
The secret key should be stored in persistent storage, and must not be exposed via any publicly accessible communication protocol.
In particular, the key must not be exposed in MAVLink parameters, MAVLink log files or dataflash log files that may be used for public log analysis.
@@ -154,9 +161,10 @@ This is to avoid the case where a key received over a secure link (e.g. USB) is
Autopilots that don't offer MAVLink over USB might create a module that can set the secret key from a command line interface (e.g. the NSH Shell).
> [!TIP]
> We recommend that GCS implementations should generate the secret key and share this with connected systems over a secure link (e.g. USB).
> The receiving system may be configured to ignore message signatures on the secure channel (i.e. accept all [signed](#accept_signed_packets), [unsigned](#accepting_unsigned_packets) or [incorrectly signed](#accepting_incorrectly_signed_packets) packets), so that it is possible to reset a key that has been lost or corrupted.
::: tip
We recommend that GCS implementations should generate the secret key and share this with connected systems over a secure link (e.g. USB).
The receiving system may be configured to ignore message signatures on the secure channel (i.e. accept all [signed](#accept_signed_packets), [unsigned](#accepting_unsigned_packets) or [incorrectly signed](#accepting_incorrectly_signed_packets) packets), so that it is possible to reset a key that has been lost or corrupted.
:::
## Logging
@@ -173,5 +181,6 @@ The [Message Signing Proposal](https://docs.google.com/document/d/1ETle6qQRcaNWA
- Evaluation of security effectiveness, including resistance to replay and offline attacks.
- Assumptions.
> [!NOTE]
> Much of this content is derived from the [Message Signing Proposal](https://docs.google.com/document/d/1ETle6qQRcaNWAmpG2wz0oOpFKSF_bcTmYMQvtTGI8ns/edit?usp=sharing) (Google Doc).
::: info
Much of this content is derived from the [Message Signing Proposal](https://docs.google.com/document/d/1ETle6qQRcaNWAmpG2wz0oOpFKSF_bcTmYMQvtTGI8ns/edit?usp=sharing) (Google Doc).
:::
en/guide/routing.md
+13 -9
View File
@@ -26,11 +26,13 @@ Broadcast messages are forwarded to all channels that haven't seen the message.
Addressed messages are resent on a new channel _iff_ the system has previously seen a message from the target on that channel
(messages are not resent if the addressee is not known or is on the original/incoming channel).
> [!WARNING]
> Forwarded messages must not be changed/repackaged by the forwarding system (the original message is passed to the new link).
::: warning
Forwarded messages must not be changed/repackaged by the forwarding system (the original message is passed to the new link).
:::
> [!NOTE]
> Systems should, where possible, forward messages according to the routing rules _even if they are unable to process them_ (e.g. signed messages that cannot be authenticated). Messages that are not supported/understood by the library should be forwarded as though they were broadcast messages (in this case the target system/component ids cannot be read).
::: info
Systems should, where possible, forward messages according to the routing rules _even if they are unable to process them_ (e.g. signed messages that cannot be authenticated). Messages that are not supported/understood by the library should be forwarded as though they were broadcast messages (in this case the target system/component ids cannot be read).
:::
## Routing Detail
@@ -47,12 +49,14 @@ Systems should forward messages to another link if any of these conditions hold:
- The `target_system` does not match the system id _and_ the system knows the link of the target system (i.e. it has previously seen a message from `target_system` on the link).
- The `target_system` matches its system id and has a `target_component` field, and the system has seen a message from the `target_system`/`target_component` combination on the link.
> [!NOTE]
> Non-broadcast messages must only be sent (or forwarded) to known destinations (i.e. a system must previously have received a message from the target system/component).
::: info
Non-broadcast messages must only be sent (or forwarded) to known destinations (i.e. a system must previously have received a message from the target system/component).
:::
> [!NOTE]
> Systems should also check for `SYSTEM_TIME` messages with a decrease in `time_boot_ms`, as this indicates that the system has rebooted.
> In this case it should clear stored routing information (and might perform other actions that are useful following a reboot - e.g. re-fetching parameters and home position etc.).
::: info
Systems should also check for `SYSTEM_TIME` messages with a decrease in `time_boot_ms`, as this indicates that the system has rebooted.
In this case it should clear stored routing information (and might perform other actions that are useful following a reboot - e.g. re-fetching parameters and home position etc.).
:::
## Library Support
en/guide/scripts.md
+3 -2
View File
@@ -15,5 +15,6 @@ The scripts can be executed by running Python with the `-m` switch, which indica
python -m pymavlink.tools.mavlogdump test_run.mavlink
```
> [!NOTE]
> Using the `-m` switch is the proper way to run Python scripts that are part of a library as per PEP-328 (and the rejected PEP-3122).
::: info
Using the `-m` switch is the proper way to run Python scripts that are part of a library as per PEP-328 (and the rejected PEP-3122).
:::
en/guide/serialization.md
+58 -49
View File
@@ -4,8 +4,9 @@ This topic provides detailed information about about MAVLink packet serializatio
It is primarily intended for developers who are creating/maintaining a MAVLink generator
> [!TIP]
> MAVLink users do not typically need to understand the serialization format, as encoding/decoding is handled by the MAVLink libraries.
::: tip
MAVLink users do not typically need to understand the serialization format, as encoding/decoding is handled by the MAVLink libraries.
:::
## Packet Format {#packet_format}
@@ -19,19 +20,19 @@ Below is the over-the-wire format for a [MAVLink 2](../guide/mavlink_2.md) packe
![MAVLink v2 packet](../../assets/packets/packet_mavlink_v2.jpg)
| Byte Index | C version | Content | Value | Explanation |
| ----------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | `uint8_t magic` | Packet start marker | 0xFD | Protocol-specific start-of-text (STX) marker used to indicate the beginning of a new packet. Any system that does not understand protocol version will skip the packet. |
| 1 | `uint8_t len` | Payload length | 0 - 255 | Indicates length of the following `payload` section. This may be affected by [payload truncation](#payload_truncation). |
| 2 | `uint8_t incompat_flags` | [Incompatibility Flags](#incompat_flags) | | Flags that must be understood for MAVLink compatibility (implementation discards packet if it does not understand flag). |
| 3 | `uint8_t compat_flags` | [Compatibility Flags](#compat_flags) | | Flags that can be ignored if not understood (implementation can still handle packet even if it does not understand flag). |
| 4 | `uint8_t seq` | Packet sequence number | 0 - 255 | Used to detect packet loss. Components increment value for each message sent. |
| 5 | `uint8_t sysid` | System ID (sender) | 1 - 255 | ID of _system_ (vehicle) sending the message. Used to differentiate systems on network. Note that the broadcast address 0 may not be used in this field as it is an invalid _source_ address. |
| 6 | `uint8_t compid` | Component ID (sender) | 1 - 255 | ID of _component_ sending the message. Used to differentiate _components_ in a _system_ (e.g. autopilot and a camera). Use appropriate values in [MAV_COMPONENT](../messages/common.md#MAV_COMPONENT). Note that the broadcast address `MAV_COMP_ID_ALL` may not be used in this field as it is an invalid _source_ address. |
| <span id="v2_msgid"></span>7 to 9 | `uint32_t msgid:24` | Message ID (low, middle, high bytes) | 0 - 16777215 | ID of _message type_ in payload. Used to decode data back into message object. |
| <span id="v2_payload"></span>For _n_-byte payload:<br>`n=0`: NA, `n=1`: 10, `n>=2`: 10 to (9+n) | `uint8_t payload[max 255]` | [Payload](#payload) | | Message data. Depends on message type (i.e. Message ID) and contents. |
| (n+10) to (n+11) | `uint16_t checksum` | [Checksum](#checksum) (low byte, high byte) | | CRC-16/MCRF4XX for message (excluding `magic` byte). Includes [CRC_EXTRA](#crc_extra) byte. |
| (n+12) to (n+25) | `uint8_t signature[13]` | [Signature](../guide/message_signing.md) | | (Optional) Signature to ensure the link is tamper-proof. |
| Byte Index | C version | Content | Value | Explanation |
| ----------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | `uint8_t magic` | Packet start marker | 0xFD | Protocol-specific start-of-text (STX) marker used to indicate the beginning of a new packet. Any system that does not understand protocol version will skip the packet. |
| 1 | `uint8_t len` | Payload length | 0 - 255 | Indicates length of the following `payload` section. This may be affected by [payload truncation](#payload_truncation). |
| 2 | `uint8_t incompat_flags` | [Incompatibility Flags](#incompat_flags) | | Flags that must be understood for MAVLink compatibility (implementation discards packet if it does not understand flag). |
| 3 | `uint8_t compat_flags` | [Compatibility Flags](#compat_flags) | | Flags that can be ignored if not understood (implementation can still handle packet even if it does not understand flag). |
| 4 | `uint8_t seq` | Packet sequence number | 0 - 255 | Used to detect packet loss. Components increment value for each message sent. |
| 5 | `uint8_t sysid` | System ID (sender) | 1 - 255 | ID of _system_ (vehicle) sending the message. Used to differentiate systems on network. Note that the broadcast address 0 may not be used in this field as it is an invalid _source_ address. |
| 6 | `uint8_t compid` | Component ID (sender) | 1 - 255 | ID of _component_ sending the message. Used to differentiate _components_ in a _system_ (e.g. autopilot and a camera). Use appropriate values in [MAV_COMPONENT](../messages/common.md#MAV_COMPONENT). Note that the broadcast address `MAV_COMP_ID_ALL` may not be used in this field as it is an invalid _source_ address. |
| <a id="v2_msgid"></a>7 to 9 | `uint32_t msgid:24` | Message ID (low, middle, high bytes) | 0 - 16777215 | ID of _message type_ in payload. Used to decode data back into message object. |
| <a id="v2_payload"></a>For _n_-byte payload:<br>`n=0`: NA, `n=1`: 10, `n>=2`: 10 to (9+n) | `uint8_t payload[max 255]` | [Payload](#payload) | | Message data. Depends on message type (i.e. Message ID) and contents. |
| (n+10) to (n+11) | `uint16_t checksum` | [Checksum](#checksum) (low byte, high byte) | | CRC-16/MCRF4XX for message (excluding `magic` byte). Includes [CRC_EXTRA](#crc_extra) byte. |
| (n+12) to (n+25) | `uint8_t signature[13]` | [Signature](../guide/message_signing.md) | | (Optional) Signature to ensure the link is tamper-proof. |
- The minimum packet length is 12 bytes for acknowledgment packets without payload.
- The maximum packet length is 280 bytes for a signed message that uses the whole payload.
@@ -42,16 +43,16 @@ Below is the over-the-wire format for a MAVLink 1 packet (the in-memory represen
![MAVLink v1 packet](../../assets/packets/packet_mavlink_v1.jpg)
| Byte Index | C version | Content | Value | Explanation |
| --------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | `uint8_t magic` | Packet start marker | 0xFE | Protocol-specific start-of-text (STX) marker used to indicate the beginning of a new packet. Any system that does not understand protocol version will skip the packet. |
| 1 | `uint8_t len` | Payload length | 0&nbsp;-&nbsp;255 | Indicates length of the following `payload` section (fixed for a particular message). |
| 2 | `uint8_t seq` | Packet sequence number | 0 - 255 | Used to detect packet loss. Components increment value for each message sent. |
| 3 | `uint8_t sysid` | System ID | 1 - 255 | ID of _system_ (vehicle) sending the message. Used to differentiate systems on network. Note that the broadcast address 0 may not be used in this field as it is an invalid _source_ address. |
| 4 | `uint8_t compid` | Component ID | 1 - 255 | ID of _component_ sending the message. Used to differentiate components in a _system_ (e.g. autopilot and a camera). Use appropriate values in [MAV_COMPONENT](../messages/common.md#MAV_COMPONENT). Note that the broadcast address `MAV_COMP_ID_ALL` may not be used in this field as it is an invalid _source_ address. |
| <span id="v1_msgid"></span>5 | `uint8_t msgid` | Message ID | 0 - 255 | ID of _message type_ in payload. Used to decode data back into message object. |
| <span id="v1_payload"></span>For _n_-byte payload:<br>`n=0`: NA, `n=1`: 6, `n>=2`: 6 to (5+n) | `uint8_t payload[max 255]` | Payload data | | Message data. Content depends on message type (i.e. Message ID). |
| (n+6) to (n+7) | `uint16_t checksum` | [Checksum](#checksum) (low byte, high byte) | | CRC-16/MCRF4XX for message (excluding `magic` byte). Includes [CRC_EXTRA](#crc_extra) byte. |
| Byte Index | C version | Content | Value | Explanation |
| --------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | `uint8_t magic` | Packet start marker | 0xFE | Protocol-specific start-of-text (STX) marker used to indicate the beginning of a new packet. Any system that does not understand protocol version will skip the packet. |
| 1 | `uint8_t len` | Payload length | 0&nbsp;-&nbsp;255 | Indicates length of the following `payload` section (fixed for a particular message). |
| 2 | `uint8_t seq` | Packet sequence number | 0 - 255 | Used to detect packet loss. Components increment value for each message sent. |
| 3 | `uint8_t sysid` | System ID | 1 - 255 | ID of _system_ (vehicle) sending the message. Used to differentiate systems on network. Note that the broadcast address 0 may not be used in this field as it is an invalid _source_ address. |
| 4 | `uint8_t compid` | Component ID | 1 - 255 | ID of _component_ sending the message. Used to differentiate components in a _system_ (e.g. autopilot and a camera). Use appropriate values in [MAV_COMPONENT](../messages/common.md#MAV_COMPONENT). Note that the broadcast address `MAV_COMP_ID_ALL` may not be used in this field as it is an invalid _source_ address. |
| <a id="v1_msgid"></a>5 | `uint8_t msgid` | Message ID | 0 - 255 | ID of _message type_ in payload. Used to decode data back into message object. |
| <a id="v1_payload"></a>For _n_-byte payload:<br>`n=0`: NA, `n=1`: 6, `n>=2`: 6 to (5+n) | `uint8_t payload[max 255]` | Payload data | | Message data. Content depends on message type (i.e. Message ID). |
| (n+6) to (n+7) | `uint16_t checksum` | [Checksum](#checksum) (low byte, high byte) | | CRC-16/MCRF4XX for message (excluding `magic` byte). Includes [CRC_EXTRA](#crc_extra) byte. |
- The minimum packet length is 8 bytes for acknowledgment packets without payload.
- The maximum packet length is 263 bytes for full payload.
@@ -61,14 +62,15 @@ Below is the over-the-wire format for a MAVLink 1 packet (the in-memory represen
Incompatibility flags are used to indicate features that a MAVLink library must support in order to be able to handle the packet.
This includes any feature that affects the packet format/ordering.
> [!NOTE]
> A MAVLink implementation **must discard** a packet if it does not understand any flag in the `incompat_flags` field.
::: info
A MAVLink implementation **must discard** a packet if it does not understand any flag in the `incompat_flags` field.
:::
Supported incompatibility flags include (at time of writing):
| Flag | C flag | Feature |
| ------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| <span id="MAVLINK_IFLAG_SIGNED"></span>0x01 | `MAVLINK_IFLAG_SIGNED` | The packet is [signed](../guide/message_signing.md) (a signature has been appended to the packet). |
| Flag | C flag | Feature |
| ------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| <a id="MAVLINK_IFLAG_SIGNED"></a>0x01 | `MAVLINK_IFLAG_SIGNED` | The packet is [signed](../guide/message_signing.md) (a signature has been appended to the packet). |
## Compatibility Flags (MAVLink 2) {#compat_flags}
@@ -92,8 +94,9 @@ Messages are encoded within the MAVLink packet:
- A [CRC_EXTRA](#crc_extra) byte is added to the message [checksum](#checksum).
A receiver can use this to confirm that it is compatible with the payload message format/definition.
> [!TIP]
> A MAVLink library should notify a bad CRC during decoding if a message specification is incompatible (e.g. the C library [mavlink_parse_char()](../getting_started/use_libraries.md#receiving) gives a status `MAVLINK_FRAMING_BAD_CRC`).
::: tip
A MAVLink library should notify a bad CRC during decoding if a message specification is incompatible (e.g. the C library [mavlink_parse_char()](../getting_started/use_libraries.md#receiving) gives a status `MAVLINK_FRAMING_BAD_CRC`).
:::
### Field Reordering {#field_reordering}
@@ -114,10 +117,11 @@ The only exception to the above reordering is for [MAVLink 2 extension fields](.
Extension fields are sent in XML-declaration order and are not included in the [CRC_EXTRA](#crc_extra) calculation.
This allows new extension fields to be appended to the end of a message without breaking binary compatibility.
> [!WARNING]
> This ordering is unique and can be easily implemented in a protocol generator by using a stable sorting algorithm.
> The alternative to using sorting would be either to use inefficient alignment, which is bad for the target architectures for typical MAVLink applications, or to have function calls in the order of the variable size instead of the application context.
> This would lead to very confusing function signatures of serialization functions.
::: warning
This ordering is unique and can be easily implemented in a protocol generator by using a stable sorting algorithm.
The alternative to using sorting would be either to use inefficient alignment, which is bad for the target architectures for typical MAVLink applications, or to have function calls in the order of the variable size instead of the application context.
This would lead to very confusing function signatures of serialization functions.
:::
<!-- FYI: Field ordering is in pymavlink/generator/mavparse.py - see https://github.com/mavlink/mavlink-devguide/pull/27#issuecomment-349215965 for info -->
@@ -131,19 +135,22 @@ An implementation that receives a (non compliant) MAVLink 2 message with zero-fi
The actual fields affected/bytes saved depends on the message and its content
(MAVLink [field reordering](../guide/serialization.md#field_reordering) means that all we can say is that any truncated fields will typically be those with the smallest data size, or extension fields).
> [!NOTE]
> The first byte of the payload is never truncated, even if the payload consists entirely of zeros.
::: info
The first byte of the payload is never truncated, even if the payload consists entirely of zeros.
:::
> [!NOTE]
> The protocol only truncates empty bytes at the end of the serialized message payload;
> any null bytes/empty fields within the body of the payload are not affected.
::: info
The protocol only truncates empty bytes at the end of the serialized message payload;
any null bytes/empty fields within the body of the payload are not affected.
:::
### CRC_EXTRA Calculation {#crc_extra}
The `CRC_EXTRA` CRC is used to verify that the sender and receiver have a shared understanding of the over-the-wire format of a particular message.
> [!TIP]
> Changes in [message specifications](../messages/index.md) that might make the over-the-wire format incompatible include: new/removed fields, or changes to field name, data type, order, or array length.
::: tip
Changes in [message specifications](../messages/index.md) that might make the over-the-wire format incompatible include: new/removed fields, or changes to field name, data type, order, or array length.
:::
When the MAVLink code generator runs, it takes a checksum of the XML structure for each message and creates an array define `MAVLINK_MESSAGE_CRCS`.
This is used to initialise the `mavlink_message_crcs[]` array in the C/C++ implementation, and is similarly used in the Python (or any other, such as the C# and JavaScript) implementation.
@@ -158,8 +165,9 @@ If you are doing your own implementation of MAVLink you can get this checksum in
As MAVLink internally reorders the message fields according to their size to prevent word / halfword alignment issues (see [Data structure alignment](http://en.wikipedia.org/wiki/Data%20structure%20alignment) (Wikipedia) for further reference), and a wrongly implemented reordering potentially can cause inconsistencies as well, the `CRC_EXTRA` is calculated based on the over-the-air message layout rather than the XML order.
> [!NOTE]
> [MAVLink 2 extension fields](../guide/define_xml_element.md#message_extensions) are not included in the `CRC_EXTRA` calculation.
::: info
[MAVLink 2 extension fields](../guide/define_xml_element.md#message_extensions) are not included in the `CRC_EXTRA` calculation.
:::
This is the Python code that calculates the `CRC_EXTRA` seed:
@@ -184,10 +192,11 @@ def message_checksum(msg):
<!-- From https://github.com/mavlink/pymavlink/blob/master/generator/mavparse.py#L385 -->
> [!NOTE]
> This uses the same CRC-16/MCRF4XX checksum that is used at runtime.
> It calculates a CRC over the message name (such as “RAW_IMU”) followed by the type and name of each field, space separated.
> The order of the fields is the order they are sent over the wire. For arrays, the array length is also added.
::: info
This uses the same CRC-16/MCRF4XX checksum that is used at runtime.
It calculates a CRC over the message name (such as “RAW_IMU”) followed by the type and name of each field, space separated.
The order of the fields is the order they are sent over the wire. For arrays, the array length is also added.
:::
## Checksum {#checksum}
en/guide/wireshark.md
+11 -8
View File
@@ -12,8 +12,9 @@ The benefits of using _Wireshark_ over other alternatives are:
This topic shows how to generate a Wireshark plugin for a particular dialect file and install it on Wireshark, and how to perform basic filtering.
It also provides an overview of how you can use _tcpdump_ for collecting traffic on a linux computer (for later analysis).
> [!NOTE]
> You will need to regenerate and reimport the plugin (as shown below) if your dialect changes.
::: info
You will need to regenerate and reimport the plugin (as shown below) if your dialect changes.
:::
## Generate MAVLink Lua Plugin for Wireshark
@@ -93,8 +94,9 @@ Below you can see the payload and the header details for an `ATTITUDE_TARGET` me
In addition to using filters for the usual _Wireshark_ things (e.g. ips and ports) you can also use the new MAVLink filters.
> [!NOTE]
> This works the same way for live view and for a _pcapng_ file loaded into _Wireshark_
::: info
This works the same way for live view and for a _pcapng_ file loaded into _Wireshark_
:::
We already saw you can filter for MAVLink packets using `mavlink_proto`.
The following is a filter example:
@@ -135,8 +137,9 @@ wireshark -k -i /tmp/mavlink &
ssh root@10.41.1.1 -p 33333 "tcpdump -s 0 -U -n -w - -i lo not port 33333" > /tmp/mavlink;
```
> [!NOTE]
> Username, IP and port above have to be adjusted to the configuration on the remote machine.
::: info
Username, IP and port above have to be adjusted to the configuration on the remote machine.
:::
1. `mkfifo /tmp/mavlink` Creates a named pipe that is used to stream the data.
1. `wireshark -k -i /tmp/mavlink &` Start _Wireshark_, open the named pipe as input and start the capture immediately.
@@ -153,10 +156,10 @@ ssh root@10.41.1.1 -p 33333 "tcpdump -s 0 -U -n -w - -i lo not port 33333" > /tm
## Measuring MAVLink data rates using Wireshark
After the plugin is setup in Wireshark ad you have started to capture a stream you can use the Wireshark IO graphsto monitor message rates for either the whole stream or just specific messages.
After the plugin is setup in Wireshark and you have started to capture a stream you can use the Wireshark IO graphs to monitor message rates for either the whole stream or just specific messages.
To do this you need to go to **Statistics > I/O Graphs** and you will get a new window.
Now you will a plot of the data rate of all packets you are analyzing.
You can filter for the usual _Wireshark_ filters and the new MAVLink ones introduced by the LUA script.
We recommend changing the y axis to bits or bytes and to reduce the x axis to 10ms or faster to get meaningful plots.
We recommend changing the `y` axis to bits or bytes and to reduce the `x` axis to 10ms or faster to get meaningful plots.
en/guide/xml_schema.md
+30 -17
View File
@@ -8,8 +8,9 @@ While this is the canonical reference, it is easier to understand the XML file b
The broad structure for MAVLink XML files is given below.
> [!NOTE]
> If you're creating a custom dialect file your file structure should be similar to the one below (but may omit any/all sections).
::: info
If you're creating a custom dialect file your file structure should be similar to the one below (but may omit any/all sections).
:::
```xml
<?xml version="1.0"?>
@@ -37,6 +38,7 @@ The broad structure for MAVLink XML files is given below.
The main tags are listed below (all are optional):
- `include`: This tag is used to specify any other XML files included in your dialect.
- Typically dialect files will include _common.xml_ as shown above.
- You can include multiple files using separate tags.
- The path to included files can be relative to your dialect file.
@@ -86,8 +88,9 @@ The main `enum` tags/fields are:
- `entry` (optional): An entry (zero or more entries can be specified for each enum)
- [deprecated](#deprecated) (optional): A tag indicating that the enum is deprecated.
> [!TIP]
> [MAVLink Commands](#mav_cmd) are defined in the [MAV_CMD](../messages/common.md#mav_commands) enum.
::: tip
[MAVLink Commands](#mav_cmd) are defined in the [MAV_CMD](../messages/common.md#mav_commands) enum.
:::
### entry {#entry}
@@ -98,17 +101,19 @@ The "normal" enum `entry` tags/fields are:
- `description` (optional): A description of the entry.
- [deprecated](#deprecated) / [wip](#wip) (optional): A tag indicating that the enum is deprecated or "work in progress".
> [!NOTE]
> An `entry` may also define the optional elements: `param`, `hasLocation`, `isDestination`, `missionOnly`.
> In practice these should only be used in the `enum` named [MAV_CMD](#MAV_CMD) (described below).
::: info
An `entry` may also define the optional elements: `param`, `hasLocation`, `isDestination`, `missionOnly`.
In practice these should only be used in the `enum` named [MAV_CMD](#MAV_CMD) (described below).
:::
## MAVLink Commands (enum MAV_CMD) {#MAV_CMD}
Individual `entry` values in the `enum` named [MAV_CMD](#MAV_CMD) are use to define _MAVLink Commands_.
Each command has a `value` (its "command number") and specifies up to 7 parameters.
> [!NOTE]
> These parameters are encoded in [MISSION_ITEM](../messages/common.md#MISSION_ITEM) or [MISSION_ITEM_INT](../messages/common.md#MISSION_ITEM_INT) messages ([Mission Protocol](../services/mission.md)), or [COMMAND_INT](../messages/common.md#COMMAND_INT) or [COMMAND_LONG](../messages/common.md#COMMAND_LONG) messages ([Command Protocol](../services/command.md)).
::: info
These parameters are encoded in [MISSION_ITEM](../messages/common.md#MISSION_ITEM) or [MISSION_ITEM_INT](../messages/common.md#MISSION_ITEM_INT) messages ([Mission Protocol](../services/mission.md)), or [COMMAND_INT](../messages/common.md#COMMAND_INT) or [COMMAND_LONG](../messages/common.md#COMMAND_LONG) messages ([Command Protocol](../services/command.md)).
:::
For example, see [MAV_CMD_NAV_PAYLOAD_PLACE](../messages/common.md#MAV_CMD_NAV_PAYLOAD_PLACE):
@@ -166,8 +171,9 @@ A `param` **should** also include the following optional attributes where approp
This is primarily intended for specifying any scaling applied to unitless values, where scaling is not encoded in the `units`.
- `reserved` - Boolean indicating whether param is reserved for future use. If the attributes is not declared, then implicitly `reserved="False"`.
> [!TIP]
> See [Defining XML Enums/Messages > Reserved/Undefined Parameters](../guide/define_xml_element.md#reserved) for more information.
::: tip
See [Defining XML Enums/Messages > Reserved/Undefined Parameters](../guide/define_xml_element.md#reserved) for more information.
:::
- `default` - Default value for the `param`
(primarily used for `reserved` params, where the value is `0` or `NaN`).
@@ -204,19 +210,24 @@ For example,the definition of the [BATTERY_STATUS](../messages/common.md#BATTERY
The main message tags/fields are:
- `message`: Each message is encapsulated by `message` tags, with the following attributes
- `id`: The id attribute is the unique index number of this message (in the example above: 147).
- For MAVLink 1:
- Valid numbers range from 0 to 255.
- The ids 0-149 and 230-255 are reserved for _common.xml_.
Dialects can use 180-229 for custom messages (provided these are not used by other included dialects).
- For [MAVLink 2](../guide/mavlink_2.md):
- Valid numbers range from 0 to 16777215.
- All numbers below 255 should be considered reserved unless messages are also intended for MAVLink 1.
> [!NOTE]
> IDs are precious in MAVLink 1!
::: info
IDs are precious in MAVLink 1!
:::
- `name`: The name attribute provides a human readable form for the message (ie "BATTERY_STATUS"). It is used for naming helper functions in generated libraries, but is not sent over the wire.
- `description`: Human readable description of message, shown in user interfaces and in code comments.
This should contain all information (and hyperlinks) to fully understand the message.
- `field`: Encodes one field of the message. The field value is its name/text string used in GUI documentation (but not sent over the wire).
@@ -241,8 +252,9 @@ The main message tags/fields are:
- `maxValue` - Maximum value for the field.
- `instance`: If `true`, this indicates that the message contains the information for a particular sensor or battery (e.g. Battery 1, Battery 2, etc.) and that this field indicates which sensor. Default is `false`.
> [!NOTE]
> This field allows a recipient automatically associate messages for a particular sensor and plot them in the same series.
::: info
This field allows a recipient automatically associate messages for a particular sensor and plot them in the same series.
:::
- `invalid`: Specifies a value that can be set on a field to indicate that the data is _invalid_: the recipient should ignore the field if it has this value.
For example, `BATTERY_STATUS.current_battery` specifies `invalid="-1"`, so a battery that does not measure supplied _current_ should set `BATTERY_STATUS.current_battery` to `-1`.
@@ -277,8 +289,9 @@ The tag attributes indicates the time of deprecation and the replacement item, w
The generator toolchain can be configured to conditionally build messages omitting the `deprecated` entries.
> [!TIP]
> An entity should be marked as deprecated only when the main users have had an opportunity to update to the new method.
::: tip
An entity should be marked as deprecated only when the main users have had an opportunity to update to the new method.
:::
As a concrete example, below we see that [SET_MODE](../messages/common.md#SET_MODE) is deprecated and replaced by [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) on `2015-12`.
en/index.md
+4 -3
View File
@@ -13,9 +13,10 @@ The reference message set that is implemented by _most_ ground control stations
[Code generators](getting_started/generate_libraries.md) create software libraries for [specific programming languages](#supported_languages) from these XML message definitions, which can then be used by drones, ground control stations, and other MAVLink systems to communicate.
The generated libraries are typically MIT-licensed, and can therefore be _used_ without limits in any closed-source application without publishing the source code of the closed-source application.
> [!NOTE]
> The C reference implementation is a header-only library that is highly optimized for resource-constrained systems with limited RAM and flash memory.
> It is field-proven and deployed in many products where it serves as interoperability interface between components of different manufacturers.
::: info
The C reference implementation is a header-only library that is highly optimized for resource-constrained systems with limited RAM and flash memory.
It is field-proven and deployed in many products where it serves as interoperability interface between components of different manufacturers.
:::
MAVLink was first released early 2009 by Lorenz Meier and has now a [significant number of contributors](https://github.com/mavlink/mavlink/graphs/contributors).
en/mavgen_c/example_c_udp.md
+20 -14
View File
@@ -3,9 +3,10 @@
The [MAVLink UDP Example](https://github.com/mavlink/mavlink/tree/master/examples/linux) is a simple C example that sends some data to _QGroundControl_ using MAVLink over UDP.
_QGroundControl_ responds with heartbeats and other messages, which are then printed by this program.
> [!NOTE]
> The example should work on any Unix-like system (Linux, MacOS, BSD, etc.).
> These instructions were tested on a clean _Ubuntu LTS 20.04_ installation using the default version of _gcc_ (9.3.0).
::: info
The example should work on any Unix-like system (Linux, MacOS, BSD, etc.).
These instructions were tested on a clean _Ubuntu LTS 20.04_ installation using the default version of _gcc_ (9.3.0).
:::
## Building/Running the Example
@@ -18,14 +19,17 @@ The following instructions show how to build and run the example.
python3 -m pymavlink.tools.mavgen --lang=C --wire-protocol=2.0 --output=./include/ message_definitions/v1.0/common.xml
```
> [!TIP]
> Alternatively you can clone the [mavlink/mavlink](https://github.com/mavlink/mavlink/) repository and [Download prebuilt headers](../index.md#prebuilt_libraries) to the same location.
::: tip
Alternatively you can clone the [mavlink/mavlink](https://github.com/mavlink/mavlink/) repository and [Download prebuilt headers](../index.md#prebuilt_libraries) to the same location.
:::
> [!NOTE]
> The example will not work with MAVLink 1 because it uses a message that includes extension fields which do not exist in MAVLink 1 (`SYS_STATUS`).
::: info
The example will not work with MAVLink 1 because it uses a message that includes extension fields which do not exist in MAVLink 1 (`SYS_STATUS`).
:::
> [!NOTE]
> You can put/generate the library wherever you like, but the build command below assumes they are located in directory named **include** below the MAVLink root directory.
::: info
You can put/generate the library wherever you like, but the build command below assumes they are located in directory named **include** below the MAVLink root directory.
:::
1. Open a terminal and navigate to [examples/linux](https://github.com/mavlink/mavlink/tree/master/examples/linux)
1. Compile with GCC using the following command:
@@ -34,9 +38,10 @@ The following instructions show how to build and run the example.
gcc -std=c99 -I ../../include/common -o mavlink_udp mavlink_udp.c
```
> [!NOTE]
> The MAVLink header directory must be added to the include path.
> The path here assumes you are building the code from the example directory, and that have installed the headers in **mavlink/include**.
::: info
The MAVLink header directory must be added to the include path.
The path here assumes you are building the code from the example directory, and that have installed the headers in **mavlink/include**.
:::
1. Run the executable from the terminal:
@@ -51,8 +56,9 @@ The following instructions show how to build and run the example.
_QGroundControl_ immediately starts broadcasting its `HEARTBEAT` on port 14551.
> [!NOTE]
> _QGroundControl_ returns data, but will not actually "connect" to the example (it will continue to display the message _Waiting for Vehicle Connection_).
::: info
_QGroundControl_ returns data, but will not actually "connect" to the example (it will continue to display the message _Waiting for Vehicle Connection_).
:::
1. The example should start displaying the received data in the terminal:
en/mavgen_c/index.md
+30 -22
View File
@@ -9,9 +9,10 @@ This topic explains how to get and use the library.
If you are using a [standard dialect](../messages/index.md#dialects) then download the _MAVLink 2_ library from Github: [c_library_v2](https://github.com/mavlink/c_library_v2).
> [!TIP]
> The MAVLink 2 library supports both MAVLink 2 and MAVLink 1, and is rebuilt for all the _standard dialects_ whenever any of the definitions in the _mavlink/mavlink_ repo change.
> It supersedes the MAVLink 1 library ([c_library_v1](https://github.com/mavlink/c_library_v1)), and should be used by preference.
::: tip
The MAVLink 2 library supports both MAVLink 2 and MAVLink 1, and is rebuilt for all the _standard dialects_ whenever any of the definitions in the _mavlink/mavlink_ repo change.
It supersedes the MAVLink 1 library ([c_library_v1](https://github.com/mavlink/c_library_v1)), and should be used by preference.
:::
If you need libraries for a custom dialect then you will need to [install mavgen](../getting_started/installation.md) and [generate](../getting_started/generate_libraries.md) them yourself.
These can then be used in the same way as the pre-generated libraries.
@@ -30,13 +31,15 @@ To use MAVLink in your C project, include the **mavlink.h** header file for your
This will automatically add the header files for all messages in your dialect, and for any dialect files that it includes.
> [!WARNING]
> Only include the header file for a single dialect.
> If you need to support messages from a _number of dialects_ then create a new "parent" dialect XML file that includes them (and use its generated header as shown above).
::: warning
Only include the header file for a single dialect.
If you need to support messages from a _number of dialects_ then create a new "parent" dialect XML file that includes them (and use its generated header as shown above).
:::
> [!TIP]
> _Do not include the individual message files_.
> If you generate your own headers, you will have to add their output location to your C compiler's search path.
::: tip
_Do not include the individual message files_.
If you generate your own headers, you will have to add their output location to your C compiler's search path.
:::
When compiling the project, make sure to add the include directory:
@@ -95,10 +98,11 @@ The _MAVLink 1_ pre-built library [mavlink/c_library_v1](https://github.com/mavl
The _MAVLink 2_ C library offers the same range of APIs as was offered by _MAVLink 1_.
> [!NOTE]
> The major change from an API perspective is that you don't need to provide a message CRC table any more, or message length table.
> These have been folded into a single packed table, replacing the old table which was indexed by `msgId`.
> That was necessary to cope with the much larger 24 bit namespace of message IDs.
::: info
The major change from an API perspective is that you don't need to provide a message CRC table any more, or message length table.
These have been folded into a single packed table, replacing the old table which was indexed by `msgId`.
That was necessary to cope with the much larger 24 bit namespace of message IDs.
:::
_MAVLink 2_ usage is covered in the following sections (this includes [Working with MAVLink 1](#mavlink_1) which explains how you can communicate with both _MAVLink 2_ and _MAVLink 1_ (only) libraries).
@@ -163,9 +167,10 @@ while(serial.bytesAvailable > 0)
}
```
> [!TIP]
> The [mavlink_helpers.h](https://github.com/mavlink/c_library_v2/blob/master/mavlink_helpers.h) include other parser functions: `mavlink_frame_char()` and `mavlink_frame_char_buffer()`.
> Generally you will want to use `mavlink_parse_char()` (which calls those functions internally), but reviewing the other methods can give you a better understanding of the parsing process.
::: tip
The [mavlink_helpers.h](https://github.com/mavlink/c_library_v2/blob/master/mavlink_helpers.h) include other parser functions: `mavlink_frame_char()` and `mavlink_frame_char_buffer()`.
Generally you will want to use `mavlink_parse_char()` (which calls those functions internally), but reviewing the other methods can give you a better understanding of the parsing process.
:::
### Decoding the Payload {#decode_payload}
@@ -208,8 +213,9 @@ if (mavlink_parse_char(chan, byte, &msg, &status)) {
The decoder/encoder functions and ids for each message in a dialect can be found in separate header files under the dialect folder.
The headers are named with a format including the message name (**mavlink_msg\__message_name_.h**)
> [!TIP]
> Individual message definitions for the dialect are pulled in when you include **mavlink.h** for your dialect, so you don't need to include these separately.
::: tip
Individual message definitions for the dialect are pulled in when you include **mavlink.h** for your dialect, so you don't need to include these separately.
:::
The most useful decoding function is named with the pattern **mavlink_msg\__message_name_\_decode()**, and extracts the whole payload into a C struct (with fields mapping to the original XML message definition).
There are also separate decoder functions to just get the values of individual fields.
@@ -248,8 +254,9 @@ A [MAVLink Command](../services/command.md) encodes a command defined in a [MAV_
Command packets are parsed and decoded in the same way as [any other payload](#decode_payload) - i.e. you switch on message id of `MAVLINK_MSG_ID_COMMAND_INT`/`MAVLINK_MSG_ID_COMMAND_LONG` and call the decoder functions `mavlink_msg_command_int_decode()`/`mavlink_msg_command_long_decode()` (respectively) to get a C struct mapping the original message.
> [!NOTE]
> The message types differ in that `COMMAND_INT` has `int32` types for parameter fields 6 and 7 (instead of `float`) and also includes a field for the geometric frame of reference of any positional information in the command.
::: info
The message types differ in that `COMMAND_INT` has `int32` types for parameter fields 6 and 7 (instead of `float`) and also includes a field for the geometric frame of reference of any positional information in the command.
:::
To decode the specific command you then switch on the value of the `mavlink_command_int_t.command` or `mavlink_command_long_t.command` field, which contains the particular `MAV_CMD` id.
@@ -319,8 +326,9 @@ if (msg->magic == MAVLINK_STX_MAVLINK1) {
In most cases this should not be necessary as the XML message definition files for _MAVLink 1_ and _MAVLink 2_ are the same, so you can treat incoming _MAVLink 1_ messages the same as _MAVLink 2_ messages.
> [!NOTE]
> _MAVLink 1_ is restricted to message IDs less than 256, so any messages with a higher message ID won't be received as _MAVLink 1_.
::: info
_MAVLink 1_ is restricted to message IDs less than 256, so any messages with a higher message ID won't be received as _MAVLink 1_.
:::
It is advisable to switch to _MAVLink 2_ when the communication partner sends _MAVLink 2_ (see [Version Handshaking](../guide/mavlink_version.md#version_handshaking)). The minimal solution is to watch incoming packets using code similar to this:
en/mavgen_python/index.md
+40 -29
View File
@@ -7,14 +7,16 @@ The library can be used with Python 3.5+ and supports both MAVLink 1 and MAVLink
This topic explains how to get and use the _Pymavlink_ MAVLink Python libraries (generated using [mavgen](../getting_started/generate_libraries.md#mavgen)).
> [!NOTE]
> Pymavlink is developed in its own [project](https://github.com/ArduPilot/pymavlink), which includes the command line MAVLink generator (mavgen), Python bindings to create _Pymavlink_, and other useful tools and utilities.
> MAVLink includes the [Pymavlink](https://github.com/ArduPilot/pymavlink) repository as a submodule.
> While you can work with that project directly, this documentation explains how to work with _pymavlink_ _**using the MAVLink project**_.
::: info
Pymavlink is developed in its own [project](https://github.com/ArduPilot/pymavlink), which includes the command line MAVLink generator (mavgen), Python bindings to create _Pymavlink_, and other useful tools and utilities.
MAVLink includes the [Pymavlink](https://github.com/ArduPilot/pymavlink) repository as a submodule.
While you can work with that project directly, this documentation explains how to work with _pymavlink_ _**using the MAVLink project**_.
:::
> [!TIP]
> If you are writing a MAVLink application to communicate with an autopilot you may prefer to use a higher level library like [MAVSDK-Python](https://github.com/mavlink/MAVSDK-Python#mavsdk-python) or [DroneKit-Python](http://python.dronekit.io/).
> These implement a number of [MAVLink microservices](../about/overview.md).
::: tip
If you are writing a MAVLink application to communicate with an autopilot you may prefer to use a higher level library like [MAVSDK-Python](https://github.com/mavlink/MAVSDK-Python#mavsdk-python) or [DroneKit-Python](http://python.dronekit.io/).
These implement a number of [MAVLink microservices](../about/overview.md).
:::
## Getting the Python MAVLink Libraries
@@ -30,8 +32,9 @@ If you need a [standard dialect](../messages/index.md#dialects) then you can ins
pip install pymavlink
```
> [!TIP]
> The [PyPi](https://pypi.org/project/pymavlink/) repository takes message definitions from the [ArduPilot/mavlink](https://github.com/ArduPilot/mavlink) fork, which may diverge slightly from _MAVLink/mavlink_.
::: tip
The [PyPi](https://pypi.org/project/pymavlink/) repository takes message definitions from the [ArduPilot/mavlink](https://github.com/ArduPilot/mavlink) fork, which may diverge slightly from _MAVLink/mavlink_.
:::
### Generate a Custom MAVLink Dialect
@@ -81,9 +84,10 @@ There are several main caveats to be aware of when using **mavutil**:
- **mavutil** is still a relatively low-level MAVLink API.
It has limited support for even the most common [MAVLink microservices](../services/index.md).
> [!TIP]
> You don't have to use **mavutil** but it includes a lot of useful code that you might otherwise have to write from scratch.
> In particular the connection code and methods to filter incoming messages are useful for any autopilot.
::: tip
You don't have to use **mavutil** but it includes a lot of useful code that you might otherwise have to write from scratch.
In particular the connection code and methods to filter incoming messages are useful for any autopilot.
:::
The set of modules in the _pymavlink_ package are listed below:
@@ -118,8 +122,9 @@ You can change this by setting environment variables:
- `MAVLINK20`: Set to 1 (if unset then default to MAVLink 1)
- `MDEF`: Location of message definition libraries
> [!TIP]
> You can also change the dialect by passing its name to `mavutil.mavlink_connection()` when [setting up a connection](#setting_up_connection).
::: tip
You can also change the dialect by passing its name to `mavutil.mavlink_connection()` when [setting up a connection](#setting_up_connection).
:::
If you are not using _mavutil_ then you can import the dialect file that you want to use directly:
@@ -136,9 +141,10 @@ from pymavlink.dialects.v20 import common as mavlink2
The **mavutil** module provides the `mavlink_connection()` method for setting up communication links to MAVLink systems over serial ports, tcp, or udp channels.
It can also connect to a file object, which is useful when working with telemetry logs.
> [!WARNING]
> The method returns an object that represents a single system, but will collect messages from multiple systems on the link.
> This is OK for two-system networks, but if you need to connect over a multi-vehicle IP network see [source-system-filtering](https://github.com/peterbarker/dronekit-python/tree/source-system-filtering/examples/multivehicle).
::: warning
The method returns an object that represents a single system, but will collect messages from multiple systems on the link.
This is OK for two-system networks, but if you need to connect over a multi-vehicle IP network see [source-system-filtering](https://github.com/peterbarker/dronekit-python/tree/source-system-filtering/examples/multivehicle).
:::
The `mavlink_connection()` method takes a [connection string](#connection_string) defining the channel, and some optional arguments for setting the baud rate and other properties of the link (the format of the connection string automatically sets, and may override, some optional arguments).
@@ -158,10 +164,11 @@ print("Heartbeat from system (system %u component %u)" % (the_connection.target_
# Once connected, use 'the_connection' to get and send messages
```
> [!NOTE]
> The `udpin` prefix used above creates a socket to _listen for_ a UDP connection on the specified port.
> This is the normal way to connect an autopilot simulator).
> The complementary `udpout` prefix creates a socket that _initiates_ an IP connection:
::: info
The `udpin` prefix used above creates a socket to _listen for_ a UDP connection on the specified port.
This is the normal way to connect an autopilot simulator).
The complementary `udpout` prefix creates a socket that _initiates_ an IP connection:
:::
```python
the_connection = mavutil.mavlink_connection('udpout:localhost:14540')
@@ -206,8 +213,9 @@ Some of the strings you can use for different types of connections are listed be
| Windows computer connected to the vehicle via USB (in this case on COM14) | `com14` |
| Windows computer connected to the vehicle using a 3DR Telemetry Radio on `COM14` | `com14` (also set `baud=57600`) |
> [!NOTE]
> While MAVLink does not define the UDP ports used for different purposes, there is a _defacto_ standard that MAVLink APIs should listen for SITL connections on UDP port `14540` while a GCS should listen for connections on UDP `14550`.
::: info
While MAVLink does not define the UDP ports used for different purposes, there is a _defacto_ standard that MAVLink APIs should listen for SITL connections on UDP port `14540` while a GCS should listen for connections on UDP `14550`.
:::
### Sending Messages {#sending}
@@ -238,8 +246,9 @@ the_connection.mav.system_time_send(time_unix_usec, time_boot_ms)
Other examples can be seen in [Publishing a Heartbeat](#heartbeat) and [Requesting Specific Messages](#specific_messages) below.
> [!NOTE]
> If you are not using **mavutil** you will need to create and set up the `MAVLink` object yourself so it knows about the channel that it should use for sending messages, which is represented by the `file` attribute.
::: info
If you are not using **mavutil** you will need to create and set up the `MAVLink` object yourself so it knows about the channel that it should use for sending messages, which is represented by the `file` attribute.
:::
### Receiving Messages
@@ -314,8 +323,9 @@ For more information see [How to request messages](../mavgen_python/howto_reques
All MAVLink components should periodically broadcast a [HEARTBEAT](../messages/common.md#HEARTBEAT) message and listen for heartbeats from other systems.
Systems consider themselves [connected](../services/heartbeat.md) to another system as long as they regularly receive a `HEARTBEAT` from it.
> [!NOTE]
> [Sending Messages](#sending) explains how messages are sent.
::: info
[Sending Messages](#sending) explains how messages are sent.
:::
The `HEARTBEAT` message can be sent using `MAVLink.heartbeat_send()` message in the generated Python dialect file.
The method definition is provided below:
@@ -350,8 +360,9 @@ the_connection.mav.heartbeat_send(mavutil.mavlink.MAV_TYPE_ONBOARD_CONTROLLER,
mavutil.mavlink.MAV_AUTOPILOT_INVALID, 0, 0, 0)
```
> [!NOTE]
> The various types used above come from `enum` in the dialect file.
::: info
The various types used above come from `enum` in the dialect file.
:::
The rate at which the heartbeat should be sent depends on the channel, but is normally 1Hz.
en/mavgen_python/message_signing.md
+12 -9
View File
@@ -7,11 +7,13 @@ All you need to do is provide a secret key and initial timestamp, optionally spe
The way you do this depends on whether you are using **mavutil** to manage the connection or using a `MAVLink` object directly.
> [!NOTE]
> While not covered in this topic, you should also write code to:
>
> - Save and load the key and last-timestamp from permanent storage
> - Implement a mechanism to create and share the key. For more information see [Message Signing > Secret Key Management](../guide/message_signing.md#secret_key).
::: info
While not covered in this topic, you should also write code to:
- Save and load the key and last-timestamp from permanent storage
- Implement a mechanism to create and share the key. For more information see [Message Signing > Secret Key Management](../guide/message_signing.md#secret_key).
:::
#### Signing using MAVLink Class
@@ -30,10 +32,11 @@ if signing:
mav.signing.sign_outgoing = True
```
> [!NOTE]
> The `MAVLink` class does not ensure that your `link_id` or _initial_ `timestamp` are appropriate.
> The initial timestamp should be based on current system time.
> For more information see [Message Signing](../guide/message_signing.md#timestamp).
::: info
The `MAVLink` class does not ensure that your `link_id` or _initial_ `timestamp` are appropriate.
The initial timestamp should be based on current system time.
For more information see [Message Signing](../guide/message_signing.md#timestamp).
:::
#### Signing using mavutil
en/services/battery.md
+23 -19
View File
@@ -7,9 +7,10 @@ MAVLink provides a number of messages for providing battery information:
- Emitted at around 0.5 Hz (for each battery).
- Some batteries may provide [fault](#MAV_BATTERY_FAULT) and [mode](#MAV_BATTERY_MODE) information in this message.
> [!NOTE]
> `BATTERY_STATUS` is expected to be superseded by [BATTERY_STATUS_V2](../messages/development.html#BATTERY_STATUS_V2).
> For more information see [RFC 0018 - Improved Battery Status Reporting](https://github.com/mavlink/rfcs/pull/19).
::: info
`BATTERY_STATUS` is expected to be superseded by [BATTERY_STATUS_V2](../messages/development.html#BATTERY_STATUS_V2).
For more information see [RFC 0018 - Improved Battery Status Reporting](https://github.com/mavlink/rfcs/pull/19).
:::
- [BATTERY_INFO](#BATTERY_INFO): Battery information that changes rarely, if ever (e.g. device name):
@@ -18,21 +19,22 @@ MAVLink provides a number of messages for providing battery information:
The messages should be sent individually for each battery in the system (the messages have an instance `id` field that is used to identify the corresponding battery).
It is up to the GCS to provide an appropriate mechanism that allows the user to assess the aggregate battery status on systems that have multiple batteries.
> [!NOTE]
> There is no standardized mechanism to report the "aggregate" battery state on a multi-battery system.
> A GCS is expected to provide enough information from the individual battery reports to allow a user to make a reasonable assessment of vehicle battery status.
::: info
There is no standardized mechanism to report the "aggregate" battery state on a multi-battery system.
A GCS is expected to provide enough information from the individual battery reports to allow a user to make a reasonable assessment of vehicle battery status.
:::
## Message/Enum Summary
| Message | Description |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| <span id="BATTERY_STATUS"></span>[BATTERY_STATUS](../messages/common.md#BATTERY_STATUS) | Battery message used for frequent status update - e.g. of current capacity, voltages, faults, etc. |
| <span id="BATTERY_INFO"></span>[BATTERY_INFO](../messages/common.md#BATTERY_INFO) (WIP) | Battery message used for invariant or infrequently changing data - e.g. battery name, battery full/empty capacity and voltages etc. |
| Message | Description |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| <a id="BATTERY_STATUS"></a>[BATTERY_STATUS](../messages/common.md#BATTERY_STATUS) | Battery message used for frequent status update - e.g. of current capacity, voltages, faults, etc. |
| <a id="BATTERY_INFO"></a>[BATTERY_INFO](../messages/common.md#BATTERY_INFO) (WIP) | Battery message used for invariant or infrequently changing data - e.g. battery name, battery full/empty capacity and voltages etc. |
| Enum | Description |
| ------------------------------------------------------------------------------------------------ | ------------------------- |
| <span id="MAV_BATTERY_FAULT"></span>[MAV_BATTERY_FAULT](../messages/common.md#MAV_BATTERY_FAULT) | Fault/health indications. |
| <span id="MAV_BATTERY_MODE"></span>[MAV_BATTERY_MODE](../messages/common.md#MAV_BATTERY_MODE) | Battery mode. |
| Enum | Description |
| ------------------------------------------------------------------------------------------ | ------------------------- |
| <a id="MAV_BATTERY_FAULT"></a>[MAV_BATTERY_FAULT](../messages/common.md#MAV_BATTERY_FAULT) | Fault/health indications. |
| <a id="MAV_BATTERY_MODE"></a>[MAV_BATTERY_MODE](../messages/common.md#MAV_BATTERY_MODE) | Battery mode. |
## Battery Components
@@ -46,8 +48,9 @@ Batteries that are distinct components on the MAVLink network must:
[MAV_COMP_ID_BATTERY](../messages/common.md#MAV_COMP_ID_BATTERY) and [MAV_COMP_ID_BATTERY2](../messages/common.md#MAV_COMP_ID_BATTERY2) should be used by default for the first two battery instances.
Subsequent instances can use any spare/unused ID.
> [!NOTE]
> Ground stations (and other components) that are interested in battery messages should differentiate batteries based on `BATTERY_STATUS.id`/`BATTERY_INFO.id`.
::: info
Ground stations (and other components) that are interested in battery messages should differentiate batteries based on `BATTERY_STATUS.id`/`BATTERY_INFO.id`.
:::
## A Note on SYS_STATUS
@@ -58,6 +61,7 @@ On a single-battery system these usually provide the same information as the `BA
On multi-battery systems the values are not standardised, and depend on the flight stack and/or flight stack configuration.
For example, a system may report the same information as the first `BATTERY_STATUS`, allow the user to configure which battery is reported (i.e. with a parameter), report the battery with the lowest remaining capacity.
> [!NOTE]
> GCS should not rely on the value of `SYS_STATUS`.
> However it cannot be removed because it is used for battery reporting on many legacy systems (e.g. On-screen displays).
::: info
GCS should not rely on the value of `SYS_STATUS`.
However it cannot be removed because it is used for battery reporting on many legacy systems (e.g. On-screen displays).
:::
en/services/camera.md
+58 -44
View File
@@ -4,14 +4,16 @@ The camera protocol v2 is used to configure camera payloads and request their st
It provides basic methods for photo capture, video capture and streaming, setting zoom and focus, querying and configuring camera storage, and selecting multiple cameras.
It also defines a camera definition file format that allows a GCS to generate a configuration UI for setting any property of the camera using parameters.
> [!NOTE]
> This protocol supersedes [Camera Protocol v1 (Simple Trigger Protocol)](../services/camera_v1.md).
> The older protocol enables camera triggering, but does not support other features or querying camera capabilities.
::: info
This protocol supersedes [Camera Protocol v1 (Simple Trigger Protocol)](../services/camera_v1.md).
The older protocol enables camera triggering, but does not support other features or querying camera capabilities.
:::
> [!WARNING]
> We are transitioning from specific request commands to a single generic requestor.
> GCS and MAVLink SDKs/apps should support both approaches as we migrate to exclusive use of the new method (documented here).
> For more information see [Migration Notes for GCS & Camera Servers](#migration-notes-for-gcs--mavlink-sdks).
::: warning
We are transitioning from specific request commands to a single generic requestor.
GCS and MAVLink SDKs/apps should support both approaches as we migrate to exclusive use of the new method (documented here).
For more information see [Migration Notes for GCS & Camera Servers](#migration-notes-for-gcs--mavlink-sdks).
:::
## MAVLink Camera Implementations
@@ -68,9 +70,10 @@ When processing a camera item in a mission the autopilot should:
- For other `Target Camera ID` values, re-emit the `MAV_CMD` using the command protocol, setting the target component id to the `id` set in the camera mission item.
It should also log any errors from the returned `COMMAND_ACK`.
> [!NOTE]
> Flight stacks that predate using a camera id typically re-emit the mission command addressed either to the broadcast component id (`0`) or to [MAV_COMP_ID_CAMERA](../messages/common.md#MAV_COMP_ID_CAMERA).
> The former triggers all cameras on the system, while the later provides better command handling because there is only one `COMMAND_ACK`.
::: info
Flight stacks that predate using a camera id typically re-emit the mission command addressed either to the broadcast component id (`0`) or to [MAV_COMP_ID_CAMERA](../messages/common.md#MAV_COMP_ID_CAMERA).
The former triggers all cameras on the system, while the later provides better command handling because there is only one `COMMAND_ACK`.
:::
## Camera Discovery
@@ -86,15 +89,17 @@ A GCS should start the [Camera Identification](#camera_identification) process t
- MAVLink camera component.
- Autopilot, in order to detect autopilot-connected cameras.
> [!NOTE]
> If a receiving system stops receiving heartbeats from the camera it is assumed to be _disconnected_, and should be removed from the list of available cameras.
> If heartbeats are again detected, the _camera identification_ process below must be restarted from the beginning.
::: info
If a receiving system stops receiving heartbeats from the camera it is assumed to be _disconnected_, and should be removed from the list of available cameras.
If heartbeats are again detected, the _camera identification_ process below must be restarted from the beginning.
:::
> [!NOTE]
> If a vehicle has more than one MAVLink camera, each camera will have a different component ID and send its own heartbeat.
> The vehicle autopilot might also have directly connected cameras, which are separately addressed by a camera device id.
> The GCS should create multiple instances of a camera controller based on the component ID of each camera, and also the component ID of the autopilot and each of its attached camera devices.
> All commands are sent to a specific camera by addressing the command to a specific component ID, and additionally the camera device id for autopilots.
::: info
If a vehicle has more than one MAVLink camera, each camera will have a different component ID and send its own heartbeat.
The vehicle autopilot might also have directly connected cameras, which are separately addressed by a camera device id.
The GCS should create multiple instances of a camera controller based on the component ID of each camera, and also the component ID of the autopilot and each of its attached camera devices.
All commands are sent to a specific camera by addressing the command to a specific component ID, and additionally the camera device id for autopilots.
:::
### Camera Identification {#camera_identification}
@@ -105,8 +110,9 @@ The process involves requesting the [CAMERA_INFORMATION](../messages/common.md#C
`CAMERA_INFORMATION.flags` provides information about camera capabilities.
It contains a bitmap of [CAMERA_CAP_FLAGS](../messages/common.md#CAMERA_CAP_FLAGS) values that tell the GCS if the camera supports still image capture, video capture, or video streaming, and if it needs to be in a certain mode for capture, etc.
> [!TIP]
> Camera identification must be carried out before all other camera operations!
::: tip
Camera identification must be carried out before all other camera operations!
:::
The first time a heartbeat is received from a new camera component ([HEARTBEAT.type=MAV_TYPE_CAMERA](../messages/common.md#MAV_TYPE_CAMERA)), the GCS should send it a [MAV_CMD_REQUEST_MESSAGE](../messages/common.md#MAV_CMD_REQUEST_MESSAGE) message asking for [CAMERA_INFORMATION](../messages/common.md#CAMERA_INFORMATION) (message id 259).
The camera will then respond with the a [COMMAND_ACK](../messages/common.md#COMMAND_ACK) message containing a result.
@@ -160,10 +166,11 @@ If this URI exists, the GCS will request it, parse it and prepare the UI for the
The `CAMERA_INFORMATION.cam_definition_version` field should provide a version for the definition file, allowing the GCS to cache it.
Once downloaded, it would only be requested again if the version number changes.
> [!NOTE]
> A GCS that implements this protocol is expected to support both HTTP (`http://`) and [MAVLink FTP](../services/ftp.md) (`mftp://`) URIs for download of the camera definition file.
> If the camera provides an HTTP or MAVLink FTP interface, the definition file can be hosted on the camera itself.
> Otherwise, it can be _hosted_ anywhere (on any reachable server).
::: info
A GCS that implements this protocol is expected to support both HTTP (`http://`) and [MAVLink FTP](../services/ftp.md) (`mftp://`) URIs for download of the camera definition file.
If the camera provides an HTTP or MAVLink FTP interface, the definition file can be hosted on the camera itself.
Otherwise, it can be _hosted_ anywhere (on any reachable server).
:::
## Basic Camera Operations
@@ -196,9 +203,9 @@ sequenceDiagram;
Camera->>GCS: CAMERA_SETTINGS
-->
> [!NOTE]
> Command acknowledgment and message resending is handled in the same way as for [camera identification](#camera_identification)
> (if a successful ACK is received the camera will expect the `CAMERA_SETTINGS` message, and repeat the cycle - up to 3 times - until it is received).
::: info
Command acknowledgment and message resending is handled in the same way as for [camera identification](#camera_identification) (if a successful ACK is received the camera will expect the `CAMERA_SETTINGS` message, and repeat the cycle - up to 3 times - until it is received).
:::
To set the camera to a specific mode, the GCS would send the [MAV_CMD_SET_CAMERA_MODE](../messages/common.md#MAV_CMD_SET_CAMERA_MODE) command with the appropriate mode.
@@ -216,8 +223,9 @@ sequenceDiagram;
Note over Camera,GCS: If MAV_RESULT_ACCEPTED, mode was changed.
-->
> [!NOTE]
> The operation follows the normal [Command Protocol](../services/command.md) rules for command/acknowledgment.
::: info
The operation follows the normal [Command Protocol](../services/command.md) rules for command/acknowledgment.
:::
### Storage Status
@@ -242,9 +250,10 @@ The camera immediately returns the normal command acknowledgment ([MAV_RESULT](.
Each time an image is captured, the camera _broadcasts_ a [CAMERA_IMAGE_CAPTURED](../messages/common.md#CAMERA_IMAGE_CAPTURED) message.
This message not only tells the GCS the image was captured, it is also intended for geo-tagging.
> [!NOTE]
> The camera must iterate `CAMERA_IMAGE_CAPTURED.image_index` and the counter used in `CAMERA_CAPTURE_STATUS.image_count` for every _new_ image capture (these values iterate until explicitly cleared using [MAV_CMD_STORAGE_FORMAT](#MAV_CMD_STORAGE_FORMAT)).
> The index and total image count can be used to [re-request missing images](#missing_images) (e.g. images captured when the vehicle was out of telemetry range).
::: info
The camera must iterate `CAMERA_IMAGE_CAPTURED.image_index` and the counter used in `CAMERA_CAPTURE_STATUS.image_count` for every _new_ image capture (these values iterate until explicitly cleared using [MAV_CMD_STORAGE_FORMAT](#MAV_CMD_STORAGE_FORMAT)).
The index and total image count can be used to [re-request missing images](#missing_images) (e.g. images captured when the vehicle was out of telemetry range).
:::
The [MAV_CMD_IMAGE_STOP_CAPTURE](../messages/common.md#MAV_CMD_IMAGE_STOP_CAPTURE) command can optionally be sent to stop an image capture sequence (this is needed if image capture has been set to continue forever).
@@ -322,8 +331,9 @@ To stop recording, the GCS uses the [MAV_CMD_VIDEO_STOP_CAPTURE](../messages/com
### Video Streaming {#video_streaming}
> [!NOTE]
> The GCS should already have identified all connected cameras by their heartbeat and followed the [Camera Identification](#camera_identification) steps to get [CAMERA_INFORMATION](../messages/common.md#CAMERA_INFORMATION) for every camera.
::: info
The GCS should already have identified all connected cameras by their heartbeat and followed the [Camera Identification](#camera_identification) steps to get [CAMERA_INFORMATION](../messages/common.md#CAMERA_INFORMATION) for every camera.
:::
A camera is capable of streaming video if it sets the [CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM](../messages/common.md#CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM) bit set in [CAMERA_INFORMATION.flags](../messages/common.md#CAMERA_INFORMATION).
@@ -351,14 +361,16 @@ The steps are:
1. GCS checks if [CAMERA_INFORMATION.flags](../messages/common.md#CAMERA_INFORMATION) contains the [CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM](../messages/common.md#CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM) flag.
1. If so, the GCS sends the [MAV_CMD_REQUEST_MESSAGE](../messages/common.md#MAV_CMD_REQUEST_MESSAGE) message to the camera requesting the video streaming configuration (`param1=269`) for all streams (`param2=0`).
> [!NOTE]
> A GCS can also request information for a _particular stream_ by setting its id in `param2`.
::: info
A GCS can also request information for a _particular stream_ by setting its id in `param2`.
:::
1. Camera returns a [VIDEO_STREAM_INFORMATION](../messages/common.md#VIDEO_STREAM_INFORMATION) message for the specified stream or all streams it supports.
> [!NOTE]
> If your camera only provides video streaming and nothing else (no camera features), the [CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM](../messages/common.md#CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM) flag is the only flag you need to set.
> The GCS will then provide video streaming support and skip camera control.
::: info
If your camera only provides video streaming and nothing else (no camera features), the [CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM](../messages/common.md#CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM) flag is the only flag you need to set.
The GCS will then provide video streaming support and skip camera control.
:::
### Video Metadata
@@ -378,9 +390,10 @@ The [CAMERA_THERMAL_RANGE](#CAMERA_THERMAL_RANGE) message can be streamed alongs
The message includes the associated stream and camera id, along with the position and value of the maximum and minimum temperature in the video frame.
That is sufficient to overlay the hottest and coldest points on a video, and in theory to determine the absolute temperature of all pixels.
> [!NOTE]
> The message is streamed alongside the video stream, but there is no precise mechanism to synchronize values to frames.
> The information is therefore an estimate/approximate.
::: info
The message is streamed alongside the video stream, but there is no precise mechanism to synchronize values to frames.
The information is therefore an estimate/approximate.
:::
The message can be requested for a particular camera and stream using the [MAV_CMD_SET_MESSAGE_INTERVAL](#MAV_CMD_SET_MESSAGE_INTERVAL), when the associated [VIDEO_STREAM_STATUS.flag](#VIDEO_STREAM_STATUS) for the stream has bit [VIDEO_STREAM_STATUS_FLAGS_THERMAL_RANGE_ENABLED](#VIDEO_STREAM_STATUS_FLAGS_THERMAL_RANGE_ENABLED) set.
Note that `MAV_CMD_SET_MESSAGE_INTERVAL.param3` indicates the stream id of the current camera, or 0 for all streams, while `param4` indicates the target `camera_device_id` for autopilot-attached cameras or 0 for MAVLink cameras.
@@ -405,8 +418,9 @@ After stopping tracking you should call `MAV_CMD_SET_MESSAGE_INTERVAL` to stop s
#### Camera tracking message sequence
> [!NOTE]
> The GCS should already have identified all connected cameras by their heartbeat and followed the [Camera Identification](#camera_identification) steps to get [CAMERA_INFORMATION](../messages/common.md#CAMERA_INFORMATION) for every camera.
::: info
The GCS should already have identified all connected cameras by their heartbeat and followed the [Camera Identification](#camera_identification) steps to get [CAMERA_INFORMATION](../messages/common.md#CAMERA_INFORMATION) for every camera.
:::
The sequence for tracking a point is shown below (tracking a rectangle is the same sequence but a different tracking command).
en/services/camera_def.md
+21 -15
View File
@@ -9,19 +9,22 @@ In addition, it may contain localisations of GUI strings for display to the user
At the bottom of this page, you can find a [full example](#full_example) of a _Camera Definition File_.
> [!NOTE]
> A _Camera Definition File_ is required because the camera options differ so greatly between cameras.
> It is not reasonable to create specific MAVLink messages for each and every possible option and to tell the GCS the valid options for each camera setting.
::: info
A _Camera Definition File_ is required because the camera options differ so greatly between cameras.
It is not reasonable to create specific MAVLink messages for each and every possible option and to tell the GCS the valid options for each camera setting.
:::
## File Compression
Camera definition files may be **.xz** compressed (this is recommended for files that are hosted on the camera component/device).
> [!WARNING]
> Systems that _request_ camera definition files **must** support extraction of **.xz**-compressed definition files.
::: warning
Systems that _request_ camera definition files **must** support extraction of **.xz**-compressed definition files.
:::
> [!TIP]
> The [Tukaani Project XZ Embedded](https://tukaani.org/xz/embedded.html) library is an easy-to-use XZ compression library for embedded systems.
::: tip
The [Tukaani Project XZ Embedded](https://tukaani.org/xz/embedded.html) library is an easy-to-use XZ compression library for embedded systems.
:::
## Schema
@@ -50,10 +53,11 @@ They will also have a description that is displayed to the user and the set of p
Parameters can be simple or quite complex, depending on the behavior they change.
> [!NOTE]
> The parameter `CAM_MODE` must be part of the parameter list.
> It maps to the command [MAV_CMD_SET_CAMERA_MODE](../messages/common.md#MAV_CMD_SET_CAMERA_MODE).
> It enables exposure of different settings based on the mode, so photo settings in photo mode and video settings in video mode.
::: info
The parameter `CAM_MODE` must be part of the parameter list.
It maps to the command [MAV_CMD_SET_CAMERA_MODE](../messages/common.md#MAV_CMD_SET_CAMERA_MODE).
It enables exposure of different settings based on the mode, so photo settings in photo mode and video settings in video mode.
:::
#### Parameter Types
@@ -111,8 +115,9 @@ The `name` field is used for display only. In other words, using the example abo
_Common Parameters_ are reserved parameter names for which the GCS can build specific UI controls (if found in a camera definition).
> [!NOTE]
> These parameters are common to many cameras (though their valid options vary considerably).
::: info
These parameters are common to many cameras (though their valid options vary considerably).
:::
| Parameter | Description |
| ---------------- | ---------------------------------------------------------------------- |
@@ -310,8 +315,9 @@ When the user makes a selection, the GCS will send the new option using the [PAR
When the GCS requires a current option for a given parameter, it will use the [PARAM_EXT_REQUEST_READ](../messages/common.md#PARAM_EXT_REQUEST_READ) message and it will expect in response a [PARAM_EXT_VALUE](../messages/common.md#PARAM_EXT_VALUE) message.
> [!NOTE]
> For more detailed information about the protocol see: [Extended Parameter Protocol](../services/parameter_ext.md).
::: info
For more detailed information about the protocol see: [Extended Parameter Protocol](../services/parameter_ext.md).
:::
## Full Camera Definition File Example {#full_example}
en/services/camera_v1.md
+4 -3
View File
@@ -3,9 +3,10 @@
The MAVLink Camera Protocol v1 defines a set of commands for configuring a camera to capture images at a particular time or distance interval, and to start/stop/pause/reset triggering.
It also includes commands to configure/control a video camera.
> [!NOTE]
> This API has been superseded by [Camera Protocol v2](../services/camera.md), which provides a more natural set of commands for using a camera, along with a comprehensive API for querying camera capabilities.
> This API is used by some older MAVLink cameras, and can be supported in parallel with the new protocol.
::: info
This API has been superseded by [Camera Protocol v2](../services/camera.md), which provides a more natural set of commands for using a camera, along with a comprehensive API for querying camera capabilities.
This API is used by some older MAVLink cameras, and can be supported in parallel with the new protocol.
:::
The protocol can be used to control cameras attached to autopilot outputs or standalone MAVLink cameras that support this protocol
en/services/component_information.md
+28 -20
View File
@@ -1,8 +1,9 @@
# Component Metadata Protocol (WIP)
> [!WARNING]
> This service is still marked as "work in progress", and should not be relied upon in production.
> It has also evolved since first created as the "Component Information Protocol".
::: warning
This service is still marked as "work in progress", and should not be relied upon in production.
It has also evolved since first created as the "Component Information Protocol".
:::
The _Component Metadata Protocol_ is a MAVLink service for requesting metadata from (and about) MAVLink components.
It is intended to provide autopilot- and version- independent feature discovery and configuration, allowing a GCS to configure its UI and/or a device without knowing anything about the connected system.
@@ -33,8 +34,9 @@ There is no mechanism, for example, to provide an update if the set of supported
| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="COMP_METADATA_TYPE"></a>[COMP_METADATA_TYPE](../messages/common.md#COMP_METADATA_TYPE) | Types of component metadata supported by the protocol - e.g. general information, parameter metadata, supported commands, events, peripherals, etc. The type identifiers are used in the "general" metadata file to identify the sections that provide information about each supported type of metadata. |
> [!NOTE]
> [COMPONENT_INFORMATION](../messages/common.md#COMPONENT_INFORMATION) is not used by thie service (it is a deprecated legacy version of [COMPONENT_METADATA](../messages/common.md#COMPONENT_METADATA)).
::: info
[COMPONENT_INFORMATION](../messages/common.md#COMPONENT_INFORMATION) is not used by thie service (it is a deprecated legacy version of [COMPONENT_METADATA](../messages/common.md#COMPONENT_METADATA)).
:::
## Component Information File Format (Schema) {#schema_files}
@@ -66,8 +68,9 @@ The location of these files is returned in the [COMPONENT_METADATA](#COMPONENT_M
Other component information files may be hosted on either the device or on the internet.
> [!NOTE]
> Where permitted by memory constraints you should host component information on the device (so that it is always available and cannot get out of sync).
::: info
Where permitted by memory constraints you should host component information on the device (so that it is always available and cannot get out of sync).
:::
Files on the device are downloaded using [MAVLink FTP](../services/ftp.md).
The URI format is defined in [MAVLink FTP URL Scheme](../services/ftp.md#mavlink-ftp-url-scheme).
@@ -87,15 +90,18 @@ It will also include [CRC32](../crc.md#crc32-algorithm) values any files that co
Component information files may be **.xz** compressed (this is recommended for files that are hosted on the device).
> [!NOTE]
> The prototype implementation generates and compresses component information files at build time.
> No compression library is required within the flight stack itself.
::: info
The prototype implementation generates and compresses component information files at build time.
No compression library is required within the flight stack itself.
:::
> [!WARNING]
> Systems that _request_ component information **must** support extraction of **.xz**-compressed JSON files.
::: warning
Systems that _request_ component information **must** support extraction of **.xz**-compressed JSON files.
:::
> [!TIP]
> The [Tukaani Project XZ Embedded](https://tukaani.org/xz/embedded.html) library is an easy-to-use XZ compression library for embedded systems and cross-platform C/C++ projects.
::: tip
The [Tukaani Project XZ Embedded](https://tukaani.org/xz/embedded.html) library is an easy-to-use XZ compression library for embedded systems and cross-platform C/C++ projects.
:::
## Sequences
@@ -113,8 +119,9 @@ A system can query whether another component supports the protocol by sending th
The component will respond with `COMPONENT_METADATA.uri` containing a valid URI if the protocol is supported.
If the protocol is not supported the component will ACK that the message with `MAV_RESULT_UNSUPPORTED`, `MAV_RESULT_DENIED` or `MAV_RESULT_FAILED`, or return a `null` value in `uri`.
> [!NOTE]
> A component that supports this service must return a general metadata file URI _that is hosted on the vehicle_ (accessed using MAVLink FTP).
::: info
A component that supports this service must return a general metadata file URI _that is hosted on the vehicle_ (accessed using MAVLink FTP).
:::
### Get MetaData
@@ -144,10 +151,11 @@ In summary:
The actuators metadata allows a GCS to create a UI to configure and test actuators, and configure vehicle geometries, without having to understand anything about the underlying flight stack.
> [!NOTE]
> The mechanism works similarly to [camera definition files](../services/camera_def.md).
> It can be used for flight stacks that allow outputs and geometry definition to be configured using parameters.
> If flight stack outputs or geometries cannot be configured using parameters, the mechanism can still be used to display the current geometry and output mappings, and to test outputs.
::: info
The mechanism works similarly to [camera definition files](../services/camera_def.md).
It can be used for flight stacks that allow outputs and geometry definition to be configured using parameters.
If flight stack outputs or geometries cannot be configured using parameters, the mechanism can still be used to display the current geometry and output mappings, and to test outputs.
:::
The definition contains information about actuator output drivers (e.g. PWM MAIN or UAVCAN), the functions that can be assigned to each output channel, supported geometries, and their configuration parameters.
Detailed information can be found in the [schema file](https://github.com/mavlink/mavlink/blob/master/component_metadata/actuators.schema.json), and there's also an [example](https://github.com/mavlink/mavlink/blob/master/component_metadata/actuators.example.json).
en/services/events.md
+10 -8
View File
@@ -1,11 +1,12 @@
# Events Interface (WIP)
> [!WARNING]
> The Events Interface is a work in progress and may change.
> It has an initial implementation in PX4 and QGroundControl and is planned for ArduPilot.
>
> The information below is just an overview.
> Full details of the interface are provided in the: [Events Interface Proposal](https://docs.google.com/document/d/18qdDgfML97lItom09MJhngYnFzAm1zFdmlCKG7TaBpg/edit)
::: warning
The Events Interface is a work in progress and may change.
It has an initial implementation in PX4 and QGroundControl and is planned for ArduPilot.
The information below is just an overview.
Full details of the interface are provided in the: [Events Interface Proposal](https://docs.google.com/document/d/18qdDgfML97lItom09MJhngYnFzAm1zFdmlCKG7TaBpg/edit)
:::
The _Events Interface_ is a generic and flexible mechanism that allows one component to reliably notify a GCS (or any other component) of sporadic events and state changes.
For example, the interface might be used notifying of arming readiness, calibration completion, and reaching the target takeoff height.
@@ -13,8 +14,9 @@ For example, the interface might be used notifying of arming readiness, calibrat
The interface provides for both common events that are shared by flight stacks or other components, and events that are specific to an implementation.
MAVLink "common" events are defined in [mavlink/libevents/events/common.json](https://github.com/mavlink/libevents/blob/master/events/common.json).
> [!NOTE]
> The events interface is intended to replace the widespread use of [STATUSTEXT](../messages/common.md#STATUSTEXT) messages, which are not really fit for purpose.
::: info
The events interface is intended to replace the widespread use of [STATUSTEXT](../messages/common.md#STATUSTEXT) messages, which are not really fit for purpose.
:::
## Key features
en/services/ftp.md
+49 -37
View File
@@ -3,9 +3,10 @@
The File Transfer Protocol (FTP) enables file transfer over MAVLink.
It supports common FTP operations like: reading, truncating, writing, removing and creating files, listing and removing directories.
> [!NOTE]
> MAVLink FTP implementation closely follows the design of the original internet [FTP protocol](https://en.wikipedia.org/wiki/File_Transfer_Protocol) in terms of the message structure, sequences, and the supported opcodes/operations.
> Developers can read the Internet protocol RFCs to understand MAVLink FTP.
::: info
MAVLink FTP implementation closely follows the design of the original internet [FTP protocol](https://en.wikipedia.org/wiki/File_Transfer_Protocol) in terms of the message structure, sequences, and the supported opcodes/operations.
Developers can read the Internet protocol RFCs to understand MAVLink FTP.
:::
The protocol follows a client-server pattern, where all commands are sent by the GCS (client),
and the Drone (server) responds either with an ACK containing the requested information, or a NAK containing an error.
@@ -24,9 +25,10 @@ FTP (v1) is supported if the [AUTOPILOT_VERSION.capability](../messages/common.m
This flag should only be set by a MAVLink component that supports the specific version of the protocol defined in this document.
> [!NOTE]
> The encoding and content of the `FILE_TRANSFER_PROTOCOL` payload field are not mandated by the specification, and other encoding schemes might be used, for example, in private networks.
> If you have implemented a private encoding or different version you **must not** set the [MAV_PROTOCOL_CAPABILITY_FTP](../messages/common.md#MAV_PROTOCOL_CAPABILITY_FTP) flag.
::: info
The encoding and content of the `FILE_TRANSFER_PROTOCOL` payload field are not mandated by the specification, and other encoding schemes might be used, for example, in private networks.
If you have implemented a private encoding or different version you **must not** set the [MAV_PROTOCOL_CAPABILITY_FTP](../messages/common.md#MAV_PROTOCOL_CAPABILITY_FTP) flag.
:::
## Payload Format {#payload}
@@ -34,8 +36,9 @@ The `FILE_TRANSFER_PROTOCOL` payload is encoded with the information required fo
This includes fields for holding the command that is being sent, the sequence number of the current FTP message (for multi-message data transfers),
the size of information in the data part of the message etc.
> [!TIP]
> Readers will note that the FTP payload format is very similar to the packet format used for serializing MAVLink itself.
::: tip
Readers will note that the FTP payload format is very similar to the packet format used for serializing MAVLink itself.
:::
Below is the over-the-wire format for the payload part of the [FILE_TRANSFER_PROTOCOL](../messages/common.md#FILE_TRANSFER_PROTOCOL) message on PX4/_QGroundControl_.
@@ -72,7 +75,7 @@ The opcodes that may be sent by the GCS (client) to the drone (server) are liste
| <a id="RemoveFile"></a> 8 | [RemoveFile](#remove-file) | Remove file at `<path>`.<br>- ACK reply with no data on success.<br>- NAK packet with [error information](#error_codes) on failure. |
| <a id="CreateDirectory"></a> 9 | [CreateDirectory](#create-directory) | Creates directory at `<path>`.<br>- Sends an ACK reply with no data on success, otherwise a NAK packet with an error code. |
| <a id="RemoveDirectory"></a> 10 | [RemoveDirectory](#remove-directory) | Removes directory at `<path>`. The directory must be empty. <br>- Sends an ACK reply with no data on success, otherwise a NAK packet with an error code. |
| <a id="OpenFileWO"></a> 11 | OpenFileWO | Opens file at `<path>` for writing, returns `<session>`. <br>- Opens the file (`path`) and allocates a _session number_. The file will be created if it does not exist. Equivalent UNIX flags: (O_CREAT &#124; O_WRONLY)<br>- Sends an ACK packet with the allocated _session number_ on success, otherwise a NAK packet with an error code.<br>- The file remains open after the operation, and must eventually be closed by `Reset` or `Terminate`. |
| <a id="OpenFileWO"></a> 11 | OpenFileWO | Opens file at `<path>` for writing, returns `<session>`. <br>- Opens the file (`path`) and allocates a _session number_. The file will be created if it does not exist. Equivalent UNIX flags: (O*CREAT &#124; O_WRONLY)<br>- Sends an ACK packet with the allocated \_session number* on success, otherwise a NAK packet with an error code.<br>- The file remains open after the operation, and must eventually be closed by `Reset` or `Terminate`. |
| <a id="TruncateFile"></a> 12 | [TruncateFile](#truncate-file) | Truncate file at `<path>` to `<offset>` length.<br>- Sends an ACK reply with no data on success, otherwise a NAK packet with an error code. |
| <a id="Rename"></a> 13 | Rename | Rename `<path1>` to `<path2>`.<br>- Sends an ACK reply the no data on success, otherwise a NAK packet with an error code (i.e. if the source path does not exist). |
| <a id="CalcFileCRC32"></a> 14 | CalcFileCRC32 | Calculate CRC32 for file at `<path>`.<br>- Sends an ACK reply with the checksum on success, otherwise a NAK packet with an error code. |
@@ -101,8 +104,9 @@ If the error code is `FailErrno`, then `data[1]` must additionally contain an er
The payload `size` field must be set to either 1 or 2, depending on whether or not `FailErrno` is specified.
> [!NOTE]
> These are **errors**. Normally if the GCS receives an error it should not attempt to continue the FTP operation, but instead return to an idle state.
::: info
These are **errors**. Normally if the GCS receives an error it should not attempt to continue the FTP operation, but instead return to an idle state.
:::
<!-- uint8_t enum ErrorCode: https://github.com/PX4/Firmware/blob/master/src/modules/mavlink/mavlink_ftp.h -->
@@ -124,8 +128,9 @@ The payload `size` field must be set to either 1 or 2, depending on whether or n
The GCS (client) starts a timeout after most commands are sent (these are cleared if an ACK/NAK is received).
> [!NOTE]
> Timeouts may not be set for some messages. For example, a timeout need not set for [ResetSessions](#ResetSessions) as the message should always succeed.
::: info
Timeouts may not be set for some messages. For example, a timeout need not set for [ResetSessions](#ResetSessions) as the message should always succeed.
:::
If a timeout activates either the command or its response is assumed to have been lost,
and the command should be re-sent with the same sequence number etc.
@@ -149,8 +154,9 @@ After opening a file session, [ReadFile](#ReadFile) is called to request a messa
The process is repeated at different offsets until the whole file has been retrieved.
The file session is then closed.
> [!NOTE]
> [Burst reading a file](#reading-a-file-burstreadfile) is a (generally) faster alternative to this approach.
::: info
[Burst reading a file](#reading-a-file-burstreadfile) is a (generally) faster alternative to this approach.
:::
The sequence of operations for downloading (reading) a file using [ReadFile] is shown below.
This assumes that there are no timeouts and all operations/requests succeed.
@@ -205,9 +211,10 @@ The last message in the burst is indicated by setting `burst_complete=1` (withou
The client tracks the recieved chunks.
On completion of the burst (or the file), if there are any missing parts of the file it can request them using either another burst or using [ReadFile](#reading-a-file-readfile).
> [!NOTE]
> Burst read is a (generally) faster alternative to using [ReadFile](#ReadFile) to [read a file](#reading-a-file-readfile).
> This is because fewer messages are sent and need to be waited on.
::: info
Burst read is a (generally) faster alternative to using [ReadFile](#ReadFile) to [read a file](#reading-a-file-readfile).
This is because fewer messages are sent and need to be waited on.
:::
The sequence of operations for a burst read is shown below (assuming there are no timeouts and all operations/requests succeed).
@@ -305,19 +312,21 @@ The sequence of operations is:
The GSC should create a timeout after `CreateFile` and `WriteFile` commands are sent, and resend the messages as needed (and [described above](#timeouts)).
A timeout is not set for `TerminateSession` (the server may ignore failure of the command or the ACK).
> [!WARNING]
> PX4 and _QGroundControl_ implement this slightly differently than outlined above.
> The implementation only has a single session (id=0) so only a single operation can be active at a time.
> As a result, this operation should only be started if no other operation is active.
> The drone expects that the session id will be set to zero by the sender of `CreateFile`.
> Last of all, the GCS sends `ResetSessions` rather than `TerminateSession`.
> While you can send either if talking to PX4, if the protocol is implemented elsewhere calling `ResetSessions` may break other communications.
::: warning
PX4 and _QGroundControl_ implement this slightly differently than outlined above.
The implementation only has a single session (id=0) so only a single operation can be active at a time.
As a result, this operation should only be started if no other operation is active.
The drone expects that the session id will be set to zero by the sender of `CreateFile`.
Last of all, the GCS sends `ResetSessions` rather than `TerminateSession`.
While you can send either if talking to PX4, if the protocol is implemented elsewhere calling `ResetSessions` may break other communications.
:::
### Remove File
> [!NOTE]
> `RemoveFile` handling is implemented in PX4 but not in _QGroundControl_.
> GCS behaviour is therefore not fully defined/tested.
::: info
`RemoveFile` handling is implemented in PX4 but not in _QGroundControl_.
GCS behaviour is therefore not fully defined/tested.
:::
The sequence of operations for removing a file is shown below (assuming there are no timeouts and all operations/requests succeed).
@@ -346,13 +355,14 @@ The GSC should create a timeout after the `RemoveFile` command is sent and resen
The sequence of operations for truncating a file is shown below (assuming there are no timeouts and all operations/requests succeed).
> [!NOTE]
> `TruncateFile` handling is implemented in PX4 but not in _QGroundControl_.
> GCS behaviour is therefore not fully defined/tested.
::: info
`TruncateFile` handling is implemented in PX4 but not in _QGroundControl_.
GCS behaviour is therefore not fully defined/tested.
:::
[![Mermaid Sequence: Truncate file](https://mermaid.ink/img/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtO1xuICAgIHBhcnRpY2lwYW50IEdDU1xuICAgIHBhcnRpY2lwYW50IERyb25lXG4gICAgR0NTLT4-RHJvbmU6ICBUcnVuY2F0ZUZpbGUgPGJyPiggZGF0YVswXT1wYXRoLCBzaXplPWxlbihwYXRoKSwgb2Zmc2V0PW9mZnNldCB0byB0cnVuY2F0ZSApXG4gICAgRHJvbmUtLT4-R0NTOiBBQ0soc2l6ZT0wKSIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtO1xuICAgIHBhcnRpY2lwYW50IEdDU1xuICAgIHBhcnRpY2lwYW50IERyb25lXG4gICAgR0NTLT4-RHJvbmU6ICBUcnVuY2F0ZUZpbGUgPGJyPiggZGF0YVswXT1wYXRoLCBzaXplPWxlbihwYXRoKSwgb2Zmc2V0PW9mZnNldCB0byB0cnVuY2F0ZSApXG4gICAgRHJvbmUtLT4-R0NTOiBBQ0soc2l6ZT0wKSIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)
<!-- Original sequnce
<!-- Original sequence
sequenceDiagram;
participant GCS
participant Drone
@@ -412,8 +422,9 @@ The sequence of operations is:
- `size` = The size of the `data`.
1. The operation is then repeated at different offsets to download the whole directory listing.
> [!NOTE]
> The offset for each request will depend on how many entries were returned by the previous request(s).
::: info
The offset for each request will depend on how many entries were returned by the previous request(s).
:::
1. The operation completes when the GCS requests an entry index (`offset`) greater than or equal to the number of entries.
In this case the drone responds with a [NAK](#error_codes) containing [EOF](#EOF) (end of file).
@@ -451,9 +462,10 @@ The GSC should not create timeouts or handle the NAK case (other than to report
### Remove Directory
> [!NOTE]
> `RemoveDirectory` handling is implemented in PX4 but not in _QGroundControl_.
> GCS behaviour is therefore not fully defined/tested.
::: info
`RemoveDirectory` handling is implemented in PX4 but not in _QGroundControl_.
GCS behaviour is therefore not fully defined/tested.
:::
The sequence of operations for removing a directory is shown below (assuming there are no timeouts and all operations/requests succeed).
Note that this operation will fail if the directory is not empty.
en/services/gimbal.md
+6 -4
View File
@@ -1,7 +1,8 @@
# Gimbal Configuration Protocol (v1)
> [!WARNING]
> This service defintion has been superseded by [Gimbal Protocol v2](../services/gimbal.md) (gimbal manufacturers/GCSs/autopilots are expected to use the new API, but the old API is still in broad use, and there is no plan to for it to be removed).
::: warning
This service definition has been superseded by [Gimbal Protocol v2](../services/gimbal.md) (gimbal manufacturers/GCSs/autopilots are expected to use the new API, but the old API is still in broad use, and there is no plan to for it to be removed).
:::
The gimbal configuration message set uses a number of commands and few special-purpose messages to configure a payload mount.
@@ -27,8 +28,9 @@ The commands to use mavlink gimbals are
To reboot or shut down a gimbal send the command [MAV_CMD_PREFLIGHT_REBOOT_SHUTDOWN](../messages/common.md#MAV_CMD_PREFLIGHT_REBOOT_SHUTDOWN). The options to be set for the gimbal are found in `param4`.
> [!NOTE]
> This is the same message/process as for autopilot systems.
::: info
This is the same message/process as for autopilot systems.
:::
## Telemetry from Gimbal
en/services/gimbal_v2.md
+36 -26
View File
@@ -1,8 +1,9 @@
# Gimbal Protocol (v2)
> [!NOTE]
> This version supersedes [Gimbal Protocol v1](../services/gimbal.md)
> Existing functionality is now fixed, but compatible changes may still be added.
::: info
This version supersedes [Gimbal Protocol v1](../services/gimbal.md)
Existing functionality is now fixed, but compatible changes may still be added.
:::
## Introduction
@@ -14,8 +15,9 @@ It additionally provides ways to assign control to different sources.
The protocol supports a number of hardware setups, and enables gimbals with varying capabilities.
> [!NOTE]
> The original protocol design document [can be found here](https://docs.google.com/document/d/16pekKRXLN2FhlL9YNFP983cjfBKAsDwN0gOSks8USo4/edit?usp=sharing).
::: info
The original protocol design document [can be found here](https://docs.google.com/document/d/16pekKRXLN2FhlL9YNFP983cjfBKAsDwN0gOSks8USo4/edit?usp=sharing).
:::
## Concepts
@@ -30,9 +32,10 @@ The _Gimbal Manager_ and _Gimbal Device_ expose respective _message sets_ that c
The key concept to understand is that a _Gimbal Manager_ has a 1:1 relationship with a particular _Gimbal Device_, and is the only party on the MAVLink network that is allowed to directly command that device - it does so using the _Gimbal Device message set_.
> [!NOTE]
> The _Gimbal Device_ must act only upon messages that come from the associated _Gimbal Manager_!
> The device will however _broadcast_ its status to all parties on the network (not just its manager).
::: info
The _Gimbal Device_ must act only upon messages that come from the associated _Gimbal Manager_!
The device will however _broadcast_ its status to all parties on the network (not just its manager).
:::
MAVLink applications (ground stations, developer APIs like the MAVSDK, etc.), and any other software that wants to control a particular gimbal, must do so via its _Gimbal Manager_, using the _Gimbal Manager message set_.
@@ -142,8 +145,9 @@ For example, a companion computer with an attached gimbal would appear as two MA
The gimbal component would identify as a type `MAV_TYPE_GIMBAL` and assert that it implements the gimbal manager protocol.
As with autopilot-attached cameras it would need to respond as a gimbal manager, and also stream required gimbal device messages.
> [!NOTE]
> Implementing each attached camera as a separate MAVLink component allows cameras attached to a companion computer to be separately addressed in missions executed on the autopilot.
::: info
Implementing each attached camera as a separate MAVLink component allows cameras attached to a companion computer to be separately addressed in missions executed on the autopilot.
:::
## Implementation and Messages
@@ -160,8 +164,9 @@ If the `capabilities` field of the above message(s) has the flag [MAV_PROTOCOL_C
The `GIMBAL_MANAGER_INFORMATION` contains important information a particular gimbal, such as its capabilities ([GIMBAL_MANAGER_CAP_FLAGS](#GIMBAL_MANAGER_CAP_FLAGS)), maximum angles and angle rates, as well as the `gimbal_device_id` which identifies the specific gimbal device controlled by a particular _Gimbal Manager_.
> [!WARNING]
> A GCS should always request `GIMBAL_MANAGER_INFORMATION` from autopilot components prior to: PX4 v1.16, ArduPilot-4.5 (when the protocol bit was added).
::: warning
A GCS should always request `GIMBAL_MANAGER_INFORMATION` from autopilot components prior to: PX4 v1.16, ArduPilot-4.5 (when the protocol bit was added).
:::
#### Gimbal Manager Status
@@ -182,13 +187,15 @@ To be co-operative entails the following rules:
- Check the [GIMBAL_MANAGER_STATUS](#GIMBAL_MANAGER_STATUS) about who is in control first and - if possible - warn user about planned action. For example, if the autopilot is in control of the gimbal as part of a mission, the ground station should ask the user first (i.e. via a pop-up) if they really want to take over manual control.
- Don't forget to release control when an action/task is finished and set the sysid/compid to 0.
> [!NOTE]
> It is possible to assign control to another component too, not just to itself.
> For example, a smart shot running on a companion computer can set itself to be in primary control but assign a ground station for secondary control to e.g. nudge during the smart shot.
::: info
It is possible to assign control to another component too, not just to itself.
For example, a smart shot running on a companion computer can set itself to be in primary control but assign a ground station for secondary control to e.g. nudge during the smart shot.
:::
> [!NOTE]
> The implementation of how primary and secondary control are combined or mixed is not defined by the protocol but up to the implementation.
> This allows flexibility for different use cases.
::: info
The implementation of how primary and secondary control are combined or mixed is not defined by the protocol but up to the implementation.
This allows flexibility for different use cases.
:::
#### Manual Gimbal Control using MAVLink
@@ -285,9 +292,10 @@ The [GIMBAL_DEVICE_ATTITUDE_STATUS.flags](#GIMBAL_DEVICE_ATTITUDE_STATUS) field
For older devices, if neither of the flags above are set, the yaw frame must be inferred from the `GIMBAL_DEVICE_FLAGS_YAW_LOCK`.
If it is set, the yaw is relative to North, otherwise to the front of the vehicle.
> [!NOTE]
> Manufacturers working on new gimbal devices should set either `GIMBAL_DEVICE_FLAGS_YAW_IN_VEHICLE_FRAME` or `GIMBAL_DEVICE_FLAGS_YAW_IN_EARTH_FRAME`.
> Components recieving the message should also handle `GIMBAL_DEVICE_FLAGS_YAW_LOCK` for backwards compatibility with older devices.
::: info
Manufacturers working on new gimbal devices should set either `GIMBAL_DEVICE_FLAGS_YAW_IN_VEHICLE_FRAME` or `GIMBAL_DEVICE_FLAGS_YAW_IN_EARTH_FRAME`.
Components receiving the message should also handle `GIMBAL_DEVICE_FLAGS_YAW_LOCK` for backwards compatibility with older devices.
:::
## Message/Command/Enum Summary
@@ -424,9 +432,10 @@ In this case the gimbal manager is implemented by the autopilot which "sends" th
Below is a short summary of all messages that a gimbal device should implement.
> [!NOTE]
> A _Gimbal Device_ can be tested by connecting it to an autopilot with a _Gimbal Manager_.
> To avoid having to do a full setup including autopilot, a [direct test using MAVSDK](https://github.com/mavlink/MAVSDK/tree/develop/examples/gimbal_device_tester) is available.
::: info
A _Gimbal Device_ can be tested by connecting it to an autopilot with a _Gimbal Manager_.
To avoid having to do a full setup including autopilot, a [direct test using MAVSDK](https://github.com/mavlink/MAVSDK/tree/develop/examples/gimbal_device_tester) is available.
:::
### Messages to Send
@@ -436,8 +445,9 @@ The messages listed should be broadcast on the network/on all connections (sent
Heartbeats should always be sent (usually at 1 Hz).
> [!NOTE]
> Gimbals that set their `sysid` from the autopilot will need to wait for the autopilot's heartbeat before emitting their own (note that if the gimbal can receive heartbeats from multiple autopilots then the `sysid` must be explicitly/statically configured).
::: info
Gimbals that set their `sysid` from the autopilot will need to wait for the autopilot's heartbeat before emitting their own (note that if the gimbal can receive heartbeats from multiple autopilots then the `sysid` must be explicitly/statically configured).
:::
- `sysid`: the same sysid as the autopilot (this can either be done by configuration, or by listening to the autopilot's heartbeat first and then copying the sysid, default: 1)
- `compid`: [MAV_COMP_ID_GIMBAL](../messages/common.md#MAV_COMP_ID_GIMBAL)
en/services/heartbeat.md
+17 -12
View File
@@ -42,8 +42,9 @@ The `HEARTBEAT` may also used by GCS (or Developer API) to determine if it **can
For example, _QGroundControl_ will only connect to a vehicle system (i.e. not another GCS, gimbal, or onboard controller), and also checks that it has a non-zero system ID before displaying the vehicle connected message.
QGC also uses the specific type of vehicle and other heartbeat information to control layout of the GUI.
> [!NOTE]
> The specific code for connecting to _QGroundControl_ can be found in [MultiVehicleManager.cc](https://github.com/mavlink/qgroundcontrol/blob/master/src/Vehicle/MultiVehicleManager.cc) (see `void MultiVehicleManager::_vehicleHeartbeatInfo`).
::: info
The specific code for connecting to _QGroundControl_ can be found in [MultiVehicleManager.cc](https://github.com/mavlink/qgroundcontrol/blob/master/src/Vehicle/MultiVehicleManager.cc) (see `void MultiVehicleManager::_vehicleHeartbeatInfo`).
:::
## Component Identity
@@ -52,23 +53,27 @@ The _type_ of a component is obtained from its [`HEARTBEAT.type`](#HEARTBEAT) ([
- A flight controller component must use a `MAV_TYPE` corresponding to a particular vehicle (e.g. `MAV_TYPE_FIXED_WING`, `MAV_TYPE_QUADROTOR` etc.), and set `HEARTBEAT.autopilot` to a valid flight stack.
- All other components must use a `MAV_TYPE` corresponding to the actual type (e.g.: `MAV_TYPE_GIMBAL`, `MAV_TYPE_BATTERY`, etc.), and should set `HEARTBEAT.autopilot` to `MAV_AUTOPILOT_INVALID`.
> [!TIP]
> The recommended way to recognise an autopilot component is to check that `HEARTBEAT.autopilot` is not `MAV_AUTOPILOT_INVALID`.
::: tip
The recommended way to recognise an autopilot component is to check that `HEARTBEAT.autopilot` is not `MAV_AUTOPILOT_INVALID`.
:::
Every component must have a system-unique component id, which is used for routing and for identifying multiple instances of a particular component type.
> [!WARNING]
> Historically the component id was also used to determine the component type.
> New code must not make any assumption about the type from the id used (type is determined from `HEARTBEAT.type`).
::: warning
Historically the component id was also used to determine the component type.
New code must not make any assumption about the type from the id used (type is determined from `HEARTBEAT.type`).
:::
MAVLink recommends that _by default_ components use a type-appropriate component id from [MAV_COMPONENT](../messages/common.md#MAV_COMPONENT), and provide an interface to change the component id if needed.
For example, a camera component might use any of the [MAV_COMP_ID_CAMERA`n`](../messages/common.md#MAV_COMP_ID_GIMBAL) ids, and should not use `MAV_COMP_ID_GPS2`.
> [!TIP]
> Using type-specific component ids:
>
> - makes id clashes less likely "out of the box" (unless two components of the same type are present on the same system).
> - reduces the impact on legacy code that determines component type from the id.
::: tip
Using type-specific component ids:
- makes id clashes less likely "out of the box" (unless two components of the same type are present on the same system).
- reduces the impact on legacy code that determines component type from the id.
:::
## Component Capabilities
en/services/high_latency.md
+4 -3
View File
@@ -21,9 +21,10 @@ In order to reduce traffic to the bare minimum, some of the fundamental assumpti
- [HEARTBEAT](../messages/common.md#HEARTBEAT) messages are not emitted on the channel (either by the autopilot or GCS).
> [!NOTE]
> The heartbeat is used to build MAVLink routing tables between channels.
> Commands addressed specifically to the high latency component may not be routed from another channel (i.e. you can connect to the component from a GCS directly, but not via a MAVLink router).
::: info
The heartbeat is used to build MAVLink routing tables between channels.
Commands addressed specifically to the high latency component may not be routed from another channel (i.e. you can connect to the component from a GCS directly, but not via a MAVLink router).
:::
- Only the [command protocol](../services/command.md) service messages and [HIGH_LATENCY2](#HIGH_LATENCY2) message should be sent over the high latency channel.
en/services/illuminator.md
+160 -160
View File
@@ -1,160 +1,160 @@
# Illuminator Protocol
The illuminator protocol allows MAVLink control over the behaviour of lights, LEDs, and/or emitters mounted or integrated on the drone.
The protocol currently allows for the following control: brightness, on/off, and a strobe feature.
Along with this, the illuminator protocol also publishes status information for developers or users.
The status messaging encompasses the current configuration of the illuminator and the health of the illuminator device.
## MAVLink Illuminator Implementations
These illuminators have built-in MAVLink support:
- Skydio Spotlight for X10
## Message/Command/Enum Summary
| Message | Description |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="COMPONENT_INFORMATION_BASIC"></a>[COMPONENT_INFORMATION_BASIC][CMPNT_INFO_BSC] | Basic illuminator information data. Should be requested using [MAV_CMD_REQUEST_MESSAGE][MAV_CMD_REQUEST_MESSAGE] on startup, or when required. |
| <a id="ILLUMINATOR_STATUS"></a>[ILLUMINATOR_STATUS](../messages/common.md#ILLUMINATOR_STATUS) | Current status of the illuminator. Recommended to publish this at a regular rate. |
| Command | Description |
| --------------------------------------------------------------------------------------------- | -------------------------------- |
| <a id="MAV_CMD_ILLUMINATOR_ON_OFF"></a>[MAV_CMD_ILLUMINATOR_ON_OFF][ILLUM_ON_OFF] | Turns illuminators ON/OFF. |
| <a id="MAV_CMD_DO_ILLUMINATOR_CONFIGURE"></a>[MAV_CMD_DO_ILLUMINATOR_CONFIGURE][DO_ILLM_CNFG] | Configures illuminator settings. |
<!-- reference links to make table above easier to edit -->
[DO_ILLM_CNFG]: ../messages/common.md#MAV_CMD_DO_ILLUMINATOR_CONFIGURE
[MAV_CMD_REQUEST_MESSAGE]: ../messages/common.md#MAV_CMD_REQUEST_MESSAGE
[CMPNT_INFO_BSC]: ../messages/common.md#COMPONENT_INFORMATION_BASIC
[ILLUM_ON_OFF]: ../messages/common.md#MAV_CMD_ILLUMINATOR_ON_OFF
| Enum Values | Description |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| <a id="MAV_TYPE_ILLUMINATOR"></a>[MAV_TYPE_ILLUMINATOR](../messages/minimal.md#MAV_TYPE_ILLUMINATOR) | Type of the component (illuminator). |
| <a id="MAV_COMP_ID_ILLUMINATOR"></a>[MAV_COMP_ID_ILLUMINATOR](../messages/minimal.md#MAV_COMP_ID_ILLUMINATOR) | ID of the component (illuminator). |
| Enum | Description |
| ------------------------------------------------------------------------------------------------------------ | ------------------------- |
| <a id="ILLUMINATOR_MODE"></a>[ILLUMINATOR_MODE](../messages/common.md#ILLUMINATOR_MODE) | Illuminator modes. |
| <a id="ILLUMINATOR_ERROR_FLAGS"></a>[ILLUMINATOR_ERROR_FLAGS](../messages/common.md#ILLUMINATOR_ERROR_FLAGS) | Fault/health indications. |
## Implementation and Messages
### Illuminator Connection
Illuminators are expected to follow the [Heartbeat/Connection Protocol](../services/heartbeat.md) and send a constant flow of heartbeats (nominally at 1Hz).
Illuminators are identified via their type [MAV_TYPE_ILLUMINATOR](#MAV_TYPE_ILLUMINATOR).
Individual illuminators are distinguished via their unique component ID, which by default should be [MAV_COMP_ID_ILLUMINATOR](#MAV_COMP_ID_ILLUMINATOR) (though this is not mandated and any ID may be used).
Once a heartbeat is received, the drone can then send a [MAV_CMD_REQUEST_MESSAGE ][MAV_CMD_REQUEST_MESSAGE] command to the illuminator to receive information, set settings, or control the illuminator.
An example below illustrates how a drone can request the status of the illuminator.
<!-- Mermaid graph:
sequenceDiagram;
participant Drone
participant Illuminator
Illuminator->>Drone: HEARTBEAT [cmp id: MAV_TYPE_ILLUMINATOR] (first)
Drone->>Illuminator: MAV_CMD_REQUEST_MESSAGE(param1=ILLUMINATOR_STATUS)
Drone->>Drone: Start timeout
Illuminator->>Drone: COMMAND_ACK
Note over Illuminator,Drone: If MAV_RESULT_ACCEPTED send info.
Illuminator->>Drone: ILLUMINATOR_STATUS [cmp id: MAV_COMP_ID_ILLUMINATOR]
-->
[![](https://mermaid.ink/img/pako:eNp9UWFLwzAQ_SshnxxMwa8VB7ENWly32aSCrBJCe9XgktQ0FcbYfzeuEzoGu0_Hy3sv7-52uLI14Ah38N2DqSBR8sNJfVcaFKqVzqtKtdJ4lDhr4BxON5teKyO9dcPjCLiezQ6qCD1RkvMHSjhaZ-QV-W0bwNAJ_raiIp3PiyxdEL7M39FVo1znJ2hwO-iDz8h1EMZZInL6UlDGRUYZI4_0KuSS-vZ-ZCcYJ7xgk1OzYyjmwxzIKw229xfCx8ssI4tEkPh5YC2sB2R_wI350yM7bQ75csqKOQ-amK44TVAHpkbKNPbmwk_nydG60i1S9XHoZbYSaXKysMEOT7EGp6WqwzF3f1iJ_SdoKHEU2lq6rxKXZh94sveWbU2FI-96mOK-raX_PzyOGrnpYP8LFgqu1A?type=png)](https://mermaid.live/edit#pako:eNp9UWFLwzAQ_SshnxxMwa8VB7ENWly32aSCrBJCe9XgktQ0FcbYfzeuEzoGu0_Hy3sv7-52uLI14Ah38N2DqSBR8sNJfVcaFKqVzqtKtdJ4lDhr4BxON5teKyO9dcPjCLiezQ6qCD1RkvMHSjhaZ-QV-W0bwNAJ_raiIp3PiyxdEL7M39FVo1znJ2hwO-iDz8h1EMZZInL6UlDGRUYZI4_0KuSS-vZ-ZCcYJ7xgk1OzYyjmwxzIKw229xfCx8ssI4tEkPh5YC2sB2R_wI350yM7bQ75csqKOQ-amK44TVAHpkbKNPbmwk_nydG60i1S9XHoZbYSaXKysMEOT7EGp6WqwzF3f1iJ_SdoKHEU2lq6rxKXZh94sveWbU2FI-96mOK-raX_PzyOGrnpYP8LFgqu1A)
### COMPONENT_INFORMATION_BASIC
While the `MAV_TYPE` and Component ID help identify the system and component, the [COMPONENT_INFORMATION_BASIC](#COMPONENT_INFORMATION_BASIC) command can be requested to retrieve component information data, which can help further identify the component being communicated with. This data includes `time_boot_ms`, `MAV_PROTOCOL_CAPABILITY`, `vendor_name`, `model_name`, `software_version`, `hardware_version`, and `serial_number`.
| Parameter | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `time_boot_ms` | Time since system boot up in milliseconds. |
| `MAV_PROTOCOL_CAPABILITY` | Bitmask detailing the component capability flags. |
| `vendor_name` | Name of the component vendor (optional). |
| `model_name` | Name of the component's model (optional). |
| `software_version` | Software version on the module, recommended format is SEMVER: 'major.minor.patch' but any format can be used (24-character string) (optional). |
| `hardware_version` | Hardware version on the module, recommended format is SEMVER: 'major.minor.patch' but any format can be used (24-character string) (optional). |
| `serial_number` | Hardware's serial number (optional). |
Optional parameters can be left empty or set to zero.
### ON/OFF
The [MAV_CMD_ILLUMINATOR_ON_OFF](#MAV_CMD_ILLUMINATOR_ON_OFF) command is used to enable/disable the illuminator.
It's usage can be seen below:
<!-- Mermaid graph:
sequenceDiagram;
participant Drone
participant Illuminator
Drone->>Illuminator: MAV_CMD_ILLUMINATOR_ON_OFF (param1 = 1)
Drone->>Drone: Start timeout
Illuminator->>Drone: MAV_RESULT_ACCEPTED
-->
[![](https://mermaid.ink/img/pako:eNplkMFqwzAMhl_F6LRCd-jVZYWQpBBImtGkOxmMSLTNLLYzVz6M0nef2zLWMV0kpE__j3SCwY8EEo70GckNVBh8C2jXyokUMwY2g5nRsSiCd_S_XU1TtMYh-3AbXrnHzeZuIEWTvei8KXRV14em2mV9u9ftTrfbrXhIamhX4kmsFn8VrlmKjpOdYGPJR74Rd9q_3MVjX3aHutdZnpfPfVnAEiwFi2ZMJ54uuwr4nSwpkKkcMXwoUO6cOIzsuy83gOQQaQlxHpF_3gHyFacjnb8BIBNkuQ?type=png)](https://mermaid.live/edit#pako:eNplkMFqwzAMhl_F6LRCd-jVZYWQpBBImtGkOxmMSLTNLLYzVz6M0nef2zLWMV0kpE__j3SCwY8EEo70GckNVBh8C2jXyokUMwY2g5nRsSiCd_S_XU1TtMYh-3AbXrnHzeZuIEWTvei8KXRV14em2mV9u9ftTrfbrXhIamhX4kmsFn8VrlmKjpOdYGPJR74Rd9q_3MVjX3aHutdZnpfPfVnAEiwFi2ZMJ54uuwr4nSwpkKkcMXwoUO6cOIzsuy83gOQQaQlxHpF_3gHyFacjnb8BIBNkuQ)
### CONFIGURE
The [MAV_CMD_DO_ILLUMINATOR_CONFIGURE](#MAV_CMD_DO_ILLUMINATOR_CONFIGURE) command controls the illuminator's settings. This will adjust how the illuminator behaves when enabled.
The operation follows the normal [Command Protocol](../services/command.md) rules for command/acknowledgment. The four parameters for this command are: Mode, Brightness, Strobe Period, Strobe Duty.
Illuminators can be set in different modes which can change the behavior of the illuminator (described in a separate section, [Modes](#MODES)).
The brightness can be set via "Brightness" as a percentage value (0-100%).
Illuminators may also have the functionality to strobe the light source.
This behavior is configured via "Strobe Period" and "Strobe Duty".
These parameters can be set to `0` when not used.
"Strobe Period" is in seconds and "Strobe Duty" is a percentage value (indicating the % of time in the "Strobe Period" the illuminator is enabled).
#### MODES
If the mode is unknown, the mode parameter value will be set to 0.
A mode value of 1 is `ILLUMINATOR_MODE_INTERNAL_CONTROL`, where the illuminator behavior is controlled by [MAV_CMD_DO_ILLUMINATOR_CONFIGURE](#MAV_CMD_DO_ILLUMINATOR_CONFIGURE) settings.
When the value is set to 2, it indicates that the illuminator mode is `ILLUMINATOR_MODE_EXTERNAL_SYNC`. This mode is for instances where the illuminator behavior is controlled by external factors: e.g. an external hardware signal.
### STATUS
The [ILLUMINATOR_STATUS](#ILLUMINATOR_STATUS) message can be requested to receive information about the status of the illuminator. This includes information such as uptime, errors, whether the illuminator is enabled via [MAV_CMD_ILLUMINATOR_ON_OFF](#MAV_CMD_ILLUMINATOR_ON_OFF), current settings from the [MAV_CMD_DO_ILLUMINATOR_CONFIGURE](#MAV_CMD_DO_ILLUMINATOR_CONFIGURE) command, and the temperature of the illuminator.
#### ILLUMINATOR_ERROR_FLAGS
The [ILLUMINATOR_ERROR_FLAGS](#ILLUMINATOR_ERROR_FLAGS) can be used to indicate if there is any issue with the illuminator. At this time, there are three flags. If there is no error and the illuminator is behaving as normal, the [ILLUMINATOR_ERROR_FLAGS](#ILLUMINATOR_ERROR_FLAGS) bitmap will be 0.
If [ILLUMINATOR_ERROR_FLAGS](#ILLUMINATOR_ERROR_FLAGS) is set to 1 or 2, this indicates an error related to the temperature of the illuminator.
`1` indicates `ILLUMINATOR_ERROR_FLAGS_THERMAL_THROTTLING` as in the illuminator is throttling its output due to a thermal issue.
`2` indicates `ILLUMINATOR_ERROR_FLAGS_OVER_TEMPERATURE_SHUTDOWN` which means that the illuminator is shutting off due to passing some temperature threshold.
The status message utilization can be seen below:
<!-- Mermaid graph:
sequenceDiagram;
participant Drone
participant Illuminator
Drone->>Illuminator: MAV_CMD_REQUEST_MESSAGE(param1=ILLUMINATOR_STATUS)
Drone->>Drone: Start timeout
Illuminator->>Drone: MAV_RESULT_ACCEPTED
Illuminator->>Drone: ILLUMINATOR_STATUS [(50000.0, 1, 1, 1, 1, 80.0, 0.0, 0.0, 95.0, 0.0, 10.0)]
Note over Illuminator, Drone: Illuminator Status published as: <br> uptime_ms = 50000.0, enable = 1, mode_bitmask = 1 <br> error_status = 1, mode = 1, brightness = 80% <br> strobe_period = 0.0, strobe_duty_cycle = 0.0, temp_c = 95.0 <br>min_strobe_period = 0.0, max_strobe_period = 10.0
-->
[![](https://mermaid.ink/img/pako:eNqFUm1rwjAQ_ishMHDghn4Qtm4KRcsQdC-27ss6QtreZrBJuuQyJmP_fWmdVlDYEdLLPc_dc5fmm-a6ABpQ4s3ChwOVw0Twd8PlTarIn1XcoMhFxRWSidEKTkPTsnRSKI7atISGfzEaHYABmYfPbDyfsEX0tIzihM2jOA7voo6vxmV_OJ3NlvPpfZg8LFichMkyPj8u2HwDEqPvgKCQoB22rAO5llvLLqJ4OUtYOB5Hj0k0-SfjuBPy0hn0vF32uqR_sK6aSLtdD_Zu3-_nr63SvUYg-hPMoWaX7CTbWD0cOksql5XCrqAg3AbkNjMj4qp6ZCYtGZJ9P6B4VoKP-H6k_7EsEyi5XdeRbRoYow2z27J73tbLjHhfoQJbI1e9s22GRaMzYBUYoQsPNEJ_wcLhhuWbvNFsAARZsdyf6vGbAn4UdrKG5F9HQH1TtEslGMlF4d_ld31rKcUVSEhp4N2Cm3VKU_XjedyhjjcqpwEaB13qqoLj7v3S4I2XFn5-AbUw5Hc?type=png)](https://mermaid.live/edit#pako:eNqFUm1rwjAQ_ishMHDghn4Qtm4KRcsQdC-27ss6QtreZrBJuuQyJmP_fWmdVlDYEdLLPc_dc5fmm-a6ABpQ4s3ChwOVw0Twd8PlTarIn1XcoMhFxRWSidEKTkPTsnRSKI7atISGfzEaHYABmYfPbDyfsEX0tIzihM2jOA7voo6vxmV_OJ3NlvPpfZg8LFichMkyPj8u2HwDEqPvgKCQoB22rAO5llvLLqJ4OUtYOB5Hj0k0-SfjuBPy0hn0vF32uqR_sK6aSLtdD_Zu3-_nr63SvUYg-hPMoWaX7CTbWD0cOksql5XCrqAg3AbkNjMj4qp6ZCYtGZJ9P6B4VoKP-H6k_7EsEyi5XdeRbRoYow2z27J73tbLjHhfoQJbI1e9s22GRaMzYBUYoQsPNEJ_wcLhhuWbvNFsAARZsdyf6vGbAn4UdrKG5F9HQH1TtEslGMlF4d_ld31rKcUVSEhp4N2Cm3VKU_XjedyhjjcqpwEaB13qqoLj7v3S4I2XFn5-AbUw5Hc)
## Test Script
### Description
The test suite included in [assets/services/illuminators](https://github.com/mavlink/mavlink-devguide/blob/master/assets/services/illuminators/) allows for testing both sides of the illuminator interaction.
- [illuminator.py](https://github.com/mavlink/mavlink-devguide/blob/master/assets/services/illuminators/illuminator.py) emulates a standard illuminator module.
- [test_illuminator.py](https://github.com/mavlink/mavlink-devguide/blob/master/assets/services/illuminators/test_illuminator.py) runs a standard test suite against the emulator, testing all commands listed in this document.
### Instructions
1. Run simple illuminator emulator `python3 illuminator.py`
2. Run test `python3 -m unittest -v test_illuminator.py`
# Illuminator Protocol
The illuminator protocol allows MAVLink control over the behaviour of lights, LEDs, and/or emitters mounted or integrated on the drone.
The protocol currently allows for the following control: brightness, on/off, and a strobe feature.
Along with this, the illuminator protocol also publishes status information for developers or users.
The status messaging encompasses the current configuration of the illuminator and the health of the illuminator device.
## MAVLink Illuminator Implementations
These illuminators have built-in MAVLink support:
- Skydio Spotlight for X10
## Message/Command/Enum Summary
| Message | Description |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="COMPONENT_INFORMATION_BASIC"></a>[COMPONENT_INFORMATION_BASIC][CMPNT_INFO_BSC] | Basic illuminator information data. Should be requested using [MAV_CMD_REQUEST_MESSAGE][MAV_CMD_REQUEST_MESSAGE] on startup, or when required. |
| <a id="ILLUMINATOR_STATUS"></a>[ILLUMINATOR_STATUS](../messages/common.md#ILLUMINATOR_STATUS) | Current status of the illuminator. Recommended to publish this at a regular rate. |
| Command | Description |
| --------------------------------------------------------------------------------------------- | -------------------------------- |
| <a id="MAV_CMD_ILLUMINATOR_ON_OFF"></a>[MAV_CMD_ILLUMINATOR_ON_OFF][ILLUM_ON_OFF] | Turns illuminators ON/OFF. |
| <a id="MAV_CMD_DO_ILLUMINATOR_CONFIGURE"></a>[MAV_CMD_DO_ILLUMINATOR_CONFIGURE][DO_ILLM_CNFG] | Configures illuminator settings. |
<!-- reference links to make table above easier to edit -->
[DO_ILLM_CNFG]: ../messages/common.md#MAV_CMD_DO_ILLUMINATOR_CONFIGURE
[MAV_CMD_REQUEST_MESSAGE]: ../messages/common.md#MAV_CMD_REQUEST_MESSAGE
[CMPNT_INFO_BSC]: ../messages/common.md#COMPONENT_INFORMATION_BASIC
[ILLUM_ON_OFF]: ../messages/common.md#MAV_CMD_ILLUMINATOR_ON_OFF
| Enum Values | Description |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| <a id="MAV_TYPE_ILLUMINATOR"></a>[MAV_TYPE_ILLUMINATOR](../messages/minimal.md#MAV_TYPE_ILLUMINATOR) | Type of the component (illuminator). |
| <a id="MAV_COMP_ID_ILLUMINATOR"></a>[MAV_COMP_ID_ILLUMINATOR](../messages/minimal.md#MAV_COMP_ID_ILLUMINATOR) | ID of the component (illuminator). |
| Enum | Description |
| ------------------------------------------------------------------------------------------------------------ | ------------------------- |
| <a id="ILLUMINATOR_MODE"></a>[ILLUMINATOR_MODE](../messages/common.md#ILLUMINATOR_MODE) | Illuminator modes. |
| <a id="ILLUMINATOR_ERROR_FLAGS"></a>[ILLUMINATOR_ERROR_FLAGS](../messages/common.md#ILLUMINATOR_ERROR_FLAGS) | Fault/health indications. |
## Implementation and Messages
### Illuminator Connection
Illuminators are expected to follow the [Heartbeat/Connection Protocol](../services/heartbeat.md) and send a constant flow of heartbeats (nominally at 1Hz).
Illuminators are identified via their type [MAV_TYPE_ILLUMINATOR](#MAV_TYPE_ILLUMINATOR).
Individual illuminators are distinguished via their unique component ID, which by default should be [MAV_COMP_ID_ILLUMINATOR](#MAV_COMP_ID_ILLUMINATOR) (though this is not mandated and any ID may be used).
Once a heartbeat is received, the drone can then send a [MAV_CMD_REQUEST_MESSAGE ][MAV_CMD_REQUEST_MESSAGE] command to the illuminator to receive information, set settings, or control the illuminator.
An example below illustrates how a drone can request the status of the illuminator.
<!-- Mermaid graph:
sequenceDiagram;
participant Drone
participant Illuminator
Illuminator->>Drone: HEARTBEAT [cmp id: MAV_TYPE_ILLUMINATOR] (first)
Drone->>Illuminator: MAV_CMD_REQUEST_MESSAGE(param1=ILLUMINATOR_STATUS)
Drone->>Drone: Start timeout
Illuminator->>Drone: COMMAND_ACK
Note over Illuminator,Drone: If MAV_RESULT_ACCEPTED send info.
Illuminator->>Drone: ILLUMINATOR_STATUS [cmp id: MAV_COMP_ID_ILLUMINATOR]
-->
[![](https://mermaid.ink/img/pako:eNp9UWFLwzAQ_SshnxxMwa8VB7ENWly32aSCrBJCe9XgktQ0FcbYfzeuEzoGu0_Hy3sv7-52uLI14Ah38N2DqSBR8sNJfVcaFKqVzqtKtdJ4lDhr4BxON5teKyO9dcPjCLiezQ6qCD1RkvMHSjhaZ-QV-W0bwNAJ_raiIp3PiyxdEL7M39FVo1znJ2hwO-iDz8h1EMZZInL6UlDGRUYZI4_0KuSS-vZ-ZCcYJ7xgk1OzYyjmwxzIKw229xfCx8ssI4tEkPh5YC2sB2R_wI350yM7bQ75csqKOQ-amK44TVAHpkbKNPbmwk_nydG60i1S9XHoZbYSaXKysMEOT7EGp6WqwzF3f1iJ_SdoKHEU2lq6rxKXZh94sveWbU2FI-96mOK-raX_PzyOGrnpYP8LFgqu1A?type=png)](https://mermaid.live/edit#pako:eNp9UWFLwzAQ_SshnxxMwa8VB7ENWly32aSCrBJCe9XgktQ0FcbYfzeuEzoGu0_Hy3sv7-52uLI14Ah38N2DqSBR8sNJfVcaFKqVzqtKtdJ4lDhr4BxON5teKyO9dcPjCLiezQ6qCD1RkvMHSjhaZ-QV-W0bwNAJ_raiIp3PiyxdEL7M39FVo1znJ2hwO-iDz8h1EMZZInL6UlDGRUYZI4_0KuSS-vZ-ZCcYJ7xgk1OzYyjmwxzIKw229xfCx8ssI4tEkPh5YC2sB2R_wI350yM7bQ75csqKOQ-amK44TVAHpkbKNPbmwk_nydG60i1S9XHoZbYSaXKysMEOT7EGp6WqwzF3f1iJ_SdoKHEU2lq6rxKXZh94sveWbU2FI-96mOK-raX_PzyOGrnpYP8LFgqu1A)
### COMPONENT_INFORMATION_BASIC
While the `MAV_TYPE` and Component ID help identify the system and component, the [COMPONENT_INFORMATION_BASIC](#COMPONENT_INFORMATION_BASIC) command can be requested to retrieve component information data, which can help further identify the component being communicated with. This data includes `time_boot_ms`, `MAV_PROTOCOL_CAPABILITY`, `vendor_name`, `model_name`, `software_version`, `hardware_version`, and `serial_number`.
| Parameter | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `time_boot_ms` | Time since system boot up in milliseconds. |
| `MAV_PROTOCOL_CAPABILITY` | Bitmask detailing the component capability flags. |
| `vendor_name` | Name of the component vendor (optional). |
| `model_name` | Name of the component's model (optional). |
| `software_version` | Software version on the module, recommended format is SEMVER: 'major.minor.patch' but any format can be used (24-character string) (optional). |
| `hardware_version` | Hardware version on the module, recommended format is SEMVER: 'major.minor.patch' but any format can be used (24-character string) (optional). |
| `serial_number` | Hardware's serial number (optional). |
Optional parameters can be left empty or set to zero.
### ON/OFF
The [MAV_CMD_ILLUMINATOR_ON_OFF](#MAV_CMD_ILLUMINATOR_ON_OFF) command is used to enable/disable the illuminator.
It's usage can be seen below:
<!-- Mermaid graph:
sequenceDiagram;
participant Drone
participant Illuminator
Drone->>Illuminator: MAV_CMD_ILLUMINATOR_ON_OFF (param1 = 1)
Drone->>Drone: Start timeout
Illuminator->>Drone: MAV_RESULT_ACCEPTED
-->
[![](https://mermaid.ink/img/pako:eNplkMFqwzAMhl_F6LRCd-jVZYWQpBBImtGkOxmMSLTNLLYzVz6M0nef2zLWMV0kpE__j3SCwY8EEo70GckNVBh8C2jXyokUMwY2g5nRsSiCd_S_XU1TtMYh-3AbXrnHzeZuIEWTvei8KXRV14em2mV9u9ftTrfbrXhIamhX4kmsFn8VrlmKjpOdYGPJR74Rd9q_3MVjX3aHutdZnpfPfVnAEiwFi2ZMJ54uuwr4nSwpkKkcMXwoUO6cOIzsuy83gOQQaQlxHpF_3gHyFacjnb8BIBNkuQ?type=png)](https://mermaid.live/edit#pako:eNplkMFqwzAMhl_F6LRCd-jVZYWQpBBImtGkOxmMSLTNLLYzVz6M0nef2zLWMV0kpE__j3SCwY8EEo70GckNVBh8C2jXyokUMwY2g5nRsSiCd_S_XU1TtMYh-3AbXrnHzeZuIEWTvei8KXRV14em2mV9u9ftTrfbrXhIamhX4kmsFn8VrlmKjpOdYGPJR74Rd9q_3MVjX3aHutdZnpfPfVnAEiwFi2ZMJ54uuwr4nSwpkKkcMXwoUO6cOIzsuy83gOQQaQlxHpF_3gHyFacjnb8BIBNkuQ)
### CONFIGURE
The [MAV_CMD_DO_ILLUMINATOR_CONFIGURE](#MAV_CMD_DO_ILLUMINATOR_CONFIGURE) command controls the illuminator's settings. This will adjust how the illuminator behaves when enabled.
The operation follows the normal [Command Protocol](../services/command.md) rules for command/acknowledgment. The four parameters for this command are: Mode, Brightness, Strobe Period, Strobe Duty.
Illuminators can be set in different modes which can change the behavior of the illuminator (described in a separate section, [Modes](#MODES)).
The brightness can be set via "Brightness" as a percentage value (0-100%).
Illuminators may also have the functionality to strobe the light source.
This behavior is configured via "Strobe Period" and "Strobe Duty".
These parameters can be set to `0` when not used.
"Strobe Period" is in seconds and "Strobe Duty" is a percentage value (indicating the % of time in the "Strobe Period" the illuminator is enabled).
#### MODES
If the mode is unknown, the mode parameter value will be set to 0.
A mode value of 1 is `ILLUMINATOR_MODE_INTERNAL_CONTROL`, where the illuminator behavior is controlled by [MAV_CMD_DO_ILLUMINATOR_CONFIGURE](#MAV_CMD_DO_ILLUMINATOR_CONFIGURE) settings.
When the value is set to 2, it indicates that the illuminator mode is `ILLUMINATOR_MODE_EXTERNAL_SYNC`. This mode is for instances where the illuminator behavior is controlled by external factors: e.g. an external hardware signal.
### STATUS
The [ILLUMINATOR_STATUS](#ILLUMINATOR_STATUS) message can be requested to receive information about the status of the illuminator. This includes information such as uptime, errors, whether the illuminator is enabled via [MAV_CMD_ILLUMINATOR_ON_OFF](#MAV_CMD_ILLUMINATOR_ON_OFF), current settings from the [MAV_CMD_DO_ILLUMINATOR_CONFIGURE](#MAV_CMD_DO_ILLUMINATOR_CONFIGURE) command, and the temperature of the illuminator.
#### ILLUMINATOR_ERROR_FLAGS
The [ILLUMINATOR_ERROR_FLAGS](#ILLUMINATOR_ERROR_FLAGS) can be used to indicate if there is any issue with the illuminator. At this time, there are three flags. If there is no error and the illuminator is behaving as normal, the [ILLUMINATOR_ERROR_FLAGS](#ILLUMINATOR_ERROR_FLAGS) bitmap will be 0.
If [ILLUMINATOR_ERROR_FLAGS](#ILLUMINATOR_ERROR_FLAGS) is set to 1 or 2, this indicates an error related to the temperature of the illuminator.
`1` indicates `ILLUMINATOR_ERROR_FLAGS_THERMAL_THROTTLING` as in the illuminator is throttling its output due to a thermal issue.
`2` indicates `ILLUMINATOR_ERROR_FLAGS_OVER_TEMPERATURE_SHUTDOWN` which means that the illuminator is shutting off due to passing some temperature threshold.
The status message utilization can be seen below:
<!-- Mermaid graph:
sequenceDiagram;
participant Drone
participant Illuminator
Drone->>Illuminator: MAV_CMD_REQUEST_MESSAGE(param1=ILLUMINATOR_STATUS)
Drone->>Drone: Start timeout
Illuminator->>Drone: MAV_RESULT_ACCEPTED
Illuminator->>Drone: ILLUMINATOR_STATUS [(50000.0, 1, 1, 1, 1, 80.0, 0.0, 0.0, 95.0, 0.0, 10.0)]
Note over Illuminator, Drone: Illuminator Status published as: <br> uptime_ms = 50000.0, enable = 1, mode_bitmask = 1 <br> error_status = 1, mode = 1, brightness = 80% <br> strobe_period = 0.0, strobe_duty_cycle = 0.0, temp_c = 95.0 <br>min_strobe_period = 0.0, max_strobe_period = 10.0
-->
[![](https://mermaid.ink/img/pako:eNqFUm1rwjAQ_ishMHDghn4Qtm4KRcsQdC-27ss6QtreZrBJuuQyJmP_fWmdVlDYEdLLPc_dc5fmm-a6ABpQ4s3ChwOVw0Twd8PlTarIn1XcoMhFxRWSidEKTkPTsnRSKI7atISGfzEaHYABmYfPbDyfsEX0tIzihM2jOA7voo6vxmV_OJ3NlvPpfZg8LFichMkyPj8u2HwDEqPvgKCQoB22rAO5llvLLqJ4OUtYOB5Hj0k0-SfjuBPy0hn0vF32uqR_sK6aSLtdD_Zu3-_nr63SvUYg-hPMoWaX7CTbWD0cOksql5XCrqAg3AbkNjMj4qp6ZCYtGZJ9P6B4VoKP-H6k_7EsEyi5XdeRbRoYow2z27J73tbLjHhfoQJbI1e9s22GRaMzYBUYoQsPNEJ_wcLhhuWbvNFsAARZsdyf6vGbAn4UdrKG5F9HQH1TtEslGMlF4d_ld31rKcUVSEhp4N2Cm3VKU_XjedyhjjcqpwEaB13qqoLj7v3S4I2XFn5-AbUw5Hc?type=png)](https://mermaid.live/edit#pako:eNqFUm1rwjAQ_ishMHDghn4Qtm4KRcsQdC-27ss6QtreZrBJuuQyJmP_fWmdVlDYEdLLPc_dc5fmm-a6ABpQ4s3ChwOVw0Twd8PlTarIn1XcoMhFxRWSidEKTkPTsnRSKI7atISGfzEaHYABmYfPbDyfsEX0tIzihM2jOA7voo6vxmV_OJ3NlvPpfZg8LFichMkyPj8u2HwDEqPvgKCQoB22rAO5llvLLqJ4OUtYOB5Hj0k0-SfjuBPy0hn0vF32uqR_sK6aSLtdD_Zu3-_nr63SvUYg-hPMoWaX7CTbWD0cOksql5XCrqAg3AbkNjMj4qp6ZCYtGZJ9P6B4VoKP-H6k_7EsEyi5XdeRbRoYow2z27J73tbLjHhfoQJbI1e9s22GRaMzYBUYoQsPNEJ_wcLhhuWbvNFsAARZsdyf6vGbAn4UdrKG5F9HQH1TtEslGMlF4d_ld31rKcUVSEhp4N2Cm3VKU_XjedyhjjcqpwEaB13qqoLj7v3S4I2XFn5-AbUw5Hc)
## Test Script
### Description
The test suite included in [assets/services/illuminators](https://github.com/mavlink/mavlink-devguide/blob/master/assets/services/illuminators/) allows for testing both sides of the illuminator interaction.
- [illuminator.py](https://github.com/mavlink/mavlink-devguide/blob/master/assets/services/illuminators/illuminator.py) emulates a standard illuminator module.
- [test_illuminator.py](https://github.com/mavlink/mavlink-devguide/blob/master/assets/services/illuminators/test_illuminator.py) runs a standard test suite against the emulator, testing all commands listed in this document.
### Instructions
1. Run simple illuminator emulator `python3 illuminator.py`
2. Run test `python3 -m unittest -v test_illuminator.py`
en/services/image_transmission.md
+10 -6
View File
@@ -1,9 +1,10 @@
# Image Transmission Protocol
> [!WARNING]
> The [Camera Protocol](../services/camera.md) and [MAVLink FTP](../services/ftp.md) are recommended for sending images, video and files.
>
> This protocol is not intended for general image transmission use (it was originally designed as a simple protocol for transfering small images over a low bandwidth channel from an optical flow sensor to a GCS).
::: warning
The [Camera Protocol](../services/camera.md) and [MAVLink FTP](../services/ftp.md) are recommended for sending images, video and files.
This protocol is not intended for general image transmission use (it was originally designed as a simple protocol for transfering small images over a low bandwidth channel from an optical flow sensor to a GCS).
:::
The image transmission protocol uses MAVLink as the communication channel to transport any kind of image (raw images, Kinect data, etc.) from one MAVLink node to another.
It basically takes a live camera image, splits it into small chunks and sends it over MAVLink.
@@ -58,8 +59,9 @@ sequenceDiagram;
Every new image comes with a new `DATA_TRANSMISSION_HANDSHAKE` ACK packet with updated image `size`, `packets` and `payload` fields.
After this ACK packet, the new image arrives as a series of `ENCAPSULATED_DATA` packets.
> [!NOTE]
> The sequence number starts at 0 for every new image of the stream.
::: info
The sequence number starts at 0 for every new image of the stream.
:::
1. To stop an image stream a GSC must send a new `DATA_TRANSMISSION_HANDSHAKE` request packet, with all 0 values.
The MAVLink node will acknowledge this by sending back `DATA_TRANSMISSION_HANDSHAKE` also containing 0 values.
@@ -70,11 +72,13 @@ To use the two modules on your MAV, you have to do the following steps:
- Compile the `mavconn` middleware for your MAV: [Guide](https://www.pixhawk.org/wiki/software/mavconn/start), [Github](https://github.com/pixhawk/mavconn).
- Start at least these components on the MAV:
```
px_mavlink_bridge_udp &
px_system_control --heartbeat &
px_camera -o lcm &
```
- Compile and start _QGroundControl_.
- Start the image streaming component (you can add the `-v` flag to see some more output): `px_imagestreamer`.
- Initiate the image stream: Open the HUD widget, right-click into the widget and choose **Enable live Image Streaming**.
en/services/landing_target.md
+15 -10
View File
@@ -12,9 +12,10 @@ Radio beacons and different types of visual markers and tags are also supported.
The message used by this protocol is [LANDING_TARGET](../messages/common.md#LANDING_TARGET).
This is _broadcast_ by the positioning system to indicate the position of a particular target at a particular time.
> [!NOTE]
> The required broadcast rate depends on the landing speed and desired accuracy;
> start with rates between 10 Hz and 50 Hz and tune performance as needed.
::: info
The required broadcast rate depends on the landing speed and desired accuracy;
start with rates between 10 Hz and 50 Hz and tune performance as needed.
:::
The original MAVLink 1 message was designed with the assumption that the target is captured from a downward facing camera, and provides fields that are relative to the captured image.
MAVLink 2 extended the message to provide positional information in terms of standard frames ([MAV_FRAME](../messages/common.md#MAV_FRAME)), a quaternion and the type of landing targets ([LANDING_TARGET_TYPE](../messages/common.md#LANDING_TARGET_TYPE)).
@@ -48,8 +49,9 @@ Otherwise the receiver of the message would need to know the camera field of vie
The sizes in x and y direction are analogous (`size_x`/`size_y`).
They describe the angle between the smallest and biggest pixel in x/y direction respectively of the target as seen in the image.
> [!TIP]
> ArduPilot supports messages with these fields if position_valid is `0`.
::: tip
ArduPilot supports messages with these fields if position_valid is `0`.
:::
## Target as Position/Quaternion (MAVLink 2 and later) {#positional}
@@ -66,8 +68,11 @@ Field meaning and use is clear from the description.
| type | uint8_t | | [LANDING_TARGET_TYPE](../messages/common.md#LANDING_TARGET_TYPE) | Type of landing target |
| position_valid | uint8_t | | | Boolean indicating whether these position field values are populated with valid position target information (1: valid, 0: invalid). The default is '0', so that if the fields are not populated the default-zero values are not interpreted as a valid target position. |
> [!TIP]
> - PX4 supports this form of positioning in [MAV_FRAME_LOCAL_NED](../messages/common.md#MAV_FRAME_LOCAL_NED) (only).
> The original (MAVLink 1) fields are ignored.
> - ArduPilot supports this form of positioning in [MAV_FRAME_BODY_FRD](../messages/common.md#MAV_FRAME_BODY_FRD) (only).
> `position_valid` must be `1` and `distance` must be filled.
::: tip
- PX4 supports this form of positioning in [MAV_FRAME_LOCAL_NED](../messages/common.md#MAV_FRAME_LOCAL_NED) (only).
The original (MAVLink 1) fields are ignored.
- ArduPilot supports this form of positioning in [MAV_FRAME_BODY_FRD](../messages/common.md#MAV_FRAME_BODY_FRD) (only).
`position_valid` must be `1` and `distance` must be filled.
:::
en/services/mavlink_id_assignment.md
+4 -3
View File
@@ -22,14 +22,15 @@ The following section suggests a process to allow MAVLink components to automati
First change the system ID of the autopilot component.
This is usually done with a flight-stack specific parameter such as [MAV_SYS_ID](https://docs.px4.io/main/en/advanced_config/parameter_reference.html#MAV_SYS_ID) (PX4) or [SYSID_THISMAV](https://ardupilot.org/copter/docs/parameters.html#sysid-thismav-mavlink-system-id-of-this-vehicle) (ArduCopter).
> [!NOTE]
> [MAV_CMD_DO_SET_SYS_CMP_ID](../messages/development.md#MAV_CMD_DO_SET_SYS_CMP_ID) is a work-in-progress command for setting and changing system and command ids.
::: info
[MAV_CMD_DO_SET_SYS_CMP_ID](../messages/development.md#MAV_CMD_DO_SET_SYS_CMP_ID) is a work-in-progress command for setting and changing system and command ids.
:::
Then reboot the vehicle off-network, so that the only autopilot visible to components should be the one on the vehicle (you can disconnect your telemetry radio, for example).
On boot, components should look for autopilot `HEARTBEAT` messages.
If HEARTBEAT messages are detected from:
If `HEARTBEAT` messages are detected from:
- Only one autopilot within 3 seconds of the first autopilot heartbeat being detected, the component should set its system id to match that of the autopilot.
- Multiple autopilots within the first 3 seconds then the autopilot should keep its current system id.
en/services/mission.md
+42 -32
View File
@@ -20,17 +20,19 @@ Mission protocol messages include the type of associated mission in the `mission
The field takes one of the [MAV_MISSION_TYPE](../messages/common.md#MAV_MISSION_TYPE) enum values:
[MAV_MISSION_TYPE_MISSION](../messages/common.md#MAV_MISSION_TYPE_MISSION), [MAV_MISSION_TYPE_FENCE](../messages/common.md#MAV_MISSION_TYPE_FENCE), [MAV_MISSION_TYPE_RALLY](../messages/common.md#MAV_MISSION_TYPE_RALLY).
> [!NOTE]
> MAVLink 1 supports only "regular" flight-plan missions (this is implied/not explicitly set).
::: info
MAVLink 1 supports only "regular" flight-plan missions (this is implied/not explicitly set).
:::
## Mission Items (MAVLink Commands) {#mavlink_commands}
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)).
> 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).
::: info
[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)).
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:
@@ -129,20 +131,23 @@ A number of local frames are also specified.
Local frame position values that are sent in integer field parameters must be encoded as _position in meters x 1E4_ (e.g. 5m would be encoded and sent as 50000).
If sent in messages `float` parameter fields the value should be sent as-is.
> [!NOTE]
> Don't use the non-INT _global frames_ in mission items (e.g. `MAV_FRAME_GLOBAL_RELATIVE_ALT`).
> These are intended to be used with messages that have `float` fields for positional information, e.g.: `MISSION_ITEM` (deprecated), `COMMAND_LONG`.
> If these frames are used, position values should be sent unencoded (i.e. no need to multiply by 1E7).
::: info
Don't use the non-INT _global frames_ in mission items (e.g. `MAV_FRAME_GLOBAL_RELATIVE_ALT`).
These are intended to be used with messages that have `float` fields for positional information, e.g.: `MISSION_ITEM` (deprecated), `COMMAND_LONG`.
If these frames are used, position values should be sent unencoded (i.e. no need to multiply by 1E7).
:::
> [!NOTE]
> As above, in theory if a global _non-INT_ frame variant is set for a `MISSION_ITEM_INT` the position value should be sent as-is (not encoded).
> This will result in the value being rounded when it is sent in the integer value, which will make the value unusable.
> In practice, many systems will assume you have encoded the value, but you should test this for your particular flight stack.
> Better just to use the correct frames!
::: info
As above, in theory if a global _non-INT_ frame variant is set for a `MISSION_ITEM_INT` the position value should be sent as-is (not encoded).
This will result in the value being rounded when it is sent in the integer value, which will make the value unusable.
In practice, many systems will assume you have encoded the value, but you should test this for your particular flight stack.
Better just to use the correct frames!
:::
> [!WARNING]
> Don't use [MAV_FRAME_MISSION](../messages/common.md#MAV_FRAME_MISSION) for mission items that contain positional data; this does not correspond to any particular real frame, and so will be ambiguous.
> `MAV_FRAME_MISSION` should be used for mission items that use params5 and param6 for other purposes.
::: warning
Don't use [MAV_FRAME_MISSION](../messages/common.md#MAV_FRAME_MISSION) for mission items that contain positional data; this does not correspond to any particular real frame, and so will be ambiguous.
`MAV_FRAME_MISSION` should be used for mission items that use params5 and param6 for other purposes.
:::
## Param 5, 6 For Non-Positional Data
@@ -178,13 +183,15 @@ It can then monitor `MISSION_CURRENT`, and check its cached values against the c
The diagram below shows the communication sequence to upload a mission to a drone (assuming all operations succeed).
> [!WARNING]
> Mission update must be robust!
> A new mission should be fully uploaded and accepted before the old mission is replaced/removed.
::: warning
Mission update must be robust!
A new mission should be fully uploaded and accepted before the old mission is replaced/removed.
:::
> [!NOTE]
> Mission upload/download can be bandwidth intensive and time consuming
> [Check for plan changes](#detecting-missionplan-changes) before uploading (or downloading) a mission.
:::
Mission upload/download can be bandwidth intensive and time consuming
[Check for plan changes](#detecting-missionplan-changes) before uploading (or downloading) a mission.
:::
[![Mission Upload Sequence](https://mermaid.ink/img/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtO1xuICAgIHBhcnRpY2lwYW50IEdDU1xuICAgIHBhcnRpY2lwYW50IERyb25lXG4gICAgR0NTLT4-RHJvbmU6IE1JU1NJT05fQ09VTlRcbiAgICBHQ1MtPj5HQ1M6IFN0YXJ0IHRpbWVvdXRcbiAgICBEcm9uZS0-PkdDUzogTUlTU0lPTl9SRVFVRVNUX0lOVCAoMClcbiAgICBEcm9uZS0-PkRyb25lOiBTdGFydCB0aW1lb3V0XG4gICAgR0NTLS0-PkRyb25lOiBNSVNTSU9OX0lURU1fSU5UICgwKVxuICAgIE5vdGUgb3ZlciBHQ1MsRHJvbmU6IC4uLiBpdGVyYXRlIHRocm91Z2ggaXRlbXMgLi4uXG4gICAgRHJvbmUtPj5HQ1M6IE1JU1NJT05fUkVRVUVTVF9JTlQgKGNvdW50LTEpXG4gICAgRHJvbmUtPj5Ecm9uZTogU3RhcnQgdGltZW91dFxuICAgIEdDUy0tPj5Ecm9uZTogTUlTU0lPTl9JVEVNX0lOVCAoY291bnQtMSlcbiAgICBEcm9uZS0-PkdDUzogTUlTU0lPTl9BQ0siLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtO1xuICAgIHBhcnRpY2lwYW50IEdDU1xuICAgIHBhcnRpY2lwYW50IERyb25lXG4gICAgR0NTLT4-RHJvbmU6IE1JU1NJT05fQ09VTlRcbiAgICBHQ1MtPj5HQ1M6IFN0YXJ0IHRpbWVvdXRcbiAgICBEcm9uZS0-PkdDUzogTUlTU0lPTl9SRVFVRVNUX0lOVCAoMClcbiAgICBEcm9uZS0-PkRyb25lOiBTdGFydCB0aW1lb3V0XG4gICAgR0NTLS0-PkRyb25lOiBNSVNTSU9OX0lURU1fSU5UICgwKVxuICAgIE5vdGUgb3ZlciBHQ1MsRHJvbmU6IC4uLiBpdGVyYXRlIHRocm91Z2ggaXRlbXMgLi4uXG4gICAgRHJvbmUtPj5HQ1M6IE1JU1NJT05fUkVRVUVTVF9JTlQgKGNvdW50LTEpXG4gICAgRHJvbmUtPj5Ecm9uZTogU3RhcnQgdGltZW91dFxuICAgIEdDUy0tPj5Ecm9uZTogTUlTU0lPTl9JVEVNX0lOVCAoY291bnQtMSlcbiAgICBEcm9uZS0-PkdDUzogTUlTU0lPTl9BQ0siLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)
@@ -233,9 +240,10 @@ Notes:
### Download a Mission from the Vehicle {#download_mission}
> [!NOTE]
> Mission upload/download can also be bandwidth intensive and time consuming.
> [Check for plan changes](#detecting-missionplan-changes) before downloading (or uploading) a mission.
::: info
Mission upload/download can also be bandwidth intensive and time consuming.
[Check for plan changes](#detecting-missionplan-changes) before downloading (or uploading) a mission.
:::
The diagram below shows the communication sequence to download a mission from a drone (assuming all operations succeed).
@@ -415,8 +423,9 @@ The location and fixed-wing loiter radius parameters are common to all commands:
The loiter time and turns are set in param 1 for the respective messages.
The direction of loiter for `MAV_CMD_NAV_LOITER_UNLIM` can be set using `param4` (Yaw).
> [!NOTE]
> The remaining parameters (xtrack and heading) apply only to forward flying aircraft (not multicopters!)
::: info
The remaining parameters (xtrack and heading) apply only to forward flying aircraft (not multicopters!)
:::
Xtrack and heading define the location at which a forward flying (fixed wing) vehicle will _exit the loiter circle, and its path to the next waypoint_ (these apply only to apply to only `MAV_CMD_NAV_LOITER_TIME` and `MAV_CMD_NAV_LOITER_TURNS`).
@@ -505,9 +514,10 @@ Source:
Mission upload, download, clearing missions, and monitoring progress are supported.
> [!NOTE]
> 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.
::: info
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):
en/services/opendroneid.md
+10 -8
View File
@@ -59,10 +59,11 @@ The ASTM, ASD-STAN and MAVLink messages are listed below.
| \_ | \_ | [OPEN_DRONE_ID_ARM_STATUS](../messages/common.md#OPEN_DRONE_ID_ARM_STATUS) | Sent by RID transmitter/receiver components to indicate that the RID system is "ready to use". This should be used as an arming condition for the flight stack. Note that this differs from the [HEARTBEAT](#heartbeat) which indicates that the component is "alive" but not necessarily ready to use. |
| \_ | \_ | [OPEN_DRONE_ID_SYSTEM_UPDATE](../messages/common.md#OPEN_DRONE_ID_SYSTEM_UPDATE) | A subset of the [OPEN_DRONE_ID_SYSTEM](#OPEN_DRONE_ID_SYSTEM) message, containing only the fields that must be updated at a high rate. Typically sent from the GCS to provide data to the RID transmitter component. If both `OPEN_DRONE_ID_SYSTEM` and `OPEN_DRONE_ID_SYSTEM_UPDATE` are used, the more efficient `OPEN_DRONE_ID_SYSTEM_UPDATE` will be used at a high rate and the full `OPEN_DRONE_ID_SYSTEM` at a low rate, to reduce the traffic on the control link. |
> [!NOTE]
> The raw byte layout of the MAVLink messages is not exactly the same as what a RID Bluetooth/Wi-Fi transmitter component will broadcast over the air.
> Slight compression is applied.
> Example code for this conversion can be found in the project: [Open Drone ID Core C Library](https://github.com/opendroneid/opendroneid-core-c).
::: info
The raw byte layout of the MAVLink messages is not exactly the same as what a RID Bluetooth/Wi-Fi transmitter component will broadcast over the air.
Slight compression is applied.
Example code for this conversion can be found in the project: [Open Drone ID Core C Library](https://github.com/opendroneid/opendroneid-core-c).
:::
The [Open Drone ID Core C Library](https://github.com/opendroneid/opendroneid-core-c) contains code for decoding the MAVLink messages and "compressing" the data into data structures for broadcast over Bluetooth or Wi-Fi (or vice-versa for reception).
@@ -140,10 +141,11 @@ Similarly, the autopilot must listen to the [ARM_STATUS](#OPEN_DRONE_ID_ARM_STAT
During flight, if the arm status indicates a failure, similar action must be taken as for a lack of `HEARTBEAT` messages from the RemoteID.
The [ARM_STATUS](#OPEN_DRONE_ID_ARM_STATUS) message must also be routed to a GCS, if present, allowing it to provide more detailed information about RemoteID arming failures.
> [!NOTE]
> In addition to the above, there are multiple additional different scenarios that must result in the Location status field being set to Emergency or Remote ID System Failure.
> The exact strategy on how to avoid having multiple MAVLink components overwriting each-others emergency declarations is not yet fully defined.
> Some preliminary discussion can be found [here](https://github.com/ArduPilot/ArduRemoteID/issues/34).
::: info
In addition to the above, there are multiple additional different scenarios that must result in the Location status field being set to Emergency or Remote ID System Failure.
The exact strategy on how to avoid having multiple MAVLink components overwriting each-others emergency declarations is not yet fully defined.
Some preliminary discussion can be found [here](https://github.com/ArduPilot/ArduRemoteID/issues/34).
:::
Optionally, further restrictions on which RID transmitter/receiver component must process a MAVLink message can be enforced if the sender fills the `target_system` and `target_component` fields of the MAVLink message.
RID transmitter/receiver components must only listen to MAVLink messages that have these fields set to either zero (broadcast) or the component's own MAVLink system ID and component ID.
en/services/parameter.md
+24 -18
View File
@@ -37,9 +37,10 @@ Support for the parameter protocol is indicated if either [MAV_PROTOCOL_CAPABILI
These protocol bits indicate different bytewise and C-style [parameter value encoding](#parameter-encoding) respectively.
> [!NOTE]
> The protocol may still be supported even if neither protocol bit is set.
> To use the protocol in this case, a connected system would need to have prior knowledge of connected component.
::: info
The protocol may still be supported even if neither protocol bit is set.
To use the protocol in this case, a connected system would need to have prior knowledge of connected component.
:::
## Parameter Names
@@ -106,8 +107,9 @@ A GCS or other component may choose to maintain a cache of parameter values for
The cache can be populated initially by first [reading the full parameter list](#read_all) at least once, and then updated by monitoring for [PARAM_VALUE](../messages/common.md#PARAM_VALUE) messages (which are emitted whenever a parameter is [written](#write) or otherwise changed).
> [!NOTE]
> Cache synchronisation is not guaranteed; a component may [miss update messages](#monitoring_unreliable) due to parameter changes by other components.
::: info
Cache synchronisation is not guaranteed; a component may [miss update messages](#monitoring_unreliable) due to parameter changes by other components.
:::
## Multi-System and Multi-Component Support
@@ -118,8 +120,9 @@ To get a complete parameter list from a system, send the request parameter messa
All components must respond to parameter request messages addressed to their ID or the ID `MAV_COMP_ID_ALL`.
> [!TIP]
> _QGroundControl_ by default queries all components of the currently connected system (it sends ID `MAV_COMP_ID_ALL`).
::: tip
_QGroundControl_ by default queries all components of the currently connected system (it sends ID `MAV_COMP_ID_ALL`).
:::
## Limitations {#limitations}
@@ -211,10 +214,11 @@ The sequence of operations is:
The drone may restart the sequence if the `PARAM_VALUE` acknowledgment is not received within the timeout.
> [!NOTE]
> There is no formal way for the drone to signal when an invalid parameter is requested (i.e. for a parameter name or id that does not exist).
> In this case the drone _should_ emit [STATUS_TEXT](../messages/common.md#STATUS_TEXT).
> The GCS may monitor for the specific notification, but will otherwise fail the request after any timeout/resend cycle completes.
::: info
There is no formal way for the drone to signal when an invalid parameter is requested (i.e. for a parameter name or id that does not exist).
In this case the drone _should_ emit [STATUS_TEXT](../messages/common.md#STATUS_TEXT).
The GCS may monitor for the specific notification, but will otherwise fail the request after any timeout/resend cycle completes.
:::
### Write Parameters {#write}
@@ -240,17 +244,19 @@ The sequence of operations is:
1. GCS starts timout waiting for acknowledgment (in the form of a [PARAM_VALUE](../messages/common.md#PARAM_VALUE) message).
1. Drone writes parameter and responds by _broadcasting_ a `PARAM_VALUE` containing the updated parameter value to all components/systems.
> [!NOTE]
> The Drone must acknowledge the `PARAM_SET` by broadcasting a `PARAM_VALUE` even if the write operation fails.
> In this case the `PARAM_VALUE` will be the current/unchanged parameter value.
::: info
The Drone must acknowledge the `PARAM_SET` by broadcasting a `PARAM_VALUE` even if the write operation fails.
In this case the `PARAM_VALUE` will be the current/unchanged parameter value.
:::
1. GCS should update the [parameter cache](#parameter_caching) (if used) with the new value.
1. The GCS may restart the sequence if the expected `PARAM_VALUE` is not received within the timeout, or if the write operation fails (the value returned in `PARAM_VALUE` does not match the value set).
> [!NOTE]
> The command [MAV_CMD_DO_SET_PARAMETER](../messages/common.md#MAV_CMD_DO_SET_PARAMETER) is not part of the parameter protocol.
> If implemented it can be used to set the value of a parameter using the _enumeration_ of the parameter within the remote system is known (rather than the id).
> This has no particular advantage over the parameter protocol methods.
::: info
The command [MAV_CMD_DO_SET_PARAMETER](../messages/common.md#MAV_CMD_DO_SET_PARAMETER) is not part of the parameter protocol.
If implemented it can be used to set the value of a parameter using the _enumeration_ of the parameter within the remote system is known (rather than the id).
This has no particular advantage over the parameter protocol methods.
:::
## Implementations
en/services/parameter_ext.md
+21 -18
View File
@@ -7,24 +7,25 @@ The protocol shares most of the same benefits and limitations of the original pr
The main difference is that when [writing a parameter](#write) the system emits one or more [PARAM_EXT_ACK](#PARAM_EXT_ACK) messages (rather than [PARAM_EXT_VALUE](#PARAM_EXT_VALUE), as you would expect from the original protocol).
This allows the _Extended Parameter Protocol_ to differentiate between the case where a write fails (or is in progress) and the case where the value update simply went missing.
> [!NOTE]
> The extensions were invented for the [Camera Protocol](../services/camera.md), which uses them to request/set parameter values specified in a [Camera Definition File](../services/camera_def.md).
> At time of writing the protocol is supported by _QGroundControl_ for this purpose, but is not otherwise supported by flight stacks.
::: info
The extensions were invented for the [Camera Protocol](../services/camera.md), which uses them to request/set parameter values specified in a [Camera Definition File](../services/camera_def.md).
At time of writing the protocol is supported by _QGroundControl_ for this purpose, but is not otherwise supported by flight stacks.
:::
## Message/Enum Summary
| Message | Description |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="PARAM_EXT_REQUEST_LIST"></span>[PARAM_EXT_REQUEST_LIST](../messages/common.md#PARAM_EXT_REQUEST_LIST) | Request all parameters of this component. On receiving this request, the requested component will emit all parameter values using [PARAM_EXT_VALUE](#PARAM_EXT_VALUE). |
| <span id="PARAM_EXT_VALUE"></span>[PARAM_EXT_VALUE](../messages/common.md#PARAM_EXT_VALUE) | Emit the value of a parameter, following a [PARAM_EXT_REQUEST_LIST](#PARAM_EXT_REQUEST_LIST) or [PARAM_EXT_REQUEST_READ](#PARAM_EXT_REQUEST_READ). The message includes `param_count` and `param_index` which the recipient can use to track received parameters and re-request missing parameters after a timeout. |
| <span id="PARAM_EXT_REQUEST_READ"></span>[PARAM_EXT_REQUEST_READ](../messages/common.md#PARAM_EXT_REQUEST_READ) | Request the value of a specific parameter using either its `param_id` or `param_index`. Expects a response in a [PARAM_EXT_VALUE](#PARAM_EXT_VALUE). |
| <span id="PARAM_EXT_SET"></span>[PARAM_EXT_SET](../messages/common.md#PARAM_EXT_SET) | Set a parameter value. Expects immediate response [PARAM_EXT_ACK](#PARAM_EXT_ACK) with result indicating success, failure, or that the request is still in progress (`PARAM_ACK_IN_PROGRESS`). If in progress, additional update [PARAM_EXT_ACK](#PARAM_EXT_ACK) messages are expected. |
| <span id="PARAM_EXT_ACK"></span>[PARAM_EXT_ACK](../messages/common.md#PARAM_EXT_ACK) | Response from a [PARAM_EXT_SET](#PARAM_EXT_SET) message, which indicates whether the value was accepted (set), failed, setting is still in progress, or that the specified parameter is invalid/unsupported. |
| Message | Description |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="PARAM_EXT_REQUEST_LIST"></a>[PARAM_EXT_REQUEST_LIST](../messages/common.md#PARAM_EXT_REQUEST_LIST) | Request all parameters of this component. On receiving this request, the requested component will emit all parameter values using [PARAM_EXT_VALUE](#PARAM_EXT_VALUE). |
| <a id="PARAM_EXT_VALUE"></a>[PARAM_EXT_VALUE](../messages/common.md#PARAM_EXT_VALUE) | Emit the value of a parameter, following a [PARAM_EXT_REQUEST_LIST](#PARAM_EXT_REQUEST_LIST) or [PARAM_EXT_REQUEST_READ](#PARAM_EXT_REQUEST_READ). The message includes `param_count` and `param_index` which the recipient can use to track received parameters and re-request missing parameters after a timeout. |
| <a id="PARAM_EXT_REQUEST_READ"></a>[PARAM_EXT_REQUEST_READ](../messages/common.md#PARAM_EXT_REQUEST_READ) | Request the value of a specific parameter using either its `param_id` or `param_index`. Expects a response in a [PARAM_EXT_VALUE](#PARAM_EXT_VALUE). |
| <a id="PARAM_EXT_SET"></a>[PARAM_EXT_SET](../messages/common.md#PARAM_EXT_SET) | Set a parameter value. Expects immediate response [PARAM_EXT_ACK](#PARAM_EXT_ACK) with result indicating success, failure, or that the request is still in progress (`PARAM_ACK_IN_PROGRESS`). If in progress, additional update [PARAM_EXT_ACK](#PARAM_EXT_ACK) messages are expected. |
| <a id="PARAM_EXT_ACK"></a>[PARAM_EXT_ACK](../messages/common.md#PARAM_EXT_ACK) | Response from a [PARAM_EXT_SET](#PARAM_EXT_SET) message, which indicates whether the value was accepted (set), failed, setting is still in progress, or that the specified parameter is invalid/unsupported. |
| Enum | Description |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="MAV_PARAM_EXT_TYPE"></span>[MAV_PARAM_EXT_TYPE](../messages/common.md#MAV_PARAM_EXT_TYPE) | Specifies the datatype of a MAVLink extended parameter (parameter values are [encoded](#parameter_encoding) within the a `char[128]` array in the messages). This type conveys the _real type_ of the encoded parameter value, e.g. `MAV_PARAM_EXT_TYPE_REAL32`. |
| <span id="PARAM_ACK"></span>[PARAM_ACK](../messages/common.md#PARAM_ACK) | Request acknowledgment status value, sent in an [PARAM_EXT_ACK](#PARAM_EXT_ACK) as a response to a [PARAM_EXT_SET](#PARAM_EXT_SET) message. A request can be accepted, fail, in-progress, or unsupported (indicating the specified parameter does not exist or has an invalid value or value type). |
| Enum | Description |
| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="MAV_PARAM_EXT_TYPE"></a>[MAV_PARAM_EXT_TYPE](../messages/common.md#MAV_PARAM_EXT_TYPE) | Specifies the datatype of a MAVLink extended parameter (parameter values are [encoded](#parameter_encoding) within the a `char[128]` array in the messages). This type conveys the _real type_ of the encoded parameter value, e.g. `MAV_PARAM_EXT_TYPE_REAL32`. |
| <a id="PARAM_ACK"></a>[PARAM_ACK](../messages/common.md#PARAM_ACK) | Request acknowledgment status value, sent in an [PARAM_EXT_ACK](#PARAM_EXT_ACK) as a response to a [PARAM_EXT_SET](#PARAM_EXT_SET) message. A request can be accepted, fail, in-progress, or unsupported (indicating the specified parameter does not exist or has an invalid value or value type). |
## Parameter Encoding {#parameter_encoding}
@@ -32,8 +33,9 @@ Parameters names/ids are set in the `param_id` field of messages where they are
The `param_id` string can store up to 16 characters.
The string is terminated with a NULL (`\0`) character if there are less than 16 human-readable chars, and without a null termination byte if the length is exactly 16 chars.
> [!NOTE]
> Names (as above) are the same as for the [Parameter Protocol](../services/parameter.md#parameter_encoding).
::: info
Names (as above) are the same as for the [Parameter Protocol](../services/parameter.md#parameter_encoding).
:::
Values are byte-wise encoded _within_ the `param_value` field, which is a `char[128]`.
The `param_type` ([MAV_PARAM_EXT_TYPE](#MAV_PARAM_EXT_TYPE)) is used to indicate the actual type of the data so that it can be decoded by the recipient.
@@ -123,8 +125,9 @@ The cache can be populated initially by first [reading the full parameter list](
A system may also monitor for [PARAM_EXT_VALUE](#PARAM_EXT_VALUE) originating from other components/systems requesting parameter values.
> [!NOTE]
> Cache synchronisation is not guaranteed; a component may [miss parameter update messages](#monitoring_unreliable) due to changes by other components.
::: info
Cache synchronisation is not guaranteed; a component may [miss parameter update messages](#monitoring_unreliable) due to changes by other components.
:::
## Limitations {#limitations}
en/services/payload.md
+24 -18
View File
@@ -3,8 +3,9 @@
MAVLink defines a number of commands for directly controlling [particular types of payloads](#payload-specific-commands) like winches and grippers, and for controlling [generic payloads](#generic-payload-commands).
In addition there are commands for [payload placement in missions](#payload-deployment-commands).
> [!NOTE]
> [Camera](camera.md) and [Gimbal](gimbal_v2.md) payloads are covered in their own topics.
::: info
[Camera](camera.md) and [Gimbal](gimbal_v2.md) payloads are covered in their own topics.
:::
## Payload-Specific Commands
@@ -24,8 +25,9 @@ They should be used (where supported) in preference to [generic payload commands
MAVLink has a number of commands for setting actuator outputs.
These can be used to control arbitrary/generic payloads.
> [!TIP]
> Use the [commands for known payload types](#payload-specific-commands) where possible as they are more intuitive for users, and in logs.
::: tip
Use the [commands for known payload types](#payload-specific-commands) where possible as they are more intuitive for users, and in logs.
:::
| Message | Description |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -34,14 +36,16 @@ These can be used to control arbitrary/generic payloads.
| <a id="MAV_CMD_DO_SET_RELAY"></a>[MAV_CMD_DO_SET_RELAY](../messages/common.md#MAV_CMD_DO_SET_RELAY) | Set a specified relay instance on or off. |
| <a id="MAV_CMD_DO_REPEAT_RELAY"></a>[MAV_CMD_DO_REPEAT_RELAY](../messages/common.md#MAV_CMD_DO_REPEAT_RELAY) | Cycle a relay on and off for a desired number of cycles with a desired period. |
> [!NOTE]
> **Implementations:**
>
> - `MAV_CMD_DO_SET_ACTUATOR` is more recent than `MAV_CMD_DO_SET_SERVO`, but has not yet been widely adopted.
> - Only implemented only on PX4 (June 2021).
> For more information see the [PX4 User Guide](https://docs.px4.io/master/en/payloads/#mission-triggering).
> - `MAV_CMD_DO_SET_SERVO` is implemented on both ArduPilot and PX4 (Missions only).
> In both cases instance numbers map to corresponding AUX outputs.
::: info
**Implementations:**
- `MAV_CMD_DO_SET_ACTUATOR` is more recent than `MAV_CMD_DO_SET_SERVO`, but has not yet been widely adopted.
- Only implemented only on PX4 (June 2021).
For more information see the [PX4 User Guide](https://docs.px4.io/master/en/payloads/#mission-triggering).
- `MAV_CMD_DO_SET_SERVO` is implemented on both ArduPilot and PX4 (Missions only).
In both cases instance numbers map to corresponding AUX outputs.
:::
## Payload Deployment Commands
@@ -51,9 +55,11 @@ These commands can be used to deploy a payload at a specfic location, controllin
| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| <a id="MAV_CMD_NAV_PAYLOAD_PLACE"></a>[MAV_CMD_NAV_PAYLOAD_PLACE](../messages/common.md#MAV_CMD_NAV_PAYLOAD_PLACE) | Move to target location, descend and release payload. |
> [!NOTE]
> **Implementations:**
>
> - [MAV_CMD_NAV_PAYLOAD_PLACE](#MAV_CMD_NAV_PAYLOAD_PLACE) is implemented in ArduPilot only, and can be used in missions.
> - [MAV_CMD_PAYLOAD_PREPARE_DEPLOY](../messages/common.md#MAV_CMD_PAYLOAD_PREPARE_DEPLOY) and [MAV_CMD_PAYLOAD_CONTROL_DEPLOY](../messages/common.md#MAV_CMD_PAYLOAD_PREPARE_DEPLOY) are not supported on any known flight stack.
> They are deprecated and should not be used.
::: info
**Implementations:**
- [MAV_CMD_NAV_PAYLOAD_PLACE](#MAV_CMD_NAV_PAYLOAD_PLACE) is implemented in ArduPilot only, and can be used in missions.
- [MAV_CMD_PAYLOAD_PREPARE_DEPLOY](../messages/common.md#MAV_CMD_PAYLOAD_PREPARE_DEPLOY) and [MAV_CMD_PAYLOAD_CONTROL_DEPLOY](../messages/common.md#MAV_CMD_PAYLOAD_PREPARE_DEPLOY) are not supported on any known flight stack.
They are deprecated and should not be used.
:::
en/services/ping.md
+4 -3
View File
@@ -39,9 +39,10 @@ The original ping**ing** system:
- Receives a `PING` message with `target_system` and `target_component` matching its address.
> [!TIP]
> Any non-zero target system/component indicates a response message.
> The matching ids inform the system that it is the intended recipient.
::: tip
Any non-zero target system/component indicates a response message.
The matching ids inform the system that it is the intended recipient.
:::
- The system calculates the latency from the current system time and the time in the response `PING` for the matching sequence number.
- A system that is sending a single `PING` can use a timeout to detect a dropped packet.
en/services/standard_modes.md
+8 -6
View File
@@ -1,8 +1,9 @@
# 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).
::: 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.
@@ -133,9 +134,10 @@ This will ACK with `MAV_RESULT_ACCEPTED` if the mode can change, and `MAV_RESULT
Custom modes must be set with [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE).
> [!NOTE]
> If both `standard_mode` and `custom_mode` are set you can determine the mapping between modes and might therefore use [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) to set a standard mode.
> `MAV_CMD_DO_SET_STANDARD_MODE` is preferred for setting standard modes.
::: info
If both `standard_mode` and `custom_mode` are set you can determine the mapping between modes and might therefore use [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) to set a standard mode.
`MAV_CMD_DO_SET_STANDARD_MODE` is preferred for setting standard modes.
:::
### Getting Current Active Mode
en/services/terrain.md
+13 -11
View File
@@ -4,18 +4,19 @@ The _Terrain Protocol_ provides a mechanism for a vehicle to get terrain informa
Support for this protocol is indicated by `AUTOPILOT_VERSION.capabilities` by the [MAV_PROTOCOL_CAPABILITY_TERRAIN](../messages/common.md#MAV_PROTOCOL_CAPABILITY_TERRAIN) flag.
> [!NOTE]
> A vehicle that supports this capability must also support terrain following in missions using the data.
> Note however that a vehicle may also support terrain handling in missions using a distance sensor, even if this protocol is not supported and capability flag is not set.
::: info
A vehicle that supports this capability must also support terrain following in missions using the data.
Note however that a vehicle may also support terrain handling in missions using a distance sensor, even if this protocol is not supported and capability flag is not set.
:::
## Message/Enum Summary
| Message | Description |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="TERRAIN_REQUEST"></span>[TERRAIN_REQUEST](../messages/common.md#TERRAIN_REQUEST) | Request from drone (to GCS) for terrain data. The message specifies a mask indicating what tiles are required, and the GCS responds by sending [TERRAIN_DATA](#TERRAIN_DATA) for each tile. The drone will also stream [TERRAIN_REPORT](#TERRAIN_REPORT) messages to provide progress updates while it is waiting for data. |
| <span id="TERRAIN_DATA"></span>[TERRAIN_DATA](../messages/common.md#TERRAIN_DATA) | Terrain data from GCS for a particular tile (sent in response to a [TERRAIN_REQUEST](#TERRAIN_REQUEST)). The `lat`/`lon` and `grid_spacing` must be the same as the `lat`/`lon` from a [TERRAIN_REQUEST](#TERRAIN_REQUEST). |
| <span id="TERRAIN_REPORT"></span>[TERRAIN_REPORT](../messages/common.md#TERRAIN_REPORT) | The drone will stream `TERRAIN_REPORT` to indicate progress of terrain download, and in response to a [TERRAIN_CHECK](#TERRAIN_CHECK). |
| <span id="TERRAIN_CHECK"></span>[TERRAIN_CHECK](../messages/common.md#TERRAIN_CHECK) | Request that the vehicle report terrain height at the given location (expected response is a [TERRAIN_REPORT](#TERRAIN_REPORT)). Used by GCS to check if vehicle has all terrain data needed for a mission. |
| Message | Description |
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="TERRAIN_REQUEST"></a>[TERRAIN_REQUEST](../messages/common.md#TERRAIN_REQUEST) | Request from drone (to GCS) for terrain data. The message specifies a mask indicating what tiles are required, and the GCS responds by sending [TERRAIN_DATA](#TERRAIN_DATA) for each tile. The drone will also stream [TERRAIN_REPORT](#TERRAIN_REPORT) messages to provide progress updates while it is waiting for data. |
| <a id="TERRAIN_DATA"></a>[TERRAIN_DATA](../messages/common.md#TERRAIN_DATA) | Terrain data from GCS for a particular tile (sent in response to a [TERRAIN_REQUEST](#TERRAIN_REQUEST)). The `lat`/`lon` and `grid_spacing` must be the same as the `lat`/`lon` from a [TERRAIN_REQUEST](#TERRAIN_REQUEST). |
| <a id="TERRAIN_REPORT"></a>[TERRAIN_REPORT](../messages/common.md#TERRAIN_REPORT) | The drone will stream `TERRAIN_REPORT` to indicate progress of terrain download, and in response to a [TERRAIN_CHECK](#TERRAIN_CHECK). |
| <a id="TERRAIN_CHECK"></a>[TERRAIN_CHECK](../messages/common.md#TERRAIN_CHECK) | Request that the vehicle report terrain height at the given location (expected response is a [TERRAIN_REPORT](#TERRAIN_REPORT)). Used by GCS to check if vehicle has all terrain data needed for a mission. |
## Sequences
@@ -60,5 +61,6 @@ In summary, the sequence is:
If it does not have tile information for the specified location, then the request is ignored.
1. GCS can verify that the terrain report matches a terrain check by comparing the latitude/longitude fields for both messages.
> [!NOTE]
> The protocol does not define how the ground station handles the case if no `TERRAIN_REPORT` is received (although it might resend the request after a timeout).
::: info
The protocol does not define how the ground station handles the case if no `TERRAIN_REPORT` is received (although it might resend the request after a timeout).
:::
en/services/timesync.md
+15 -11
View File
@@ -9,8 +9,9 @@ The original system can use this information to determine the round-trip time, a
This sequence is run multiple times and filtered/averaged to reduce the transient effects of the channel and processor usage on the offset calculation.
> [!NOTE]
> This version replaces [Time Synchronization Protocol v1](#time-synchronization-protocol-v1).
::: info
This version replaces [Time Synchronization Protocol v1](#time-synchronization-protocol-v1).
:::
## Message/Enum Summary
@@ -34,10 +35,11 @@ The sequence is:
- determine the round trip time (by comparing its current timestamp with the original stamp that was returned in the message in `ts1`).
- estimate the offset between system timestamps, using the round trip time and the timestamp sent back by the remote system.
> [!NOTE]
> `TIMESYNC` responses to the broadcast address indicate that the remote system supports [Time Synchronization Protocol v1](#time-synchronization-protocol-v1).
> Synchronization may be unreliable if there are multiple sychronising components on the network (report/log an error and upgrade the remote system).
> The component should ignore responses to all other addresses.
::: info
TIMESYNC` responses to the broadcast address indicate that the remote system supports [Time Synchronization Protocol v1](#time-synchronization-protocol-v1).
Synchronization may be unreliable if there are multiple synchronising components on the network (report/log an error and upgrade the remote system).
The component should ignore responses to all other addresses.
:::
The offset is an estimate because the time spent, both inbound and outbound, will change over time based on things like link congestion and processing time.
Therefore the above sequence might be run a significant number of times, and filtering used to remove outlying estimates.
@@ -53,12 +55,14 @@ Version 1 of the timesync protocol uses the same message and sequences as versio
The difference is the `TIMESYNC` message in version 1 did not have `target_system` and `target_component` fields, and so the message was always broadcast.
This could result in unreliable timesync if there are multiple synchronizing components on the network, because there is no way for a component to know whether a `TIMESYNC` response is to its request.
> [!NOTE]
> ArduPilot encodes the system id in `TIMESYNC.ts1` of the request.
> This allows filtering of the response to a particular system (but not component), reducing the risk of clashes.
::: info
ArduPilot encodes the system id in `TIMESYNC.ts1` of the request.
This allows filtering of the response to a particular system (but not component), reducing the risk of clashes.
:::
> [!NOTE]
> Version 2 makes adds the target address, so a syncing system can filter on just the responses to its requests.
::: info
Version 2 makes adds the target address, so a syncing system can filter on just the responses to its requests.
:::
## Implementations
en/services/traffic_management.md
+7 -5
View File
@@ -13,16 +13,18 @@ There are two main traffic management systems supported by MAVLink:
- [Unmanned Aircraft System Traffic Management (UTM)](https://www.faa.gov/uas/research_development/traffic_management/) - an avoidance system focussing on UAVs.
- [Automatic Dependent Surveillance–Broadcast (ADS-B](https://en.wikipedia.org/wiki/Automatic_Dependent_Surveillance%E2%80%93Broadcast) - an avoidance system developed for manned aircraft and extended to UAVs.
> [!NOTE]
> FLARM is a transponder-based system that integrates with MAVLink using the ADS-B messages.
::: info
FLARM is a transponder-based system that integrates with MAVLink using the ADS-B messages.
:::
The two systems share significant overlap and have very similar messages.
Both have a single message that encapsulates the vehicle position and trajectory: [UTM_GLOBAL_POSITION](#UTM_GLOBAL_POSITION) and [ADSB_VEHICLE](#ADSB_VEHICLE).
A flight controller will typically recieve these messages from the appropriate transponder or service, and may also publish them to a transponder or service.
> [!NOTE]
> The [Open Drone ID](https://mavlink.io/en/services/opendroneid.html) service provides additional information about vehicle identity.
> This is still a "work in progress", and there are no known MAVLink implementations,
::: info
The [Open Drone ID](https://mavlink.io/en/services/opendroneid.html) service provides additional information about vehicle identity.
This is still a "work in progress", and there are no known MAVLink implementations,
:::
## Message/Enum Summary
en/services/trajectory.md
+3 -2
View File
@@ -23,8 +23,9 @@ sequenceDiagram;
When path planning is active, autopilots are expected to navigate using the most recent setpoint from the companion computer (and should have sensible behaviour if setpoints "run out").
> [!NOTE]
> The path planning system might send setpoints all the time, or only when a desired trajectory cannot be achieved (this depends on the specific service implementation).
::: info
The path planning system might send setpoints all the time, or only when a desired trajectory cannot be achieved (this depends on the specific service implementation).
:::
The protocol defines two messages:
en/services/tunnel.md
+13 -11
View File
@@ -2,9 +2,10 @@
The _Tunnel Protocol_ allows MAVLink to be used as a "dumb channel" to pass data in any format across, through or into a MAVLink network.
> [!WARNING]
> **Tunnels use is highly discouraged**, as they lose most of the benefits of MAVLink in terms of efficiently and interoperability.
> You should almost always create "dedicated" MAVLink messages for communicating in a MAVLink system.
::: warning
**Tunnels use is highly discouraged**, as they lose most of the benefits of MAVLink in terms of efficiently and interoperability.
You should almost always create "dedicated" MAVLink messages for communicating in a MAVLink system.
:::
An example where this protocol is useful is connecting a _STorM32 gimbal_ to a computer for configuration/debugging (via a USB connection to the autopilot and using MAVLink to carry the native serial protocol between it and the gimbal).
Normally you would connect the gimbal directly via USB, but when mounted on the drone the gimbal USB port may be hard to access.
@@ -18,21 +19,22 @@ For wider distribution they should [register the payload type](#register).
## Message/Enum Summary
| Message | Description |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="TUNNEL"></span>[TUNNEL](../messages/common.md#TUNNEL) | Message for transporting "arbitrary" variable-length data from one component to another (broadcast is not forbidden, but discouraged). |
| Message | Description |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="TUNNEL"></a>[TUNNEL](../messages/common.md#TUNNEL) | Message for transporting "arbitrary" variable-length data from one component to another (broadcast is not forbidden, but discouraged). |
| Enum | Description |
| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="MAV_TUNNEL_PAYLOAD_TYPE"></span>[MAV_TUNNEL_PAYLOAD_TYPE](../messages/common.md#MAV_TUNNEL_PAYLOAD_TYPE) | A code that identifies the format of the payload (0 for unknown, which is the default). You can use any value over 32768 for on private networks or [register a payload type](#register). |
| Enum | Description |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="MAV_TUNNEL_PAYLOAD_TYPE"></a>[MAV_TUNNEL_PAYLOAD_TYPE](../messages/common.md#MAV_TUNNEL_PAYLOAD_TYPE) | A code that identifies the format of the payload (0 for unknown, which is the default). You can use any value over 32768 for on private networks or [register a payload type](#register). |
## Register a Payload Type {#register}
The format of the tunnel message data is indicated by the value of `TUNNEL.payload_type`.
Vendors can register their own formats in [MAV_TUNNEL_PAYLOAD_TYPE](#MAV_TUNNEL_PAYLOAD_TYPE) by creating a PR to update the enum in [common.xml](https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/common.xml).
> [!TIP]
> If you register an enum value in **common.xml** the MAVLink toolchain will generate an error if other dialect attempts to define the same value (if the dialect includes **common.xml**).
::: tip
If you register an enum value in **common.xml** the MAVLink toolchain will generate an error if other dialect attempts to define the same value (if the dialect includes **common.xml**).
:::
The rules for adding new `MAV_TUNNEL_PAYLOAD_TYPE` values are: