mirror of
https://gitee.com/mirrors_PX4/PX4-Autopilot.git
synced 2026-10-22 22:23:33 +08:00
358574f9f6
* Applying PR #17084 * Comitting missing changes * Adding incoming SETUP_SIGNING handling * Adding proper message decoding for SETUP_SIGNING * Adding persistance of sign key in chunks of 32 bits into parameters * Allowing SETUP_SIGNING to be handled only on usb_uart * Removing unused type and variable * Changing the default for Mavlink Timestamp * Fixing styling * Merging * Merging submodules * Replacing parameters with sdcard storage for secured key and ts * Fixing styles * Isolating signing related items in separate class * Adding new files * Syncing with main * Fixing styles * Changing the signing logic to work only if key and ts properly initialized, adding store the ts on stop * Updated submodules to latest versions * Updated gz to proper version * libfc-sensor-api to proper version * libcanard to proper version * Updated fuzztest to proper version * Updated public_regulated_data_types to proper version * Updated mip_sdk to proper version * Updated pydronecan to proper version * Updated rosidl to proper version * Fixing styles * Fixing cyclonedds version * initializing sign control in the member declaration * Update src/modules/mavlink/mavlink_main.h Co-authored-by: Jacob Dahl <37091262+dakejahl@users.noreply.github.com> * Fixing comments * Fixing duplicate method * Fixing defines * Fixing styles * Fixing the define errors * replace duplicate logic with write_key_and_timestamp() function * add docs * Update docs/en/mavlink/message_signing.md Co-authored-by: Julian Oes <julian@oes.ch> * Update src/modules/mavlink/mavlink_sign_control.cpp Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update src/modules/mavlink/mavlink_sign_control.h Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update docs/en/mavlink/message_signing.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * rename to MAV_SIGN_CFG, fix copyright dates, fix docs SHA type, rename secrets file * fix newlines --------- Co-authored-by: Jacob Dahl <37091262+dakejahl@users.noreply.github.com> Co-authored-by: Jacob Dahl <dahl.jakejacob@gmail.com> Co-authored-by: Julian Oes <julian@oes.ch> Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
91 lines
7.9 KiB
Markdown
91 lines
7.9 KiB
Markdown
# MAVLink Messaging
|
|
|
|
[MAVLink](https://mavlink.io/en/) is a very lightweight messaging protocol that has been designed for the drone ecosystem.
|
|
|
|
PX4 uses _MAVLink_ to communicate with ground stations and MAVLink SDKs, such as _QGroundControl_ and [MAVSDK](https://mavsdk.mavlink.io/), and as the integration mechanism for connecting to drone components outside of the flight controller: companion computers, MAVLink enabled cameras, and so on.
|
|
|
|
This topic provides a brief overview of fundamental MAVLink concepts, such as messages, commands, and microservices.
|
|
It also links instructions for how you can add PX4 support for:
|
|
|
|
- [Adding Standard Messages](../mavlink/adding_messages.md)
|
|
- [Streaming MAVLink messages](../mavlink/streaming_messages.md)
|
|
- [Handling incoming MAVLink messages (and writing to a uORB topic)](../mavlink/receiving_messages.md)
|
|
- [Custom MAVLink Messages](../mavlink/custom_messages.md)
|
|
- [Message Signing](../mavlink/message_signing.md)
|
|
- [Protocols/Microservices](../mavlink/protocols.md)
|
|
|
|
::: info
|
|
We do not yet cover _command_ handling and sending, or how to implement your own microservices.
|
|
:::
|
|
|
|
## MAVLink Overview
|
|
|
|
MAVLink is a lightweight protocol that was designed for efficiently sending messages over unreliable low-bandwidth radio links.
|
|
|
|
_Messages_ are simplest and most "fundamental" definition in MAVLink, consisting of a name (e.g. [ATTITUDE](https://mavlink.io/en/messages/common.html#ATTITUDE)), id, and fields containing relevant data.
|
|
They are deliberately lightweight, with a constrained size, and no semantics for resending and acknowledgement.
|
|
Stand-alone messages are commonly used for streaming telemetry or status information, and for sending commands where no acknowledgement is required - such as setpoint commands sent at high rate.
|
|
|
|
[Microservices](../mavlink/protocols.md) are "meta protocols" built on top of MAVLink messages.
|
|
They are used to communicate information that cannot be sent in a single message.
|
|
|
|
For example, the [Command Protocol](https://mavlink.io/en/services/command.html) is a service for sending commands that may need acknowledgement and retransmission (quality of service).
|
|
Specific commands are defined as values of the [MAV_CMD](https://mavlink.io/en/messages/common.html#mav_commands) enumeration, such as the takeoff command [MAV_CMD_NAV_TAKEOFF](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_TAKEOFF), and include up to 7 numeric "param" values.
|
|
The protocol sends a command by packaging the parameter values in a `COMMAND_INT` or `COMMAND_LONG` message, and waits for an acknowledgement with a result in a `COMMAND_ACK`.
|
|
The command is automatically resent a number of times if no acknowledgment is received.
|
|
Note that [MAV_CMD](https://mavlink.io/en/messages/common.html#mav_commands) definitions are also used to define mission actions, and that not all definitions are supported for use in commands/missions on PX4.
|
|
|
|
Others services include the [File Transfer Protocol](https://mavlink.io/en/services/ftp.html), [Camera Protocol](https://mavlink.io/en/services/camera.html), [Parameter Protocol](https://mavlink.io/en/services/parameter.html), and [Mission Protocol](https://mavlink.io/en/services/mission.html).
|
|
For more information on what PX4 supports see [Microservices](../mavlink/protocols.md).
|
|
|
|
MAVLink messages, commands and enumerations are defined in [XML definition files](https://mavlink.io/en/guide/define_xml_element.html).
|
|
The MAVLink toolchain includes code generators that create programming-language-specific libraries from these definitions for sending and receiving messages.
|
|
Note that most generated libraries do not create code to implement microservices.
|
|
|
|
The MAVLink project standardizes a number of messages, commands, enumerations, and microservices, for exchanging data using the following definition files (note that higher level files _include_ the definitions of the files below them):
|
|
|
|
- [development.xml](https://mavlink.io/en/messages/development.html) — Definitions that are proposed to be part of the standard.
|
|
The definitions move to `common.xml` if accepted following testing.
|
|
- [common.xml](https://mavlink.io/en/messages/common.html) — A "library" of definitions meeting many common UAV use cases.
|
|
These are supported by many flight stacks, ground stations, and MAVLink peripherals.
|
|
Flight stacks that use these definitions are more likely to interoperate.
|
|
- [standard.xml](https://mavlink.io/en/messages/standard.html) — Definitions that are actually standard.
|
|
They are present on the vast majority of flight stacks and implemented in the same way.
|
|
- [minimal.xml](https://mavlink.io/en/messages/minimal.html) — Definitions required by a minimal MAVLink implementation.
|
|
|
|
The project also hosts [dialect XML definitions](https://mavlink.io/en/messages/#dialects), which contain MAVLink definitions that are specific to a flight stack or other stakeholder.
|
|
|
|
The protocol relies on each end of the communication having a shared definition of what messages are being sent.
|
|
What this means is that in order to communicate both ends of the communication must use libraries generated from the same XML definition.
|
|
|
|
<!--
|
|
The messages are sent over-the-wire in the "payload" of a [MAVLink packet](https://mavlink.io/en/guide/serialization.html#mavlink2_packet_format).
|
|
In order to reduce the amount of information that must be sent, the packet does not include the message metadata, such as what fields are in the message and so on.
|
|
Instead, the fields are serialized in a predefined order based on data size and XML definition order, and MAVLink relies on each end of the communication having a shared definition of what messages are being sent.
|
|
The shared identity of the message is conveyed by the message id, along with a CRC ("`CRC_EXTRA`") that uniquely identifies the message based on its name and id, and the field names and types.
|
|
The receiving end of the communication will discard any packet for which the message id and the `CRC_EXTRA` do not match.
|
|
-->
|
|
|
|
## PX4 and MAVLink
|
|
|
|
PX4 releases build `common.xml` MAVLink definitions by default, for the greatest compatibility with MAVLink ground stations, libraries, and external components such as MAVLink cameras.
|
|
In the `main` branch, these are included from `development.xml` on SITL, and `common.xml` for other boards.
|
|
|
|
::: info
|
|
To be part of a PX4 release, any MAVLink definitions that you use must be in `common.xml` (or included files such as `standard.xml` and `minimal.xml`).
|
|
During development you can use definitions in `development.xml`.
|
|
You will need to work with the [MAVLink team](https://mavlink.io/en/contributing/contributing.html) to define and contribute these definitions.
|
|
:::
|
|
|
|
PX4 includes the [mavlink/mavlink](https://github.com/mavlink/mavlink) repo as a submodule under [/src/modules/mavlink](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/mavlink).
|
|
This contains XML definition files in [/mavlink/messages/1.0/](https://github.com/mavlink/mavlink/tree/master/message_definitions/v1.0).
|
|
|
|
The build toolchain generates the MAVLink 2 C header files at build time.
|
|
The XML file for which headers files are generated may be defined in the [PX4 kconfig board configuration](../hardware/porting_guide_config.md#px4-board-configuration-kconfig) on a per-board basis, using the variable `CONFIG_MAVLINK_DIALECT`:
|
|
|
|
- For SITL `CONFIG_MAVLINK_DIALECT` is set to `development` in [boards/px4/sitl/default.px4board](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/sitl/default.px4board#L36).
|
|
You can change this to any other definition file, but the file must include `common.xml`.
|
|
- For other boards `CONFIG_MAVLINK_DIALECT` is not set by default, and PX4 builds the definitions in `common.xml` (these are build into the [mavlink module](../modules/modules_communication.md#mavlink) by default — search for `menuconfig MAVLINK_DIALECT` in [src/modules/mavlink/Kconfig](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/Kconfig#L10)).
|
|
|
|
The files are generated into the build directory: `/build/<build target>/mavlink/`.
|