合宙 IOT 通用报文协议 - AirCloud

一、协议概述

1.1 协议定位与设计目的

AirCloud 是合宙自研 IoT 通用二进制报文协议，作为 4G/WiFi/MCU/iRTU/模拟器等其他未知设备统一通信标准，用于实现设备数据上报、平台指令下发标准化，方便将设备采集的各种数据能够按照统一格式上报到合宙云平台或者第三方云平台进行记录和管理。

1.2 协议特性

统一格式：上下行报文结构完全一致，一套格式兼顾上报与控制
易于扩展：固定 16 字节消息头 + TLV 可变消息体，扩展字段无需修改底层头部
省流低耗：采用二进制传输，相比 JSON 大幅降低流量与模组功耗
多载兼容：支持多种传输载体，TCP/MQTT/UDP 传输业务报文，HTTP 仅用于大文件上传
部署灵活：多层鉴权体系，合宙公有云配套 getip 调度，私有服务器可独立部署
轻量保活：原生心跳保活机制，复用业务数据保持连接，无需单独心跳包

1.3 支持设备类型

此处仅展示目前支持的设备类型，后续会持续更新。

0x01：4G主控设备（Air700/780/8000系列）
0x02：WiFi主控设备（Air8101系列）
0x03：MCU 主控设备（Air1601/1602/1780系列）
0x09：虚拟设备（PC 模拟器使用）
0xFF：未知设备

1.4 适用业务场景

传感数据采集：温湿度、水位、酸碱度、CPU 温度；
设备状态监控：电量、4G 信号、ICCID、GPIO、固件版本、内存占用；
GNSS 位置追踪：经纬度、速度、卫星数量、航向角；
远程控制：开关、参数配置、短信下发、设备重启；
文件采集：拍照、录音、本地运维日志云端归档；
产线批量挂测、工业终端数据采集。

二、报文结构

2.1 AirCloud 整体报文分层总览

AirCloud 设备和云端交互的数据包统一由 16 字节标准消息头 + TLV 消息体两大部分组成。

名词释义：TLV 全称 Type-Length-Value（类型 - 长度 - 值），下文 2.4 会完整讲解该二进制封装格式。

补充说明：TCP、MQTT、UDP 是设备与云端建立数据通道的三种方式，详细使用规则见第 3 章。

根据设备与云端建立数据通道的方式分为两类数据包：普通数据包、UDP 专用扩展数据包。

2.1.1 TCP/MQTT 普通数据包基础结构

TCP、MQTT 两种传输通道适用同一套基础数据包，无需额外扩展字段，层级顺序固定：

16 字节通用消息头 + TLV 消息体

约束说明：

TLV 消息单包最大支持 1400 字节，整包总长度上限为 16 + 1400 = 1416 字节，超出需拆分为多条独立数据包进行传输；
多包拆分后无内置重组机制，设备与云端业务层自行实现分片拼接逻辑。

2.1.2 UDP 扩展数据包结构

UDP 传输通道无持续长连接会话，每一条数据包都需要独立身份校验，因此在消息头与 TLV 消息体中间，额外增加一段 64 字节固定鉴权 KEY，层级顺序不可颠倒：

16 字节通用消息头 + 64 字节 UDP 专属鉴权 KEY + TLV 消息体

约束说明：

消息头内消息标识的 bit5 必须置 1，用来标记当前这条数据包是 UDP 通道传输；
64 字节 KEY 固定占位，密钥文本不足 64 字节时，尾部补 0 填充；
TLV 消息体同样限制最大 1400 字节。
UDP 单包不支持跨包分片，大数据必须拆分为多条独立 UDP 报文。

2.2 固定 16 字节通用消息头（TCP/MQTT/UDP 三种传输通道共用）

无论设备使用 TCP、MQTT、UDP 哪种方式连接云端，都共用一套 16 字节消息头，字段顺序、字节长度、编码规则完全统一，全部采用大端序（高位在前）存储，不可调整字段顺序。

字段名称	占用字节数	简要说明
设备 ID	8	第一字节标记设备类型，第 2 ~ 8 字节为硬件唯一标识
流水号	2	消息自增序列号，用于应答匹配、重复数据包去重、丢包定位
消息长度	2	仅统计后续 TLV 消息体总字节，不含头部、UDP 专属 64 字节 KEY，最长不超过 1400 字节
消息标识	4	协议版本号、应答标记、UDP 数据包标记、预留扩展位等

2.2.1 设备 ID 详解

设备 ID 共 8 个字节，左侧为最高位，结构如下：

第 1 字节：设备类型，定义如下：
- 0x01：4G主控设备（Air700/780/8000系列）
- 0x02：WiFi主控设备（Air8101系列）
- 0x03：MCU 主控设备（Air1601/1602/1780系列）
- 0x04：保留
- 0x05：保留
- 0x06：保留
- 0x07：保留
- 0x08：保留
- 0x09：虚拟设备（PC 模拟器使用）
- 0xFF：未知设备
剩余 7 字节：设备唯一标识，可使用 IMEI、MAC 地址或 Chip ID 等

设备 ID 编码规则：

采用 BCD 编码方式
长度不足 7 字节的，高位补 0
对于 IMEI，只使用前 14 位数字（第 15 位为校验位）
MAC 去除横杠分隔符，转为连续十六进制串填充。

示例：

4G 设备，IMEI 为 861234567890123：设备 ID 为 0x0186123456789012
WiFi 设备，MAC 为 00-1A-2B-3C-4D-5E：设备 ID 为 0x0200001A2B3C4D5E

2.2.2 流水号详解

流水号共 2 个字节，取值范围 0 ~ 65535，设备每发送一条数据包，流水号自增 1，到达 65535（0xFFFF）后循环归零；

上行、下行报文流水号一一对应，云端下发响应数据包时，携带与上行完全一致的流水号；
设备依靠流水号匹配回执、识别重复推送报文；
重传报文必须复用原有流水号，便于平台去重。

2.2.3 消息体长度详解

该字段仅代表 TLV 消息体总字节长度，最大值 1400；
UDP 场景下，64 字节鉴权 KEY 不计入该长度；
服务端解析时，若实际 TLV 字节与本字段数值不匹配，判定报文非法并直接丢弃。

2.2.4 消息标识详解

