ArduPilot MAVLink Communication Protocol: Complete Architecture & Implementation Guide (2026)

Key Takeaways

ArduPilot implements a complete MAVLink 2.0 protocol stack across 33 source files in libraries/GCS_MAVLink/, supporting 8 distinct vehicle types (Copter, Plane, Rover, Sub, Tracker, Blimp, Periph, Dummy)
The message routing system supports up to 20 concurrent routes with automatic route learning from received messages, heartbeat-based route discovery, and per-channel routing masks
Message scheduling uses a 10-bucket deferred system with per-stream rate control (SR0_* parameters) and dynamic interval adjustment via MAV_CMD_SET_MESSAGE_INTERVAL
Parameter protocol operates asynchronously with an I/O timer and thread-safe queues; parameter writes can be locked for safety
Three independent mission item transfer protocols (Waypoints, Fence, Rally) are handled through a shared MissionItemProtocol base class
MAVLink 2.0 signing, FTP file transfer, SERIAL_CONTROL passthrough, HIGH_LATENCY2 satellite mode, and 40+ MAV_CMD commands are all supported
A clearly documented deprecation timeline exists for legacy features like MISSION_REQUEST and AUTOPILOT_VERSION_REQUEST messages

This article is generated from analysis of the ArduPilot master branch source code, providing a comprehensive deep-dive into MAVLink’s complete implementation architecture.

1. MAVLink Overview

MAVLink (Micro Air Vehicle Link) is the lightweight, open-source communication protocol standard for unmanned vehicles. ArduPilot implements the full MAVLink 2.0 protocol stack through its GCS_MAVLink library, supporting:

Dual MAVLink 1.0 and 2.0 protocol coexistence with automatic negotiation
Multi-channel concurrent communication (up to 16 channels in SITL, 5-8 on embedded hardware)
Message routing and forwarding (up to 20 routing table entries)
MAVLink 2.0 signing (security authentication)
MAVLink FTP file transfer protocol
HIGH_LATENCY2 (satellite/high-latency link support)
SERIAL_CONTROL (serial port passthrough)
CAN over MAVLink (CAN bus forwarding)

1.1 MAVLink Submodules

MAVLink header files are included as a Git submodule:

modules/mavlink/├── mavlink/ # MAVLink 协议定义和代码生成├── pymavlink/ # Python MAVLink 库└── mavnative/ # C 原生 MAVLink 加速

ArduPilot uses include/mavlink/v2.0/ardupilotmega.xml as its message definition, which contains ArduPilot-specific extended messages.

2. Code Architecture

2.1 File Organization

libraries/GCS_MAVLink/# 核心 MAVLink 库 (33 个文件)├── GCS.h# 核心类定义：GCS_MAVLINK 和 GCS 类├── GCS.cpp# GCS 全局实现├── GCS_Common.cpp# 消息处理分发 (245KB，最大文件)├── GCS_MAVLink.h# MAVLink 头文件包装├── GCS_MAVLink.cpp# 通道缓冲区管理├── GCS_config.h# 编译时功能开关├── GCS_MAVLink_Parameters.cpp# 流速率参数定义├── GCS_Param.cpp# 参数协议处理├── GCS_FTP.h / .cpp# MAVLink FTP 子协议├── GCS_Signing.cpp# MAVLink2 签名实现├── GCS_serial_control.cpp# SERIAL_CONTROL 处理├── GCS_DeviceOp.cpp# DEVICE_OP 远程 I2C/SPI 访问├── GCS_Fence.cpp# 围栏状态处理├── GCS_ServoRelay.cpp# 舵机/继电器命令├── MAVLink_routing.h / .cpp# 消息路由表实现├── ap_message.h# 内部消息 ID 枚举 (MSG_*)├── MissionItemProtocol.h/.cpp# 任务项传输协议基类├── MissionItemProtocol_Waypoints.h/.cpp# 航点协议├── MissionItemProtocol_Fence.h/.cpp# 围栏协议├── MissionItemProtocol_Rally.h/.cpp# Rally 点协议├── GCS_Dummy.h / .cpp# 测试桩└── examples/routing/# 路由示例

2.2 Class Hierarchy

GCS (全局单例)├── _chan[MAVLINK_COMM_NUM_BUFFERS] → GCS_MAVLINK 对象数组│├── 车辆特定子类:│ ├── GCS_Copter : GCS (ArduCopter/GCS_Copter.h)│ ├── GCS_Plane : GCS (ArduPlane/GCS_Plane.h)│ ├── GCS_Rover : GCS (Rover/GCS_Rover.h)│ ├── GCS_Sub : GCS (ArduSub/GCS_Sub.h)│ ├── GCS_Tracker : GCS (AntennaTracker/GCS_Tracker.h)│ ├── GCS_Blimp : GCS (Blimp/GCS_Blimp.h)│ ├── GCS_Periph : GCS (Tools/AP_Periph/)│ └── GCS_Dummy : GCS (用于工具/测试)│└── GCS_MAVLINK (单通道 MAVLink 后端) ├── GCS_MAVLINK_Copter : GCS_MAVLINK ├── GCS_MAVLINK_Plane : GCS_MAVLINK ├── GCS_MAVLINK_Rover : GCS_MAVLINK ├── GCS_MAVLINK_Sub : GCS_MAVLINK ├── GCS_MAVLINK_Tracker : GCS_MAVLINK ├── GCS_MAVLINK_Blimp : GCS_MAVLINK ├── GCS_MAVLINK_Periph : GCS_MAVLINK └── GCS_MAVLINK_Dummy : GCS_MAVLINK

全局单例：管理所有 MAVLink 通道
参数：SYSID_THISMAV、MAV_GCS_SYSID、MAV_OPTIONS、MAV_TELEM_DELAY
Statustext 队列：容量 10-30 条，线程安全
传感器状态：维护 present/enabled/health 三个 32 位掩码
串口透传：管理 UART 转发
高延迟：启用/管理高延迟连接
单通道管理：每个 UART 端口对应一个实例
消息接收/解码/路由
消息发送调度（bucket 系统）
流速率控制 (10 个数据流)
参数协议处理
签名管理
心跳生成

3. Protocol Version & Configuration

3.1 MAVLink 1.0 vs 2.0

// 协议版本自动协商bool GCS_MAVLINK::sending_mavlink1() const; // 数据包开销static uint8_t packet_overhead_chan(mavlink_channel_t chan);

ArduPilot sends MAVLink 2.0 frames by default. If the remote end only supports MAVLink 1.0, it automatically downgrades. Buffer space is checked before sending via the HAVE_PAYLOAD_SPACE macro:

#define PAYLOAD_SIZE(chan, id) \ (unsigned(GCS_MAVLINK::packet_overhead_chan(chan) + MAVLINK_MSG_ID_ ## id ## _LEN)) #define HAVE_PAYLOAD_SPACE(_chan, id) \ (comm_get_txspace(_chan) >= PAYLOAD_SIZE(_chan, id) ? true : \ (gcs_out_of_space_to_send(_chan), false))

