飞控与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旁路记录指令审计日志]                      │
  │                      │                         │

飞控与App远程接口(4G)控制文档 ​

修订记录 ​

1. 概述 ​

1.1 目的 ​

1.2 接口范围 ​

1.3 关联文档 ​

1.4 术语定义 ​

2. 系统架构 ​

2.1 架构决策说明 ​

2.1.1 架构对比与选型理由 ​

2.1.2 选择方案A的核心理由 ​

2.1.3 未来迭代升级路径 ​

2.2 通信架构 ​

2.3 4G模块硬件要求 ​

3. 远程遥测数据接口（MAVLink TCP Relay） ​

3.1 MAVLink TCP Relay规格 ​

3.2 遥测数据采集说明 ​

3.3 连接管理 ​

4. 远程指令下发接口 ​

4.1 指令分类与权限 ​

4.2 指令传输方式 ​

4.3 支持的远程指令（V1.0） ​

4.4 指令安全机制 ​

5. 远程图传接口 ​

5.1 远程图传方案 ​

5.2 远程图传需求 ​

6. 云平台对接接口 ​

6.1 云平台架构概述 ​

6.2 云平台API接口 ​

6.3 云平台对接需求 ​

7. 安全认证机制 ​

7.1 设备认证 ​

7.2 用户认证 ​

7.3 防劫持机制 ​

8. 性能需求 ​

9. 待决事项 (TBD) ​

附录 ​

附录A：需求追溯矩阵 ​

附录B：消息序列图 — 远程返航指令 ​