消息标识共 4 个字节（32bit），bit 由低位向高位编号，定义如下：

比特区间	含义
bit0 ~ bit3	协议版本号
bit4	是否需要云端回复：1 = 云端必须下发应答数据包，0 = 无需回执
bit5	UDP 数据包标记：1 = 本条数据走 UDP 通道，0 = 本条数据走 TCP/MQTT 通道
bit6 ~ bit31	预留扩展位，传输时统一填充 0

2.3 UDP 专属 64 字节鉴权 KEY 详解

本节内容仅适用于通过 UDP 通道传输的数据包，TCP、MQTT 通道无此字段。

2.3.1 KEY 来源与获取方式

使用合宙公有云端：

调用 getip 接口并传入 type = 4，接口返回内容中会给到该设备专属 64 字节 KEY；
设备重新调用 getip 会刷新 KEY，旧密钥同步失效。

使用客户自建私有云端 UDP 服务：

方式一：自建调度服务。修改 getip_url 指向私有调度服务地址，由私有调度服务统一管理并下发 64 字节密钥，实现方式与合宙公有云一致；
方式二：固定密钥模式。不使用调度服务（设置 use_getip = false），在脚本代码中直接填入 64 字节固定密钥，需确保设备端与服务端密钥一致。

2.3.2 数据包填充位置、长度约束

填充位置：固定放置在 16 字节消息头与 TLV 消息体中间，是 UDP 报文强制结构；

长度约束：协议规定该字段固定占用 64 字节二进制空间；

不可省略：所有 UDP 数据包必须携带此字段，否则服务端鉴权校验失败。

2.3.3 云端校验逻辑与安全作用

校验逻辑：服务端接收 UDP 数据包时，优先校验 64 字节 KEY 合法性，KEY 不匹配则不再解析头部与 TLV；

安全作用：UDP 属于无连接传输，不存在持续会话，无法依靠一次连接鉴权保护后续报文，通过每条数据包独立校验 KEY，过滤伪造、非法设备发送的数据包，保障数据安全。

2.4 TLV 可变消息体规范（TCP/MQTT/UDP 三种传输通道通用）

2.4.1 TLV 基础完整定义

TLV 全称 Type-Length-Value（类型 - 长度 - 值），是行业通用轻量二进制封装格式。

每一组业务数据单独封装为一段 TLV 单元，多个 TLV 可连续拼接组成完整消息体；优势是新增数据字段无需修改头部结构，兼容性、扩展性极强。

单段 TLV 固定三段顺序，不可调换：

字段名称	占用字节数	简要说明
Type（类型）	2	bit0 ~ bit11 表示字段含义，bit12 ~ bit15 表示数据类型
Length（长度）	2	Value 部分占用的字节数
Value（值）	可变	实际的字段值

2.4.2 字段含义定义

字段含义占用 Type 字段的 bit0 ~ bit11，范围 0 ~ 4095，分为以下几类：

范围	类型	说明
0 ~ 15	预留	保留给未来使用
16 ~ 255	控制信令	用于设备与服务器之间的控制通信
256 ~ 2047	业务字段	用于设备上报业务数据
2048 ~ 4095	预留	保留给未来使用

提示：所有区间对应的完整编号、字段名称明细，统一查阅文档【附录 A TLV 全字段速查表】。

2.4.3 数据类型定义

数据类型占用 Type 字段的 bit12 ~ bit15，定义如下：

类型值	数据类型	说明
0000	整数	有符号整数
0001	浮点数	IEEE 754 标准浮点数
0002	布尔值	0x00 表示 false，0x01 表示 true
0003	ASCII 字符串	可打印 ASCII 字符
0004	二进制数据	任意二进制数据
0005	Unicode 字符串	UTF-8 编码的字符串

2.4.4 多 TLV 拼接、分包长度限制规则

多 TLV 拼接：多条 TLV 直接连续排列，可一次性上报温度、电量、定位多组数据；
分包约束：单条数据包内全部 TLV 总字节（消息体长度）最大 1400 字节，超出必须拆分为多条独立数据包发送；
分包无内置重组逻辑，设备与云端业务层自行处理大数据分片拼接。

2.5 完整数据包示例

2.5.1 TCP 温度上报标准数据包示例

业务：上报 25.0℃ 温度

16 字节消息头：0186123456789012 0001 000C 00000001

设备 ID：01 86 12 34 56 78 90 12（4G 设备 IMEI）
流水号：0001
消息体长度：000C（12 字节，单段 TLV 总长度）
Flags：00000001（版本 1，无需回复，走 TCP 通道 bit5=0）

TLV 消息体：

Type：0x0101（256 温度 + 0001 浮点数）
Length：0x0004
Value：0x41C80000 = 25.0

2.5.2 UDP 心跳上报扩展数据包示例（含 64 字节 KEY）

业务：上报设备电量 5000mV 数据包分层顺序：

16 字节消息头（Flags bit5 置 1，标记走 UDP 通道）；
64 字节 UDP 鉴权 KEY（占位填充）；
TLV 消息体：
- Type=0x0300（bit0 ~ bit11 为 769 电量，bit12 ~ bit15 为 0000 整数）
- Length=0x0002
- Value=0x1388 对应十进制 5000mV

三、通信承载

AirCloud 业务二进制报文支持 TCP/MQTT/UDP 三种承载通道，用于传输标准 AirCloud TLV 报文；HTTP 为独立配套通道，不承载任何 AirCloud 二进制报文，仅用于图片、音频、运维日志等大文件上传。

三种承载通道适用场景对比：

通道	推荐场景	核心优势	局限性
TCP	工业采集、长期在线设备、高频上报	低延迟、双向流式、协议开销小	不支持离线消息
MQTT	电池设备、低功耗场景、网络不稳定环境	离线消息、低功耗、一对多广播	经Broker转发，延迟稍高
UDP	实时监控、允许少量丢包的场景	超低延迟、无连接开销	不可靠、不支持大包

3.1 TCP（工业设备推荐首选长连接）