3.2 Channel Configuration

// 根据硬件平台动态调整通道数#if CONFIG_HAL_BOARD == HAL_BOARD_SITL#define MAVLINK_COMM_NUM_BUFFERS 16 // SITL: 16通道#elif HAL_PROGRAM_SIZE_LIMIT_KB > 1024#define MAVLINK_COMM_NUM_BUFFERS 8 // 大内存平台: 8通道#else#define MAVLINK_COMM_NUM_BUFFERS 5 // 标准嵌入式: 5通道#endif

3.3 Channel Options

enum class Option : uint16_t { MAVLINK2_SIGNING_DISABLED = (1U << 0), // 禁用手动签名 NO_FORWARD = (1U << 1), // 禁止路由转发 NOSTREAMOVERRIDE = (1U << 2), // 忽略 GCS 速率覆盖 FORWARD_BAD_CRC = (1U << 3), // 转发 CRC 错误包};

主要参数：

SYSID_THISMAV — 本机系统 ID
MAV_GCS_SYSID — 期望的 GCS 系统 ID
MAV_OPTIONS — GCS_SYSID_ENFORCE 强制 GCS sysid 检查

4. Message Routing System

4.1 Routing Architecture

The routing system is implemented by the MAVLink_routing class (MAVLink_routing.h/.cpp), with this core structure:

#define MAVLINK_MAX_ROUTES 20 struct route { uint8_t sysid; // 目标系统 ID uint8_t compid; // 目标组件 ID mavlink_channel_t channel; // 到达目标的通道 uint8_t mavtype; // MAV_TYPE (如 MAV_TYPE_GCS)};

4.2 Routing Decision Flow

GCS::update_receive() └── 遍历所有 GCS_MAVLINK 通道 └── GCS_MAVLINK::update_receive() └── 从 UART 读取字节 └── mavlink_parse_char() 解码 └── 成功 → raw_packetReceived() └── MAVLink_routing::check_and_forward() ├── 检查 framing_status (OK/BAD_CRC/BAD_SIGNATURE) ├── learn_route() — 学习发送者路由 ├── handle_heartbeat() — 特殊心跳处理 └── forward() — 根据目标决定转发 └── packetReceived() (虚函数) └── handle_message() — 消息分发

4.3 Forwarding Decision Rules

// ========== 转发决策规则 (check_and_forward / forward) ========== // ---- 本地处理 (不转发) ----if (!msg_has_target_system(msg)) // 1. 消息不含 target_system 字段 return HANDLE_LOCAL; if (msg.target_system == 0) // 2. target_system == 0 (广播到所有) return HANDLE_LOCAL; if (msg.target_system == my_sysid && !msg_has_target_component(msg)) // 3. target_system == 本机 sysid 且无 target_component return HANDLE_LOCAL; if (msg.target_system == my_sysid && msg.target_component == my_compid) // 4. target_system/compid 都指向本机 return HANDLE_LOCAL; if (msg.target_system == my_sysid && !route_seen(msg.sysid, msg.compid)) // 5. 对端 sysid/compid 组合未见过 return HANDLE_LOCAL; // ---- 转发到其他链路 ----if (!msg_has_target_system(msg) || msg.target_system == 0) { broadcast_to_all_except_source(); // 无目标或广播 → 所有非源通道 } else if (msg.target_system != my_sysid && route_known(msg.target_system)) { unicast_to_route(msg.target_system); // 目标非本机且路由已知 → 单播 } else if (msg.target_system == my_sysid && msg.target_component != my_compid) { lookup_and_forward(msg.target_component); // 本机系统但不同组件 → 查路由表转发}

4.4 Heartbeat Special Handling

Heartbeat messages bypass the regular routing logic:

通过所有非私有通道广播
排除已知源通道 (避免回环)
自动学习路由表

4.5 Routing Mask

// 屏蔽特定通道的路由转发static void disable_channel_routing(mavlink_channel_t chan);// no_route_mask 位掩码阻止该通道被转发

5. Message Scheduling & Send Mechanism

5.1 Bucket Scheduling System

ArduPilot uses the deferred message bucket system to schedule outgoing messages:

// 延迟消息桶 (10 个桶)struct deferred_message_bucket_t { Bitmask ap_message_ids; // 该桶中的消息 ID 集合 uint16_t interval_ms; // 发送间隔 uint16_t last_sent_ms; // 上次发送时间};deferred_message_bucket_t deferred_message_bucket[10];

Special messages (not subject to stream rate control):

struct deferred_message_t { const ap_message id; uint16_t interval_ms; uint16_t last_sent_ms;} deferred_message[3] = { { MSG_HEARTBEAT, }, { MSG_NEXT_PARAM, }, { MSG_HIGH_LATENCY2, }, // 仅当 HIGH_LATENCY2 启用};

5.2 Message Send Timing

GCS::update_send() └── 轮转 first_backend_to_send (防止饥渴) └── 遍历所有活跃通道 └── GCS_MAVLINK::update_send() ├── 检查调度器剩余时间 > min_loop_time_remaining ├── 优先发送 pushed 消息 (HEARTBEAT 等) ├── 发送 deferred message (非流控消息) └── 发送 bucket 中的流控消息 ├── find_next_bucket_to_send() ├── 按速率依次发送 └── 缓冲区满 → stream_slowdown 降速

5.3 Stream Rate Control

10 个标准遥测数据流：

enum streams : uint8_t { STREAM_RAW_SENSORS, // IMU、GPS 等原始传感器 STREAM_EXTENDED_STATUS, // 扩展状态 STREAM_RC_CHANNELS, // RC 通道值 STREAM_RAW_CONTROLLER, // 控制器原始输出 STREAM_POSITION, // 位置信息 STREAM_EXTRA1, // 额外数据 1 STREAM_EXTRA2, // 额外数据 2 STREAM_EXTRA3, // 额外数据 3 STREAM_PARAMS, // 参数流 STREAM_ADSB, // ADS-B 数据 NUM_STREAMS};

每个流有对应的 SRx_* 参数控制速率（Hz）。

5.4 Messages per Stream

每个流包含一组内部消息 ID，定义在 all_stream_entries[] 中：

// ========== 各流包含的消息 ========== STREAM_RAW_SENSORS // RAW_IMU, SCALED_IMU2/3, SCALED_PRESSURE2/3, BARO, // AHRS2, SYS_STATUS, POWER_STATUS, MEMINFO, MCU_STATUS, // ATTITUDE, ATTITUDE_QUATERNION, MAG_CAL_REPORT, // BATTERY2, AIRSPEED STREAM_EXTENDED_STATUS // SYS_STATUS, POWER_STATUS, MEMINFO, CURRENT_WAYPOINT, // GPS_RAW, GPS_RTK, GPS2_RAW, GPS2_RTK, // NAV_CONTROLLER_OUTPUT, FENCE_STATUS STREAM_POSITION // GLOBAL_POSITION_INT, LOCAL_POSITION, // HOME_POSITION, GPS_GLOBAL_ORIGIN STREAM_RC_CHANNELS // RC_CHANNELS, RC_CHANNELS_RAW, SERVO_OUTPUT_RAW STREAM_RAW_CONTROLLER // RC_CHANNELS STREAM_EXTRA1 // ATTITUDE, SIMSTATE, AHRS2, PID_TUNING, RANGEFINDER STREAM_EXTRA2 // VFR_HUD STREAM_EXTRA3 // AHRS, SYSTEM_TIME, RANGEFINDER, WIND, // DISTANCE_SENSOR, BATTERY2 STREAM_PARAMS // NEXT_PARAM STREAM_ADSB // ADSB_VEHICLE, UAVIONIX_ADSB_OUT_STATUS

5.5 Stream Rate Parameters

参数格式：SR0_* 到 SRn_*，其中 n 对应通道号：

SR0_RAW_SENSORS → 原始传感器流频率 (Hz)SR0_EXT_STAT → 扩展状态流频率SR0_RC_CHAN → RC 通道流频率SR0_RAW_CTRL → 原始控制流频率SR0_POSITION → 位置流频率SR0_EXTRA1 → 额外数据 1 频率SR0_EXTRA2 → 额外数据 2 频率SR0_EXTRA3 → 额外数据 3 频率SR0_PARAMS → 参数流频率SR0_ADSB → ADS-B 流频率

默认流速率在 GCS_MAVLink_Parameters.cpp 中定义：

// default_rates[]: {RAW_SENSORS, EXT_STAT, RC_CHAN, RAW_CTRL, POSITION, EXTRA1, EXTRA2, EXTRA3, PARAMS, ADSB}const uint8_t default_rates[GCS_MAVLINK::NUM_STREAMS] = { MAVLINK_STREAM_RAW_SENSORS_DEFAULT_RATE, // 2 Hz MAVLINK_STREAM_EXTENDED_STATUS_DEFAULT_RATE, // 2 Hz MAVLINK_STREAM_RC_CHANNELS_DEFAULT_RATE, // 5 Hz MAVLINK_STREAM_RAW_CONTROLLER_DEFAULT_RATE, // 0 Hz (Copter/Rover) or 5 Hz (Plane) MAVLINK_STREAM_POSITION_DEFAULT_RATE, // 2 Hz (Copter/Rover) or 3 Hz (Plane) MAVLINK_STREAM_EXTRA1_DEFAULT_RATE, // 5 Hz (Copter) or 10 Hz (Plane/Rover) MAVLINK_STREAM_EXTRA2_DEFAULT_RATE, // 5 Hz (Copter) or 10 Hz (Plane/Rover) MAVLINK_STREAM_EXTRA3_DEFAULT_RATE, // 2 Hz (Copter) or 3 Hz (Plane/Rover) MAVLINK_STREAM_PARAMS_DEFAULT_RATE, // 50 Hz (高优先级) MAVLINK_STREAM_ADSB_DEFAULT_RATE, // 0 Hz};

5.6 Dynamic Message Interval Control

支持通过 MAVLink 命令动态调整消息间隔：

// MAV_CMD_SET_MESSAGE_INTERVAL — 设置特定消息的发送间隔MAV_RESULT set_message_interval(uint32_t msg_id, int32_t interval_us); // MAV_CMD_REQUEST_MESSAGE — 请求单次消息MAV_RESULT handle_command_request_message(const mavlink_command_int_t &packet);

5.7 Loading Interval Config from File

如果启用 HAL_MAVLINK_INTERVALS_FROM_FILES_ENABLED，可以从 SD 卡/ROMFS 加载消息间隔配置文件：

APM/MAVLink/message_interval.cfg — SD 卡配置@ROMFS/message_interval.cfg — ROMFS 配置

文件格式：每行 mavlink_message_id interval_ms

6. Message Reception & Processing

6.1 handle_message() — Core Dispatch Function

消息在 GCS_Common.cpp 的 handle_message() 中通过 switch(msg.msgid) 分发到各处理函数：

void GCS_MAVLINK::handle_message(const mavlink_message_t &msg) { switch (msg.msgid) { case MAVLINK_MSG_ID_HEARTBEAT: handle_heartbeat(msg); break; case MAVLINK_MSG_ID_RC_CHANNELS_OVERRIDE: handle_rc_channels_override(msg); break; case MAVLINK_MSG_ID_PARAM_REQUEST_LIST: handle_param_request_list(msg); break; case MAVLINK_MSG_ID_PARAM_SET: handle_param_set(msg); break; case MAVLINK_MSG_ID_COMMAND_LONG: handle_command_long(msg); break; case MAVLINK_MSG_ID_COMMAND_INT: handle_command_int(msg); break; case MAVLINK_MSG_ID_MISSION_WRITE_PARTIAL_LIST: handle_mission_write_partial_list(msg); break; // ... 80+ 消息类型 }}

6.2 Message Category Overview

// ========== 消息分类总览 ========== 系统控制 // HEARTBEAT, SET_MODE, STATUSTEXT, PING, SYSTEM_TIME参数 // PARAM_REQUEST_LIST, PARAM_REQUEST_READ, PARAM_SET, PARAM_VALUE任务 // MISSION_REQUEST_LIST, MISSION_REQUEST_INT, MISSION_COUNT, // MISSION_ITEM, MISSION_WRITE_PARTIAL_LIST, MISSION_CLEAR_ALL, MISSION_ACK命令 // COMMAND_LONG, COMMAND_INT, COMMAND_ACKRC 控制 // RC_CHANNELS_OVERRIDE, MANUAL_CONTROL, RADIO_RC_CHANNELS, RC_CHANNELS遥测 // RADIO_STATUS, DISTANCE_SENSOR, OBSTACLE_DISTANCE视觉 // VISION_POSITION_ESTIMATE, GLOBAL_VISION_POSITION_ESTIMATE, // ATT_POS_MOCAP, ODOMETRY, LANDING_TARGET, VISION_SPEED_ESTIMATE, // VICON_POSITION_ESTIMATE, VISION_POSITION_DELTA传感器 // OPTICAL_FLOW, DISTANCE_SENSOR, OBSTACLE_DISTANCE, OBSTACLE_DISTANCE_3D安全 // ADSB_VEHICLE, SETUP_SIGNING设备 // SERIAL_CONTROL, DEVICE_OP_READ, DEVICE_OP_WRITE相机/云台 // 通过 MOUNT 和 CAMERA 相关消息处理其他 // TIMESYNC, NAMED_VALUE_FLOAT, OSD_PARAM_CONFIG, // FILE_TRANSFER_PROTOCOL, DATA_PACKET

6.3 Command Handling (COMMAND_LONG / COMMAND_INT)

// COMMAND_LONG 自动转换为 COMMAND_INT 处理void handle_command_long(const mavlink_message_t &msg);void handle_command_int(const mavlink_message_t &msg); // COMMAND_INT 各子命令处理handle_command_int_packet() { switch (packet.command) { case MAV_CMD_COMPONENT_ARM_DISARM: // 解锁/上锁 case MAV_CMD_DO_SET_HOME: // 设置 Home 点 case MAV_CMD_NAV_TAKEOFF: // 起飞 case MAV_CMD_NAV_LAND: // 降落 case MAV_CMD_DO_SET_MODE: // 切换模式 case MAV_CMD_DO_FLIGHTTERMINATION: // 紧急停机 case MAV_CMD_PREFLIGHT_CALIBRATION: // 校准 case MAV_CMD_PREFLIGHT_REBOOT_SHUTDOWN:// 重启 case MAV_CMD_SET_MESSAGE_INTERVAL: // 设置消息间隔 case MAV_CMD_REQUEST_MESSAGE: // 请求消息 case MAV_CMD_DO_FENCE_ENABLE: // 围栏使能 case MAV_CMD_DO_SET_ROI: // 设置兴趣点 case MAV_CMD_DO_GRIPPER: // 夹爪 case MAV_CMD_DO_SPRAYER: // 喷洒 case MAV_CMD_DO_AUX_FUNCTION: // 辅助功能 case MAV_CMD_DO_FOLLOW: // Follow-me case MAV_CMD_CAN_FORWARD: // CAN 转发 case MAV_CMD_RUN_PREARM_CHECKS: // 预解锁检查 case MAV_CMD_FLASH_BOOTLOADER: // 烧写 Bootloader // ... 40+ 命令 }}

7. Parameter Protocol

7.1 Overview

The parameter protocol is implemented in GCS_Param.cpp, operating flight controller parameters through the following MAVLink messages:

// ========== 参数协议消息 ========== PARAM_REQUEST_LIST // 请求所有参数列表PARAM_REQUEST_READ // 读取单个参数PARAM_SET // 设置参数值PARAM_VALUE // 参数值响应

7.2 Async Parameter I/O

Parameter read/write operates asynchronously via an I/O timer:

static bool param_timer_registered; // IO 定时器注册标志void param_io_timer(void); // IO 定时器回调 // 请求和响应队列static ObjectBuffer param_requests;static ObjectBuffer param_replies;

7.3 Parameter Send Flow

GCS 请求 PARAM_REQUEST_LIST └── handle_param_request_list(msg) └── 遍历所有 AP_Param 条目 └── 加入 param_replies 队列 └── param_io_timer() 定时发送 └── send_parameter_value(name, type, value)

7.4 Parameter Set Safety Mechanism

// 全局控制：是否允许通过 MAVLink 设置参数bool get_allow_param_set() const;void set_allow_param_set(bool new_allowed); // 参数错误响应enum MAV_PARAM_ERROR { MAV_PARAM_ERROR_NONE, // 成功 MAV_PARAM_ERROR_INVALID_TYPE, // 类型错误 // ...};

8. Mission Protocol

8.1 Protocol Types

Three independent transfer protocols are handled through MissionItemProtocol:

// ========== 协议类型与对应类 ========== 航点 MAV_MISSION_TYPE_MISSION MissionItemProtocol_Waypoints围栏 MAV_MISSION_TYPE_FENCE MissionItemProtocol_FenceRally点 MAV_MISSION_TYPE_RALLY MissionItemProtocol_Rally

8.2 Mission Message Handling

// 任务列表操作handle_mission_request_list(msg); // MISSION_REQUEST_LISThandle_mission_count(msg); // MISSION_COUNThandle_mission_request_int(msg); // MISSION_REQUEST_INThandle_mission_item(msg); // MISSION_ITEM_INThandle_mission_write_partial_list(msg); // MISSION_WRITE_PARTIAL_LISThandle_mission_clear_all(msg); // MISSION_CLEAR_ALL

8.3 Transfer Protocol Base Class

// MissionItemProtocol.hclass MissionItemProtocol { // 核心方法 void handle_mission_request_list(...); void handle_mission_count(...); void handle_mission_request_int(...); void handle_mission_item(...); void queued_request_send(); // 发送队列中的任务请求 bool active() const; // 是否有活跃的传输};

9. MAVLink FTP File Transfer

9.1 Overview

MAVLink FTP implements the FILE_TRANSFER_PROTOCOL message, enabling remote file system access over MAVLink.

Compile flag: AP_MAVLINK_FTP_ENABLED

Files: GCS_FTP.h / GCS_FTP.cpp

9.2 Architecture

class GCS_FTP { // 单例模式 static GCS_FTP *ftp;
 // 最多 5 个并发会话 Session sessions[AP_MAVLINK_FTP_MAX_SESSIONS]; // 默认 5
 // 请求队列 ObjectBuffer requests{AP_MAVLINK_FTP_MAX_SESSIONS};};

9.3 Supported Operations

enum class FTP_OP : uint8_t { None, // 无操作 TerminateSession,// 终止会话 ResetSessions, // 重置所有会话 ListDirectory, // 列出目录 OpenFileRO, // 只读打开文件 ReadFile, // 读取文件 CreateFile, // 创建文件 WriteFile, // 写入文件 RemoveFile, // 删除文件 CreateDirectory, // 创建目录 RemoveDirectory, // 删除目录 OpenFileWO, // 只写打开文件 TruncateFile, // 截断文件 Rename, // 重命名 CalcFileCRC32, // 计算 CRC32 BurstReadFile, // 突发读取 Ack, // 确认 Nack, // 否认};

9.4 Workflow

GCS 发送 FILE_TRANSFER_PROTOCOL └── handle_file_transfer_protocol(msg, chan) └── 加入请求队列 └── worker() 异步处理 ├── 验证 session ├── 执行文件操作 └── 发送响应 (Ack/Nack + 数据)

9.5 Error Codes

enum class FTP_ERROR : uint8_t { None, // 无错误 Fail, // 通用失败 FailErrno, // 系统错误 (含 errno) InvalidDataSize, // 数据大小无效 InvalidSession, // 会话无效 NoSessionsAvailable, // 无可用会话 EndOfFile, // 文件结束 UnknownCommand, // 未知命令 FileExists, // 文件已存在 FileProtected, // 文件受保护 FileNotFound, // 文件未找到};

10. Signing & Security

10.1 Overview

MAVLink 2.0 signing is implemented in GCS_Signing.cpp. Compile flag: AP_MAVLINK_SIGNING_ENABLED.

10.2 Signing Management

#if AP_MAVLINK_SIGNING_ENABLED mavlink_signing_t signing; // 签名结构 static mavlink_signing_streams_t signing_streams; // 签名流 static uint32_t last_signing_save_ms; // 上次保存时间
 // 存储访问 static StorageAccess _signing_storage; static bool signing_key_save(const struct SigningKey &key); static bool signing_key_load(struct SigningKey &key);
 // 签名操作 void load_signing_key(void); bool signing_enabled(void) const; static void save_signing_timestamp(bool force_save_now); static void update_signing_timestamp(uint64_t timestamp_usec);#endif

10.3 SETUP_SIGNING Flow

GCS 发送 SETUP_SIGNING └── handle_setup_signing(msg) ├── 读取初始时间戳 ├── 加载/保存签名密钥 └── 启用签名

签名密钥持久化存储在飞控存储区中。

11. SERIAL_CONTROL Serial Passthrough

11.1 Function

GCS_serial_control.cpp implements SERIAL_CONTROL message handling, allowing GCS to remotely operate serial devices on the flight controller via MAVLink (e.g., configuring telemetry modules, RTK GPS, etc.).

11.2 Flags

// SERIAL_CONTROL_FLAGSERIAL_CONTROL_FLAG_REPLY // 回复标志SERIAL_CONTROL_FLAG_RESPOND // 要求响应SERIAL_CONTROL_FLAG_EXCLUSIVE // 独占模式SERIAL_CONTROL_FLAG_BLOCKING // 阻塞模式SERIAL_CONTROL_FLAG_MULTI // 多设备

11.3 Exclusive Mode

当 SERIAL_CONTROL 设置独占模式时，对应的 MAVLink 通道会被锁定：

void lock(bool _lock) { _locked = _lock;}

A locked channel no longer processes MAVLink messages and is dedicated to passthrough.

12. High Latency Mode (HIGH_LATENCY2)

12.1 Overview

The HIGH_LATENCY2 message is designed for satellite/HF high-latency links (extremely low bandwidth, high latency), with a single message containing all critical flight data.

Compile flag: HAL_HIGH_LATENCY2_ENABLED

12.2 HIGH_LATENCY2 Message Fields

void send_high_latency2() const; // 发送高延迟消息 // 车辆需重写的辅助函数virtual int16_t high_latency_target_altitude() const;virtual uint8_t high_latency_tgt_heading() const;virtual uint16_t high_latency_tgt_dist_dam() const;virtual uint8_t high_latency_tgt_airspeed() const;virtual uint8_t high_latency_wind_speed() const;virtual uint8_t high_latency_wind_direction() const;

12.3 High Latency Control

// CONTROL_HIGH_LATENCY 命令处理MAV_RESULT handle_control_high_latency(const mavlink_command_int_t &packet); // 全局管理void enable_high_latency_connections(bool enabled);bool get_high_latency_status();

13. Compile-Time Configuration Options

All feature toggles are defined in GCS_config.h:

// ========== 编译时配置选项 ========== HAL_GCS_ENABLED 1 全局 GCS 开关HAL_MAVLINK_BINDINGS_ENABLED HAL_GCS_ENABLED MAVLink 绑定AP_MAVLINK_SIGNING_ENABLED HAL_GCS_ENABLED 签名支持HAL_HIGH_LATENCY2_ENABLED 1 高延迟模式AP_MAVLINK_FTP_ENABLED HAL_GCS_ENABLED FTP 文件传输AP_MAVLINK_MSG_SERIAL_CONTROL_ENABLED HAL_GCS_ENABLED 串口控制AP_MAVLINK_MSG_DEVICE_OP_ENABLED HAL_GCS_ENABLED 设备 I2C/SPI 操作AP_MAVLINK_SERVO_RELAY_ENABLED HAL_GCS_ENABLED && 舵机/继电器 AP_SERVORELAYEVENTS_ENABLEDAP_MAVLINK_COMMAND_LONG_ENABLED 1 COMMAND_LONG 支持AP_MAVLINK_MSG_MISSION_REQUEST_ENABLED AP_MISSION_ENABLED MISSION_REQUEST (旧版)AP_MAVLINK_MSG_RANGEFINDER_SENDING_ENABLED AP_RANGEFINDER_ENABLED RANGEFINDER 消息AP_MAVLINK_MSG_HIGHRES_IMU_ENABLED >1024KB flash HIGHRES_IMUAP_MAVLINK_MSG_FLIGHT_INFORMATION_ENABLED HAL_GCS_ENABLED && 飞行信息 AP_ARMING_ENABLEDAP_MAVLINK_MAV_CMD_GET_HOME_POSITION.. AP_AHRS_ENABLED GET_HOME_POSITION (即将移除)AP_MAVLINK_AUTOPILOT_VERSION_REQUEST.. SITL only 旧版版本请求 (即将移除)AP_MAVLINK_UTM_GLOBAL_POSITION_SENDING.. >2048KB flash UTM 位置AP_MAVLINK_FAILURE_CREATION_ENABLED 1 开发者故障注入AP_MAVLINK_SET_GPS_GLOBAL_ORIGIN.. HAL_GCS_ENABLED && GPS 原点设置消息 (即将移除) AP_AHRS_ENABLEDHAL_MAVLINK_INTERVALS_FROM_FILES_ENABLED 文件系统 + >1024KB flash 从文件加载消息间隔

13.1 Deprecation Timeline

ArduPilot has a clear deprecation plan for legacy MAVLink features:

// ========== 废弃时间线 ==========// 4.5 4.8 4.9 4.10MISSION_REQUEST 默认开启 默认编译排除 代码移除 停止警告AUTOPILOT_VERSION.. 可编译排除 默认编译排除 代码移除 ---MAV_CMD_REQUEST_.. 可编译排除 默认编译排除 代码移除 ---MAV_CMD_GET_HOME.. 默认开启 可编译排除 默认排除 代码移除RANGEFINDER 正常 默认停止发送 代码移除 ---SET_GPS_GLOBAL_ORIGIN 正常 开始警告 继续警告 默认排除MISSION_SET_CURRENT 正常 --- --- ---

14. Internal Message ID Enumeration

Defined in ap_message.h for internal message scheduling. MSG_LAST marks the end of the enum (currently ~120 IDs).

14.1 Core Messages (Partial)

enum ap_message : uint8_t { MSG_HEARTBEAT = 0, MSG_AHRS = 1, MSG_AHRS2 = 2, MSG_ATTITUDE = 3, MSG_ATTITUDE_QUATERNION = 4, MSG_LOCATION = 5, MSG_VFR_HUD = 6, MSG_SYS_STATUS = 7, MSG_POWER_STATUS = 8, MSG_MEMINFO = 9, MSG_NAV_CONTROLLER_OUTPUT = 10, MSG_CURRENT_WAYPOINT = 11, MSG_SERVO_OUTPUT_RAW = 12, MSG_RC_CHANNELS = 13, MSG_RC_CHANNELS_RAW = 14, MSG_RAW_IMU = 15, MSG_SCALED_IMU = 16, MSG_SCALED_IMU2 = 17, MSG_SCALED_IMU3 = 18, MSG_SCALED_PRESSURE = 19, MSG_SCALED_PRESSURE2 = 20, MSG_SCALED_PRESSURE3 = 21, MSG_GPS_RAW = 22, MSG_GPS_RTK = 23, MSG_GPS2_RAW = 24, MSG_GPS2_RTK = 25, MSG_SYSTEM_TIME = 26, MSG_NEXT_MISSION_REQUEST_WAYPOINTS = 28, MSG_NEXT_MISSION_REQUEST_RALLY = 29, MSG_NEXT_MISSION_REQUEST_FENCE = 30, MSG_NEXT_PARAM = 31, MSG_FENCE_STATUS = 32, MSG_SIMSTATE = 33, MSG_SIM_STATE = 34, MSG_WIND = 36, // ... 相机/云台 ... MSG_CAMERA_FEEDBACK = 42, MSG_CAMERA_INFORMATION = 43, MSG_CAMERA_SETTINGS = 44, MSG_CAMERA_FOV_STATUS = 45, MSG_CAMERA_CAPTURE_STATUS = 46, MSG_CAMERA_THERMAL_RANGE = 47, MSG_GIMBAL_DEVICE_ATTITUDE_STATUS = 48, MSG_GIMBAL_MANAGER_INFORMATION = 49, MSG_GIMBAL_MANAGER_STATUS = 50, // ... 其他 ... MSG_HIGH_LATENCY2 = 78, MSG_MCU_STATUS = 90, MSG_ATTITUDE_TARGET = 92, MSG_HIGHRES_IMU = 96, MSG_AIRSPEED = 97, MSG_AVAILABLE_MODES = 98, MSG_AVAILABLE_MODES_MONITOR = 99, MSG_FLIGHT_INFORMATION = 100, MSG_LAST // 枚举结束标记};

14.2 Design Principles

Each MSG_* corresponds to one MAVLink message, ensuring non-blocking sends
For multiple messages of the same type, create new MSG_ IDs
Compile flags control message inclusion (e.g., AP_MAVLINK_MSG_HIGHRES_IMU_ENABLED)

15. Heartbeat & System Status

15.1 Heartbeat Message

心跳是最高优先级的系统消息，不受流速率控制：

// 发送频率通过 deferred_message 固定void send_heartbeat(void) const; // 心跳包含的关键信息// - type: MAV_TYPE (如 MAV_TYPE_QUADROTOR)// - autopilot: MAV_AUTOPILOT_ARDUPILOTMEGA// - base_mode: 是否解锁、自定义模式等// - custom_mode: 车辆特定模式 (如 Copter::ALT_HOLD)// - system_status: MAV_STATE (如 MAV_STATE_ACTIVE)

15.2 Heartbeat Reception

void handle_heartbeat(const mavlink_message_t &msg);

When a heartbeat is received:

15.3 System Status

// 由车辆子类实现virtual MAV_STATE vehicle_system_status() const = 0; // 状态枚举enum MAV_STATE { MAV_STATE_UNINIT, // 未初始化 MAV_STATE_BOOT, // 启动中 MAV_STATE_CALIBRATING, // 校准中 MAV_STATE_STANDBY, // 待命 MAV_STATE_ACTIVE, // 活跃 MAV_STATE_CRITICAL, // 危急 MAV_STATE_EMERGENCY, // 紧急 MAV_STATE_POWEROFF, // 断电 MAV_STATE_FLIGHT_TERMINATION, // 终止飞行};

16. Camera & Gimbal Protocol

16.1 Camera Messages

ArduPilot sends the following camera-related MAVLink messages:

// ========== 相机消息 ========== CAMERA_FEEDBACK // 相机拍照/录像反馈CAMERA_INFORMATION // 相机设备信息CAMERA_SETTINGS // 相机当前设置CAMERA_FOV_STATUS // 视场角状态CAMERA_CAPTURE_STATUS // 拍摄状态CAMERA_THERMAL_RANGE // 热成像范围

16.2 Gimbal Messages

// ========== 云台消息 ========== GIMBAL_DEVICE_ATTITUDE_STATUS // 云台姿态GIMBAL_MANAGER_INFORMATION // 云台管理器信息GIMBAL_MANAGER_STATUS // 云台管理器状态

16.3 Gimbal Control Commands

#if HAL_MOUNT_ENABLED void handle_mount_message(const mavlink_message_t &msg); virtual MAV_RESULT handle_command_mount(const mavlink_command_int_t &packet,  const mavlink_message_t &msg);#endif

17. Command Processing System

17.1 Command Types

Two command message formats are supported:

COMMAND_LONG — 传统命令格式（通过 try_command_long_as_command_int 转换为 COMMAND_INT）
COMMAND_INT — 扩展命令格式（推荐使用）

17.2 Main Command List

// ========== 主要命令列表 ========== MAV_CMD_COMPONENT_ARM_DISARM // handle_command_component_arm_disarm // 解锁/上锁MAV_CMD_DO_SET_HOME // handle_command_do_set_home // 设置 HomeMAV_CMD_NAV_TAKEOFF // 车辆特定 // 起飞MAV_CMD_NAV_LAND // 车辆特定 // 降落MAV_CMD_DO_SET_MODE // handle_command_do_set_mode // 切换模式MAV_CMD_DO_FLIGHTTERMINATION // handle_flight_termination // 紧急停机MAV_CMD_PREFLIGHT_CALIBRATION // handle_command_preflight_calibration // 校准传感器MAV_CMD_PREFLIGHT_REBOOT_SHUTDOWN // handle_preflight_reboot // 重启飞控MAV_CMD_SET_MESSAGE_INTERVAL // handle_command_set_message_interval // 设置消息间隔MAV_CMD_REQUEST_MESSAGE // handle_command_request_message // 请求指定消息MAV_CMD_DO_FENCE_ENABLE // handle_command_do_fence_enable // 围栏使能MAV_CMD_DO_SET_ROI // handle_command_do_set_roi // 设置兴趣点MAV_CMD_DO_GRIPPER // handle_command_do_gripper // 夹爪控制MAV_CMD_DO_SPRAYER // handle_command_do_sprayer // 喷洒器控制MAV_CMD_DO_AUX_FUNCTION // handle_command_do_aux_function // 辅助功能MAV_CMD_DO_FOLLOW // handle_command_do_follow // Follow-meMAV_CMD_RUN_PREARM_CHECKS // handle_command_run_prearm_checks // 预解锁检查MAV_CMD_FLASH_BOOTLOADER // handle_command_flash_bootloader // 烧写 BootloaderMAV_CMD_CAN_FORWARD // handle_can_forward // CAN 总线转发MAV_CMD_DO_SET_SAFETY_SWITCH_STATE // handle_do_set_safety_switch_state // 安全开关MAV_CMD_BATTERY_RESET // handle_command_battery_reset // 电池计数重置MAV_CMD_STORAGE_FORMAT // handle_command_storage_format // 格式化存储MAV_CMD_DO_JUMP_TAG // handle_command_do_jump_tag // 任务跳转MAV_CMD_DO_SET_MISSION_CURRENT // handle_command_do_set_mission_current // 设置当前任务项MAV_CMD_DO_SET_GLOBAL_ORIGIN // handle_command_do_set_global_origin // 设置全局原点MAV_CMD_AIRFRAME_CONFIGURATION // handle_command_airframe_configuration // 机身配置MAV_CMD_CONTROL_HIGH_LATENCY // handle_control_high_latency // 高延迟控制MAV_CMD_ACCELCAL_VEHICLE_POS // handle_command_accelcal_vehicle_pos // 加速度计校准位置MAV_CMD_FIXED_MAG_CAL_YAW // handle_command_fixed_mag_cal_yaw // 固定磁罗盘校准MAV_CMD_SET_EKF_SOURCE_SET // handle_command_set_ekf_source_set // 设置 EKF 源MAV_CMD_DEBUG_TRAP // handle_command_debug_trap // 调试陷进

17.3 Command Execution Confirmation

// 长时间运行任务的进度反馈class GCS_MAVLINK_InProgress { enum class Type { NONE, AIRSPEED_CAL, // 空速校准 SD_FORMAT, // SD 卡格式化 }; bool conclude(MAV_RESULT result); bool send_in_progress();};

17.4 External Estimation Handling

// VIO/外部视觉位置估计MAV_RESULT handle_command_int_external_position_estimate(const mavlink_command_int_t &packet);MAV_RESULT handle_command_int_external_wind_estimate(const mavlink_command_int_t &packet);

18. Telemetry Streams

18.1 Stream to Message Mapping

Each streams enum value maps to a set of ap_message IDs via the stream_entries structure:

struct stream_entries { const streams stream_id; const ap_message *ap_message_ids; const uint8_t num_ap_message_ids;};

18.2 Time Synchronization (TIMESYNC)

void send_timesync(); // 发送时间同步请求void handle_timesync(const mavlink_message_t &msg); // 处理时间同步 struct { int64_t sent_ts1; uint32_t last_sent_ms; const uint16_t interval_ms = 10000; // 每 10 秒同步} _timesync_request;

18.3 Jitter Correction

JitterCorrection lag_correction; // 延迟抖动修正 uint64_t timesync_receive_timestamp_ns() const;uint64_t timesync_timestamp_ns() const;

18.4 Statustext Message Queue

// 线程安全的 statustext 队列struct statustext_t { mavlink_statustext_t msg; uint16_t entry_created_ms; mavlink_channel_mask_t bitmask;}; // 容量: <=192KB 内存区 10 条，>192KB 内存区 30 条static const uint8_t _status_capacity = 10; // 或 30StatusTextQueue _statustext_queue{_status_capacity};

Text messages are sent using the GCS_SEND_TEXT() macro:

GCS_SEND_TEXT(MAV_SEVERITY_INFO, ”Altitude: %.1f m”, altitude);GCS_SEND_TEXT(MAV_SEVERITY_WARNING, ”GPS glitch detected”);GCS_SEND_TEXT(MAV_SEVERITY_CRITICAL, ”Battery low: %d%%”, percent);

18.5 Video Stream Information

MSG_VIDEO_STREAM_INFORMATION = 51,// 编译开关: AP_MAVLINK_MSG_VIDEO_STREAM_INFORMATION_ENABLED

19. Vehicle-Specific Implementations

19.1 Copter (ArduCopter/)

// ArduCopter/GCS_Mavlink.cpp — 主要的 MAVLink 实现// ArduCopter/GCS_Copter.h — GCS_Copter 类定义 class GCS_MAVLINK_Copter : public GCS_MAVLINK { // 实现虚函数 void send_nav_controller_output() const override; void send_pid_tuning() override; uint8_t base_mode() const override; MAV_STATE vehicle_system_status() const override; uint8_t send_available_mode(uint8_t index) const override;
 // 模式切换处理 void handle_guided_request(...); void handle_change_alt_request(...);
 // 手动控制 void handle_manual_control_axes(...) override;};

19.2 Plane (ArduPlane/)

// ArduPlane/GCS_Mavlink.cpp — 主要的 MAVLink 实现// ArduPlane/GCS_Plane.h — GCS_Plane 类定义 class GCS_MAVLINK_Plane : public GCS_MAVLINK { // Plane 特有的遥测扩展 // 额外的状态消息发送};

19.3 Rover (Rover/)

// Rover/GCS_Mavlink.cpp — 主要的 MAVLink 实现// Rover/GCS_Rover.h — GCS_Rover 类定义 class GCS_MAVLINK_Rover : public GCS_MAVLINK { // Rover 特有的 RANGEFINDER 逻辑 void send_rangefinder() const override;};

19.4 AP_Periph (CAN Peripherals)

// Tools/AP_Periph/GCS_MAVLink.cpp — CAN 外设 MAVLink class GCS_MAVLINK_Periph : public GCS_MAVLINK { // 轻量级实现，通过 DroneCAN 通信};

19.5 Message Differences by Vehicle

// ========== 各车辆发送消息差异 ==========// Copter Plane Rover Sub Tracker Blimpsend_nav_ctrl 位置/速度 滚转/俯仰 转向/油门 深度控制 --- 位置/速度send_pid_tuning 滚转/俯仰 滚转/俯仰 转向/速度 --- --- ---send_rangefinder 下视测距 --- 所有测距 --- --- ---send_attitude.. yes --- --- --- --- ---send_winch.. yes --- yes --- --- ---handle_manual.. yes yes yes yes --- ---

20. MAVLink Routing Table

20.1 Routing Table Structure

#define MAVLINK_MAX_ROUTES 20 class MAVLink_routing { uint8_t num_routes; struct route { uint8_t sysid; // 系统 ID uint8_t compid; // 组件 ID mavlink_channel_t channel; // 到达该目标的通道 uint8_t mavtype; // MAV_TYPE (心跳中获取) } routes[MAVLINK_MAX_ROUTES];
 uint8_t no_route_mask; // 禁止路由的通道掩码};

20.2 Route Learning

// 从接收到的消息中自动学习路由void learn_route(GCS_MAVLINK &link, const mavlink_message_t &msg);

学习过程：

20.3 Route Lookup

// 按 MAV_TYPE 查找static bool find_by_mavtype(uint8_t mav_type, uint8_t &sysid,  uint8_t &compid, mavlink_channel_t &channel); // 按 MAV_TYPE + COMPID 查找static bool find_by_mavtype_and_compid(uint8_t mav_type, uint8_t compid,  uint8_t &sysid, mavlink_channel_t &channel);

20.4 Send to Known Components

// 向所有已知组件发送消息（含路由信息）static void send_to_components(uint32_t msgid, const char *pkt, uint8_t pkt_len);

20.5 Channel Types

// 活跃通道static mavlink_channel_mask_t mavlink_active; // 私有通道（不广播，不转发）static mavlink_channel_mask_t mavlink_private; // 正在发送的通道static mavlink_channel_mask_t chan_is_streaming;

Appendix A: Key Data Flows

A.1 Inbound Message Flow

UART RX 中断 └── GCS_MAVLINK::update_receive(max_time_us=1000) ├── 循环读取字节 ├── mavlink_parse_char() 状态机解码 │ ├── STX → LEN → SEQ → SYS → COMP → MSG → PAYLOAD → CKA → CKB → SIGNING │ └── 成功 → raw_packetReceived(framing_status, status, msg) ├── raw_packetReceived() │ ├── 检查 accept_packet() (GCS sysid 强制?) │ ├── MAVLink_routing::check_and_forward() │ │ ├── 帧状态检查 (OK/BAD_CRC/BAD_SIGNATURE) │ │ ├── learn_route() 学习 │ │ ├── handle_heartbeat() 特殊处理 │ │ └── forward() 转发决策 │ └── packetReceived() 虚函数 → handle_message() 分发 └── handle_message() ├── HEARTBEAT → handle_heartbeat() ├── PARAM_* → handle_common_param_message() ├── MISSION_* → handle_common_mission_message() ├── COMMAND_LONG → handle_command_long() ├── COMMAND_INT → handle_command_int() ├── RC_CHANNELS_OVERRIDE → handle_rc_channels_override() ├── MANUAL_CONTROL → handle_manual_control() └── ... (80+ 消息类型)

A.2 Outbound Message Flow

GCS::update_send() └── 耗时控制: 循环直到 main loop 剩余时间 < min_loop_time_remaining └── 遍历通道 (轮转 first_backend_to_send) └── GCS_MAVLINK::update_send() ├── 1. 检查流速率 (+ stream_slowdown) ├── 2. 发送 deferred_message (HEARTBEAT, NEXT_PARAM, HIGH_LATENCY2) ├── 3. 发送 pushed_ap_message_ids ├── 4. 发送 bucket 中的流控消息 │ ├── find_next_bucket_to_send() │ ├── 遍历 bucket 中消息 │ └── try_send_message(id) └── 5. 队列发送 (参数、任务) ├── queued_param_send() └── queued_mission_request_send()

A.3 COMMAND_INT Execution Flow

handle_command_int(msg) └── handle_command_int_packet(packet, msg) └── switch(packet.command) ├── MAV_CMD_COMPONENT_ARM_DISARM │ └── handle_command_component_arm_disarm() │ ├── 检查 magic force 值 (2989 / 21196) │ ├── 检查 pre-arm checks │ └── arm/disarm motors ├── MAV_CMD_DO_SET_MODE │ └── handle_command_do_set_mode() │ └── set_mode(base_mode, custom_mode) ├── MAV_CMD_SET_MESSAGE_INTERVAL │ └── handle_command_set_message_interval() │ └── set_ap_message_interval(id, interval_ms) ├── MAV_CMD_REQUEST_MESSAGE │ └── handle_command_request_message() │ └── pushed_ap_message_ids.set(id) └── ...  └── 发送 COMMAND_ACK 确认

Appendix B: Common Macros & Utilities

B.1 Send Space Check Macros

// 基础检查#define PAYLOAD_SIZE(chan, id) \ (unsigned(GCS_MAVLINK::packet_overhead_chan(chan) + MAVLINK_MSG_ID_ ## id ## _LEN)) // 条件检查（有副作用，失败时递增计数器）#define HAVE_PAYLOAD_SPACE(_chan, id) \ (comm_get_txspace(_chan) >= PAYLOAD_SIZE(_chan, id) ? true : \ (gcs_out_of_space_to_send(_chan), false)) // 在 GCS_MAVLINK 方法中使用#define CHECK_PAYLOAD_SIZE(id) \ if (!check_payload_size(MAVLINK_MSG_ID_ ## id ## _LEN)) return false // 在任意上下文中使用（需要 chan 变量）#define CHECK_PAYLOAD_SIZE2(id) \ if (!HAVE_PAYLOAD_SPACE(chan, id)) return false // void 函数中使用#define CHECK_PAYLOAD_SIZE2_VOID(chan, id) \ if (!HAVE_PAYLOAD_SPACE(chan, id)) return

B.2 Text Send Macros

// 标准文本发送#define GCS_SEND_TEXT(severity, format, args...) \ gcs().send_text(severity, format, ##args) // 消息发送#define GCS_SEND_MESSAGE(msg) gcs().send_message(msg)

B.3 Channel Method Definition Macros

// 避免每个子类重复编写 chan() 方法#define GCS_MAVLINK_CHAN_METHOD_DEFINITIONS(subclass_name) \ subclass_name *chan(const uint8_t ofs) override { ... } \ const subclass_name *chan(const uint8_t ofs) const override { ... }

Appendix C: Performance & Optimization

C.1 Scheduler Priority

MAVLink send priority is lower than the flight control loop:

// 飞行控制循环最少保留 200usvirtual uint16_t min_loop_time_remaining_for_message_send_us() const { return 200;}

C.2 Buffer Management

// txspace 上限 8192 字节，防止单循环发送过多uint16_t txspace() const { if (_locked) return 0; return MIN(_port->txspace(), 8192U);}

C.3 Flow Control Slowdown

// 当链路拥塞时，自动增加 slowdown 延迟uint16_t stream_slowdown_ms;uint16_t get_stream_slowdown_ms() const { return stream_slowdown_ms; }

C.4 Message Interval Cap

// 消息间隔不能超过 0.8 * SCHED_LOOP_RATEuint16_t cap_message_interval(uint16_t interval_ms) const;

C.5 High vs Low Bandwidth Channels

// COMM_0 通常为 USB/高速数传bool is_high_bandwidth() { return chan == MAVLINK_COMM_0; } // 检查硬件流控bool have_flow_control();

C.6 Debug Statistics

#if GCS_DEBUG_SEND_MESSAGE_TIMINGSstruct { uint32_t longest_time_us; ap_message longest_id; uint32_t no_space_for_message; uint16_t statustext_last_sent_ms; uint32_t behind; uint32_t out_of_time; uint16_t fnbts_maxtime; uint32_t max_retry_deferred_body_us;} try_send_message_stats;#endif

Need help implementing MAVLink-based communication for your UAV? Aomway specializes in ArduPilot integration, custom MAVLink extensions, and drone telemetry optimization. Contact us at [email protected] for expert support.

Appendix D: Related Tools & Scripts

D.1 MAVLink Code Generation

# 从 XML 定义生成 C 头文件modules/mavlink/pymavlink/tools/mavgen.py # ArduPilot 使用的消息定义modules/mavlink/message_definitions/v1.0/ardupilotmega.xmlmodules/mavlink/message_definitions/v1.0/common.xml

D.2 Autotest MAVLink Testing

# Tools/autotest/common.py — mavlink 连接管理和消息解析# Tools/autotest/pymavlink/ — Python MAVLink 库

D.3 Routing Test Example

libraries/GCS_MAVLink/examples/routing/