motian_mavbridge

摩天云 MQTT–MAVLink 串口桥

使用子模块 msg_definitions/msg_definitions/VKFly.xml 生成的 MAVLink 2 方言解析串口数据（也接受 MAVLink 1 通用帧），按平台 Base JSON 协议上报核心遥测；不执行文档中的飞行业务指令。现有原始字节块透传保持不变：飞控串口读到的每个字节块转换为大写 HEX，包装为 DataType=526 发布到 /PUBLISH/<SystemID>；订阅 /OBTAIN/<SystemID>，把同类型消息的 HEX Data 解码后原样写入串口。原始读取块不等于 MAVLink 帧边界。

结构化上报

均发布到 /RECEIVE/<SystemID>，使用 DataType、UAVType、Data、SystemID、带时区的 TimeStamp 外壳：

DataType	来源	行为
258 飞行状态	HEARTBEAT、ATTITUDE、GLOBAL_POSITION_INT、VFR_HUD、GPS_RAW_INT、HOME_POSITION	心跳有效时每秒合并一次；未知字段不发送
257 电池	仅 VK_BMS_STATUS	有新值时至多每秒一次；bat_id=0/1 分别映射左右电池
260 提示	STATUSTEXT	收到就上报，保留原始严重级别和 UTF-8 文本
274 飞行状态	HEARTBEAT 解锁标志	首次获知及改变时上报布尔值；true=解锁、false=上锁，并非实际离地/着陆

只解析首个有效飞控 HEARTBEAT 对应的 system/component ID。串口重连重选来源并清空缓存；心跳超过 5 秒暂停 #258，其他来源字段超过 5 秒自动剔除。只被动接收，不请求飞控遥测；如缺少字段，请先确认飞控串口是否广播对应消息。缺失消息类型可用 --debug 查看。#257 在双电池时不假定并联/串联或容量一致，不填写推算的总电压/电量。

安装和运行

python3 -m venv .venv
.venv/bin/python -m pip install -e .
cp config.example.json config.local.json
# 修改 config.local.json：真实 SystemID、平台分配的 UAVType、串口及 MQTT 参数
export MOTIAN_MQTT_PASSWORD='由部署环境提供的密码'
.venv/bin/motian-mavlink-bridge --config config.local.json

config.local.json 已被忽略，不要提交凭据。无账号时将 mqtt_username 和 mqtt_password_env 均设为 null。mqtt_tls=true 使用系统可信 CA 或 mqtt_ca_file；不要关闭证书校验。serial_port 可以是 /dev/tty* 或 pyserial 支持的 URL。配置文件中的 uav_type: 0 只是示例，正式值须由平台分配。

publish_raw_mavlink 默认为 true，设置为 false 可停止 /PUBLISH/ 原始上行，下行 #526 不受影响。下行 JSON 必须有 DataType（没有尾随空格）、UAVType、Data、SystemID、TimeStamp，设备标识须与本机配置一致。Data 必须是非空、偶数长度的 HEX 字符串，最多 max_command_bytes 字节。其他 DataType 默认只记日志并丢弃；不会伪造 ACK。所有 retained 下行均丢弃，MQTT 使用 QoS 0、不保留发布消息。MQTT 或串口断线期间不主动缓存数据；重连后不会主动重放旧指令。

扩展飞控业务时，通过 Bridge.register_handler(data_type, handler) 注册非 526 命令回调。回调收到 BaseMessage 和桥实例，可调用 bridge.publish_report(data_type, data) 向 /RECEIVE/<SystemID> 上报。透传上行通过同一方法的 passthrough=True 发布到 /PUBLISH/<SystemID>。回调应自行处理飞控交互和业务 ACK，不要把未实现的命令视为成功。

本地检查

.venv/bin/python -m unittest discover -s tests -v

方言源文件由 msg_definitions Git 子模块提供，实际 XML 位于 msg_definitions/msg_definitions/。若子模块中的 XML 改动，需要用项目环境中的 pymavlink 重新生成提交的 Python 文件（原文件不要手工修改）：

.venv/bin/python -m pymavlink.tools.mavgen --lang Python --wire-protocol 2.0 \
    --output motian_bridge/dialects/v20/VKFly.py msg_definitions/msg_definitions/VKFly.xml
.venv/bin/python -m unittest discover -s tests -v

当前生成文件使用 pymavlink 2.4.50；生成时会显示 XML bitmask 枚举的已有警告，但会完成生成。重新生成后应复测真实 MAVLink 帧，以确认设备 XML 版本和校验码兼容。

协议仅定义 /PUBLISH/无人机id 为“透传包”，没有提供上行载荷示例。本实现按 Base JSON + DataType 526 + HEX Data 约定，正式联调前需平台确认。TimeStamp 为本机时区 ISO-8601 时间；应确保设备时间正确。MQTT QoS 0 降低重放风险，但不是严格端到端交付保证。此服务不做飞行安全仲裁，正式部署应限制 Broker 访问权限。