连接方式：设备建立 TCP 长连接直连业务服务端
端口与 IP 来源：合宙公有云必须通过getip(type=3)接口动态获取；自建私有服务器有两种方式：一是配置getip_url指向私有调度服务，由调度服务统一分配；二是固定填写 IP / 端口，跳过 getip
鉴权规则：TCP 链路建立成功后，第一条报文必须发送鉴权 TLV，未鉴权报文服务端直接丢弃、超时断连
收发逻辑：双向流式传输，设备上行上报、平台下行下发指令，无消息主题隔离
服务端数据处理：合法报文解析后入库存储，支持实时指令下发
断连重连策略：链路断开后本地重试 3 次；3 次失败需重新调用 getip 刷新服务地址
适用场景：工业采集、长期在线设备、对数据可靠性要求高的场景

3.2 MQTT

标准主题格式：/AirCloud/direction/DeviceID/ServType
- direction：up = 设备上行上报；down = 平台下行控制
- Device：8 字节设备 ID 十六进制字符串
- ServType：auth = 鉴权专用主题；all = 普通业务数据主题
账号密码来源：接入合宙公有云会调用getip(type=5)获取 MQTT 连接参数，返回的用户名为{imei}、密码为{muid}；设备连接时需将{imei}替换为真实设备 IMEI，{muid}替换为真实设备 MUID，不可直接使用占位字符串（此操作完全由扩展库内部自动实现，无需用户关心）；自建私有服务器有两种方式：一是配置getip_url指向私有调度服务获取账号密码；二是自定义账号体系
鉴权规则：鉴权报文仅允许发布至/AirCloud/up/{设备ID}/auth主题；鉴权成功后，上行发布/AirCloud/up/{设备ID}/all，订阅/AirCloud/down/{设备ID}/all接收指令
服务端数据处理：平台订阅全量上行主题，接收所有设备上报数据；下发指令定向推送至对应设备下行主题
优势：支持离线消息、轻量低功耗，适合低速率物联网设备

3.3 UDP（低时延无连接通道）

使用场景：网络稳定、对传输延迟要求高、允许少量丢包的业务；不适合关键控制类数据
连接方式：无长连接会话，每条数据包独立发送，无握手保活链路
双层鉴权体系
- 报文内置 64 字节 UDP 专属 KEY（每条报文独立校验）
- 链路层无鉴权报文，依靠 KEY 完成设备身份识别
KEY 获取规则：合宙公有云调用getip(type=4)获取；自建私有服务器有两种方式：一是配置getip_url指向私有调度服务获取 KEY；二是固件预烧固定 64 字节密钥
强制报文结构：16 字节消息头 + 64 字节 UDP 鉴权 KEY + TLV 消息体，消息标识 bit5 必须置 1
关键注意事项
- 可靠性：UDP 无重传、无 ACK、无序到达；设备业务层必须自行实现超时重传、重复报文去重（依靠流水号 Seq）
- 安全性：每条报文独立校验 KEY，非法密钥数据包直接丢弃，不解析报文内容
- 分片限制：UDP 单包整体长度受链路 MTU 限制，消息体必须严格控制在 1400 字节内，不支持跨包重组

3.4 HTTP

使用边界：仅传输图片、音频、运维日志二进制文件，不能发送 AirCloud 标准报文；文件上传前后通过 TCP/MQTT/UDP 发送文件通知类 TLV 信令
使用场景：大体积文件传输，不适合高频小数据上报
完整上传流程
1. 获取上传配置：通过 getip 获取上传 URL 及表单参数；
2. 前置校验：检查文件是否存在且不为空，检查设备是否已连接服务器；
3. 发送上传开始通知：通过 AirCloud 报文发送 Type=23「文件上传开始通知」；
4. 执行 HTTP 上传：使用 HTTPS POST、form\-data 格式上传二进制文件，支持失败重试 1 次；
5. 发送上传完成通知：通过 AirCloud 报文发送 Type=24「文件上传完成通知」；
6. 资源回收：执行轻量级 GC 释放内存。
补充约束
1. 上传参数获取：设备建立连接时，扩展会自动调用 getip 获取上传配置（imginfo/audinfo/mtninfo）；若首次未获取到（如 getip 响应中不含该字段），后续调用文件上传接口时扩展库内部会自动重试获取；合宙公有云通过 getip(type=3/4/5) 获取；自建私有服务器需配置 getip_url 指向私有调度服务，由调度服务返回上传参数；
2. 自建服务器限制：文件上传功能依赖 getip 调度获取上传参数，因此自建服务器必须配置 getip_url，并开启 getip 服务（默认开启状态）才能使用扩展库文件上传接口；若只填写 IP/端口而不开启 getip 服务，则无法使用扩展库文件上传接口，需要自行在脚本逻辑中实现文件上传功能；
3. 文件通知机制：图片/音频上传前，设备通过 TCP/MQTT/UDP 发送 Type=23「文件上传开始通知」，携带文件类型、文件名、文件大小；上传完成后，发送 Type=24「文件上传完成通知」，携带上传结果状态（成功/失败）；运维日志上传跳过 Type=23/24 通知；
4. HTTP 通道定位：HTTP 通道仅用于图片、音频、运维日志等大文件上传，不承载 AirCloud 二进制报文；文件上传前后的控制信令通过 TCP/MQTT/UDP 通道传输。

四、getip 负载均衡调度接口

4.1 接口基础概述

4.1.1 接口核心功能

getip 是合宙公有云专属 HTTPS 负载均衡调度接口，仅服务合宙官方 AirCloud 公有云集群，承担设备接入前统一调度分发能力，核心功能包含 5 项：

集群节点负载调度：合宙云采用多分布式业务服务器集群，无固定公网接入地址；接口根据设备地理位置、各服务器实时负载，动态分配延迟最优、空闲充足的 TCP/MQTT/UDP 业务服务器 IP 与端口，均衡分散全量设备连接压力；
故障自动容灾切换：当接入节点服务器出现宕机、维护、线路故障时，设备连续 3 次重连失败后重新调用本接口，调度服务会自动下发备用正常节点地址，无需修改设备固件硬编码 IP；
前置设备合法性校验：接口请求携带项目密钥、设备硬件标识、MUID 三重凭证，在设备发起长连接前完成预校验，未注册、伪造、非法设备直接拒绝分配接入节点，提前拦截恶意接入；
一站式分发全套业务参数：依据请求传入的 type 业务类型，一次性返回对应链路完整配置，包含 TCP/UDP/MQTT 连接地址、UDP 专属 64 字节鉴权密钥、MQTT 登录账号密码，以及图片、音频、运维日志文件上传所需 HTTP 地址、表单鉴权参数；
统一管控文件上传链路：所有多媒体、日志文件上传通道由调度接口统一分配，实现云端统一鉴权、存储归档、数据入库管控。

