协议详解

合宙 IOT 通用报文协议 AirCloud

三、协议详解

3.1 消息头结构

消息头固定 16 字节，包含以下字段：

字段	字节数	说明
设备 ID	8	包含设备类型（1字节）和设备唯一标识（7字节）
流水号	2	消息序列号，用于标识消息顺序
消息长度	2	从消息体开始的消息长度，最长不超过 1400 字节
消息标识	4	包含协议版本号、是否需要回复等标志

3.1.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 位为校验位）

示例：

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

3.1.2 消息标识详解

消息标识共 4 字节（32 位），定义如下：

位	含义
bit0-3	协议版本号
bit4	是否需要回复（1：需要，0：不需要）
bit5	是否是 UDP 承载（1：是，0：否）
bit6-31	预留（置 0）

3.1.3 UDP 专用字段

注意：当使用 UDP 承载时（消息标识 bit5 为 1），在消息头和消息体之间需要添加一个 64 字节的 key 字段。

字段	字节数	说明
UDP Key	64	用于 UDP 报文的鉴权，通过 getip 接口获取

使用规则：

• 仅在 UDP 承载时需要添加此字段
• Key 长度固定为 64 字节
• Key 通过调用 getip 接口（type=4）获取
• 服务器会对每个 UDP 消息进行 Key 的合法性检查

3.2 消息体结构

消息体采用 TLV（Type-Length-Value）格式，可包含多个 TLV 单元，每个 TLV 单元由以下三部分组成：

字段	字节数	说明
Type（类型）	2	前 12 位表示字段含义，后 4 位表示数据类型
Length（长度）	2	Value 字段的长度
Value（值）	可变	实际的字段值

3.2.1 数据类型定义

数据类型占用 Type 字段的后 4 位，定义如下：

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

3.2.2 字段含义定义

字段含义占用 Type 字段的前 12 位，范围 0-4095，分为以下几类：

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