From d1e7f019944a70b10ef1fceef43e4bb2e4e7c6b2 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 29 May 2025 11:28:01 +1000 Subject: [PATCH] Docs: add skeleton topic for indicating protocol support --- docs/en/SUMMARY.md | 5 +- docs/en/mavlink/index.md | 88 +++++++++++++++++++++++++++++++++++ docs/en/mavlink/protocols.md | 53 +++++++++++++++++++++ docs/en/middleware/mavlink.md | 88 +---------------------------------- 4 files changed, 145 insertions(+), 89 deletions(-) create mode 100644 docs/en/mavlink/index.md create mode 100644 docs/en/mavlink/protocols.md diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index aa6dcbc6d0..a94d3c15ea 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -722,12 +722,13 @@ - [AirspeedValidatedV0](msg_docs/AirspeedValidatedV0.md) - [VehicleAttitudeSetpointV0](msg_docs/VehicleAttitudeSetpointV0.md) - [VehicleStatusV0](msg_docs/VehicleStatusV0.md) - - [MAVLink Messaging](middleware/mavlink.md) + - [MAVLink Messaging](mavlink/index.md) - [Adding Messages](mavlink/adding_messages.md) - [Streaming Messages](mavlink/streaming_messages.md) - [Receiving Messages](mavlink/receiving_messages.md) - [Custom MAVLink Messages](mavlink/custom_messages.md) - - [Standard Modes Protocol](mavlink/standard_modes.md) + - [Protocols/Microservices](mavlink/protocols.md) + - [Standard Modes Protocol](mavlink/standard_modes.md) - [uXRCE-DDS (PX4-ROS 2/DDS Bridge)](middleware/uxrce_dds.md) - [Modules & Commands](modules/modules_main.md) - [Autotune](modules/modules_autotune.md) diff --git a/docs/en/mavlink/index.md b/docs/en/mavlink/index.md new file mode 100644 index 0000000000..8b81cbe595 --- /dev/null +++ b/docs/en/mavlink/index.md @@ -0,0 +1,88 @@ +# 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) +- [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. + +The [Command Protocol](https://mavlink.io/en/services/command.html) is a higher level protocol for sending commands that may need acknowledgement. +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 resent automatically 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. + +[Microservices](https://mavlink.io/en/services/) are other higher level protocols built on top of MAVLink messages. +They are used to communicate information that cannot be sent in a single message, and to deliver features such as reliable communication. +The command protocol described above is one such service. +Others include the [File Transfer Protocol](https://mavlink.io/en/services/ftp.html), [Camera Protocol](https://mavlink.io/en/services/camera.html) and [Mission Protocol](https://mavlink.io/en/services/mission.html). + +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. + + + +## 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/blob/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//mavlink/`. diff --git a/docs/en/mavlink/protocols.md b/docs/en/mavlink/protocols.md new file mode 100644 index 0000000000..316c527469 --- /dev/null +++ b/docs/en/mavlink/protocols.md @@ -0,0 +1,53 @@ +# MAVLink Microservices (Protocols) + +MAVLink "microservices" are a protocols that use multiple messages exchanged between components to communicate more complicated information. +For example, the [Command Protocol](https://mavlink.io/en/services/command.html) provides an efficient mechanism for packaging a command in a (particular) message and receiving acknowledgement of the command in another message. + +MAVLink microservices are documented the [MAVLink Guide](https://mavlink.io/en/services/) (this is not exhaustive: not all messages are grouped into protocols and not all protocols are documented). + +This section lists the services known to be supported/not supported by PX4 in this version. + +## Supported Microservices + +These services are known to be supported in some form: + +- [Battery Protocol](https://mavlink.io/en/services/battery.html) + - [BATTERY_STATUS](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) and [BATTERY_INFO](https://mavlink.io/en/messages/common.html#BATTERY_STATUS) are streamed. +- Camera Protocols + - [Camera Protocol v2](https://mavlink.io/en/services/camera.html) + - [Camera Definition](https://mavlink.io/en/services/camera_def.html) + - [Camera Protocol v1 (Simple Trigger Protocol)](https://mavlink.io/en/services/camera_v1.html) +- [Command Protocol](https://mavlink.io/en/services/command.html) +- [Component Metadata Protocol (WIP)](https://mavlink.io/en/services/component_information.html) +- [Events Interface (WIP)](https://mavlink.io/en/services/events.html) +- [File Transfer Protocol (FTP)](https://mavlink.io/en/services/ftp.html) +- Gimbal Protocols + - [Gimbal Protocol v2](https://mavlink.io/en/services/gimbal_v2.html) + - Can be enabled by [Gimbal Configuration](../advanced/gimbal_control.md#mavlink-gimbal-mnt-mode-out-mavlink) + - PX4 an act as a MAVLink Gimbal for one FC-connected Gimbal + - [Gimbal Protocol v1 (superseded)](https://mavlink.io/en/services/gimbal.html) +- [Heartbeat/Connection Protocol](https://mavlink.io/en/services/heartbeat.html) +- [High Latency Protocol](https://mavlink.io/en/services/high_latency.html) — PX4 streams [HIGH_LATENCY2](https://mavlink.io/en/messages/common.html#HIGH_LATENCY2) +- [Image Transmission Protocol](https://mavlink.io/en/services/image_transmission.html) +- [Landing Target Protocol](https://mavlink.io/en/services/landing_target.html) +- [Manual Control (Joystick) Protocol](https://mavlink.io/en/services/manual_control.html) +- [MAVLink Id Assignment (sysid, compid)](https://mavlink.io/en/services/mavlink_id_assignment.html) +- [Mission Protocol](https://mavlink.io/en/services/mission.html) +- [Offboard Control Protocol](https://mavlink.io/en/services/offboard_control.html) +- [Remote ID](../peripherals/remote_id.md) ([Open Drone ID Protocol](https://mavlink.io/en/services/opendroneid.html)) +- [Parameter Protocol](https://mavlink.io/en/services/parameter.html) +- [Parameter Protocol Extended](https://mavlink.io/en/services/parameter_ext.html) — Allows setting string parameters. Used for setting string parameters set in camera definition files. +- [Payload Protocol](https://mavlink.io/en/services/payload.html) +- [Ping Protocol](https://mavlink.io/en/services/ping.html) +- [Standard Modes Protocol](mavlink/standard_modes.md) +- [Terrain Protocol](https://mavlink.io/en/services/terrain.html) +- [Time Synchronization](https://mavlink.io/en/services/timesync.html) +- [Traffic Management (UTM/ADS-B)](https://mavlink.io/en/services/traffic_management.html) +- [Arm Authorization Protocol](https://mavlink.io/en/services/arm_authorization.html) + +## Unsupported + +These services are not supported/used by PX4: + +- [Illuminator Protocol](https://mavlink.io/en/services/illuminator.html) +- [Tunnel Protocol](https://mavlink.io/en/services/tunnel.html) diff --git a/docs/en/middleware/mavlink.md b/docs/en/middleware/mavlink.md index f79efa9c0b..c88fc7840e 100644 --- a/docs/en/middleware/mavlink.md +++ b/docs/en/middleware/mavlink.md @@ -1,87 +1 @@ -# 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) - -::: 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. - -The [Command Protocol](https://mavlink.io/en/services/command.html) is a higher level protocol for sending commands that may need acknowledgement. -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 resent automatically 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. - -[Microservices](https://mavlink.io/en/services/) are other higher level protocols built on top of MAVLink messages. -They are used to communicate information that cannot be sent in a single message, and to deliver features such as reliable communication. -The command protocol described above is one such service. -Others include the [File Transfer Protocol](https://mavlink.io/en/services/ftp.html), [Camera Protocol](https://mavlink.io/en/services/camera.html) and [Mission Protocol](https://mavlink.io/en/services/mission.html). - -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. - - - -## 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/blob/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//mavlink/`. +