Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Ardupilot/ardupilot/llms.txt

Use this file to discover all available pages before exploring further.

MAVLink (Micro Air Vehicle Link) is the lightweight binary messaging protocol used by ArduPilot to communicate with ground control stations, companion computers, and other autopilots. ArduPilot implements MAVLink 2 by default, with automatic fallback to MAVLink 1 for legacy systems. The protocol defines a fixed message framing structure, a system/component addressing scheme, and a large set of pre-defined message types covering everything from attitude telemetry to mission upload. All MAVLink handling in ArduPilot lives under libraries/GCS_MAVLink/, with the primary class being GCS_MAVLINK in GCS.h. Vehicle-specific subclasses (e.g. GCS_MAVLINK_Copter) override the send and receive methods to handle vehicle-specific messages.

​
Connection methods

ArduPilot exposes MAVLink on any serial port configured with the SERIALn_PROTOCOL parameter set to 1 (MAVLink 1) or 2 (MAVLink 2). Typical configurations:
TransportTypical use
Hardware UARTTelemetry radios (SiK, RFD900) on SERIAL1
USB (SERIAL0)Direct connection to Mission Planner or MAVProxy
UDPSITL, companion computers, networking
TCPLong-range GCS links, Wi-Fi
The baud rate is set by SERIALn_BAUD. Telemetry radios typically operate at 57600 baud; USB connections run at native USB speed (negotiated by the OS).
Up to 8 simultaneous MAVLink channels are supported on boards with sufficient memory (MAVLINK_COMM_NUM_BUFFERS). Each channel maintains its own send buffer, stream rates, and routing state.

​
Heartbeat messages

Every MAVLink participant must emit a HEARTBEAT message at 1 Hz to announce its presence on the bus. ArduPilot sends a heartbeat containing:
  • type — the MAV_TYPE of the vehicle (e.g. MAV_TYPE_QUADROTOR)
  • autopilot — always MAV_AUTOPILOT_ARDUPILOTMEGA
  • base_mode — bitmask including MAV_MODE_FLAG_CUSTOM_MODE_ENABLED and the armed state
  • custom_mode — the numeric flight mode from the vehicle’s mode enum
  • system_status — current MAV_STATE (e.g. MAV_STATE_ACTIVE when flying)
ArduPilot also monitors heartbeats from the GCS (identified by SYSID_MYGCS). If no heartbeat is received for longer than FS_GCS_TIMEOUT seconds the GCS failsafe triggers.

​
Common message types

MessageDirectionPurpose
HEARTBEATBothSystem presence and status
STATUSTEXTVehicle → GCSHuman-readable status and warning text
COMMAND_LONGGCS → VehicleSend a MAV_CMD_* command with up to 7 float parameters
COMMAND_ACKVehicle → GCSAcknowledge a received command and report result
PARAM_REQUEST_LISTGCS → VehicleRequest the full parameter list
PARAM_VALUEVehicle → GCSSend one parameter value (response to request or set)
PARAM_SETGCS → VehicleWrite a parameter value
MISSION_COUNTGCS → VehicleBegin a mission upload with item count
MISSION_ITEM_INTGCS → VehicleOne mission waypoint or command (integer lat/lon)
MISSION_ACKBothAcknowledge mission operation result
ATTITUDEVehicle → GCSRoll, pitch, yaw angles and rates
GLOBAL_POSITION_INTVehicle → GCSLatitude, longitude, altitude, velocity
VFR_HUDVehicle → GCSAirspeed, groundspeed, heading, throttle, altitude
RC_CHANNELSVehicle → GCSRaw RC channel input values
BATTERY_STATUSVehicle → GCSBattery voltage, current, and remaining capacity
SYS_STATUSVehicle → GCSSensor health bitmask and load
SET_MODEGCS → VehicleChange the active flight mode
SET_POSITION_TARGET_GLOBAL_INTGCS → VehicleGuided mode position/velocity target

​
Parameter protocol

ArduPilot implements the full MAVLink parameter protocol:
1

Request

The GCS sends PARAM_REQUEST_LIST. ArduPilot queues all parameters for streaming.
2

Stream

ArduPilot sends successive PARAM_VALUE messages, each containing the parameter name (up to 16 characters, null-padded), its float value, its type, the total count, and an index.
3

