MAVLink Message Documentation

This page contains a binary-accurate version of MAVLink v2's message set (more specifically, all.xml), including all the extension fields. I've been wanting to make this post for a very long time now (for around 6 months), but I've never really got around to it until now. But... here it is.

If you would prefer to directly jump to the content instead of sitting through all the Context and Background behind this post, jump to HEARTBEAT (0).

Context / Upgrades from Official MAVLink Docs

The inspiration for this post happened when Benny (go check him out here) and I were working on parsing live/malicious MAVLink packets as part of a research project (AeroShield) with the Stevens MACC Lab (and I guess the US DoD/DoW and our other sponsors) in our automated attack shell.

I'm by no means an expert on this, but for those that have no clue what I'm talking about:

The MAVLink protocol (or if we want to be fancy, the Micro Air Vehicle Link protocol) is one of the most common standards for communicating, interacting with, and issuing commands to drones (UAVs). It's designed as a layer 7 protocol to allow it to work over Serial Links, Wi-Fi, and different network stacks. Image Source.

Here's how a MAVLink v1/v2 packet looks like at a binary level. For the purposes of this post, we're only looking at the Payload field. The Payload fields contain different MAVLink messages that, like we mentioned earlier, are used to communicate between or issue commands to the drones. For example, you have things like:

• GLOBAL_POSITION_INT - Reports the rough coordinates/location of the drone
• HEARTBEAT - Periodic heartbeat messages so the Ground Control Station knows the drone didn't explode
• COMMAND_LONG - Send a command to the drone (such as telling it to shut down in midair and fall to the ground)

Unfortunately, the Official MAVLink documentation website is:

• Very disorganized and decentralized
  • Message types are split among 20 different .xml files and web pages
  • This also applies to the MAVLink Github repository
• Out of order when compared to the physical layout of the actual MAVLink packets
  • This includes the official .xml files on Github
  • The physical layout of MAVLink bytes you see in transmission follow the Serialization rules for MAVLink. This is hidden away on the website and have a weird way of dealing with MAVLink 2 extensions
• Missing details compared to what you find in the official .xml files
• MAVLink documentation outside of the official website is scarce and practically non-existent
  • At least for the public. Maybe one day the powers that be gift me a TS/SCI clearance and I find out otherwise 🤷‍♂️

This means if you're trying to use the MAVLink website (or even the official Github .xml files) to parse MAVLink packets, it's very annoying and unhelpful. I made this page out of spite to hopefully stop people from wasting their weekend trying to go down the rabbit hole.

