跳转至

合宙 IOT 通用报文协议 AirCloud -- 1.0

二、协议报文详解

报文分为消息头和消息体两部分。

消息头只有一个，在报文开头，固定12个字节，分为设备ID，消息长度，版本标志三个字段。

消息体可以有多个，采用TLV的形式。

除了特殊约定外，报文的各个字节采用大端对齐的方式。

2.1 消息头

消息头一共 16 字节。

2.1.1 设备 ID - 8 字节

其中第一个字节，代表设备类型，4G，WiFi，BLE，等。

0x01 - 4G 设备；

0x02 - WiFi 设备；

0x03 - BLE 设备；

0x04 - 以太网设备；

0x05 - 4G 主控，多网融合设备；

0x06 - WiFi 主控，多网融合设备

0x07 - BLE 主控，多网融合设备；

0x08 - 以太网主控，多网融合设备。

剩余 7 字节为设备 ID，可以是 IMEI，也可以是 MAC， 也可以是 Chip ID，不做特殊约定。

其中， IMEI 在这里只放前面14个数字，第15个数字，参见3.3.1 小节计算出来。

设备 ID 采用 BCD 编码方式。

设备 ID 长度不足 7 字节的，自动在高位补 0.

例 1，一个 4G 设备， IMEI 是 861234567890123 的，设备的 8 个字节的内容是：

0x0186123456789012

第 15 个数字 3， 是不在设备 ID 体现的。

例 2，一个 WIFI 设备的 MAC 地址是 00-1A-2B-3C-4D-5E，该设备的 8 个字节的内容是：

0x 02 00 00 1A 2B 3C 4D 5E

2.1.2 流水号 - 2 字节

2.1.3 消息长度 - 2 字节

从消息标识开始的消息长度，最长不能大于 1400字节。

2.1.4 消息标识-4 字节

用来做协议和消息约定的32个bit。

bit0-3： 协议版本号；

bit4：    是否需要回复

bit5：    是否携带鉴权 key

bit6：    是否是 UDP 承载。

其余25个bit 为0.

2.2 消息体

消息体有多个 TLV 组成： T-字段类型，L-字段长度，V-字段取值，可以任意多个 TLV， 只要消息长度不超过 1400 字节即可。

1， 字段类型 - 2 字节

前面 12 个 bit， 代表字段含义，比如温度，湿度，转速，工作或者停止，等等；

后面 4bit，代表数据类型（整数，浮点，bool，ascii，binary）

2， 长度 - 2 字节

字段取值的长度

3， 字段值

实际的值。

2.3 消息字段示例

字段
**字段名**
**长度**
含义
消息头
设备ID
8

第一个字节，代表设备类型，4G，WiFi，BLE，等；
剩余7字节为设备ID，可以是IMEI，也可以是MAC， 也可以是Chip ID，不做特殊约定。
详细解释参见2.1.1节
消息头
流水号
2

消息头
消息长度
2

从消息体（既不包含消息头和认证key（可选））开始的消息长度，长度不做限制。
消息头
消息标识
4

bit0-3： 协议版本号；
bit4： 是否需要回复
bit5： 是否是 UDP承载
其余26个bit 为0.
认证key（可选）
key
64

用于 UDP 报文的鉴权
TLV1
字段类型
2
 bit0 到 bit11， 代表字段含义，比如温度，湿度，转速，工作或者停止，等等；
bit12到bit15，代表数据类型（整数，浮点，bool，ascii，binary）
TLV1
长度
2

TLV1
字段值
N

TLV2
字段类型
2

TLV2
长度
2

TLV2
字段值
N

......







2.4 设备鉴权

在设备建立连接之前，需要发送鉴权消息。

鉴权的方式是，通过 TLV 传递用户的 key+IMEI(或者 MAC)+MUID，由服务器判断是否合法，如果不合法的话，服务器主动发起断链操作。

报文 value：用户 key+"-"+imei（或 mac）+"-"+muid（或 unique_id）

字段类型： 0003 - ASCII 可打印字符串

示例： 对于 4g 模组：

例如：

完整报文就是：X1zBmxSd1H2Gy69DtAyNytmUe7dudGXm-862419074073247-20250605190426A662704A3771265005

对于 wifi 模组：

用户 key：客户在平台创建项目的时候生成的字符串，可打印字符

Sta mac：wifi 模组的 sta mac，获取的 hex 格式的 mac 地址，为 16 进制可见字符串

muid：等待适配

例如：

用户 key 参考 iot 平台的如：X1zBmxSd1H2Gy69DtAyNytmUe7dudGXm

Sta mac：C8C2C68E12E6

完整报文：X1zBmxSd1H2Gy69DtAyNytmUe7dudGXm-C8C2C68E12E6-muid（等待适配）

对于以太网模组（mcu+ 网口）：

用户 key：客户在平台创建项目的时候生成的字符串，可打印字符

以太网 mac：以太网的 mac，需要转为十六进制可见字符串

unique_id：muc 通过 mcu.unique_id()获取的唯一 id，需要转为十六进制可见字符串

示例：用户 key 参考 iot 平台的如：X1zBmxSd1H2Gy69DtAyNytmUe7dudGXm

服务器校验逻辑：

服务器收到鉴权消息后解析出 key、imei（mac）、muid，并校验 imei 和 muid 是不是匹配，然后通过 key 找到对应的项目，在项目中查找是否存在该 imei（mac）设备，存在就返回鉴权成功，不存在就返回失败，并断开链接

服务器需要注意，生成的用户 key 不能有 "-"符号。

服务器校验成功后，需要下发"ok"或者"success"通知模组，字段类型为 17

2.5 心跳约定

设备主动向云平台报告在线状态、维持连接活性。

心跳规则：

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