Set

To write a value the GCS sends PARAM_SET. ArduPilot validates the name and range, writes the value to EEPROM if valid, and replies with PARAM_VALUE showing the accepted value.
4

Confirm

The GCS compares the echoed value to the requested value. A mismatch indicates a range clamp or an unknown parameter name.

​
Mission protocol

Mission upload uses a request-response handshake: 
GCS → Vehicle:  MISSION_COUNT   (n items, mission type)
Vehicle → GCS:  MISSION_REQUEST_INT  (index 0)
GCS → Vehicle:  MISSION_ITEM_INT     (item 0)
Vehicle → GCS:  MISSION_REQUEST_INT  (index 1)
...
GCS → Vehicle:  MISSION_ITEM_INT     (item n-1)
Vehicle → GCS:  MISSION_ACK          (MAV_MISSION_ACCEPTED)
MISSION_ITEM_INT encodes latitude and longitude as integers (degrees × 10⁷) to avoid floating-point rounding errors in position-critical waypoints.

​
Command protocol

One-shot commands use COMMAND_LONG: 
GCS → Vehicle:  COMMAND_LONG {
  command: MAV_CMD_DO_SET_MODE,
  param1:  MAV_MODE_FLAG_CUSTOM_MODE_ENABLED,
  param2:  5   // LOITER mode number
}
Vehicle → GCS:  COMMAND_ACK {
  command: MAV_CMD_DO_SET_MODE,
  result:  MAV_RESULT_ACCEPTED
}
ArduPilot sends telemetry messages in named stream groups. Each group has a rate parameter SRn_* where n is the channel number (0 = primary GCS link):
Stream groupParameterTypical messages
STREAM_RAW_SENSORSSR0_RAW_SENSRAW_IMU, SCALED_PRESSURE
STREAM_EXTENDED_STATUSSR0_EXT_STATSYS_STATUS, MEMINFO
STREAM_RC_CHANNELSSR0_RC_CHANRC_CHANNELS, SERVO_OUTPUT_RAW
STREAM_POSITIONSR0_POSITIONGLOBAL_POSITION_INT, LOCAL_POSITION_NED
STREAM_EXTRA1SR0_EXTRA1ATTITUDE, SIMSTATE
STREAM_EXTRA2SR0_EXTRA2VFR_HUD
STREAM_EXTRA3SR0_EXTRA3AHRS, HWSTATUS, WIND
Rate values are in Hz. Setting a rate to 0 disables the stream group. The maximum rate is capped internally to 0.8 × SCHED_LOOP_RATE to prevent overloading the scheduler.

​
Sending status text from C++

ArduPilot uses the GCS_SEND_TEXT() macro to emit STATUSTEXT messages to all connected GCS channels. These messages appear as console output in Mission Planner and MAVProxy: 
// Preferred form — broadcasts to all channels
GCS_SEND_TEXT(MAV_SEVERITY_WARNING, "Radio Failsafe");
GCS_SEND_TEXT(MAV_SEVERITY_INFO, "Mode changed to %s", flightmode->name());

// Per-channel form, used inside GCS_MAVLINK methods
gcs().send_text(MAV_SEVERITY_WARNING, "GCS Failsafe Cleared");
Severity levels follow the MAVLink MAV_SEVERITY enum: EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG. MAVLink_routing (libraries/GCS_MAVLink/MAVLink_routing.h) implements the forwarding table that allows messages received on one channel to be relayed to other channels. This supports multi-GCS setups and companion-computer-to-GCS bridging. A routing entry maps a (sysid, compid) pair to the channel on which that component was last seen. MAVLink 2 supports optional HMAC-SHA256 message signing to authenticate traffic and prevent injection attacks. When signing is enabled:
  • Each outbound message includes a 6-byte timestamp and a 6-byte signature derived from the session key.
  • Incoming messages are rejected if the signature does not match.
  • The signing key is exchanged out-of-band (typically by uploading a key file through the GCS).
Signing is configured through GCS_MAVLINK parameters and is disabled by default. It is recommended when the telemetry link is exposed to an untrusted network.
Enabling MAVLink signing on all channels and then losing the key will leave the vehicle unable to accept commands from a GCS. Store the key securely before enabling signing.

Build docs developers (and LLMs) love

Get started for freeTalk to us