4. 第一个MAVLink监听程序：接收心跳包并解析系统状态

好，咱们正式开始写代码了。

前面几章我们把MAVLink协议的结构、心跳包的含义都捋了一遍。现在，是时候让电脑真正听懂飞控在说什么了。

这一章的目标很明确：写一个Python程序，连上飞控，接收它不断广播的HEARTBEAT包，然后把它里面的系统状态、飞行模式、是否 armed 这些关键信息解析出来，打印到屏幕上。

说白了，就是给飞控“把个脉”。

4.1 准备工作：环境与依赖

工欲善其事，必先利其器。咱们得先把工具准备好。

我个人习惯用 Python 3.8+，配合 pymavlink 这个库。它是MAVLink协议最成熟的Python实现，没有之一。

安装命令：

pip install pymavlink

如果你用的是 pyserial，也一并装上：

pip install pyserial

嗯，这里要注意一下：pymavlink 底层依赖 lxml 和 future，如果安装报错，多半是网络问题，换个国内镜像源就行。

4.2 核心思路：监听流程

整个监听程序的逻辑其实很简单，就三步：

建立连接：通过串口或者UDP，连上飞控。
循环接收：不断读取飞控发来的MAVLink数据包。
解析心跳：从数据流里过滤出 HEARTBEAT 消息，提取字段。

你想想看，飞控就像一个电台，一直在广播。我们的程序就是收音机，调对频率，就能收到信号。

下面这张图，把整个数据流画清楚了：

4.3 代码实战：逐行拆解

好，直接上代码。我会把每一段都拆开讲清楚。

4.3.1 导入库与配置参数

import time
from pymavlink import mavutil

# 连接参数 —— 根据你的实际情况修改
CONNECTION_STRING = '/dev/ttyUSB0'  # Linux 串口
# CONNECTION_STRING = 'COM3'        # Windows 串口
# CONNECTION_STRING = 'udp:127.0.0.1:14550'  # UDP 模拟

BAUDRATE = 115200  # 飞控的波特率，Pixhawk 默认 115200

这里我多说一句：连接字符串是新手最容易卡住的地方。如果你用的是SITL仿真，就用UDP地址；如果是真机，先确认飞控的串口号和波特率。

⚠️ 常见坑点：

Linux下串口权限不够？加 sudo 或者把用户加到 dialout 组。
Windows下COM口不对？去设备管理器里查。
波特率不匹配？飞控和程序必须一致，否则收不到任何数据。

4.3.2 建立连接

# 建立与飞控的连接
master = mavutil.mavlink_connection(CONNECTION_STRING, baud=BAUDRATE)

print("正在等待飞控心跳...")
# 等待第一个心跳包，确认连接成功
master.wait_heartbeat()
print(f"连接成功！系统ID: {master.target_system}, 组件ID: {master.target_component}")

wait_heartbeat() 这个函数会阻塞，直到收到第一个有效的心跳包。我曾经遇到过一个问题：飞控上电了但程序一直卡在这里，后来发现是串口线松了。嗯，硬件问题往往比软件问题更隐蔽。

4.3.3 主循环：持续监听与解析

try:
    while True:
        # 接收一个MAVLink消息，超时1秒
        msg = master.recv_match(type='HEARTBEAT', blocking=True, timeout=1)
        
        if msg is None:
            print("未收到心跳包，等待中...")
            continue
        
        # 解析心跳包
        system_status = msg.system_status
        base_mode = msg.base_mode
        custom_mode = msg.custom_mode
        mav_type = msg.type
        
        # 将状态码转换为可读文本
        status_text = mavutil.mavlink.enums['MAV_STATE'][system_status].description
        mode_text = mavutil.mode_string_v10(master)
        armed = (base_mode & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED) != 0
        
        # 打印结果
        print(f"\n--- 心跳包接收时间: {time.strftime('%H:%M:%S')} ---")
        print(f"系统类型: {mav_type}")
        print(f"系统状态: {status_text} (码值: {system_status})")
        print(f"飞行模式: {mode_text}")
        print(f"是否解锁: {'✅ 已解锁' if armed else '❌ 未解锁'}")
        
        # 控制接收频率，避免刷屏
        time.sleep(0.5)

except KeyboardInterrupt:
    print("\n用户中断，程序退出。")
finally:
    master.close()

这段代码里，有几个地方值得细说：

recv_match(type='HEARTBEAT')：只接收心跳包，其他消息自动过滤掉。效率很高。
mavutil.mode_string_v10(master)：这个函数能把 custom_mode 的数字码值转换成人类能读懂的飞行模式名称，比如 STABILIZE、LOITER、GUIDED。
base_mode & MAV_MODE_FLAG_SAFETY_ARMED：位运算，检查 base_mode 的第7位是否为1。这是判断解锁状态的“标准做法”。

💡 小技巧：

如果你不想每次都查枚举值，可以用 mavutil.mavlink.enums 这个字典。它包含了所有MAVLink枚举的定义，非常方便。

4.4 运行效果与验证

把上面的代码整合到一个文件里，比如 heartbeat_listener.py，然后运行：

python heartbeat_listener.py

如果一切正常，你会看到类似这样的输出：

正在等待飞控心跳...
连接成功！系统ID: 1, 组件ID: 1

--- 心跳包接收时间: 14:23:05 ---
系统类型: 2
系统状态: MAV_STATE_ACTIVE (码值: 4)
飞行模式: STABILIZE
是否解锁: ❌ 未解锁

--- 心跳包接收时间: 14:23:06 ---
系统类型: 2
系统状态: MAV_STATE_ACTIVE (码值: 4)
飞行模式: STABILIZE
是否解锁: ❌ 未解锁

看到这个输出，说明你的监听程序已经跑通了。飞控的“脉搏”已经被你抓住了。

4.5 常见问题与避坑指南

写这个程序的时候，我踩过不少坑。挑几个典型的说说：

问题现象	可能原因	解决办法
程序卡在 `wait_heartbeat()`	串口不通、波特率错误、飞控未上电	检查硬件连接，确认波特率，用串口助手先测一下
收到心跳但 `mode_string_v10` 返回 `None`	飞控固件版本较老，或者自定义模式未注册	升级固件，或者手动解析 `custom_mode` 码值
程序运行一段时间后卡死	串口缓冲区溢出，或者线程阻塞	增加 `timeout` 参数，或者用非阻塞模式
UDP连接收不到数据	端口被占用、防火墙拦截、IP地址不对	检查端口占用，关闭防火墙测试，确认SITL的监听地址

我曾经在调试一架四旋翼时，发现 mode_string_v10 总是返回 None。折腾了半天，最后发现是飞控固件版本太旧，不支持新的模式枚举。升级固件后问题就解决了。所以，固件版本的一致性也很重要。

4.6 本章小结

这一章，我们亲手写了一个完整的MAVLink监听程序。从环境搭建到代码实现，再到问题排查，走了一遍完整的流程。

你现在已经掌握了：

如何用 pymavlink 连接飞控
如何接收并过滤 HEARTBEAT 消息
如何解析系统状态、飞行模式、解锁状态
如何应对常见的连接和解析问题

这个程序虽然简单，但它是所有MAVLink监控工具的基石。后面我们要做的姿态数据读取、参数调优、实时曲线绘制，都是在这个基础上扩展的。