# 摩天云 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` 在双电池时不假定并联/串联或容量一致，不填写推算的总电压/电量。

## 安装和运行

```bash
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，不要把未实现的命令视为成功。

## 本地检查

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

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

```bash
.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 访问权限。