MAVLink Messaging
MAVLink 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, 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
- Streaming MAVLink messages
- Handling incoming MAVLink messages (and writing to a uORB topic)
- Custom MAVLink Messages
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), 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 is a higher level protocol for sending commands that may need acknowledgement. Specific commands are defined as values of the MAV_CMD enumeration, such as the takeoff command 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 definitions are also used to define mission actions, and that not all definitions are supported for use in commands/missions on PX4.
Microservices 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, Camera Protocol and Mission Protocol.
MAVLink messages, commands and enumerations are defined in XML definition files. 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 — Definitions that are proposed to be part of the standard. The definitions move to
common.xml
if accepted following testing. - common.xml — 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 — Definitions that are actually standard. They are present on the vast majority of flight stacks and implemented in the same way.
- minimal.xml — Definitions required by a minimal MAVLink implementation.
The project also hosts dialect XML definitions, 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 to define and contribute these definitions.
PX4 includes the mavlink/mavlink repo as a submodule under /src/modules/mavlink. This contains XML definition files in /mavlink/messages/1.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 on a per-board basis, using the variable CONFIG_MAVLINK_DIALECT
:
- For SITL
CONFIG_MAVLINK_DIALECT
is set todevelopment
in boards/px4/sitl/default.px4board. You can change this to any other definition file, but the file must includecommon.xml
. - For other boards
CONFIG_MAVLINK_DIALECT
is not set by default, and PX4 builds the definitions incommon.xml
(these are build into the mavlink module by default — search formenuconfig MAVLINK_DIALECT
in src/modules/mavlink/Kconfig).
The files are generated into the build directory: /build/<build target>/mavlink/
.