• I guess instead of this post, you can technically jump down the rabbit hole of combining all 20+ .xml files, determining the field order for EVERY MAVLink message type using the Serialization Rules (be careful if you're doing this, MAVLink 2 Extension Fields are handled weirdly), and generating your own docs ._.
• But don't waste your weekend doing this. I kind of did it for you

Additional Resources

If you're curious, here's some resources:

• MAVLink Schema - A collection of .json and .xml files you can use to manually parse MAVLink payloads yourself without having to rely on some third-party library
  • Be careful about doing this; certain setups will send MAVLink packets as a continuous byte stream
• MAVLink Markdown Site - Contains code to generate this XML page
• (To do when AeroShield or Benny open sources aeroSH) - Code used to parse all.xml and properly sort the packets

HEARTBEAT (0)

The heartbeat message shows that a system or component is present and responding. The type and autopilot fields (along with the message component id), allow the receiving system to treat further messages from this system appropriately (e.g. by laying out the user interface based on the autopilot). This microservice is documented at https://mavlink.io/en/services/heartbeat.html

SYS_STATUS (1)

The general system state. If the system is following the MAVLink standard, the system state is mainly defined by three orthogonal states/modes: The system mode, which is either LOCKED (motors shut down and locked), MANUAL (system under RC control), GUIDED (system with autonomous position control, position setpoint controlled manually) or AUTO (system guided by path/waypoint planner). The NAV_MODE defined the current flight state: LIFTOFF (often an open-loop maneuver), LANDING, WAYPOINTS or VECTOR. This represents the internal navigation state machine. The system status shows whether the system is currently active or not and if an emergency occurred. During the CRITICAL and EMERGENCY states the MAV is still considered to be active, but should start emergency procedures autonomously. After a failure occurred it should first move from active to critical to allow manual intervention and then move to emergency after a certain timeout.

SYSTEM_TIME (2)

The system time is the time of the master clock. This can be emitted by flight controllers, onboard computers, or other components in the MAVLink network. Components that are using a less reliable time source, such as a battery-backed real time clock, can choose to match their system clock to that of a SYSTEM_TYPE that indicates a more recent time. This allows more broadly accurate date stamping of logs, and so on. If precise time synchronization is needed then use TIMESYNC instead.

PING (4)

A ping message either requesting or responding to a ping. This allows to measure the system latencies, including serial port, radio modem and UDP connections. The ping microservice is documented at https://mavlink.io/en/services/ping.html

CHANGE_OPERATOR_CONTROL (5)

Request to control this MAV

CHANGE_OPERATOR_CONTROL_ACK (6)

Accept / deny control of this MAV

AUTH_KEY (7)

Emit an encrypted signature / key identifying this system. PLEASE NOTE: This protocol has been kept simple, so transmitting the key requires an encrypted channel for true safety.

LINK_NODE_STATUS (8)

Status generated in each node in the communication chain and injected into MAVLink stream.

SET_MODE (11)

Set the system mode, as defined by enum MAV_MODE. There is no target component id as the mode is by definition for the overall aircraft, not only for one component.

PARAM_REQUEST_READ (20)

Request to read the onboard parameter with the param_id string id. Onboard parameters are stored as key[const char*] -> value[float]. This allows to send a parameter to any other component (such as the GCS) without the need of previous knowledge of possible parameter names. Thus the same GCS can store different parameters for different autopilots. See also https://mavlink.io/en/services/parameter.html for a full documentation of QGroundControl and IMU code.

PARAM_REQUEST_LIST (21)

Request all parameters of this component. After this request, all parameters are emitted. The parameter microservice is documented at https://mavlink.io/en/services/parameter.html

PARAM_VALUE (22)

Emit the value of a onboard parameter. The inclusion of param_count and param_index in the message allows the recipient to keep track of received parameters and allows him to re-request missing parameters after a loss or timeout. The parameter microservice is documented at https://mavlink.io/en/services/parameter.html

PARAM_SET (23)

Set a parameter value (write new value to permanent storage). The receiving component should acknowledge the new parameter value by broadcasting a PARAM_VALUE message (broadcasting ensures that multiple GCS all have an up-to-date list of all parameters). If the sending GCS did not receive a PARAM_VALUE within its timeout time, it should re-send the PARAM_SET message. The parameter microservice is documented at https://mavlink.io/en/services/parameter.html.

GPS_RAW_INT (24)

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_INT for the global position estimate.

GPS_STATUS (25)

The positioning status, as reported by GPS. This message is intended to display status information about each satellite visible to the receiver. See message GLOBAL_POSITION_INT for the global position estimate. This message can contain information for up to 20 satellites.

SCALED_IMU (26)

The RAW IMU readings for the usual 9DOF sensor setup. This message should contain the scaled values to the described units

RAW_IMU (27)

The RAW IMU readings for a 9DOF sensor, which is identified by the id (default IMU1). This message should always contain the true raw values without any scaling to allow data capture and system debugging.

RAW_PRESSURE (28)

The RAW pressure readings for the typical setup of one absolute pressure and one differential pressure sensor. The sensor values should be the raw, UNSCALED ADC values.

SCALED_PRESSURE (29)

The pressure readings for the typical setup of one absolute and differential pressure sensor. The units are as specified in each field.

ATTITUDE (30)

The attitude in the aeronautical frame (right-handed, Z-down, Y-right, X-front, ZYX, intrinsic).

ATTITUDE_QUATERNION (31)

The attitude in the aeronautical frame (right-handed, Z-down, X-front, Y-right), expressed as quaternion. Quaternion order is w, x, y, z and a zero rotation would be expressed as (1 0 0 0).

LOCAL_POSITION_NED (32)

The filtered local position (e.g. fused computer vision and accelerometers). Coordinate frame is right-handed, Z-axis down (aeronautical frame, NED / north-east-down convention)

GLOBAL_POSITION_INT (33)

The filtered global position (e.g. fused GPS and accelerometers). The position is in GPS-frame (right-handed, Z-up). It is designed as scaled integer message since the resolution of float is not sufficient.

RC_CHANNELS_SCALED (34)

The scaled values of the RC channels received: (-100%) -10000, (0%) 0, (100%) 10000. Channels that are inactive should be set to INT16_MAX.

RC_CHANNELS_RAW (35)

The RAW values of the RC channels received. The standard PPM modulation is as follows: 1000 microseconds: 0%, 2000 microseconds: 100%. A value of UINT16_MAX implies the channel is unused. Individual receivers/transmitters might violate this specification.

SERVO_OUTPUT_RAW (36)

Superseded by ACTUATOR_OUTPUT_STATUS. The RAW values of the servo outputs (for RC input from the remote, use the RC_CHANNELS messages). The standard PPM modulation is as follows: 1000 microseconds: 0%, 2000 microseconds: 100%.

MISSION_REQUEST_PARTIAL_LIST (37)

Request a partial list of mission items from the system/component. https://mavlink.io/en/services/mission.html. If start and end index are the same, just send one waypoint.

MISSION_WRITE_PARTIAL_LIST (38)

This message is sent to the MAV to write a partial list. If start index == end index, only one item will be transmitted / updated. If the start index is NOT 0 and above the current list size, this request should be REJECTED!

MISSION_ITEM (39)

Message encoding a mission item. This message is emitted to announce the presence of a mission item and to set a mission item on the system. The mission item can be either in x, y, z meters (type: LOCAL) or x:lat , y:lon , z:altitude . Local frame is Z-down, right handed (NED), global frame is Z-up, right handed (ENU). NaN may be used to indicate an optional/default value (e.g. to use the system's current latitude or yaw rather than a specific value). See also https://mavlink.io/en/services/mission.html.

MISSION_REQUEST (40)

Request the information of the mission item with the sequence number seq. The response of the system to this message should be a MISSION_ITEM message. https://mavlink.io/en/services/mission.html

MISSION_SET_CURRENT (41)

Set the mission item with sequence number seq as the current item and emit MISSION_CURRENT (whether or not the mission number changed). If a mission is currently being executed, the system will continue to this new mission item on the shortest path, skipping any intermediate mission items. Note that mission jump repeat counters are not reset (see MAV_CMD_DO_JUMP param2).

This message may trigger a mission state-machine change on some systems: for example from MISSION_STATE_NOT_STARTED or MISSION_STATE_PAUSED to MISSION_STATE_ACTIVE. If the system is in mission mode, on those systems this command might therefore start, restart or resume the mission. If the system is not in mission mode this message must not trigger a switch to mission mode.

MISSION_CURRENT (42)

Message that announces the sequence number of the current target mission item (that the system will fly towards/execute when the mission is running). This message should be streamed all the time (nominally at 1Hz). This message should be emitted following a call to MAV_CMD_DO_SET_MISSION_CURRENT or MISSION_SET_CURRENT.

MISSION_REQUEST_LIST (43)

Request the overall list of mission items from the system/component.

MISSION_COUNT (44)

This message is emitted as response to MISSION_REQUEST_LIST by the MAV and to initiate a write transaction. The GCS can then request the individual mission item based on the knowledge of the total number of waypoints.

MISSION_CLEAR_ALL (45)

Delete all mission items at once.

MISSION_ITEM_REACHED (46)

A certain mission item has been reached. The system will either hold this position (or circle on the orbit) or (if the autocontinue on the WP was set) continue to the next waypoint.

MISSION_ACK (47)

Acknowledgment message during waypoint handling. The type field states if this message is a positive ack (type=0) or if an error happened (type=non-zero).

SET_GPS_GLOBAL_ORIGIN (48)

Sets the GPS coordinates of the vehicle local origin (0,0,0) position. Vehicle should emit GPS_GLOBAL_ORIGIN irrespective of whether the origin is changed. This enables transform between the local coordinate frame and the global (GPS) coordinate frame, which may be necessary when (for example) indoor and outdoor settings are connected and the MAV should move from in- to outdoor.

GPS_GLOBAL_ORIGIN (49)

Publishes the GPS coordinates of the vehicle local origin (0,0,0) position. Emitted whenever a new GPS-Local position mapping is requested or set - e.g. following SET_GPS_GLOBAL_ORIGIN message.

PARAM_MAP_RC (50)

Bind a RC channel to a parameter. The parameter should change according to the RC channel value.

MISSION_REQUEST_INT (51)

Request the information of the mission item with the sequence number seq. The response of the system to this message should be a MISSION_ITEM_INT message. https://mavlink.io/en/services/mission.html

SAFETY_SET_ALLOWED_AREA (54)

Set a safety zone (volume), which is defined by two corners of a cube. This message can be used to tell the MAV which setpoints/waypoints to accept and which to reject. Safety areas are often enforced by national or competition regulations.

SAFETY_ALLOWED_AREA (55)

Read out the safety zone the MAV currently assumes.

ATTITUDE_QUATERNION_COV (61)

The attitude in the aeronautical frame (right-handed, Z-down, X-front, Y-right), expressed as quaternion. Quaternion order is w, x, y, z and a zero rotation would be expressed as (1 0 0 0).

NAV_CONTROLLER_OUTPUT (62)

The state of the navigation and position controller.

GLOBAL_POSITION_INT_COV (63)

The filtered global position (e.g. fused GPS and accelerometers). The position is in GPS-frame (right-handed, Z-up). It is designed as scaled integer message since the resolution of float is not sufficient. NOTE: This message is intended for onboard networks / companion computers and higher-bandwidth links and optimized for accuracy and completeness. Please use the GLOBAL_POSITION_INT message for a minimal subset.

LOCAL_POSITION_NED_COV (64)

The filtered local position (e.g. fused computer vision and accelerometers). Coordinate frame is right-handed, Z-axis down (aeronautical frame, NED / north-east-down convention)

RC_CHANNELS (65)

The PPM values of the RC channels received. The standard PPM modulation is as follows: 1000 microseconds: 0%, 2000 microseconds: 100%. A value of UINT16_MAX implies the channel is unused. Individual receivers/transmitters might violate this specification.

REQUEST_DATA_STREAM (66)

Request a data stream.

DATA_STREAM (67)

Data stream status information.

MANUAL_CONTROL (69)

Manual (joystick) control message. This message represents movement axes and button using standard joystick axes nomenclature. Unused axes can be disabled and buttons states are transmitted as individual on/off bits of a bitmask. For more information see https://mavlink.io/en/manual_control.html

RC_CHANNELS_OVERRIDE (70)

The RAW values of the RC channels sent to the MAV to override info received from the RC radio. The standard PPM modulation is as follows: 1000 microseconds: 0%, 2000 microseconds: 100%. Individual receivers/transmitters might violate this specification. Note carefully the semantic differences between the first 8 channels and the subsequent channels

MISSION_ITEM_INT (73)

Message encoding a mission item. This message is emitted to announce the presence of a mission item and to set a mission item on the system. The mission item can be either in x, y, z meters (type: LOCAL) or x:lat , y:lon , z:altitude . Local frame is Z-down, right handed (NED), global frame is Z-up, right handed (ENU). NaN or INT32_MAX may be used in float/integer params (respectively) to indicate optional/default values (e.g. to use the component's current latitude, yaw rather than a specific value). See also https://mavlink.io/en/services/mission.html.

VFR_HUD (74)

Metrics typically displayed on a HUD for fixed wing aircraft.

COMMAND_INT (75)

Send a command with up to seven parameters to the MAV, where params 5 and 6 are integers and the other values are floats. This is preferred over COMMAND_LONG as it allows the MAV_FRAME to be specified for interpreting positional information, such as altitude. COMMAND_INT is also preferred when sending latitude and longitude data in params 5 and 6, as it allows for greater precision. Param 5 and 6 encode positional data as scaled integers, where the scaling depends on the actual command value. NaN or INT32_MAX may be used in float/integer params (respectively) to indicate optional/default values (e.g. to use the component's current latitude, yaw rather than a specific value). The command microservice is documented at https://mavlink.io/en/services/command.html