飞控与App远程接口(4G)控制文档
| 字段 | 内容 |
|---|---|
| 文档编号 | ICD-07-V0.1 |
| 版本 | V0.1 |
| 状态 | 草稿 |
| 作者 | 产品团队 |
| 日期 | 2026-04-15 |
| 审核人 | [待定] |
| 接口双方 | 飞控系统 (FC) ↔ 操控App系统 (APP)，经4G LTE网络 |
修订记录
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| V0.1 | 2026-04-15 | 产品团队 | 初稿 |
| V0.2 | 2026-04-16 | 产品团队 | 架构澄清修订：OcuSync→直连数据链；MQTT→MAVLink TCP + REST分离架构 |
1. 概述
1.1 目的
本文档定义飞控系统与操控App之间通过4G LTE网络进行远程通信的接口规范，包括4G模块部署、远程遥测数据传输、远程指令下发、远程图传、云平台对接及安全认证机制。作为飞控固件团队、App开发团队和云平台团队协同开发的技术依据。
1.2 接口范围
本接口覆盖以下远程通信链路：
- 飞行器端：飞控系统通过机载4G模块接入移动网络，与云平台服务器建立持久连接
- App端：操控App通过遥控器Wi-Fi/4G网络接入云平台服务器，获取远程遥测数据并下发远程指令
- 通信路径：飞行器(4G) → 云平台服务器 → App(Wi-Fi/4G)
注意：本接口为直连数据链的增强/备份通道，非主要通信链路。主通信链路为App通过AR8131数据链直接与飞控进行MAVLink通信（ICD-02定义）。
1.3 关联文档
| 文档编号 | 文档名称 |
|---|---|
| SUB-FC-V0.1 | 飞控系统PRD |
| SUB-APP-V0.1 | 操控App系统PRD |
| SUB-RC-V0.1 | 遥控器系统PRD |
| ICD-02-V0.1 | 飞控与遥控器接口 |
| ICD-06-V0.1 | 遥控器与操控App接口 |
| PRD-MASTER-V0.1 | 总体产品需求文档 |
1.4 术语定义
| 术语 | 定义 |
|---|---|
| 4G LTE | 第四代移动通信技术，Long Term Evolution |
| MAVLink TCP Relay | 云端MAVLink透传中继服务，不解析不转换MAVLink消息，仅做TCP会话转发 |
| TLS | Transport Layer Security，传输层安全协议 |
| mTLS | 双向TLS认证，设备和服务端互相验证证书 |
| HMAC | Hash-based Message Authentication Code，基于哈希的消息认证码 |
| Token | 令牌，用于身份验证的临时凭证 |
| Heartbeat | 心跳包，此处特指MAVLink HEARTBEAT消息 |
| REST API | 基于HTTP的业务接口（用户认证、OTA、作业记录等） |
| OTA | Over-The-Air，空中固件升级 |
2. 系统架构
2.1 架构决策说明
我们选择"MAVLink TCP直连 + REST API分离"的混合架构，而非全MQTT方案。
2.1.1 架构对比与选型理由
| 维度 | 方案A：MAVLink TCP + REST（采用） | 方案B：全MQTT（原方案，弃用） |
|---|---|---|
| 前期开发量 | 低——App已有MAVLink协议栈，4G通道只是换个socket，代码复用率高 | 高——需额外开发MAVLink↔JSON转换层、MQTT客户端、Broker部署 |
| 协议栈数量 | App维护1套（MAVLink），云端REST独立 | App维护2套（MAVLink + MQTT），飞行器端也需MQTT客户端 |
| 实时性 | 直接TCP转发，延迟低 | 多一层Broker转发 + JSON序列化，延迟高 |
| 直连/4G代码复用 | 完全复用——App看到的都是MAVLink，底层transport不同而已 | 不可复用——两条链路协议完全不同 |
| 一对多订阅 | 不擅长（TCP是点对点） | 擅长（Pub/Sub天然支持多订阅者） |
| 离线消息 | 不支持 | 支持（QoS 1/2 + 持久会话） |
| 机队管理看板 | 需另建REST/WebSocket推送 | 原生支持多客户端订阅同一Topic |
| 生态兼容 | QGC/Mission Planner原生支持MAVLink TCP远程连接 | 需定制开发 |
2.1.2 选择方案A的核心理由
- 前期开发难度最低：App团队只写一套MAVLink协议栈，直连和4G两条路径在transport层切换，业务代码零修改
- 团队资源现实：当前没有专职后端团队，全MQTT方案需要额外的Broker运维和协议转换开发
- 种子用户阶段够用：100台设备，不需要一对多实时订阅，TCP relay足够
- 渐进式升级路径清晰：未来当机队规模扩大、需要多人同时监控多机时，可在云端TCP relay后面加一层MQTT fanout，App端无需改动
2.1.3 未来迭代升级路径
V1.0（种子用户100台）：
MAVLink TCP relay（云端纯转发） + REST API（基础业务）
→ 开发量最小，快速上线
V1.5（规模扩大至1000台）：
TCP relay + REST API + WebSocket推送（机队看板实时更新）
→ 在REST层加WebSocket，不动MAVLink通道
V2.0（万台级别）：
TCP relay → MQTT fanout层（多订阅者）
→ 仅在云端relay后面加MQTT Broker做消息分发
→ App端仍然收MAVLink，由Broker负责协议桥接
→ App代码不变，只是云端架构升级2.2 通信架构
实时通道（MAVLink TCP Relay）：
飞行器(4G) ──TCP──→ 云端MAVLink Relay ──TCP──→ App
（MAVLink v2二进制流直接透传，云端不解析不转换）
业务通道（REST API）：
App ←──HTTPS──→ 云平台后端服务
（用户认证、OTA、作业记录、GEO围栏、机队管理）┌─────────────────────────────────────────────────┐
│ 飞行器端 │
│ │
│ ┌──────┐ UART/USB ┌──────────────┐ │
│ │ 飞控 │ ───────────→ │ 4G通信模块 │ │
│ │ (FC) │ ←─────────── │ (LTE Cat.4) │ │
│ └──────┘ MAVLink │ 含SIM卡槽 │ │
│ │ 含GPS（备用）│ │
│ └──────┬───────┘ │
│ │ TCP over 4G LTE │
└────────────────────────────────┼─────────────────┘
│
┌────────▼────────┐
│ 移动运营商网络 │
└────────┬────────┘
│
┌────────▼────────┐
│ 云平台服务器 │
│ MAVLink TCP │
│ Relay服务 │
│ REST API服务 │
│ 视频流中继 │
└────────┬────────┘
│ TCP / HTTPS
┌────────▼────────┐
│ 操控App端 │
│ (经RC Wi-Fi │
│ 或4G上网) │
└─────────────────┘2.3 4G模块硬件要求
| 项目 | 规格 |
|---|---|
| 通信制式 | 4G LTE Cat.4（下行150Mbps / 上行50Mbps） |
| 频段 | B1/B3/B5/B8/B34/B38/B39/B40/B41（覆盖中国移动/联通/电信主要频段） |
| SIM卡 | Micro SIM或eSIM，支持物联网卡 |
| 天线 | 外置LTE天线，安装于飞行器机身上方，避开螺旋桨遮挡 |
| 与飞控接口 | UART（波特率921600bps）或USB 2.0 |
| 供电 | DC 5V/2A，由飞行器电源分配板供电 |
| 工作温度 | -20°C ~ 60°C |
| 安装位置 | 飞行器机身中部上方，远离电调/电机高频干扰源 |
3. 远程遥测数据接口（MAVLink TCP Relay）
3.1 MAVLink TCP Relay规格
飞行器4G模块通过TCP连接云端MAVLink Relay服务，发送标准MAVLink v2消息流（与直连链路格式完全一致）。Relay服务不解析不转换MAVLink消息，仅做TCP会话级转发。
| 编号 | 参数 | 规格 | 备注 |
|---|---|---|---|
| ICD-07-R-001 | 传输协议 | TCP over TLS 1.2+ | mTLS认证（设备证书） |
| ICD-07-R-002 | Relay服务端口 | [TBD] | 飞行器端和App端各一个TCP端口 |
| ICD-07-R-003 | 消息格式 | MAVLink v2二进制帧 | 与直连链路完全一致，Relay透传 |
| ICD-07-R-004 | 心跳检测 | MAVLink HEARTBEAT消息（1Hz） | 30秒无心跳判定断连 |
| ICD-07-R-005 | 设备-用户绑定 | Relay根据绑定关系转发 | 验证设备证书后建立TCP会话 |
3.2 遥测数据采集说明
以下精简包/完整包字段定义保留为说明性文档，描述MAVLink流中哪些消息被Relay旁路采集用于云端存储，不再作为独立的封装格式。
精简包字段（Relay旁路采集，1Hz写入时序数据库）：
| 字段 | 来源MAVLink消息 | 说明 |
|---|---|---|
| timestamp | 采集时间 | Unix时间戳(ms) |
| lat, lon | GLOBAL_POSITION_INT(33) | 经纬度 |
| alt_rel | GLOBAL_POSITION_INT(33) | 相对高度 |
| heading | VFR_HUD(74) | 航向 |
| speed_h, speed_v | VFR_HUD(74) | 速度 |
| bat_pct | SYS_STATUS(1) | 电池电量 |
| gps_fix, sat_count | GPS_RAW_INT(24) | 定位状态 |
| flight_mode | HEARTBEAT(0) | 飞行模式 |
| spray_state, tank_pct | 自定义消息50001 | 喷洒状态 |
完整包字段（Relay旁路采集，0.2Hz写入）：
在精简包基础上追加：
| 字段 | 来源MAVLink消息 | 说明 |
|---|---|---|
| bat_voltage, bat_temp | BATTERY_STATUS(147) | 电池详情 |
| motor_status | 自定义消息 | 电机状态 |
| area_done, spray_volume | 自定义消息50001 | 作业进度 |
| oa_front/rear/left/right/down | 自定义消息50003 | 避障距离 |
3.3 连接管理
| 需求编号 | 需求描述 | 优先级 |
|---|---|---|
| ICD-07-I-001 | 飞行器4G模块开机后应自动建立TCP连接至Relay服务，使用mTLS加密传输 | P0 |
| ICD-07-I-002 | 连接建立后通过MAVLink HEARTBEAT消息保活，30秒无心跳判定连接断开 | P0 |
| ICD-07-I-003 | 连接断开后应在5秒内自动重连，最多重试10次，重试间隔指数退避（5s/10s/20s/40s...） | P0 |
| ICD-07-I-004 | 4G信号弱（RSSI < -100dBm）时，MAVLink消息流自动降级（降低非关键消息频率） | P1 |
| ICD-07-I-005 | 飞行器端应缓存最近60秒的MAVLink消息，网络恢复后补发缓存数据（带时间戳排序） | P1 |
4. 远程指令下发接口
4.1 指令分类与权限
远程指令按安全等级分为三级（保持不变）：
| 安全等级 | 说明 | 认证要求 | 示例指令 |
|---|---|---|---|
| L1 — 查询类 | 只读操作，无飞行安全风险 | Token认证 | 查询飞行器状态、查询作业记录 |
| L2 — 安全操作类 | 趋向安全的主动保护指令 | Token + HMAC签名 | 一键返航、紧急停机 |
| L3 — 控制类 | 可能影响飞行安全的操控指令 | Token + HMAC签名 + 时间窗口验证 | 远程起飞(V1.0不支持)、航线修改(V1.0不支持) |
V1.0 仅支持 L1 和 L2 级别指令，L3 级别指令不在 V1.0 范围内。
4.2 指令传输方式
远程指令通过同一TCP连接发送标准MAVLink COMMAND_LONG（MSG ID:76）/ COMMAND_INT（MSG ID:75）消息。App通过TCP连接Relay服务，Relay透传指令至飞行器的TCP会话。
L1查询指令：App通过REST API发送（不走MAVLink通道），云端直接从时序数据库返回。
L2安全指令：App通过MAVLink TCP通道发送COMMAND_LONG消息，Relay透传至飞行器。
4.3 支持的远程指令（V1.0）
| MAVLink消息 | 命令ID | 安全等级 | 说明 |
|---|---|---|---|
| COMMAND_LONG | MAV_CMD_NAV_RETURN_TO_LAUNCH (20) | L2 | 一键返航 |
| COMMAND_LONG | MAV_CMD_COMPONENT_ARM_DISARM (400) disarm | L2 | 紧急停机（disarm） |
| COMMAND_LONG | MAV_CMD_DO_PAUSE_CONTINUE (193) pause | L2 | 暂停当前作业 |
| COMMAND_LONG | MAV_CMD_DO_PAUSE_CONTINUE (193) continue | L2 | 恢复作业 |
| COMMAND_LONG | MAV_CMD_DO_SET_HOME (179) | L2 | 设置返航高度 |
4.4 指令安全机制
| 需求编号 | 需求描述 | 优先级 |
|---|---|---|
| ICD-07-I-010 | TCP会话建立时进行Token+HMAC验证，验证通过后会话内的MAVLink指令免重复认证 | P0 |
| ICD-07-I-011 | TCP会话层Token应设置有效期（≤2小时），过期后需重新认证 | P0 |
| ICD-07-I-012 | Relay服务应记录所有转发的COMMAND消息（指令审计日志），保留≥1年 | P0 |
| ICD-07-I-013 | 紧急停机指令应在Relay转发后≤500ms内到达飞行器端 | P0 |
| ICD-07-I-014 | 飞行器端应在收到COMMAND后通过MAVLink COMMAND_ACK回复执行结果，超时3秒未收到ACK的App端应提示"指令发送超时" | P0 |
| ICD-07-I-015 | 当直连数据链正常工作时，远程指令与直连指令冲突的情况下，直连链路指令优先级更高 | P0 |
| ICD-07-I-016 | 远程指令通道不支持遥控器摇杆实时操控（延迟不满足实时操控要求），仅支持高级指令（返航/停机/暂停/恢复） | P0 |
5. 远程图传接口
5.1 远程图传方案
远程图传为直连数据链图传的低带宽备选方案，适用于超视距作业监控场景。
| 项目 | 规格 |
|---|---|
| 视频编码 | H.264 Baseline Profile |
| 分辨率 | 480p（854×480）或 360p（640×360），根据带宽自适应切换 |
| 帧率 | 10~15 fps（根据带宽自适应调整） |
| 码率 | 300~800 kbps（自适应码率控制） |
| 传输协议 | WebRTC（首选，P2P穿透减少延迟）或 RTMP/HLS（回退方案，经云平台中继） |
| 端到端延迟目标 | ≤2 秒（WebRTC P2P场景）/ ≤5 秒（云平台中继场景） |
5.2 远程图传需求
| 需求编号 | 需求描述 | 优先级 |
|---|---|---|
| ICD-07-I-020 | 飞行器端4G模块应支持将FPV相机视频流编码为H.264并通过4G网络上传 | P2 |
| ICD-07-I-021 | 远程图传应支持自适应码率控制，根据4G上行带宽动态调整分辨率和帧率 | P2 |
| ICD-07-I-022 | 当4G上行带宽不足300kbps时，应自动暂停图传推流，仅保留遥测数据上报 | P2 |
| ICD-07-I-023 | App端应在远程图传画面上叠加"远程图传"水印标识，与本地直连图传区分 | P2 |
| ICD-07-I-024 | 远程图传功能应支持手动开启/关闭，默认关闭以节省流量 | P2 |
注意：远程图传为V1.0可延后功能（Master PRD C-02），V1.0版本优先保证远程遥测和远程指令功能。
6. 云平台对接接口
6.1 云平台架构概述
┌────────────────────────────────────────────────────┐
│ 云平台服务器 │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────────┐ │
│ │ MAVLink │ │ Web API │ │ 视频流中继 │ │
│ │ TCP Relay │ │ (REST) │ │ (WebRTC/RTMP) │ │
│ │ │ │ │ │ │ │
│ │ MAVLink流 │ │ 用户认证 │ │ 远程图传中继 │ │
│ │ 透传转发 │ │ 设备管理 │ │ │ │
│ │ 旁路采集 │ │ GEO数据库 │ │ │ │
│ └───────────┘ │ 固件分发 │ └───────────────┘ │
│ │ 作业数据 │ │
│ └───────────┘ │
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ 数据存储层 │ │
│ │ · 设备注册表 · 遥测时序数据 · 作业记录 │ │
│ │ · 用户账号 · GEO围栏数据 · 固件版本库 │ │
│ │ · 指令审计日志 │ │
│ └───────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────┘6.2 云平台API接口
| API路径 | 方法 | 说明 | 认证 |
|---|---|---|---|
/api/v1/auth/login | POST | 用户登录，获取JWT Token | 账号密码 |
/api/v1/auth/refresh | POST | 刷新Token | Refresh Token |
/api/v1/devices | GET | 获取用户绑定的设备列表 | JWT |
/api/v1/devices/{id}/bindcode | POST | 设备绑定（扫码/手动输入） | JWT |
/api/v1/devices/{id}/status | GET | 获取设备在线状态和最新遥测 | JWT |
/api/v1/devices/{id}/telemetry | GET | 查询历史遥测数据（时间范围查询） | JWT |
/api/v1/devices/{id}/missions | GET | 查询作业记录列表 | JWT |
/api/v1/devices/{id}/cmd | POST | 下发L1查询类远程指令（云端直接返回） | JWT |
/api/v1/relay/status | GET | MAVLink TCP Relay服务状态（在线设备数、连接数） | JWT(管理员) |
/api/v1/relay/sessions | GET | 查看当前活跃TCP会话列表 | JWT(管理员) |
/api/v1/relay/sessions/{id}/disconnect | POST | 强制断开指定设备TCP会话 | JWT(管理员) |
/api/v1/geo/zones | GET | 查询GEO围栏数据（按区域查询） | JWT |
/api/v1/firmware/{model}/latest | GET | 查询最新固件版本 | JWT |
/api/v1/firmware/{model}/{version} | GET | 下载固件包 | JWT |
/api/v1/maps/upload | POST | 上传航测高清地图 | JWT |
/api/v1/maps/list | GET | 获取用户高清地图列表 | JWT |
6.3 云平台对接需求
| 需求编号 | 需求描述 | 优先级 |
|---|---|---|
| ICD-07-I-030 | 云平台服务器应部署于中国境内机房，满足数据安全法要求 | P0 |
| ICD-07-I-031 | 云平台应支持≥10,000台设备同时在线的并发连接 | P1 |
| ICD-07-I-032 | 云平台API应采用HTTPS（TLS 1.2+）加密传输 | P0 |
| ICD-07-I-033 | 云平台应提供GEO围栏数据库，支持App定期同步最新围栏数据（增量更新） | P0 |
| ICD-07-I-034 | 云平台应提供固件版本管理和OTA分发服务，支持灰度发布和版本回滚 | P1 |
| ICD-07-I-035 | 云平台遥测数据保留周期≥90天，作业记录保留周期≥1年 | P1 |
7. 安全认证机制
7.1 设备认证
| 需求编号 | 需求描述 | 优先级 |
|---|---|---|
| ICD-07-I-040 | 每台飞行器出厂时应预置唯一的设备证书（X.509），用于4G连接时的双向TLS认证 | P0 |
| ICD-07-I-041 | 设备证书应由产品CA签发，私钥存储于飞行器端安全存储区（Secure Element或加密Flash），不可导出 | P0 |
| ICD-07-I-042 | 4G模块连接TCP Relay时应使用设备证书进行mTLS（双向TLS）认证，Relay验证设备身份后建立TCP会话 | P0 |
7.2 用户认证
| 需求编号 | 需求描述 | 优先级 |
|---|---|---|
| ICD-07-I-045 | App用户登录采用账号+密码+短信验证码双因素认证 | P0 |
| ICD-07-I-046 | JWT Access Token有效期≤2小时，Refresh Token有效期≤7天 | P0 |
| ICD-07-I-047 | 用户下发远程指令时，App应在指令消息中附加HMAC-SHA256签名，签名密钥由服务端会话密钥派生 | P0 |
7.3 防劫持机制
| 需求编号 | 需求描述 | 优先级 |
|---|---|---|
| ICD-07-I-050 | 所有远程指令必须经过时间戳验证（±30秒窗口）和nonce去重（5分钟窗口），防止重放攻击 | P0 |
| ICD-07-I-051 | 飞行器端应维护指令来源白名单，仅接受已绑定账号的指令，拒绝未知来源的指令 | P0 |
| ICD-07-I-052 | 设备绑定/解绑操作需通过物理确认（飞行器端按键确认或扫码确认），不可纯远程完成 | P0 |
| ICD-07-I-053 | 连续3次认证失败后，飞行器端应锁定远程指令通道30分钟，并通过遥测数据上报安全事件 | P0 |
| ICD-07-I-054 | 云平台应记录所有远程指令的完整审计日志（发送者、指令内容、时间戳、执行结果），保留≥1年 | P0 |
8. 性能需求
| 编号 | 性能指标 | 目标值 | 优先级 |
|---|---|---|---|
| ICD-07-P-001 | 遥测数据端到端延迟（飞行器→App） | ≤3 秒（4G网络正常时） | P0 |
| ICD-07-P-002 | 远程指令端到端延迟（App→飞行器） | ≤2 秒 | P0 |
| ICD-07-P-003 | 4G模块月均流量消耗（仅MAVLink遥测+指令，无图传） | ≤300 MB/月（按每天飞行2小时计，MAVLink二进制比JSON更省流量） | P1 |
| ICD-07-P-004 | 4G连接建立时间（开机→TCP Relay连接成功） | ≤15 秒 | P1 |
| ICD-07-P-005 | 断网重连时间 | ≤10 秒（4G信号恢复后） | P1 |
| ICD-07-P-006 | TCP Relay消息吞吐量 | ≥100 msg/s（单设备） | P1 |
9. 待决事项 (TBD)
| 编号 | 事项描述 | 责任人 | 期望决定日期 | 影响范围 |
|---|---|---|---|---|
| TBD-ICD07-001 | 4G通信模块选型（型号、供应商）确认 | 硬件团队 | 2025-05 | 模块集成开发 |
| TBD-ICD07-002 | 物联网SIM卡运营商选择及资费方案 | 商务/运营 | 2025-05 | 流量成本控制 |
| TBD-ICD07-003 | 云平台技术选型（MAVLink TCP Relay自研 vs 第三方方案） | 后端团队 | 2025-05 | 云平台架构 |
| TBD-ICD07-004 | 远程图传WebRTC方案的NAT穿透成功率评估 | 通信团队 | 2025-06 | 图传方案选择 |
| TBD-ICD07-005 | 设备证书签发和管理流程设计（产品CA架构） | 安全团队 | 2025-06 | 设备认证 |
| TBD-ICD07-006 | V1.0是否支持4G远程遥测（或仅预留4G硬件接口，软件功能V1.5上线） | 产品经理 | 2025-05 | 开发范围 |
附录
附录A：需求追溯矩阵
| 接口需求编号 | 系统级需求来源 | 子系统需求来源 | 验证状态 |
|---|---|---|---|
| ICD-07-I-001~005 | SYS-P-050 | APP-I-002 | 未验证 |
| ICD-07-I-010~016 | SYS-S-001 | APP-F-107 | 未验证 |
| ICD-07-I-020~024 | SYS-P-050 | APP-F-101 | 未验证 |
| ICD-07-I-030~035 | SYS-C-002/004 | APP-C-002 | 未验证 |
| ICD-07-I-040~054 | SYS-S-001 | APP-S-009/010 | 未验证 |
附录B：消息序列图 — 远程返航指令
App端 云端TCP Relay 飞行器端(4G)
│ │ │
│ TCP连接已建立 │ TCP连接已建立(mTLS) │
│ (Token认证通过) │ │
│ │ │
│ MAVLink COMMAND_LONG │ │
│ (MAV_CMD_NAV_RTL) │ │
│ ────────────────────→ │ │
│ │ MAVLink COMMAND_LONG │
│ │ （透传，不解析） │
│ │ ──────────────────────→ │
│ │ │ 验证MAVLink签名
│ │ │ 执行返航
│ │ MAVLink COMMAND_ACK │
│ │ ←────────────────────── │
│ MAVLink COMMAND_ACK │ │
│ ←──────────────────── │ │
│ │ │
│ [Relay旁路记录指令审计日志] │
│ │ │