mirror of
https://github.com/mavlink/mavlink-devguide.git
synced 2026-06-19 07:36:26 +00:00
Spelling and grammar plus a few link fixes (#676)
This commit is contained in:
Hamish Willee
+1
-1
@@ -72,6 +72,6 @@
|
||||
<dt>How can I further reduce the generated C library size?</dt>
|
||||
<dd>On extremely resource-constrained systems you may be able to reduce the size of the generated library by setting <code>MAVLINK_COMM_NUM_BUFFERS=1</code> and <code>MAVLINK_MAX_PAYLOAD_LEN</code>="size of your largest buffer" (assuming only one comm link and that your payload is less than the maximum supported by MAVLink).
|
||||
You should also make sure that any buffers you use to pass into MAVLink are also as small as possible (e.g. the one passed into <code>mavlink_msg_to_send_buffer()</code>).
|
||||
<br><br>Another alternative is to use one of the other generators. For example <a href="https://github.com/olliw42/fastmavlink">fastMavlink</a> asserts that it is smaller and more efficient than the libraries generated by mavgen (this has not been valided by the MAVLink project).</dd>
|
||||
<br><br>Another alternative is to use one of the other generators. For example <a href="https://github.com/olliw42/fastmavlink">fastMavlink</a> asserts that it is smaller and more efficient than the libraries generated by mavgen (this has not been validated by the MAVLink project).</dd>
|
||||
|
||||
</dl>
|
||||
|
||||
@@ -28,7 +28,7 @@ The sections below explain how to contribute to each category and how to raise a
|
||||
Changes to the [mavgen](../getting_started/generate_libraries.md#mavgen) generator must be added as pull requests through the [ArduPilot/pymavlink](https://github.com/ArduPilot/pymavlink) project.
|
||||
|
||||
Changes to existing generator code (e.g. bug fixes) are automatically tested by continuous integration (github actions).
|
||||
Once you have made against your PR pass, the changes will be reviewed by a project team member.
|
||||
Once you have made your PR pass, the changes will be reviewed by a project team member.
|
||||
|
||||
More significant changes to the generator, such as the addition of a new programming language, will require:
|
||||
|
||||
@@ -47,14 +47,14 @@ Ideally:
|
||||
|
||||
## How to Contribute Stand Alone Generators
|
||||
|
||||
We would prefer that new languages are supported via [mavgen](../getting_started/generate_libraries.md#mavgen) rather than "standalone generators", as this provides a consistent inteface for end users, and ensures that source files are parsed and handled consistently.
|
||||
We would prefer that new languages are supported via [mavgen](../getting_started/generate_libraries.md#mavgen) rather than "standalone generators", as this provides a consistent interface for end users, and ensures that source files are parsed and handled consistently.
|
||||
|
||||
That said will consider moving stand-alone generators into the MAVLink project under the same conditions as for new mavgen generator code (see section above).
|
||||
Primarily this means that the team developing the generator must provide sufficient validation that the generator works and commitment to support it.
|
||||
|
||||
## How to Open a Pull Request
|
||||
|
||||
1. First [fork and clone](https://help.github.com/articles/fork-a-repo) the project project.
|
||||
1. First [fork and clone](https://help.github.com/articles/fork-a-repo) the project.
|
||||
2. Create a feature branch off master
|
||||
|
||||
```
|
||||
|
||||
@@ -16,7 +16,7 @@ _QGroundControl_ and many other GCS support an older plain-text format for missi
|
||||
This is not officially part of MAVLink and does not allow rally point or geofence information to be provided.
|
||||
|
||||
The format is shown below.
|
||||
The first line contains the file format and version information, while subsequent the line(s) are mission items.
|
||||
The first line contains the file format and version information, while subsequent line(s) are mission items.
|
||||
|
||||
```
|
||||
QGC WPL <VERSION>
|
||||
|
||||
@@ -20,7 +20,7 @@ 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).
|
||||
1. If you are generating messages for a [custom dialect](../messages/dialects.md), 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).
|
||||
|
||||
::: 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.
|
||||
@@ -88,7 +88,7 @@ python3 -m pymavlink.tools.mavgen --lang=C --wire-protocol=2.0 --output=generate
|
||||
```
|
||||
|
||||
::: info
|
||||
The syntax for for generating Python modules is the same, except that the `--output` specifies a _filename_ rather than a directory.
|
||||
The syntax 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 -->
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Installing MAVLink Toolchain
|
||||
|
||||
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).
|
||||
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 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).
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@ MAVLink services that need to use a Cyclic Redundancy Check (CRC) should choose
|
||||
|
||||
::: 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.
|
||||
Do not introduce another unless there is a compelling technical reason.
|
||||
:::
|
||||
|
||||
::: info
|
||||
|
||||
@@ -171,7 +171,7 @@ Messages must be declared between the `<messages></messages>` tags in either **c
|
||||
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.
|
||||
The 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:
|
||||
@@ -250,7 +250,7 @@ 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.
|
||||
Before proposing changes to **common.xml** check the codebase of major stakeholders to confirm impact.
|
||||
:::
|
||||
|
||||
It is possible to change the message and field descriptions without breaking binary compatibility.
|
||||
@@ -406,7 +406,7 @@ 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.
|
||||
Before proposing changes to **common.xml** check the codebase of major stakeholders to confirm impact.
|
||||
:::
|
||||
|
||||
For an enum in **common.xml** either change requires the agreement of major stakeholders
|
||||
@@ -473,7 +473,7 @@ If you are creating a new public dialect, [create an issue](https://github.com/m
|
||||
:::
|
||||
|
||||
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.
|
||||
Generally you would only use these ranges in order to give a new command an id that is close to related to that of related commands.
|
||||
This can be done provided that the command id value is not used by any other XML file in the _mavlink/mavlink_ repo.
|
||||
|
||||
### Entry Names {#command_names}
|
||||
@@ -524,7 +524,7 @@ If the param is reused the original default value must still mean "no action", s
|
||||
|
||||
::: 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.
|
||||
The default value cannot later be changed from `NaN` to `0` (or vice versa) without potential compatibility issues.
|
||||
:::
|
||||
|
||||
To declare a `param` as `reserved` with `default` value of `NaN` you should use the following syntax.
|
||||
|
||||
@@ -13,7 +13,7 @@ The key new features of _MAVLink 2_ are:
|
||||
- [Packet signing](../guide/message_signing.md) - Authenticate that messages were sent by trusted systems.
|
||||
- [Message extensions](../guide/define_xml_element.md#message_extensions) - Add new fields to existing MAVLink message definitions without breaking binary compatibility for receivers that have not updated.
|
||||
- [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).
|
||||
- [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 flag 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.
|
||||
|
||||
@@ -10,7 +10,7 @@ The _MAVLink 2.0_ C/C++ and Python libraries are backwards compatible with MAVLi
|
||||
|
||||
::: info
|
||||
_MAVLink v0.9_ is a pre-release version that is no longer supported.
|
||||
The associated message set deleted in August 2018.
|
||||
The associated message set was deleted in August 2018.
|
||||
Legacy code may be present in generator and test code.
|
||||
:::
|
||||
|
||||
@@ -50,7 +50,7 @@ This is reasonable because the majority of systems and communication links now r
|
||||
Most flight stacks assume communication links are transparent.
|
||||
Possible causes of links not being transparent are:
|
||||
|
||||
- Routing, which can can change or reserialize MAVLink packets (for example, there might be an intermediate router that converts between versions).
|
||||
- Routing, which can change or reserialize MAVLink packets (for example, there might be an intermediate router that converts between versions).
|
||||
- Wireless links that rely on fixed length packetization may distort or truncate variable-length MAVLink 2 frames.
|
||||
For example, older SiK Radios may consume MAVLink 2 messages.
|
||||
|
||||
|
||||
@@ -13,15 +13,15 @@ More detailed information for developers using existing MAVLink libraries can be
|
||||
|
||||
## Frame Format
|
||||
|
||||
For a signed packet the **0x01** bit of the [incompatibility flag field](../guide/mavlink_2.md#incompat_flags) is set true and an additional 13 bytes of "signature" data appended to the packet.
|
||||
For a signed packet the **0x01** bit of the [incompatibility flag field](../guide/serialization.md#incompat_flags) is set true and an additional 13 bytes of "signature" data appended to the packet.
|
||||
The signed packet format is shown below.
|
||||
|
||||
|
||||
|
||||
::: 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.
|
||||
The [incompatibility flags](../guide/serialization.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 C library uses [MAVLINK_IFLAG_SIGNED](../guide/serialization.md#MAVLINK_IFLAG_SIGNED) to represent the "supports message signing" bit.
|
||||
:::
|
||||
|
||||
The 13 bytes of the signature are:
|
||||
@@ -29,7 +29,7 @@ The 13 bytes of the signature are:
|
||||
| Data | Description |
|
||||
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [linkID](#link_ids) (8 bits) | ID of link on which packet is sent. Normally this is the same as the _channel_. |
|
||||
| [timestamp](#timestamps) (48 bits) | Timestamp in 10 microsecond units since 1st January 2015 GMT time. This _must_ monotonically increase for every message on a particular [link](#link_ids). Note that means the timestamp may get ahead of the actual time if the packet rate averages more than 100,000 packets per second. |
|
||||
| [timestamp](#timestamp) (48 bits) | Timestamp in 10 microsecond units since 1st January 2015 GMT time. This _must_ monotonically increase for every message on a particular [link](#link_ids). Note that means the timestamp may get ahead of the actual time if the packet rate averages more than 100,000 packets per second. |
|
||||
| [signature](#signature) (48 bits) | A 48 bit signature for the packet, based on the complete packet, timestamp, and secret key. |
|
||||
|
||||
See below for more information about the fields.
|
||||
@@ -154,7 +154,7 @@ The secret key may be shared to other devices using the [SETUP_SIGNING](../messa
|
||||
The message should only ever be sent over a secure link (e.g. USB or wired Ethernet) as a direct message to each connected `system_id`/`component_id`.
|
||||
The receiving system must be set up to process the message and store the received secret key to the appropriate permanent storage.
|
||||
|
||||
The same secure method can be used to both _set_ and _reset_ a system's key (reseting a key does not have to be "more secure" than setting it in the first place).
|
||||
The same secure method can be used to both _set_ and _reset_ a system's key (resetting a key does not have to be "more secure" than setting it in the first place).
|
||||
|
||||
The `SETUP_SIGNING` message should never be broadcast, and received `SETUP_SIGNING` messages must never be automatically forwarded to other active MAVLink devices/streams/channels.
|
||||
This is to avoid the case where a key received over a secure link (e.g. USB) is automatically forwarded to another system over an insecure link (e.g. Wifi).
|
||||
@@ -170,7 +170,7 @@ The receiving system may be configured to ignore message signatures on the secur
|
||||
|
||||
In order to avoid leaking the secret key used for signing, systems should omit [SETUP_SIGNING](../messages/common.md#SETUP_SIGNING) messages from logs (or replace the secret with 32 0xFF bytes in the logged message).
|
||||
|
||||
Similarly, signed packets should have the signature [incompatibility bit](../guide/mavlink_2.md#incompat_flags) cleared and the signature block removed before being put into telemetry log files.
|
||||
Similarly, signed packets should have the signature [incompatibility bit](../guide/serialization.md#incompat_flags) cleared and the signature block removed before being put into telemetry log files.
|
||||
This makes it harder for potential attacker to collect large amounts of signature data with which to attack the system.
|
||||
|
||||
## Further Information
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Packet Loss Calculation
|
||||
|
||||
MAVLink packet loss is calculated from the packet sequence number, an 8 bit field that is incremented each time a message is emitted on a channel.
|
||||
The recipient of the message can track the last recieved/next expected sequence number, and if a packet sequence number is bigger than expected, any intermediate packets between the sequence numbers are assumed to have been lost.
|
||||
The recipient of the message can track the last received/next expected sequence number, and if a packet sequence number is bigger than expected, any intermediate packets between the sequence numbers are assumed to have been lost.
|
||||
The sequence number will wrap around at 255, and the recipient is expected to compensate for this.
|
||||
|
||||
This approach works if all messages sent on a channel are routed to the system calculating packet loss, and if messages from only one channel are received by the system calculating packet loss.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Packet Serialization
|
||||
|
||||
This topic provides detailed information about about MAVLink packet serialization, including the over-the-wire formats for MAVLink v1 and v2 packets, the ordering of fields in the message payload, and the `CRC_EXTRA` used for ensuring that the sender and reciever share a compatible message definition.
|
||||
This topic provides detailed information about MAVLink packet serialization, including the over-the-wire formats for MAVLink v1 and v2 packets, the ordering of fields in the message payload, and the `CRC_EXTRA` used for ensuring that the sender and receiver share a compatible message definition.
|
||||
|
||||
It is primarily intended for developers who are creating/maintaining a MAVLink generator
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ The benefits of using _Wireshark_ over other alternatives are:
|
||||
- it can view _all_ traffic on a network interface (GCS tools like [MAVLink Inspector](https://docs.qgroundcontrol.com/master/en/analyze_view/mavlink_inspector.html) often only analyse incoming traffic).
|
||||
- you can use it to analyse traffic logged on a companion computer (this allows analysis of traffic between the companion computer and flight controller, which might otherwise not be visible to _Wireshark_).
|
||||
- it is easy to update for new custom messages and dialects.
|
||||
Rebuilding _QGroundControl_ so you can use it analyse custom messages is much harder!
|
||||
Rebuilding _QGroundControl_ so you can use it to analyse custom messages is much harder!
|
||||
|
||||
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).
|
||||
@@ -24,7 +24,7 @@ The MAVLink generator (**mavgen**) can build this plugin for a dialect in the sa
|
||||
The steps are:
|
||||
|
||||
1. [Install MAVLink](../getting_started/installation.md) (if you have not already done so).
|
||||
1. Build libraries for your target dialect, specifing `WLua` as the target language.
|
||||
1. Build libraries for your target dialect, specifying `WLua` as the target language.
|
||||
This process is described in the topic [Generate MAVLink Libraries](../getting_started/generate_libraries.md).
|
||||
|
||||
For example, to build the MAVLink 2 Wireshark plugin for [common.xml](../messages/common.md) you might use the following command:
|
||||
@@ -58,7 +58,7 @@ This might be necessary, for example, in order to monitor traffic recorded on th
|
||||
|
||||
To import the plugin into _Wireshark_:
|
||||
|
||||
1. Copy the plugin file into the wireshare plugins directory.
|
||||
1. Copy the plugin file into the wireshark plugins directory.
|
||||
- On Linux systems this might be: `~/.local/lib/wireshark/plugins` (or `~/.wireshark/plugins` for older versions of Wireshark).
|
||||
Note that users will need to be added to the `wireshark` group to use the tool.)
|
||||
- On Windows this might be: `Program Files/Wireshark/plugins`.
|
||||
|
||||
+15
-9
@@ -100,7 +100,7 @@ The values are defined in nested [`<entry>`](#entry) elements.
|
||||
Attributes:
|
||||
|
||||
- `name` (required): The name of the enum. This is a string of capitalized, underscore-separated words.
|
||||
- `bitmask` (optional): Set to `true` for enums that defines entries with values that increase by a power of 2, such as flags.
|
||||
- `bitmask` (optional): Set to `true` for enums that define entries with values that increase by a power of 2, such as flags.
|
||||
|
||||
Nested elements:
|
||||
|
||||
@@ -279,7 +279,13 @@ Nested elements:
|
||||
The field value is its name/text string used in GUI documentation (but not sent over the wire).
|
||||
Every message must have at least one field.
|
||||
- `<extensions />` (optional): This self-closing tag is used to indicate that subsequent fields apply to MAVLink 2 only.
|
||||
- The tag should be used for MAVLink 1 messages only (id < 256) that have been extended in MAVLink 2.
|
||||
|
||||
### `<extensions />` element {#extensions}
|
||||
|
||||
A self-closing tag that indicates that subsequent fields apply to MAVLink 2 only.
|
||||
|
||||
This should only be used if a message needs new fields after it is already published.
|
||||
New messages are preferred as extensions are not part of the CRC check, and can hence lead to undetectable incompatibilities.
|
||||
|
||||
### `<field>` element {#field}
|
||||
|
||||
@@ -290,7 +296,7 @@ The field inner content text string is used in GUI documentation (but not sent o
|
||||
Attributes:
|
||||
|
||||
- `type`: Similar to a field in a C `struct` - the size of the data required to store/represent the data type.
|
||||
- Fields can be signed/unsigned integers of size 8, 16, 23, 64 bits (`{u)int8_t`, `(u)int16_t`, `(u)int32_t`, `(u)int64_t`), single/double precision IEEE754 floating point numbers.
|
||||
- Fields can be signed/unsigned integers of size 8, 16, 32, 64 bits (`{u)int8_t`, `(u)int16_t`, `(u)int32_t`, `(u)int64_t`), single/double precision IEEE754 floating point numbers.
|
||||
They can also be arrays of the other types - e.g. `uint16_t[10]`.
|
||||
- `name`: Name of the field (used in code).
|
||||
- [enum](#enum) (optional): Name of an `enum` defining possible values of the field (e.g. `MAV_BATTERY_CHARGE_STATE`).
|
||||
@@ -308,13 +314,13 @@ Attributes:
|
||||
- `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`.
|
||||
|
||||
::: info
|
||||
This field allows a recipient automatically associate messages for a particular sensor and plot them in the same series.
|
||||
This field allows a recipient to 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`.
|
||||
|
||||
Where possible the value that indicates the field is invalid should be selected to outside the expected/valid range of the eld (`0` is preferred if it is not an acceptable value for the field).
|
||||
Where possible the value that indicates the field is invalid should be selected to outside the expected/valid range of the field (`0` is preferred if it is not an acceptable value for the field).
|
||||
For integers we usually select the largest possible value (i.e. `UINT16_MAX`, `INT16_MAX`, `UINT8_MAX`, `UINT8_MAX`).
|
||||
For floats we usually select `invalid="NaN"`.
|
||||
|
||||
@@ -347,7 +353,7 @@ They should not be included in release builds.
|
||||
The generator toolchain can be configured to conditionally build messages omitting the `<wip>` entries.
|
||||
|
||||
Generally new elements should be defined in `development.xml`, and any definitions in that file are considered WIP by default.
|
||||
The `wip` element is intended primiarly for indicating WIP additions to `common.xml` that for whatever reason could not be added to `development.xml`.
|
||||
The `wip` element is intended primarily for indicating WIP additions to `common.xml` that for whatever reason could not be added to `development.xml`.
|
||||
|
||||
Once the associated definition has been tested, it may be accepted into `common.xml` and the `<wip>` tag removed.
|
||||
|
||||
@@ -362,7 +368,7 @@ Attributes:
|
||||
|
||||
- `since` (optional): A datestamp indicating when the corresponding element was proposed.
|
||||
This should be formatted as such as `YYYYMM`
|
||||
This hints to the maintainter team when WIP elements should be reviewed for addition or removal.
|
||||
This hints to the maintainer team when WIP elements should be reviewed for addition or removal.
|
||||
|
||||
Nested elements
|
||||
|
||||
@@ -385,7 +391,7 @@ Attributes:
|
||||
|
||||
- `since` (required): A datestamp indicating when the new element was accepted into files managed by the MAVLink team.
|
||||
This should be formatted as such as `YYYY-MM`.
|
||||
- `replaced_by` (required): The name of the definition that supersedes this elements.
|
||||
- `replaced_by` (required): The name of the definition that supersedes this element.
|
||||
|
||||
Nested elements
|
||||
|
||||
@@ -394,7 +400,7 @@ Nested elements
|
||||
### `<deprecated>` element {#deprecated}
|
||||
|
||||
The `<deprecated>` element is used to indicate when an element should not be used because it is on the path for removal from the standard.
|
||||
Often by the time and element is deprecated it has already been removed from current releases of the main flight stacks.
|
||||
Often by the time an element is deprecated it has already been removed from current releases of the main flight stacks.
|
||||
|
||||
The attributes indicates the time of deprecation and the replacement element, and may also include the intended date of removal.
|
||||
The content of the element may (optionally) contain a string with additional information about the planned removal and alternative definitions.
|
||||
|
||||
+1
-1
@@ -31,7 +31,7 @@ MAVLink was first released early 2009 by Lorenz Meier and has now a [significant
|
||||
|
||||
## Language/Generator List {#supported_languages}
|
||||
|
||||
The sections below lists MAVLink generators and their associated programming languages.
|
||||
The sections below list MAVLink generators and their associated programming languages.
|
||||
|
||||
### MAVLink Project Generators/Languages
|
||||
|
||||
|
||||
@@ -85,7 +85,7 @@ mavlink/common/../mavlink_helpers.h:86:24: warning: taking address of packed mem
|
||||
```
|
||||
|
||||
The warning indicates the potential for hard faults caused by unaligned access to packed data.
|
||||
This does not happen on most of the common architectures on which MAVLink is run, and generally the warning can be supressed.
|
||||
This does not happen on most of the common architectures on which MAVLink is run, and generally the warning can be suppressed.
|
||||
|
||||
You can suppress the warnings using `-Wno-address-of-packed-member`.
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ A system can request that additional messages are sent as a stream, or change th
|
||||
A single instance of a message can be requested by sending [MAV_CMD_REQUEST_MESSAGE](../messages/common.md#MAV_CMD_REQUEST_MESSAGE).
|
||||
|
||||
The example below shows how you can request the [BATTERY_STATUS](../messages/common.md#BATTERY_STATUS) message is streamed at the rate of 1Hz, by sending `MAV_CMD_SET_MESSAGE_INTERVAL` in a [COMMAND_LONG](../messages/common.md#COMMAND_LONG).
|
||||
Because this is a command, we then wait for a `COMMAND_ACK` to be recieved with the matching command id, and then display the result.
|
||||
Because this is a command, we then wait for a `COMMAND_ACK` to be received with the matching command id, and then display the result.
|
||||
Note that you could equally well send the command in a [COMMAND_INT](../messages/common.md#COMMAND_INT), if supported by the flight stack.
|
||||
|
||||
```python
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Arm Authorization
|
||||
|
||||
When enabled by setting a parameter on flight stack, the drone will only arm the motors if authorized by a external entity.
|
||||
When enabled by setting a parameter on the flight stack, the drone will only arm the motors if authorized by a external entity.
|
||||
This external entity is responsible for requesting any information that it needs from the drone and from other sources (example: weather) and whether (or not) to authorize the arming procedure.
|
||||
|
||||
This is required to comply with [NASA UTM](https://utm.arc.nasa.gov/), but may also be useful for private companies.
|
||||
@@ -25,7 +25,7 @@ sequenceDiagram;
|
||||
Drone->>Remote control/QCS: QCS COMMAND_ACK command=MAV_CMD_COMPONENT_ARM_DISARM result=ACCEPTED, TEMPORARILY_REJECTED or DENIED
|
||||
-->
|
||||
|
||||
In case the authorizer need a lot of time to get and process the information is better have another authorization flow to avoid arm the drone at unexpected time.
|
||||
In case the authorizer needs a lot of time to get and process the information is better have another authorization flow to avoid arm the drone at unexpected time.
|
||||
|
||||
[](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtO1xuICAgIHBhcnRpY2lwYW50IERyb25lXG4gICAgcGFydGljaXBhbnQgUmVtb3RlIGNvbnRyb2wvUUNTXG4gICAgcGFydGljaXBhbnQgQXJtIGF1dGhvcml6ZXJcbiAgICBwYXJ0aWNpcGFudCBJbnRlcm5ldFxuXG4gICAgUmVtb3RlIGNvbnRyb2wvUUNTLT4-RHJvbmU6IFJlcXVlc3QgYXJtMVxuICAgIERyb25lLT4-UmVtb3RlIGNvbnRyb2wvUUNTOiBRQ1MgQ09NTUFORF9BQ0sgcmVzdWx0PVRFTVBPUkFSSUxZX1JFSkVDVEVEXG4gICAgRHJvbmUtPj5Bcm0gYXV0aG9yaXplcjogQ09NTUFORF9MT05HIGNvbW1hbmQ9TUFWX0NNRF9BUk1fQVVUSE9SSVpBVElPTl9SRVFVRVNUXG4gICAgQXJtIGF1dGhvcml6ZXItPj5Ecm9uZTogQ09NTUFORF9BQ0sgcmVzdWx0PU1BVl9SRVNVTFRfSU5fUFJPR1JFU1NcbiAgICBBcm0gYXV0aG9yaXplci0-PkRyb25lOiAob3B0aW9uYWwpUmVxdWVzdCBpbmZvcm1hdGlvbiBhYm91dCBtaXNzaW9uLCBiYXR0ZXJ5IGxldmVsIGFuZCBldGMuXG4gICAgQXJtIGF1dGhvcml6ZXItPj5JbnRlcm5ldDogKG9wdGlvbmFsKVJlcXVlc3QgaW5mb3JtYXRpb24gYWJvdXQgd2VhdGhlciwgYWVyb3NwYWNlIHRyYWZpYyBhbmQgZXRjLlxuICAgIEFybSBhdXRob3JpemVyLT4-RHJvbmU6IENPTU1BTkRfQUNLIGNvbW1hbmQ9TUFWX0NNRF9BUk1fQVVUSE9SSVpBVElPTl9SRVFVRVNUIHJlc3VsdD1BQ0NFUFRFRCwgVEVNUE9SQVJJTFlfUkVKRUNURUQgb3IgREVOSUVEXG4gICAgRHJvbmUtPj5SZW1vdGUgY29udHJvbC9RQ1M6IFFDUyBTVEFUVVNURVhUIHRleHQ9QXJtIGF1dGhvcml6YXRpb24gd2FzIGFwcHJvdmVkIG9yIGRlbmllZFxuXG4gICAgUmVtb3RlIGNvbnRyb2wvUUNTLT4-RHJvbmU6IFJlcXVlc3QgYXJtMlxuICAgIERyb25lLT4-UmVtb3RlIGNvbnRyb2wvUUNTOiBRQ1MgQ09NTUFORF9BQ0sgY29tbWFuZD1NQVZfQ01EX0NPTVBPTkVOVF9BUk1fRElTQVJNIHJlc3VsdD1BQ0NFUFRFRCwgVEVNUE9SQVJJTFlfUkVKRUNURUQgb3IgREVOSUVEIiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0)
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ MAVLink provides a number of messages for providing battery information:
|
||||
- Some batteries may provide [fault](#MAV_BATTERY_FAULT) and [mode](#MAV_BATTERY_MODE) information in this message.
|
||||
|
||||
::: info
|
||||
`BATTERY_STATUS` is expected to be superseded by [BATTERY_STATUS_V2](../messages/development.html#BATTERY_STATUS_V2).
|
||||
`BATTERY_STATUS` is expected to be superseded by [BATTERY_STATUS_V2](../messages/development.md#BATTERY_STATUS_V2).
|
||||
For more information see [RFC 0018 - Improved Battery Status Reporting](https://github.com/mavlink/rfcs/pull/19).
|
||||
:::
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ The protocol can be used to control cameras attached to autopilot outputs or sta
|
||||
|
||||
## Standalone MAVLink cameras
|
||||
|
||||
A standalone MAVLink camera that needs to interact with a ground station must be able to send and recieve MAVLink messages from the ground station.
|
||||
A standalone MAVLink camera that needs to interact with a ground station must be able to send and receive MAVLink messages from the ground station.
|
||||
If the GCS and Camera are connected to the flight stack on different MAVLink channels then the flight stack will need to forward messages between them.
|
||||
|
||||
If the MAVLink camera does not emit the [CAMERA_TRIGGER](#CAMERA_TRIGGER) message on image capture then the flight stack may need to do this on its behalf.
|
||||
@@ -31,7 +31,7 @@ A GCS should address the commands to the autopilot component, which will need to
|
||||
The flight stack will also need to trigger the camera when the commands are found in a mission.
|
||||
|
||||
Note that a flight stack implementation can generally trigger attached cameras and emit a MAVLink command in missions.
|
||||
If a connected camera and MAVLink camera are connected, both with be triggered.
|
||||
If a connected camera and MAVLink camera are connected, both will be triggered.
|
||||
|
||||
## Message/Command Summary
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ If no acknowledgement is received the command must be automatically re-sent.
|
||||
| Message | Description |
|
||||
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <a id="COMMAND_INT"></a>[COMMAND_INT](../messages/common.md#COMMAND_INT) | Message for encoding a command ([MAV_CMD](#MAV_CMD)). The message encodes commands into up to 7 parameters: parameters 1-4, 7 are floats, and parameters 5,6 are scaled integers. The scaled integers are used for positional information (scaling depends on the actual command value). The coordinate frame of positional parameters is explicitly specified in a frame field. Commands that require float-only properties in parameters 5, 6 cannot be sent in this message (e.g. commands where NaN has an explicit meaning). |
|
||||
| <a id="COMMAND_LONG"></a>[COMMAND_LONG](../messages/common.md#COMMAND_LONG) | Message for encoding a command ([MAV_CMD](#MAV_CMD)). The mesage encodes commands into up to 7 float parameters. The coordinate frame used for positional co-ordinates is implementation dependent. Any command may be packaged in this message, but there may be some loss of precision for positional co-ordinates (latitude, longitude). |
|
||||
| <a id="COMMAND_LONG"></a>[COMMAND_LONG](../messages/common.md#COMMAND_LONG) | Message for encoding a command ([MAV_CMD](#MAV_CMD)). The message encodes commands into up to 7 float parameters. The coordinate frame used for positional co-ordinates is implementation dependent. Any command may be packaged in this message, but there may be some loss of precision for positional co-ordinates (latitude, longitude). |
|
||||
| <a id="COMMAND_ACK"></a>[COMMAND_ACK](../messages/common.md#COMMAND_ACK) | Command acknowledgement. Includes result (success, failure, still in progress) and may include progress information and additional detail about failure reasons. |
|
||||
| <a id="COMMAND_CANCEL"></a>[COMMAND_CANCEL](../messages/common.md#COMMAND_CANCEL) | Cancel a long running command. |
|
||||
|
||||
@@ -85,8 +85,8 @@ sequenceDiagram;
|
||||
### Long Running Commands {#long_running_commands}
|
||||
|
||||
Some commands are _long running_, and cannot complete immediately.
|
||||
The drone reports its progress by sending `COMMMAND_ACK` messages with [COMMAND_ACK.result=MAV_RESULT_IN_PROGRESS](../messages/common.md#MAV_RESULT_IN_PROGRESS) and the progress as a percentage in `COMMMAND_ACK.progress` ([0-100] percent complete, 255 if progress not supplied).
|
||||
When the operation completes, the drone must terminate with a `COMMMAND_ACK` containing the final [result](#MAV_RESULT) of the operation: `MAV_RESULT_ACCEPTED`, `MAV_RESULT_FAILED`, `MAV_RESULT_CANCELLED`).
|
||||
The drone reports its progress by sending `COMMAND_ACK` messages with [COMMAND_ACK.result=MAV_RESULT_IN_PROGRESS](../messages/common.md#MAV_RESULT_IN_PROGRESS) and the progress as a percentage in `COMMAND_ACK.progress` ([0-100] percent complete, 255 if progress not supplied).
|
||||
When the operation completes, the drone must terminate with a `COMMAND_ACK` containing the final [result](#MAV_RESULT) of the operation: `MAV_RESULT_ACCEPTED`, `MAV_RESULT_FAILED`, `MAV_RESULT_CANCELLED`).
|
||||
|
||||
[](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtO1xuICAgIHBhcnRpY2lwYW50IEdDU1xuICAgIHBhcnRpY2lwYW50IERyb25lXG4gICAgR0NTLT4-RHJvbmU6IENPTU1BTkRfTE9ORygpXG4gICAgR0NTLT4-R0NTOiBTdGFydCB0aW1lb3V0XG4gICAgRHJvbmUtPj5HQ1M6IENPTU1BTkRfQUNLKHJlc3VsdD1NQVZfUkVTVUxUX0lOX1BST0dSRVNTLHByb2dyZXNzPT8pXG4gICAgR0NTLT4-R0NTOiBTdGFydCAobG9uZ2VyKSB0aW1lb3V0XG4gICAgRHJvbmUtPj5HQ1M6IENPTU1BTkRfQUNLKHJlc3VsdD1NQVZfUkVTVUxUX0lOX1BST0dSRVNTLHByb2dyZXNzPT8pXG4gICAgR0NTLT4-R0NTOiBTdGFydCAobG9uZ2VyKSB0aW1lb3V0XG4gICAgTm90ZSByaWdodCBvZiBHQ1M6IC4uLlxuICAgIERyb25lLT4-R0NTOiBDT01NQU5EX0FDSyhyZXN1bHQ9TUFWX1JFU1VMVF9BQ0NFUFRFRCkiLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)
|
||||
|
||||
@@ -116,9 +116,9 @@ Generally though, the GCS should have a much increased timeout after receiving a
|
||||
If a timeout is triggered when waiting for a progress or completion update, the GCS should terminate the sequence (return to the idle state) and notify the user if appropriate.
|
||||
|
||||
Only one instance of a _particular_ long running command can execute at a time; to restart a long running operation (i.e. with new parameters) it must first be cancelled!
|
||||
If the same command is recieved while the operation is in progress the new command should be ACKed with `MAV_RESULT_TEMPORARILY_REJECTED` (to indicate that the target is busy).
|
||||
If the same command is received while the operation is in progress the new command should be ACKed with `MAV_RESULT_TEMPORARILY_REJECTED` (to indicate that the target is busy).
|
||||
|
||||
The protocol allows for _different_ long running commands to run in parallel, if supported by the state machine of the recieving flight stack.
|
||||
The protocol allows for _different_ long running commands to run in parallel, if supported by the state machine of the receiving flight stack.
|
||||
If a flight stack does not support multiple commands running in parallel it should ACK new commands with `MAV_RESULT_TEMPORARILY_REJECTED` (with the possible exception of the [COMMAND_CANCEL](#COMMAND_CANCEL), which might be used to cancel the first request).
|
||||
|
||||
## Location Commands and Frame Types
|
||||
|
||||
@@ -30,7 +30,7 @@ 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. |
|
||||
|
||||
::: 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](../messages/common.md#COMPONENT_INFORMATION) is not used by this service (it is a deprecated legacy version of [COMPONENT_METADATA](../messages/common.md#COMPONENT_METADATA)).
|
||||
:::
|
||||
|
||||
## Component Information File Format (Schema) {#schema_files}
|
||||
@@ -42,7 +42,7 @@ The component information file types and schema are (at time of writing):
|
||||
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <a id="COMP_METADATA_TYPE_GENERAL"></a>General metadata | [COMP_METADATA_TYPE_GENERAL](../messages/common.md#COMP_METADATA_TYPE_GENERAL) | [general.schema.json](https://github.com/mavlink/mavlink/blob/master/component_metadata/general.schema.json) | General information about the component including hardware/firmware vendor version. This metadata includes information about all the other metadata types are supported by the component and where their metadata files are located. This metadata type must be supported if this protocol is supported and the file must be present on vehicle and delivered by MAVLink FTP. Note however that you never actually need to specify this type! |
|
||||
| <a id="COMP_METADATA_TYPE_PARAMETER"></a>Parameter metadata | [COMP_METADATA_TYPE_PARAMETER](../messages/common.md#COMP_METADATA_TYPE_PARAMETER) | [parameter.schema.json](https://github.com/mavlink/mavlink/blob/master/component_metadata/parameter.schema.json) | Information about parameters supported by the vehicle (on boot). |
|
||||
| <a id="COMP_METADATA_TYPE_COMMANDS"></a> Command protocol metadata | [COMP_METADATA_TYPE_COMMANDS](../messages/common.md#COMP_METADATA_TYPE_COMMANDS) | TBD | Information about which commands and command paramters are supported in via the command protocol. |
|
||||
| <a id="COMP_METADATA_TYPE_COMMANDS"></a> Command protocol metadata | [COMP_METADATA_TYPE_COMMANDS](../messages/common.md#COMP_METADATA_TYPE_COMMANDS) | TBD | Information about which commands and command parameters are supported via the command protocol. |
|
||||
| <a id="COMP_METADATA_TYPE_PERIPHERALS"></a> Peripheral metadata | [COMP_METADATA_TYPE_PERIPHERALS](../messages/common.md#COMP_METADATA_TYPE_PERIPHERALS) | [peripherals.schema.json](https://github.com/mavlink/mavlink/blob/master/component_metadata/peripherals.schema.json) | Information about non-MAVLink peripherals connected to vehicle (on boot). |
|
||||
| <a id="COMP_METADATA_TYPE_EVENTS"></a> Event metadata | [COMP_METADATA_TYPE_EVENTS](../messages/common.md#COMP_METADATA_TYPE_EVENTS) | TBD | Information about events interface support by the vehicle. |
|
||||
| <a id="COMP_METADATA_TYPE_ACTUATORS"></a> Event metadata | [COMP_METADATA_TYPE_ACTUATORS](../messages/common.md#COMP_METADATA_TYPE_ACTUATORS) | [actuators.schema.json ](https://github.com/mavlink/mavlink/blob/master/component_metadata/actuators.schema.json) | Metadata for actuator configuration (motors, servos and vehicle geometry) and testing. |
|
||||
@@ -262,7 +262,7 @@ The example repository is https://github.com/PX4/PX4-Metadata-Translations:
|
||||
|
||||
Schema _management_ has not yet been signed off.
|
||||
|
||||
### Guaranteed Availablility of Component Information
|
||||
### Guaranteed Availability of Component Information
|
||||
|
||||
There is a concern that vehicles reliant on internet-hosted component information files may stop working if the hosting ceases.
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@ The following key features are provided by the interface:
|
||||
|
||||
| Enum | Description |
|
||||
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| <a id="MAV_EVENT_CURRENT_SEQUENCE_FLAGS"></a>[MAV_EVENT_CURRENT_SEQUENCE_FLAGS](../messages/common.md#CURRENT_EVENT_SEQUENCE) | Flags for [CURRENT_EVENT_SEQUENCE](#CURRENT_EVENT_SEQUENCE). For exmaple, to indicate when the sequence has reset. |
|
||||
| <a id="MAV_EVENT_CURRENT_SEQUENCE_FLAGS"></a>[MAV_EVENT_CURRENT_SEQUENCE_FLAGS](../messages/common.md#CURRENT_EVENT_SEQUENCE) | Flags for [CURRENT_EVENT_SEQUENCE](#CURRENT_EVENT_SEQUENCE). For example, to indicate when the sequence has reset. |
|
||||
| <a id="MAV_EVENT_ERROR_REASON"></a>[MAV_EVENT_ERROR_REASON](../messages/common.md#MAV_EVENT_ERROR_REASON) | Reasons for an error, as provided in [RESPONSE_EVENT_ERROR](#RESPONSE_EVENT_ERROR). For example, common error would be that the event is not available (i.e. it has been discarded). |
|
||||
|
||||
## Implementations
|
||||
|
||||
@@ -178,7 +178,7 @@ It is possible for multiple components to want to control a gimbal at the same t
|
||||
|
||||
In order to start controlling a gimbal, a component first needs to send the [MAV_CMD_DO_GIMBAL_MANAGER_CONFIGURE](#MAV_CMD_DO_GIMBAL_MANAGER_CONFIGURE) command.
|
||||
This allows setting which MAVLink component (set by system ID and component ID) is in primary control and which one is in secondary control.
|
||||
The gimbal manager is to ignore any gimbal controls which come from MAVLink components that are not explicity set to "in control".
|
||||
The gimbal manager is to ignore any gimbal controls which come from MAVLink components that are not explicitly set to "in control".
|
||||
This should prevent conflicts between various inputs as long as all components are fair/co-operative when using the configure command.
|
||||
|
||||
To be co-operative entails the following rules:
|
||||
@@ -203,7 +203,7 @@ A ground station can manually control a gimbal by sending [GIMBAL_MANAGER_SET_MA
|
||||
This allows controlling the gimbal with either angles, or angular rates, using a normalized unit (-1..1).
|
||||
The gimbal device is responsible for translating the input based on angle, speed, and "smoothness" settings.
|
||||
|
||||
This input can additionally be scaled by the gimbal manager depending on its state. For example, if the gimbal manager is on a camera and knows the current zoom level / focal length of the camera, it can scale the angular rate down to support smooth paning and tilting.
|
||||
This input can additionally be scaled by the gimbal manager depending on its state. For example, if the gimbal manager is on a camera and knows the current zoom level / focal length of the camera, it can scale the angular rate down to support smooth panning and tilting.
|
||||
|
||||
#### Controlling Gimbal Angle and/or Angular Rate using MAVLink
|
||||
|
||||
@@ -232,7 +232,7 @@ This data is required by the _Gimbal Device_ attitude estimator (horizon compens
|
||||
|
||||
The gimbal device should send out its attitude and status in [GIMBAL_DEVICE_ATTITUDE_STATUS](#GIMBAL_DEVICE_ATTITUDE_STATUS) at a regular rate, e.g. 10 Hz.
|
||||
|
||||
This message is a meant as broadcast, so it's set to the GCS, _Gimbal Manager_, and all parties on the network (not just _Gimbal Manager_, like all other messages).
|
||||
This message is a meant as broadcast, so it's sent to the GCS, _Gimbal Manager_, and all parties on the network (not just _Gimbal Manager_, like all other messages).
|
||||
|
||||
### Custom Gimbal Device Settings
|
||||
|
||||
@@ -278,7 +278,7 @@ The recommendation is to make it configurable using (for instance) a parameter.
|
||||
|
||||
A non-MAVLink gimbal needs to be connected to a gimbal manager, which then takes care of sending the gimbal device messages.
|
||||
Since a non-MAVLink gimbal can't be addressed with a MAVLink component ID, the `gimbal_device_id` needs to be set to one of the magic values (1 to 6).
|
||||
This signals that the gimbal manager also is also acting as the gimbal device.
|
||||
This signals that the gimbal manager is also acting as the gimbal device.
|
||||
|
||||
Also see [how to address non-MAVLink gimbal devices](#non_mavlink_gimbal_device_addressing).
|
||||
|
||||
@@ -350,7 +350,7 @@ This is the set of messages/enums for communication between gimbal manager and g
|
||||
|
||||
## Sequences
|
||||
|
||||
Depicted below are message sequences for some common scenarious.
|
||||
Depicted below are message sequences for some common scenarios.
|
||||
|
||||
### Discovery
|
||||
|
||||
@@ -408,7 +408,7 @@ sequenceDiagram
|
||||
|
||||
[](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtXG4gICAgcGFydGljaXBhbnQgR3JvdW5kIFN0YXRpb25cbiAgICBwYXJ0aWNpcGFudCBHaW1iYWwgTWFuYWdlclxuICAgIHBhcnRpY2lwYW50IEdpbWJhbCBEZXZpY2VcbiAgICBHcm91bmQgU3RhdGlvbi0-PkdpbWJhbCBNYW5hZ2VyOiBNQVZfQ01EX0RPX1NFVF9ST0lfTE9DQVRJT05cbiAgICBHaW1iYWwgTWFuYWdlci0-Pkdyb3VuZCBTdGF0aW9uOiBDT01NQU5EX0FDS1xuICAgIEdpbWJhbCBNYW5hZ2VyLT4-R2ltYmFsIERldmljZTogR0lNQkFMX0RFVklDRV9TRVRfQVRUSVRVREUgKHN0cmVhbSlcbiAgICBHaW1iYWwgRGV2aWNlLT4-R2ltYmFsIE1hbmFnZXI6IEdJTUJBTF9ERVZJQ0VfQVRUSVRVREVfU1RBVFVTIChzdHJlYW0pXG4gICAgR2ltYmFsIERldmljZS0-Pkdyb3VuZCBTdGF0aW9uOiBHSU1CQUxfREVWSUNFX0FUVElUVURFX1NUQVRVUyAoc3RyZWFtKVxuICAgIEdyb3VuZCBTdGF0aW9uLT4-R2ltYmFsIE1hbmFnZXI6IE1BVl9DTURfRE9fU0VUX1JPSV9OT05FXG4gICAgR2ltYmFsIE1hbmFnZXItPj5Hcm91bmQgU3RhdGlvbjogQ09NTUFORF9BQ0siLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)
|
||||
|
||||
ROI can be started using a command and should also be stopped again with a command. The ROI command is translated to a gimbal attitude in the the gimbal manager.
|
||||
ROI can be started using a command and should also be stopped again with a command. The ROI command is translated to a gimbal attitude in the gimbal manager.
|
||||
|
||||
### Attitude Set During Mission
|
||||
|
||||
|
||||
@@ -107,7 +107,7 @@ The following messages and enums are used by the service.
|
||||
The legacy version of the protocol also supported [MISSION_REQUEST](../messages/common.md#MISSION_REQUEST) for requesting that a mission be sent as a sequence of [MISSION_ITEM](../messages/common.md#MISSION_ITEM) messages.
|
||||
|
||||
Both `MISSION_REQUEST` and `MISSION_ITEM` messages are now deprecated, and should no longer be sent.
|
||||
If `MISSION_REQUEST` is recieved the system should instead respond with [MISSION_ITEM_INT](#MISSION_ITEM_INT) items (as though it received [MISSION_REQUEST_INT](#MISSION_REQUEST_INT)).
|
||||
If `MISSION_REQUEST` is received the system should instead respond with [MISSION_ITEM_INT](#MISSION_ITEM_INT) items (as though it received [MISSION_REQUEST_INT](#MISSION_REQUEST_INT)).
|
||||
|
||||
## Frames & Positional Information
|
||||
|
||||
@@ -176,7 +176,7 @@ The only expectation is that the scheme used makes it unlikely that the GCS will
|
||||
On upload, the generated ID is sent to the GCS in the final part of the upload sequence in the [MISSION_ACK.opaque_id](#MISSION_ACK) field.
|
||||
On download, the stored ID is sent to the GCS in the [MISSION_COUNT.opaque_id](#MISSION_COUNT) field.
|
||||
|
||||
The GCS should store the value of the ID from the flight stack as the "current id" for whatever part of the plan was uploaded/download.
|
||||
The GCS should store the value of the ID from the flight stack as the "current id" for whatever part of the plan was uploaded/downloaded.
|
||||
It can then monitor `MISSION_CURRENT`, and check its cached values against the current plan ids to determine whether it has a matching mission, or needs to download the mission from the vehicle.
|
||||
|
||||
### Upload a Mission to the Vehicle {#uploading_mission}
|
||||
@@ -340,7 +340,7 @@ In more detail, the sequence of operations is:
|
||||
1. GCS/API sends [MISSION_CLEAR_ALL](../messages/common.md#MISSION_CLEAR_ALL)
|
||||
- A [timeout](#timeout) is started for the GCS to wait on `MISSION_ACK` from Drone.
|
||||
1. Drone receives the message, and clears the mission from storage.
|
||||
1. Drone responds with [MISSION_ACK](../messages/common.md#MISSION_ACK) with result `type` of [MAV_MISSION_ACCEPTED](../messages/common.md#MAV_MISSION_ACCEPTED)[MAV_MISSION_RESULT](../messages/common.md#MAV_MISSION_RESULT).
|
||||
1. Drone responds with [MISSION_ACK](../messages/common.md#MISSION_ACK) with result `type` of [MAV_MISSION_ACCEPTED](../messages/common.md#MAV_MISSION_ACCEPTED) indicating success.
|
||||
1. GCS receives `MISSION_ACK` and clears its own stored information about the mission.
|
||||
The operation is now complete.
|
||||
|
||||
@@ -382,7 +382,7 @@ An operation may also complete with an error - `MISSION_ACK.type` set to [MAV_MI
|
||||
This can occur in response to any message/anywhere in the sequence.
|
||||
|
||||
Errors are considered unrecoverable.
|
||||
In an error is sent, both ends of the system should reset themselves to the idle state and the current state of the mission on the vehicle should be unaltered.
|
||||
If an error is sent, both ends of the system should reset themselves to the idle state and the current state of the mission on the vehicle should be unaltered.
|
||||
|
||||
Note:
|
||||
|
||||
@@ -427,7 +427,7 @@ The direction of loiter for `MAV_CMD_NAV_LOITER_UNLIM` can be set using `param4`
|
||||
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`).
|
||||
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 `MAV_CMD_NAV_LOITER_TIME` and `MAV_CMD_NAV_LOITER_TURNS`).
|
||||
|
||||
| Param (:Label) | Description | Units |
|
||||
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
|
||||
|
||||
@@ -13,7 +13,7 @@ The particular types of setpoints that are supported, if any, depend on the vehi
|
||||
|
||||
| Message | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| <a id="SET_POSITION_TARGET_LOCAL_NED"></a>[SET_POSITION_TARGET_LOCAL_NED](../messages/common.md#SET_POSITION_TARGET_LOCAL_NED) | Sets a desired vehicle position, velocity, and/or accelaration setpoint in a local north-east-down coordinate frame. |
|
||||
| <a id="SET_POSITION_TARGET_LOCAL_NED"></a>[SET_POSITION_TARGET_LOCAL_NED](../messages/common.md#SET_POSITION_TARGET_LOCAL_NED) | Sets a desired vehicle position, velocity, and/or acceleration setpoint in a local north-east-down coordinate frame. |
|
||||
| <a id="SET_POSITION_TARGET_GLOBAL_INT"></a>[SET_POSITION_TARGET_GLOBAL_INT](../messages/common.md#SET_POSITION_TARGET_GLOBAL_INT) | Sets a desired vehicle position, velocity, and/or acceleration in a global coordinate system (WGS84) |
|
||||
| <a id="SET_ATTITUDE_TARGET"></a>[SET_ATTITUDE_TARGET](../messages/common.md#SET_ATTITUDE_TARGET) | Sets a desired vehicle attitude. |
|
||||
| <a id="POSITION_TARGET_LOCAL_NED"></a>[POSITION_TARGET_LOCAL_NED](../messages/common.md#POSITION_TARGET_LOCAL_NED) | Publishes current local NED target (set by `SET_POSITION_TARGET_LOCAL_NED`). |
|
||||
|
||||
@@ -48,7 +48,7 @@ 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.
|
||||
|
||||
## Parameter Encoding
|
||||
## Parameter Encoding {#parameter_encoding}
|
||||
|
||||
Parameter values are encoded in the `param_value` field, an IEE754 single-precision, 4 byte, floating point value (see [PARAM_SET](#PARAM_SET) and [PARAM_VALUE](#PARAM_VALUE)).
|
||||
The `param_type` ([MAV_PARAM_TYPE](../messages/common.md#MAV_PARAM_TYPE)) is used to indicate the actual type of the data, so that it can be decoded by the recipient.
|
||||
@@ -58,7 +58,7 @@ Two encoding approaches are supported:
|
||||
|
||||
- **Byte-wise encoding:** The parameter's bytes are copied directly into the bytes used for the field.
|
||||
A 32-bit integer is sent as 32 bits of data.
|
||||
- **C-style cast:** The parameter value is converted to a `float`. This may result in some loss of precision as a `float` can represent an integer with up to 24 bits of pecision.
|
||||
- **C-style cast:** The parameter value is converted to a `float`. This may result in some loss of precision as a `float` can represent an integer with up to 24 bits of precision.
|
||||
|
||||
Byte wise encoding is recommended as it allows very large integers to be exchanged (e.g. 1E7 scaled integers can be useful for encoding some types of data, but lose precision if cast directly to floats).
|
||||
|
||||
|
||||
@@ -49,7 +49,7 @@ Use the [commands for known payload types](#payload-specific-commands) where pos
|
||||
|
||||
## Payload Deployment Commands
|
||||
|
||||
These commands can be used to deploy a payload at a specfic location, controlling the approach and land behaviour.
|
||||
These commands can be used to deploy a payload at a specific location, controlling the approach and land behaviour.
|
||||
|
||||
| Message | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
|
||||
|
||||
@@ -61,7 +61,7 @@ This allows filtering of the response to a particular system (but not component)
|
||||
:::
|
||||
|
||||
::: info
|
||||
Version 2 makes adds the target address, so a syncing system can filter on just the responses to its requests.
|
||||
Version 2 adds the target address, so a syncing system can filter on just the responses to its requests.
|
||||
:::
|
||||
|
||||
## Implementations
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Traffic Managment and Avoidance (UTM/ADSB)
|
||||
# Traffic Management and Avoidance (UTM/ADSB)
|
||||
|
||||
Air traffic management and avoidance systems enable vehicles to share their position and planned path or trajectory with other vehicles (and ground stations),
|
||||
allowing them to take appropriate action to avoid collisions.
|
||||
@@ -19,7 +19,7 @@ There are two main traffic management systems supported by MAVLink:
|
||||
|
||||
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.
|
||||
A flight controller will typically receive these messages from the appropriate transponder or service, and may also publish them to a transponder or service.
|
||||
|
||||
::: info
|
||||
The [Open Drone ID](https://mavlink.io/en/services/opendroneid.html) service provides additional information about vehicle identity.
|
||||
|
||||
+1
-1
@@ -13,7 +13,7 @@
|
||||
"docs:gen_alt_sidebar_ubuntu": "python3 ./scripts/gen_alt_sidebar.py",
|
||||
"docs:get_alt_sidebar_windows": "python ./scripts/gen_alt_sidebar.py",
|
||||
"start": "yarn docs:dev",
|
||||
"linkcheck": "markdown_link_checker_sc -d en -i assets"
|
||||
"linkcheck": "markdown_link_checker_sc -d en -i assets -toc SUMMARY.md"
|
||||
},
|
||||
"dependencies": {
|
||||
"@red-asuka/vitepress-plugin-tabs": "^0.0.3",
|
||||
|
||||
Reference in New Issue
Block a user