4.1.2 底层通信协议要求

传输协议强制使用 HTTPS TLS1.2 及以上版本，明文 HTTP 不支持；
通信方式固定为 POST 请求，请求体、服务端返回响应均为标准 JSON 格式；
接口域名固定： gps.openluat.com``/iam/iot/getip ，无备用域名；
接口属于短连接调度服务，仅下发配置参数，不传输设备业务传感、控制报文；
接口具备版本兼容能力，同时适配存量老设备与新功能扩展，支持动态新增业务 type 类型，无需设备固件升级。

4.1.3 整体通信逻辑

设备本地 4G/WiFi 联网完成，具备公网访问能力后，发起 HTTPS POST 请求至调度接口；
调度服务接收请求，解析请求体内的项目密钥、业务类型参数，首先校验密钥拼接格式、设备凭证是否在合宙平台完成绑定；
凭证校验通过后，根据业务类型匹配对应服务，查询当前集群可用服务器节点、文件上传资源；
组装对应业务全套参数，以 JSON 格式返回给设备，包含：数据服务器地址与端口、传输协议鉴权凭据（如 UDP 专属密钥、MQTT 登录账号密码），以及图片、音频、运维日志文件上传所需的 HTTP 地址与表单参数；凭证校验失败则直接返回错误提示，不分配任何接入资源；
设备接收响应后缓存全套参数，根据返回的服务器地址与鉴权凭据建立 TCP/MQTT/UDP 长连接，或使用文件上传参数执行图片、音频、运维日志上传；
若业务服务器连接失败、文件上传地址失效，设备可重新发起调度请求刷新全套配置。

4.2 通信接口详细设计

请求（HTTPS）：

URL              https://gps.openluat.com/iam/iot/getip
METHOD           POST
CONTENT-TYPE     application/x-www-form-urlencoded
BODY             key=用户key-imei-muid&type=5

参数说明：

key：用户key + "-" + imei（或mac或者unique id）+ "-" + muid；string格式

type：0或不携带：定位产品

3：表示aircloud业务基于tcp协议上报数据；

4：表示aircloud业务基于udp协议上报数据；

5：表示aircloud业务基于mqtt协议上报数据。

8：表示最小急救系统业务基于http协议；

其他：后期指定业务

响应（JSON 格式）：

正常返回码：200，其他均是错误返回
注：对于 400、408 响应码，设备端需要考虑网络质量不稳定的处理

失败响应：

首先判断非 200 的。对于 200 响应时，需要检查响应中的 msg 参数是否为 "ok"，如果不是 "ok"，则描述的是失败原因。

{
  "msg": "invalid client"
}

成功响应：

首先判断 200 的，然后检查 msg 参数，如果结果是 "ok"，则是成功响应。响应的具体内容与 type 有关。

当 type 为 0 时，表示 gps 位置上报类的业务，响应格式为：

{
  "ipv4": "124.xx.xx.xx",
  "tcp": 7808,
  "ipv6": "2407:xxxx:xxxx:xxxx::xxxx:xxxx",
  "udp": 7809,
  "msg": "ok"
}
注意：可以提供ipv4及ipv6地址，且每类地址均可提供tcp及udp连接。

当 type 为 3、4、5 的时候，都表示基于 aircloud 的业务，返回格式相同，相应格式举例：

{
    "msg": "ok",
    "conninfo": {
        "ipv4": "124.xx.xx.xx",
        "ssl": "",// mqtt 才会有
        "port": xxxx,
        "key": "",// udp 鉴权 key
        "username": "{imei}",// mqtt 才会有
        "password": "{muid}",// mqtt 才会有
        "auth_key": "xxxxxxx"// turnkey 项目自动获取的 key
    },
    "imginfo": {
        "url": "https://xxx.xxx.com/api",
        "data_key": "f",
        "data_param": {
            "key": "xxxxxxx",
            "tip": ""
        }
    },
    "audinfo": {
        "url": "https://xxx.xxx.com/api",
        "data_key": "f",
        "data_param": {
            "key": "xxxxxxx",
            "tip": ""
        }
    },
    "mtninfo": {
        "url": "https://xxx.xxx.com/api",
        "data_key": "f",
        "data_param": {
            "key": "xxxxxxx",
            "tip": ""
        }
    }
}
说明： 
    conninfo段表示连接信息。其中：
    ipv4表示分配到的上传服务器ip，port表示上传端口。
    imageinfo和audioinfo分别表示图片上传及音频上传的服务器信息。其中：
    url是上传的api，上传时需要以form-data方式POST数据；
    data_key表示数据部分的参数（示例为”f”，按实际返回值填写），需要注意数据上传时，使用的名字即需要服务器保存的文件名，如果多次上传使用相同的文件名，后面的文件会覆盖前面的文件。 
    data_param里面作为其它参数（示例里表示需要额外加一个”key”,值为”xxxxx”，如果有其他参数，都作为POST参数携带）。

当 type 为 8 的时候，表示基于最小子系统急救的业务，返回的相应格式如下：

{
    "url":"https://gps.openluat.com/iot/open/fota/get_bin",        // 获取升级文件 URL
    "report_url":"https://gps.openluat.com/iot/open/fota/report",  // 上报升级结果 URL
    "key":"WxJrc1Y4ekQ1EmugbhHcDyGfENsr1ynEc9istK",  // 鉴权 Key,get_bin 及 report 时都携带该 key
    "msg":"ok"
}

4.3 getip 标准调用时机规范

满足以下任一条件，设备必须发起一次 getip 请求：

设备首次上电、冷重启，本地无缓存任何服务器连接、文件上传参数；
TCP/MQTT/UDP 长连接连续 3 次重连业务服务器全部失败，判定当前节点异常；
触发图片 / 音频 / 日志文件上传，但本地无有效上传 URL 缓存；
设备长时间离线后重新联网，重连业务服务器连续失败 3 次，触发 getip 刷新配置；
设备固件升级后，需应用层主动调用 excloud.close() + excloud.open() 重新初始化，触发 getip 拉取全套资源参数。

