The MAVLink (Micro Air Vehicle Link) protocol is a lightweight messaging protocol designed for communication between unmanned vehicles and ground control stations. This document explains the implementation of MAVLink in Mission Planner, including its message structure, code generation pipeline, packet parsing, CRC validation, and signing mechanisms.
MAVLink is a binary serialization protocol designed for resource-constrained systems. In Mission Planner, the MAVLink implementation is contained within the ExtLibs/Mavlink directory as a partial class structure that handles various message types for telemetry, command and control, and parameter management.
Key characteristics of the implementation:
0xFE) and 2.0 (STX 0xFD).unsafe pointers and GCHandle pinning.Sources: ExtLibs/Mavlink/Mavlink.cs6-37 ExtLibs/Mavlink/MAVLinkMessage.cs5-45
Mission Planner uses a Python-based generator (mavgen_cs.py) to transform MAVLink XML definitions into C# code. This ensures that the Ground Control Station (GCS) stays synchronized with the latest ArduPilot message definitions.
ExtLibs/Mavlink/message_definitions/, including common.xml, ardupilotmega.xml, and uAvionix.xml.mavgen_cs.py uses MAVTemplate to inject constants, enums, and message structures into the MAVLink partial class.MAVLINK_MESSAGE_INFOS array, which maps msgid to metadata like name, CRC extra, and the corresponding C# Type.| Component | File Path | Role |
|---|---|---|
| Generator | ExtLibs/Mavlink/pymavlink/generator/mavgen_cs.py | Python script that generates the C# MAVLink class. |
| Definitions | ExtLibs/Mavlink/message_definitions/common.xml | Standard MAVLink message set. |
| Dialect | ExtLibs/Mavlink/message_definitions/ardupilotmega.xml | ArduPilot-specific extensions. |
| Batch Script | ExtLibs/Mavlink/regenerate.bat | Automates the execution of the generator. |
Sources: ExtLibs/Mavlink/pymavlink/generator/mavgen_cs.py31-178 ExtLibs/Mavlink/message_definitions/common.xml1-50 ExtLibs/Mavlink/message_definitions/ardupilotmega.xml1-30 ExtLibs/Mavlink/regenerate.bat1-16
The protocol defines specific lengths for headers and trailers to facilitate stream synchronization. The implementation supports both standard messages and "offspec" work-in-progress messages.
| Constant | Value | Description |
|---|---|---|
MAVLINK_STX | 253 (0xFD) | MAVLink 2.0 Start-of-Frame byte. |
MAVLINK_STX_MAVLINK1 | 0xFE | MAVLink 1.0 Start-of-Frame byte. |
MAVLINK_CORE_HEADER_LEN | 9 | Header length for v2.0 (excluding STX). |
MAVLINK_CORE_HEADER_MAVLINK1_LEN | 5 | Header length for v1.0 (excluding STX). |
MAVLINK_SIGNATURE_BLOCK_LEN | 13 | Length of the optional v2.0 signature. |
MAVLINK_MAX_PAYLOAD_LEN | 255 | Maximum payload size. |
Sources: ExtLibs/Mavlink/Mavlink.cs8-28 ExtLibs/Mavlink/message_definitions/offspec.xml7-19
Parsing is handled by the MavlinkParse class, which reads from a Stream and reconstructs MAVLinkMessage objects.
The ReadPacket function implements a state machine to find the STX byte and then read the header and payload.
Sources: ExtLibs/Mavlink/MavlinkParse.cs128-234 ExtLibs/Mavlink/MAVLinkMessage.cs160-209
MAVLink uses a CRC-16-CCITT checksum. To prevent collisions between different versions of the same message ID, a "CRC Extra" byte (derived from the message definition) is accumulated into the final checksum using MavlinkCRC.crc_accumulate.
Sources: ExtLibs/Mavlink/MavlinkParse.cs216-227 ExtLibs/Mavlink/Mavlink.cs32
The MavlinkUtil class provides high-performance conversion between byte arrays and C# structures. It defaults to using unsafe pointer operations for speed.
ByteArrayToStructure<T>: Uses ReadUsingPointer to map a byte array directly to a struct without intermediate allocations.ByteArrayToStructureGC: Uses GCHandle.Alloc with GCHandleType.Pinned and a pre-allocated buffer pool (gcbuffer) to handle serialization in a thread-safe manner using a SemaphoreSlim.trim_payload: Removes trailing zeros from MAVLink 2.0 payloads to reduce bandwidth.Sources: ExtLibs/Mavlink/MavlinkUtil.cs15-32 ExtLibs/Mavlink/MavlinkUtil.cs119-143 ExtLibs/Mavlink/MavlinkUtil.cs145-190 ExtLibs/Mavlink/MavlinkUtil.cs108-118
MAVLink 2.0 supports message signing to prevent spoofing. The MAVLinkMessage class exposes signature properties:
sig: The raw 13-byte signature block.sigLinkid: Identifies the specific link.sigTimestamp: A 48-bit timestamp used to prevent replay attacks.The signature is extracted during processBuffer if the MAVLINK_IFLAG_SIGNED bit is set in the incompatibility flags.
Sources: ExtLibs/Mavlink/MAVLinkMessage.cs106-134 ExtLibs/Mavlink/MAVLinkMessage.cs184-189 ExtLibs/Mavlink/MavlinkParse.cs190-194
For debugging, the repository includes mavlink.lua, a Wireshark dissector. This script allows developers to inspect MAVLink traffic in real-time.
mavlink_proto as a new protocol in Wireshark.messageName table mapping numeric IDs to string names (e.g., 1 to SYS_STATUS, 24 to GPS_RAW_INT).get_timezone and a reference timestamp to decode MAVLink 2.0 signature timestamps.Sources: ExtLibs/Mavlink/mavlink.lua4-22 ExtLibs/Mavlink/mavlink.lua114-167 ExtLibs/Mavlink/mavlink.lua8-13
This diagram bridges the protocol implementation with the Mission Planner message processing.
Sources: ExtLibs/Mavlink/MavlinkParse.cs128-213 ExtLibs/Mavlink/MAVLinkMessage.cs53-97 ExtLibs/Mavlink/Mavlink.cs39-41 ExtLibs/Mavlink/MavlinkUtil.cs166-185
Refresh this wiki