MAVLink

MAVLink or Micro Air Vehicle Link is a protocol for communicating with small unmanned vehicle. It is designed as a header-only message marshaling library. MAVLink was first released early 2009 by Lorenz Meier under the LGPL license.

Applications

It is used mostly for communication between a Ground Control Station (GCS) and Unmanned vehicles, and in the inter-communication of the subsystem of the vehicle. It can be used to transmit the orientation of the vehicle, its GPS location and speed.

Packet Structure

In version 1.0 the packet structure is the following:

Field name	Index (Bytes)	Purpose
Start-of-frame	0	Denotes the start of frame transmission (v1.0: 0xFE)
Payload-length	1	length of payload (n)
Packet sequence	2	Each component counts up their send sequence. Allows for detection of packet loss.
System ID	3	Identification of the SENDING system. Allows to differentiate different systems on the same network.
Component ID	4	Identification of the SENDING component. Allows to differentiate different components of the same system, e.g. the IMU and the autopilot.
Message ID	5	Identification of the message - the id defines what the payload “means” and how it should be correctly decoded.
Payload	6 to (n+6)	The data into the message, depends on the message id.
CRC	(n+7) to (n+8)	Check-sum of the entire packet, excluding the packet start sign (LSB to MSB)

After Version 2, the packet structure was expanded into the following:

Field name	Index (Bytes)	Purpose
Start-of-frame	0	Denotes the start of frame transmission (v2: 0xFD)
Payload-length	1	length of payload (n)
incompatibility flags	2	Flags that must be understood for MAVLink compatibility
compatibility flags	3	Flags that can be ignored if not understood
Packet sequence	4	Each component counts up their send sequence. Allows for detection of packet loss.
System ID	5	Identification of the SENDING system. Allows to differentiate different systems on the same network.
Component ID	6	Identification of the SENDING component. Allows to differentiate different components of the same system, e.g. the IMU and the autopilot.
Message ID	7 to 9	Identification of the message - the id defines what the payload “means” and how it should be correctly decoded.
Payload	10 to (n+10)	The data into the message, depends on the message id.
CRC	(n+11) to (n+12)	Check-sum of the entire packet, excluding the packet start sign (LSB to MSB)
Signature	(n+13) to (n+25)	Signature to verify that messages originate from a trusted source. (optional)

CRC field

To ensure message integrity a cyclic redundancy check (CRC) is calculated to every message into the last two bytes. Another function of the CRC field is to ensure the sender and receiver both agree in the message that is being transferred. It is computed using an ITU X.25/SAE AS-4 hash of the bytes in the packet, excluding the Start-of-Frame indicator (so 6+n+1 bytes are evaluated, the extra +1 is the seed value).

Additionally a seed value is appended to the end of the data when computing the CRC. The seed is generated with every new message set of the protocol, and it is hashed in a similar way as the packets from each message specifications. Systems using the MAVLink protocol can use a precomputed array to this purpose.

The CRC algorithm of MAVLink has been implemented in many languages, like Python and Java.

Messages

The payload from the packets described above are MAVLink messages. Every message is identifiable by the ID field on the packet, and the payload contains the data from the message. An XML document in the MAVlink source has the definition of the data stored in this payload.

Below is the message with ID 24 extracted from the XML document.

<message id="24" name="GPS_RAW_INT">
        <description>The global position, as returned by the Global Positioning System (GPS). This is NOT the global position estimate of the system, but rather a RAW sensor value. See message GLOBAL_POSITION for the global position estimate. Coordinate frame is right-handed, Z-axis up (GPS frame).</description>
        <field type="uint64_t" name="time_usec">Timestamp (microseconds since UNIX epoch or microseconds since system boot)</field>
        <field type="uint8_t" name="fix_type">0-1: no fix, 2: 2D fix, 3: 3D fix. Some applications will not use the value of this field unless it is at least two, so always correctly fill in the fix.</field>
        <field type="int32_t" name="lat">Latitude (WGS84), in degrees * 1E7</field>
        <field type="int32_t" name="lon">Longitude (WGS84), in degrees * 1E7</field>
        <field type="int32_t" name="alt">Altitude (WGS84), in meters * 1000 (positive for up)</field>
        <field type="uint16_t" name="eph">GPS HDOP horizontal dilution of position in cm (m*100). If unknown, set to: UINT16_MAX</field>
        <field type="uint16_t" name="epv">GPS VDOP vertical dilution of position in cm (m*100). If unknown, set to: UINT16_MAX</field>
        <field type="uint16_t" name="vel">GPS ground speed (m/s * 100). If unknown, set to: UINT16_MAX</field>
        <field type="uint16_t" name="cog">Course over ground (NOT heading, but direction of movement) in degrees * 100, 0.0..359.99 degrees. If unknown, set to: UINT16_MAX</field>
        <field type="uint8_t" name="satellites_visible">Number of satellites visible. If unknown, set to 255</field>
</message>

Note: The XML document describes the logical ordering of the fields for the protocol. The actual wire format (and typical in-memory representation) has the fields reordered to reduce Data structure alignment issues. This can be a source of confusion when reading the code generated from the message definitions.

MAVLink Ecosystem

MAVLink is used as the communication protocol in many projects, which may mean there is some compatibility between them. A tutorial explaining basics of MAVLink has been written.