4.4 开发与业务通用注意事项

重试约束：单次 getip 请求失败，最多连续重试 3 次；每次重试间隔 5 秒，禁止高频循环轰炸接口；
缓存策略：接口返回的 conninfo、imginfo、audinfo 参数仅内存缓存，设备重启后丢失需重新拉取；正常重连优先复用缓存，减少 HTTPS 请求消耗流量；
编码规范：key 拼接分隔符严格使用英文 - ，禁止中文横杠、空格、下划线；IMEI/MAC 不可混入多余字符；
网络依赖：调用前必须确认模组 4G/WiFi 正常附着、DNS 解析正常，443 端口未被运营商防火墙拦截，否则会出现请求超时；
参数匹配约束：上报 AirCloud 二进制报文必须使用 type=3/4/5，若误传 type=1/2，响应不会返回业务长连接参数，无法建立 TCP/MQTT/UDP；
UDP 密钥约束：仅 type=4 场景会返回 64 字节 UDP 鉴权 KEY，type=3、5 无此字段，设备不可强行读取；
资源失效处理：缓存参数使用过程中出现鉴权报错、连接被主动断开，需清空本地缓存，重新调用 getip 刷新全套配置；
私有化部署约束：自建服务器场景不可保留 getip 自动调用逻辑，否则会持续请求合宙调度接口造成不必要流量消耗。

4.5 核心问题：客户自建私有 AirCloud 服务器，是否必须调用 getip？

结论说明：完全不需要，可直接关闭、跳过整套 getip 调用流程

底层边界说明：
- getip 是合宙公有云集群配套专属调度服务，仅用于获取合宙官方分布式节点地址；
- 客户自研、私有化部署 AirCloud 服务端时，TCP/MQTT/UDP 服务器 IP、端口为固定配置，或者服务端自行部署负载均衡，无需访问合宙调度接口。
设备端适配改造方案：
- 使用合宙 excloud 扩展库，在调用 excloud.setup 接口时手动关闭 getip 并写入私有服务地址。
关闭 getip 后的配套变更点
- UDP 承载所需 64 字节鉴权 KEY 无法从接口获取，需设备固件与私有服务端提前约定固定密钥；
- 图片、音频、运维日志文件上传 URL 不再由 getip 下发，客户需自行开发独立 HTTP 上传接口；
- 无自动容灾切换逻辑，断连后仅能重复重试固定 IP；如需多节点负载均衡，客户需自行搭建内部调度服务。
适用边界
- 仅设备接入合宙官方公有云平台时，强制启用 getip 调度流程；
- 自建私有服务器也可使用 getip 接口，只需配置 getip_url 指向私有调度服务地址；
- 若不使用 getip，需手动配置连接参数（host、port 等），但文件上传功能将不可用。

五、设备鉴权

TCP/MQTT 连接成功后，第一条上行报文必须发送鉴权 TLV

5.1 鉴权流程

设备准备：设备准备鉴权所需信息，包括用户 key（通过 getip 获取到的 auth_key）、设备 ID 和 MUID
发送鉴权请求：设备通过 TLV 格式发送鉴权请求
服务器校验：服务器解析鉴权信息，验证用户 key 和设备 ID 的合法性
返回鉴权结果：服务器返回鉴权成功或失败的响应

5.2 鉴权报文格式

TLV 类型：0x0010（16-鉴权请求）+ 0x0003（ASCII 字符串）

TLV 值（有 MUID）：用户 key + "-" + 设备 ID + "-" + MUID

TLV 值（无 MUID）：用户 key + "-" + 设备 ID

示例：

4G 设备鉴权：X1zBmxSd1H2Gy69DtAyNytmUe7dudGXm-862419074073247-20250605190426A662704A3771265005
WiFi 设备鉴权：X1zBmxSd1H2Gy69DtAyNytmUe7dudGXm-C8C2C68E12E6-20250605190426A662704A3771265005

5.3 鉴权回复

TLV 类型：0x0011（17-鉴权回复）+ 0x0003（ASCII 字符串）

TLV 值："ok" 或 "success"（鉴权成功），或错误信息（鉴权失败）

5.4 核心作用（公有云、自建私有服务器全部适用）

非法设备准入拦截

校验项目密钥、设备硬件 ID、MUID 三重凭证，仿冒、未注册设备直接断连，避免垃圾数据污染数据库、端口扫描攻击。
多租户数据隔离

一套服务端承载多个客户项目，依靠鉴权携带的项目 KEY 区分设备归属；不同客户数据、控制指令完全隔离，防止跨项目信息泄露。
流量、权限管控

合宙公有云：统计单设备每日上报消息量，匹配客户套餐限额，超限限制上报；区分设备是否允许下发短信、远程拉日志。私有服务器：可复用鉴权信息实现设备分级权限、自定义流量统计。
全链路故障溯源

鉴权报文绑定完整设备硬件标识，异常上报、故障指令可精准定位具体设备，便于售后排查、批量设备管理。

5.3 公有云与私有服务器鉴权差异

合宙公有云：KEY、IMEI、MUID 需提前在平台后台绑定，搭配 getip 实现双层前置校验；鉴权失败直接断开连接。
客户自建私有服务器：校验逻辑自主开发，可沿用标准拼接格式，也可简化规则；无 getip 前置校验，仅依靠连接后鉴权报文验证身份。

5.4 强制约束

无论公有云还是私有服务端，禁止跳过鉴权流程；未完成鉴权的设备，服务端拒收所有业务上报、控制指令，超时自动断开连接。

六、心跳机制

6.1 心跳规则

频率：设备每 5 分钟必须至少发送一个数据包至云端
内容：任何上行数据包都算作心跳，遵循 AirCloud 协议即可
超时：若两个心跳周期（10 分钟）未收到任何数据包，服务器将发起断链

6.2 心跳示例

设备可以通过定期上报设备状态信息作为心跳，例如上报设备电量：

字段	字节数	示例值	说明
消息头	16	0x01861234567890120002000C00000001	包含设备 ID、流水号、消息长度和消息标识
TLV 类型	2	0x0300	字段类型（769-电量）+ 数据类型（0000-整数）
TLV 长度	2	0x0002	电量值长度（2字节）
TLV 值	2	0x1388	电量值（5000mV）

