# MQTT–MAVLink 串口透传实施方案

## 概要

新建 Linux/Python 服务。本期只实现原始字节块透传，不解析 MAVLink 帧，也不转换起飞、航线等业务指令。

## 实现

- 订阅 `/OBTAIN/<SystemID>`，仅将 `DataType=526`、设备标识匹配、`Data` 为合法 HEX 的 Base JSON 解码后写入串口；拒绝 retained 消息。
- 串口读到的字节块逐块转为 HEX，作为 `DataType=526` 的 Base JSON 发布到 `/PUBLISH/<SystemID>`；`UAVType`、`SystemID` 来自配置，`TimeStamp` 使用带时区时间。使用正确字段名 `DataType`，不沿用文档示例的尾随空格。
- 串口参数、MQTT 地址、认证、TLS 和设备标识由部署配置提供。MQTT 使用 QoS 0、不保留消息；断线重连但不主动缓存或重放旧数据。
- 提供按 `DataType` 注册回调和通用上报 API；未实现的非 526 指令只记录日志并丢弃，不发送未定义的应答。

## 测试

使用模拟 MQTT 和串口验证双向字节一致性、JSON Base 字段、非法数据及 retained 消息拒绝、断线丢弃、重连恢复和扩展回调分派。取得实际设备及平台参数后进行现场联调。

## 前提

协议未提供 `/PUBLISH/<SystemID>` 的载荷样例；上行暂定 **Base JSON + 526 + HEX Data**，正式接入前须平台确认。`UAVType` 正式值由平台分配，不猜测。

## 第二阶段：VKFly MAVLink 状态上报（2026-09-29）

- 使用 `msg_definitions` Git 子模块中的 `msg_definitions/VKFly.xml` 及其包含文件生成 MAVLink 2 Python 方言，解析串口完整帧；只被动接收并自动绑定首个飞控 HEARTBEAT，串口重连时重置。
- `/RECEIVE/<SystemID>` 增加 #258 飞行状态（1 秒合并）、#257 厂商 BMS 电池（有更新时至多每秒一次）、#260 STATUSTEXT 提示、#274 解锁/上锁布尔事件。只上报有效的已知字段；心跳或其他来源超过 5 秒即停止使用旧数据。
- 保持下行 #526 不变；原始串口字节上行 #526 保留，增加 `publish_raw_mavlink` 配置开关，默认为开启。
- 使用生成的真实 MAVLink 帧验证分块、CRC、来源、单位、超时及双电池；平台对部分字段的接受情况仍需实际联调。#274 的“飞行”在此阶段按解锁解释，不代表物理离地。