七、设备数据上报（设备 → 服务端）

7.1 上报总体说明

设备主动将传感器采集数据、定位信息、设备运行状态、系统日志、短信流水等业务数据封装为协议报文上传至服务端，TCP、MQTT、UDP 三种传输通道共用同一套外层报文结构与 TLV 消息体编码规则。

上报分为三种触发模式：

定时周期上报：按照预设时间间隔周期性打包全量或精简测点数据；
事件触发上报：异常告警、参数变更、文件生成、短信收发等事件发生时即时上报；
被动查询上报：收到服务端查询指令后，按需回传指定字段数据。

7.2 报文外层结构与通用约束

完整报文头部、校验算法、数据包序列号、重传超时机制、错误丢弃规则，统一遵循本协议第 2 章报文结构；
消息体由一组或多组 TLV 单元连续拼接构成，TLV 基础编码规则见 2.4 章节；
单条数据包 TLV 总载荷最大长度为 1400 字节，超出长度必须拆分多包发送，分片重组由设备与服务端业务层自行实现。

7.3 上报 TLV 字段选用规则

上行上报业务载荷仅使用附录 A A.2 业务字段（类型值 256~2047）区间的 TLV 类型；
16~255 控制信令区间仅用于上报应答、文件上传通知等交互信令，不得作为采集测点数据封装；
A.2 业务字段分为五大类：传感采集类、GNSS 资产管理类、设备参数类、软件短信日志类、通用测试数据类，每一类具体类型编号、字段名称、数据含义完整定义查阅附录 A TLV 完整字段定义手册；
TLV 内部 bit12 ~ bit15 数据类型严格执行 2.4.3 章节规范（整数、浮点数、ASCII 字符串、二进制、UTF-8 字符串等）。

上报 TLV 组装示例

单次上报温度、GNSS 经纬度、电池电压三个测点，依次拼接 3 条独立 TLV：

Type=256 温度（浮点型）
Type=512 GNSS 经度（浮点型）
Type=771 设备电量（有符号整型，单位 mV）

各字段详细约束、取值范围参考附录 A 对应条目。

7.4 上报应答交互流程

设备组装完成上报数据包并发送；
服务端校验报文合法后，下行回复Type=18 上报回应控制信令；
Type=18 信令完整定义、传输方向见附录 A.1.1 控制信令总表；
设备未在超时窗口内收到上报回应时，启动报文重传逻辑，重传次数与超时时间由设备侧配置。

7.5 文件与运维日志上报特殊流程

设备如需上传图片、音频文件或运维日志，不直接在普通上报包传输二进制流，而是先上行发送Type=23 文件上传开始通知控制信令：

Type=23 信令 Value 域嵌套子 TLV 结构，包含文件上传类型、文件名、文件大小；
子 TLV 编号 784、785、786 释义见附录 A.2.3，嵌套组合格式详见附录 A.1.2.1；
服务端收到通知后开启文件接收通道，设备分片传输原始文件；
文件传输完毕后设备上行发送 Type=24 文件上传完成通知，携带上传结果状态，嵌套规则参考附录 A.1.2.2。

八、服务端指令下发（服务端 → 设备）

8.1 下发总体说明

服务端通过 TCP/MQTT/UDP 通道向设备下发远程控制指令、参数配置修改、短信发送请求、日志拉取、iRTU 透传命令等操作指令，下行报文外层帧格式、校验方式、序列号规则与设备上报报文完全一致，保证协议单侧解析逻辑复用。

8.2 下行 TLV 字段选用规则

指令下发消息体载荷仅使用附录 A A.1 控制信令（类型值 16~255）区间 TLV 类型；
256 及以上业务字段不直接作为一级下发 TLV，仅可在部分复杂信令内部作为嵌套子 TLV 使用；
全部控制信令编号、名称、通信方向、基础用途统一查阅附录 A.1.1 控制信令总表；
嵌套子 TLV 编码、长度计算、数据类型规则与全局 TLV 规范保持一致。

8.3 核心指令分类与嵌套规范

8.3.1 基础交互类信令

包含设备鉴权请求 / 回复、上报应答、指令回执闭环等链路基础信令，用于维持通信链路有效性与数据交互可靠性。

8.3.2 通用远程控制命令

Type=19 控制命令：平台通用下发指令，可实现设备重启、修改上报周期、调整休眠模式、切换联网参数等配置操作；其 Value 域可嵌套附录 A.2.3 设备参数类子 TLV 传递配置值；
Type=21 iRTU 下行命令：专属工业 RTU 设备透传控制指令，用于串口 / Modbus 下游设备操控。

8.3.3 文件与运维类指令

Type=25 运维日志上传请求：服务端主动触发设备上传本地运行日志；
文件上传相关回执信令（Type=24）嵌套 784/785/787 子 TLV，结构约束详见附录 A.1.2。

8.3.4 短信 SMS 业务指令

Type=28 SMS 发送请求：平台远程下发短信发送任务，指定接收号码与短信内容；
设备执行后上行 Type=29 发送响应，送达回执通过 Type=30 上报，平台使用 Type=31 确认回执，完整 SMS 信令链路定义参考附录 A.1.1。

8.4 指令执行回执闭环机制

服务端下发指令报文携带唯一报文流水号；
设备解析有效指令并完成业务执行后，上行携带相同流水号的应答报文：
- Type=19 通用控制命令 → 设备回复 Type=20 控制回应；
- Type=21 iRTU 下行命令 → 设备回复 Type=22 iRTU 上行回复；
- SMS、文件、日志类信令对应专属回执 TLV；
服务端依据流水号匹配原始下发指令，判断执行结果，完成一次完整指令下发闭环。

8.5 下发分包长度限制

单条下行数据包整体 TLV 消息体最大长度同样约束为 1400 字节，超长批量配置指令由服务端做分包下发，设备业务层完成多条分包数据汇总解析。

九、业务流程与时序图

9.1 AirCloud 连接流程

初始化配置：设备初始化配置，调用 setup 方法
调用 open 方法：启动连接流程
获取连接信息：调用 getip 服务，获取连接信息
获取服务器信息：获取成功后，获取服务器信息；失败则重复获取三次，三次都失败则返回失败
创建连接：创建连接，连接服务器
发送鉴权请求：连接成功后，发送鉴权请求
鉴权成功：鉴权成功后，进行状态数据上报、文件上报、接收下发数据和指令
启动心跳机制：启动心跳机制，定期发送心跳
重连机制：若连接失败，进入重连机制，先用当前连接信息重连，达到最大重连次数后重新调用 getip 服务

aircloud运行流程.png

9.2 文件上传流程

调用上传接口：设备调用上传接口（upload_image/upload_audio）
检查 getip 服务：检查是否使用 getip 服务，若否则返回失败（手动填写 IP 不允许上传）
检查文件存在：检查文件是否存在，若否则返回失败
检查服务器连接：检查是否连接到服务器，若否则返回失败
检查上传配置：检查上传配置（url），若无配置则调用 getip 获取
上传文件：获取配置成功后，开始上传文件
发送通知：根据上传结果发送成功或失败通知
返回结果：返回上传结果

aircloud文件上传流程.png

9.3 运维日志功能流程

9.3.1 初始化流程

初始化 excloud.setup：在 excloud.setup 时初始化运维日志功能
检查是否启用：检查是否启用运维日志功能，若否则返回成功但功能禁用
初始化 exmtn：调用 exmtn.init 初始化，若失败则返回失败并记录错误
初始化成功：初始化成功后，运维日志功能可用

aircloud运维日志初始化.png

9.3.2 日志写入流程

调用 excloud.mtn_log：调用 excloud.mtn_log 接口写入日志
检查是否启用：检查是否启用运维日志功能，若否则返回失败
记录日志：调用 exmtn.log 记录日志，返回成功

aircloud运维日志写入.png

9.3.3 日志上传流程

接收上传请求：接收运维日志上传请求并处理
检查是否正在上传：检查是否正在上传，若是则抛弃新请求
发送响应：发送运维日志上传响应，启动上传任务
设置上传标志：设置上传标志位，扫描运维日志文件
遍历日志文件：遍历检查每个日志文件，若文件存在且不为空则开始上传
检查上传配置：检查上传配置，若无配置则调用 getip 获取
上传文件：获取配置成功后，调用 upload_file 上传文件
发送状态通知：根据上传结果发送成功或失败状态通知
通知上传进度：通知上传进度，若还有文件则继续上传
通知上传完成：所有文件上传完成后，通知上传完成并清除上传标志位

aircloud运维日志上传.png

9.4 时序图

9.4.1 http+mqtt基本业务

aircloud_mqtt+http时序图.png

9.4.2 http+tcp基本业务

aircloud_tcp+http时序图.png

9.4.3 http+udp基本业务

aircloud_udp+http时序图.png

十、云端实现

10.1 数据存储

存储方式：设备全部上报数据统一存入后台数据库进行持久化存储；
存储内容：涵盖终端上传的各类业务采集数据、云端下发的远程控制信令、设备在线状态交互指令等全量交互信息。

10.2 数据查询与展示

Web 管理后台：内置网页表单化日志查询功能，支持多条件筛选检索，查询结果可直接导出为本地文件留存；
开放 API 接口：对外提供标准化数据查询 API 接口，便于客户第三方业务系统、上位管控平台快速对接集成；
数据可视化：提供数据可视化展示功能，直观呈现设备运行状态等信息。

10.3 安全机制

设备接入鉴权：所有终端设备发起云端连接请求前均需完成身份鉴权校验，非法设备直接拦截拒绝接入；
传输数据加密：设备与云平台之间的通信报文支持传输加密，防止数据在公网传输过程中被窃听、篡改；
分级访问控制：后台采用账号权限分级管理模式，依据角色分配不同操作权限，规范数据查看、导出、设备管控等操作范围。

十一、客户套餐

合宙云平台设置多档位分级客户套餐，适配个人测试、中小项目、规模化批量部署等不同使用场景需求，具体资费与权益如下：

套餐版本	年费	可接入设备数量	每日上行消息限额	数据保存时间	API 对接权限	日志导出	二级用户数量
免费版	0	3	1000	7 天	不支持	不支持	不支持
标准版	¥3000	100（支持付费扩容）	1.5 万	6 个月	支持	支持	10
VIP 版	¥10000	1000（支持付费扩容）	150 万	12 个月	支持	支持	100

扩容增值费用说明：

设备数量扩容：每新增 100 台设备，年费增加 500 元
每日上行消息扩容：每新增 10 万条日消息额度，年费增加 500 元
二级子账号扩容：每新增 100 个二级管理用户，年费增加 200 元
历史数据存储扩容：每年新增 1 亿条报文存储容量，年费增加 1000 元

十二、常见问题及解决方案

12.1 设备无法连接云平台

可能原因：

网络问题：设备网络连接异常
鉴权失败：用户 key 或设备 ID 错误
服务器问题：云平台服务器暂时不可用

解决方案：

检查设备网络连接状态
验证用户 key 和设备 ID 是否正确
稍后重试连接

12.2 数据上报失败

可能原因：

消息格式错误：协议格式不符合要求
消息长度超限：单条消息超过 1400 字节
网络中断：数据传输过程中网络中断

解决方案：

检查消息格式是否正确
拆分长消息为多条短消息
实现断点续传机制

12.3 设备频繁断连

可能原因：

心跳超时：设备未按时发送心跳包
网络不稳定：设备网络连接不稳定
服务器压力：云平台服务器压力过大

解决方案：

确保设备按时发送心跳包
优化设备网络连接稳定性
联系合宙技术支持

附录 A TLV 完整字段定义手册

说明：本附录对应正文 2.4.2 小节，TLV 的 bit0 ~ bit11 为此处十进制类型值，bit12 ~ bit15 为数据类型（见正文 2.4.3）。

A.1 控制信令（类型值 16 ~ 255）

A.1.1 控制信令总表

类型值	名称	方向	说明
16	鉴权请求	上行	设备向服务器发送鉴权信息
17	鉴权回复	下行	服务器返回鉴权结果
18	上报回应	下行	服务器对设备上报的回应
19	控制命令	下行	服务器对设备下发的控制命令
20	控制回应	上行	设备对控制命令的回应
21	iRTU 下行命令	下行	服务器向 iRTU 设备下发的命令
22	iRTU 上行回复	上行	iRTU 设备对命令的回复
23	文件上传开始通知	上行	设备通知服务器开始上传文件
24	文件上传完成通知	上行	服务器通知设备文件上传完成
25	运维日志上传请求	下行	服务器请求设备上传运维日志
26	文件上传完成通知	上行	设备回应运维日志上传请求
27	运维日志上传状态	上行	设备上报单个日志文件上传状态
28	SMS 发送请求	下行	平台向设备下发短信发送指令
29	SMS 发送响应	上行	设备向平台回复短信发送结果
30	SMS 回执上报	上行	设备收到短信送达回执后，上报给平台
31	SMS 回执确认	下行	平台确认收到回执上报

A.1.2 特殊信令子 TLV 结构说明

A.1.2.1 23 文件上传开始通知（Type=23）

作用：设备通过 TCP/MQTT 通知服务器开始上传文件。

完整 TLV 结构：

T: 0x0017 (信令类型 23)
L: 内部所有子 TLV 总字节长度
V 内部包含以下子 TLV：
- 784 文件上传类型（整数：1 = 图片，2 = 音频）
- 785 文件名称（ASCII 字符串）
- 786 文件大小（整数，单位字节）

A.1.2.2 24 文件上传完成通知（Type=24）

作用：设备通知服务器文件上传成功。

完整 TLV 结构：

T: 0x0018 (信令类型 24)
L: 内部所有子 TLV 总字节长度
V 内部包含以下子 TLV：
- 784 文件上传类型（整数）
- 785 文件名称（ASCII 字符串）
- 787 上传结果状态（整数：0 = 成功，1 = 失败）

A.2 业务字段（类型值 256 ~ 2047）

A.2.1 传感采集类（256 ~ 511）

类型值	名称	说明
256	温度	设备采集的温度数据
257	湿度	设备采集的湿度数据
258	颗粒数	设备采集的颗粒物数量
259	酸度	设备采集的酸度值
260	碱度	设备采集的碱度值
261	海拔	设备当前海拔高度
262	水位	设备采集的水位数据
263	CPU 温度	设备 CPU 温度
264	电量计量	设备电量消耗计量

A.2.2 GNSS 资产管理类（512 ~ 767）

类型值	名称	说明
512	GNSS 经度	设备定位经度
513	GNSS 纬度	设备定位纬度
514	行驶速度	设备行驶速度
515	GNSS 卫星 CN	最强 4 颗卫星的信号强度
516	卫星总数	搜到的卫星总数
517	可见卫星数	可见卫星数量
518	航向角	设备行驶方向角
519	定位标识	基站定位/GNSS 定位标识
520	GNSS 芯片信息	GNSS 芯片型号和固件版本
521	方向	设备朝向

A.2.3 设备参数类（768 ~ 1023）

类型值	名称	说明
768	高度	设备高度
769	宽度	设备宽度
770	转速	设备转速
771	电量	设备电量（mV）
772	驻留频段	设备当前驻留频段
773	小区信息	驻留小区和临区信息
774	元器件型号	设备元器件型号
775	GPIO 状态	GPIO 高低电平状态
776	开机原因	设备开机原因
777	开机次数	设备开机次数
778	休眠模式	设备休眠模式
779	定时唤醒间隔	设备定时唤醒间隔
780	IP 类型	设备入网的 IPV4/IPV6 标志
781	联网方式	当前联网方式（4G/WiFi/以太网）
782	4G 信号强度	4G 网络信号强度
783	ICCID	SIM 卡 ICCID
784	文件上传类型	文件上传类型（1: 图片, 2: 音频）
785	文件名称	上传文件的名称
786	文件大小	上传文件的大小（字节）
787	上传结果状态	文件上传结果状态（0: 成功, 1: 失败）

A.2.4 软件 \& 短信日志类（1024 ~ 1279）

类型值	名称	说明
1024	Lua 核心库错误	LuatOS 核心库错误上报
1025	Lua 扩展卡错误	LuatOS 扩展卡错误上报
1026	Lua 业务错误	LuatOS 业务错误上报
1027	固件版本号	设备固件版本号
1028	SMS 转发	短信转发内容
1029	来电转发	来电信息转发
1030	系统总内存大小	系统总内存大小
1031	系统当前已使用内存大小	系统当前已使用的内存大小
1032	系统历史最高已使用内存大小	系统历史最高已使用内存大小
1033	Lua 虚拟机总内存大小	Lua 虚拟机总内存大小
1034	Lua 虚拟机当前已使用内存大小	Lua 虚拟机当前已使用内存大小
1035	Lua 虚拟机历史最高已使用内存大小	Lua 虚拟机历史最高已使用内存大小
1036	PSRAM 总内存大小	PSRAM 总内存大小
1037	PSRAM 当前已使用内存大小	PSRAM 当前已使用内存大小
1038	PSRAM 历史最高已使用内存大小	PSRAM 历史最高已使用内存大小
1039	SMS 流水号	消息唯一编号
1040	SMS 接收方号码	短信接收方手机号
1041	SMS 短信内容	短信文本
1042	SMS 状态码	发送/送达结果
1043	SMS 发送方号码	接收短信时的来电号码
1044	SMS 长短信标志	0=普通短信，1=长短信
1045	SMS 长短信总条数	长短信的总分片数
1046	SMS 长短信当前序号	长短信当前分片的序号
1047	运营商消息参考号	运营商返回的消息参考号
1048	SMS 状态码原始值	发送/送达结果

A.2.5 通用测试数据类（1280 ~ 1535）

类型值	名称	说明
1280	时间	当前时间
1281	无意义数据	测试用无意义数据

附录 B 专业术语表

术语	解释
AirCloud	合宙 IOT 通用报文协议，用于设备数据上报和指令下发
getip	合宙提供的负载均衡接口，用于获取服务器 IP 和端口
GNSS	Global Navigation Satellite System，全球导航卫星系统
ICCID	Integrated Circuit Card Identifier，集成 SIM 卡标识
IMEI	International Mobile Equipment Identity，国际移动设备标识
iRTU	合宙工业远程终端单元，用于工业设备监控和控制
MAC	Media Access Control，媒体访问控制地址
MUID	设备唯一标识，用于设备鉴权
TLV	Type-Length-Value，一种数据编码格式，包含类型、长度和值三部分