三级架构串口协议

Zigbee 三级架构简介

涂鸦 Zigbee 三级架构主要用于集中器类设备，例如空调集中器、暖通集中器等（以下称为二级设备）。该类设备通过 Zigbee 模组与网关通信，从而实现远程访问。同时，该类设备可以挂载多个三级设备，例如通过 485 总线控制的终端设备。

整体架构图如下：

每一个三级子设备注册成功后，都能通过涂鸦 App 看到其自身的控制面板，进而实现独立控制。

硬件连接

涂鸦 Zigbee 模组和 MCU 端主控均采用 DC 3.3V 电压供电。两者之间使用串口通讯，UART 接口引脚采用标准逻辑。在空闲状态下，TXD 和 RXD 引脚均为高电平，以低电平作为起始位，以高电平作为停止位。

串口通信参数

• 波特率：115200 bps
• 数据位：8
• 奇偶校验：无
• 停止位：1
• 数据流控：无
• 模组 TXD：PA5
• 模组 RXD：PA6

帧格式说明

通讯帧格式如下：

字段	中文	说明
Frame Head	帧头	固定为 0x55AA。该字段会被用于帧格式检查（进行数值的比较，而不是字符/字符串的比较）
Version	版本号	串口通信协议版本，升级扩展用，本协议版本号为 0x02。该字段会被用于帧格式检查（进行数值的比较，而不是字符/字符串的比较）
SEQ	序列号	传输数据序列号（Sequence number），1 ~ 0xfff0 循环。下文用 xx xx 表示
Command ID	命令字	命令 ID，持续更新。该字段会被用于帧命令解析（进行数值的比较，而不是字符/字符串的比较）
Data Length	数据长度	传输的有效数据长度
Data	数据	传输的有效数据。如果有效数据长度为 0，则帧不包含该字段
Checksum	校验和	用于数据校验。从帧头开始按字节求和，然后将计算结果对 256 求余。下文用 xx 表示

命令字索引（Command ID）

命令字	发送方	说明
0x01	Z	产品信息查询
0x02	Z	模组网络状态通知
0x03	M	模组配网/复位
0x04	M	添加三级子设备（支持多 PID）
0x05	M	添加三级子设备 （可扩展 PID，只支持单个 PID，多个 Address）
0x06	M	模组 RF 测试
0x07	Z	查询所有三级设备状态
0x08	Z	三级设备命令下发
0x09	M	三级设备状态上报
0x0A	M	MCU 删除三级子设备
0x0B	Z/M	查询 MCU 版本
0x0C	Z	OTA 升级通知
0x0D	M	OTA 固件内容请求
0x0E	M	OTA 升级结果上报
0x10	Z	二级设备命令下发
0x11	M	二级设备状态上报（被动）
0x12	M	二级设备状态上报（主动）
0x24	M	同步时间
0x44	M	群组广播

协议详解

产品信息查询（0x01）

Zigbee 模组上电后会主动向 MCU 发送产品信息查询命令来请求 PID 与版本号信息。

MCU 应答 PID 和版本号信息应该是模组上电后 MCU 发送给模组的第一条命令，MCU 需在应答此命令后，方可发送其他命令。若 MCU 未回复或回复内容格式有误，模组会间隔 5s 重复查询。

模组发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x01
数据长度	2	0x0000
数据	0	无
校验和	1	xx

示例：55 AA 02 xx xx 01 00 00 xx

MCU 回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x01
数据长度	2	N
数据	N	产品信息，示例 {"p":"AIp08kLI", "v":"1.0.0"}
校验和	1	xx

产品信息：

• p：表示该集中器在涂鸦开发者平台的 PID（产品标识），由涂鸦云开发者平台生成。
• v：表示 MCU 固件版本号，x.y.z 格式。其中 x：0 ~ 3、y：0 ~ 3、z：1 ~ 15，因此可表示的固件版本范围是：0.0.1 ~ 3.3.15。

示例：55 AA 02 xx xx 01 00 1C 7B 22 70 22 3A 22 41 49 70 30 38 6B 4C 49 22 2C 22 76 22 3A 22 31 2E 30 2E 30 22 7D xx

模组网络状态通知（0x02）

当网络状态发生改变，模组会主动发送此命令给 MCU。

网络状态是指 Zigbee 本地网络状态（非互联网连接状态），该状态不会因网关断电、父节点丢失等情况而变更。

模组发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x02
数据长度	2	0x0001
数据	1	模组网络状态
校验和	1	xx

模组网络状态

• 0x00：未入网，例如设备首次上电、设备配网失败、App 移除等。
• 0x01：已入网，表示设备已加入一个 Zigbee 网络。
• 0x02：网络状态异常，表示模组还没有准确收到来自 MCU 的 产品信息。
• 0x03：设备正在配网。

示例：55 AA 02 xx xx 02 00 01 01 xx 表示模组已入网。

MCU 回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x02
数据长度	2	0x0000
数据	0	无
校验和	1	xx

示例：55 AA 02 xx xx 02 00 00 xx

模组配网/复位（0x03）

MCU 可以主动发送此命令给模组，让模组软件复位或者开始配网。

当 MCU 回复 PID 信息与版本后，可以发起配网指令（0x03）。当模组收到配网指令后，会先给 MCU 发送未入网的联网状态，再发送配网中的联网状态。在配网超时时间内模组入网后会发送配网成功联网状态，反之模组回复未入网状态。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x03
数据长度	2	0x0001
数据	1	0x00：模组软件复位 0x01：模组开始配网（先断开与网关的通信，再配网）
校验和	1	xx

示例：55 AA 02 xx xx 03 00 01 01 xx 模组开始配网。

模组回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x03
数据长度	2	0x0001
数据	1	0x00：成功
校验和	1	xx

示例：55 AA 02 xx xx 03 00 01 00 xx

添加三级设备（0x04）

MCU 通过此命令添加三级子设备，需包含三级子设备的 PID、地址信息，支持多个 PID 同时添加。
地址由 MCU 管理编号，每个三级子设备地址唯一。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x04
数据长度	2	N
数据	N	添加三级子设备列表
校验和	1	xx

添加三级子设备列表

字段	字节数	说明
添加子设备个数	1	N：最大不超过 10 个设备
终端设备 1 PID	8	三级子设备的 PID
设备 1 地址	2	三级子设备的地址，由 MCU 管理
终端设备 2 PID	8	-
设备 2 地址	2	-
……		根据添加设备个数，增加字段
终端设备 10 PID	8	-
设备 10 地址	2	-

示例：55 AA 02 xx xx 04 00 0B 01 66 6A 35 66 71 65 67 39 00 01 xx

本例中，添加一个三级子设备，子设备 PID 为 fj5fqeg9，地址为 00 01。

模组回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x04
数据长度	2	0x0000
数据	0	无
校验和	1	xx

示例：55 AA 02 xx xx 04 00 00 xx

添加三级设备-拓展命令（0x05）

该条协议为扩展功能为：适用于 PID 长度超过 8 个字节的情况。子设备地址默认 2 字节，网关会将地址作为编号处理，设备地址唯一。

仅支持添加单个 PID，支持添加多个子设备地址。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x05
数据长度	2	N
数据	N	添加三级子设备扩展列表
校验和	1	xx

添加三级子设备扩展列表

字段	字节数	说明
PID 长度	1	根据实际 PID 长度填写
PID	N	三级子设备的 PID
子设备数量	1	添加的子设备数量 M
子设备地址	2 * M	添加的子设备地址列表

示例：55 AA 02 xx xx 05 00 14 10 78 76 72 6F 31 77 30 77 6A 6E 64 67 73 77 78 64 01 00 01 xx

在本例，添加一个 PID 长度为 16 的三级子设备，子设备地址为00 01。

模组回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x05
数据长度	2	0x0000
数据	0	无
校验和	1	xx

示例：55 AA 02 xx xx 05 00 00 xx

模组 RF 测试（0x06）

MCU 可以主动发送此命令给模组，让模组开始 RF 测试，从而测试模组的 RF 数据发送和接收是否正常。

开始 RF 测试前，需要准备一个产测 Dongle，并将产测 Dongle 配置为 RF 模式，详细流程请参考 设置 Zigbee Dongle。

模组收到该命令后，会进入 RF 测试，然后向空中发送特定格式的裸数据包，每包间隔 20 ms，共发 100 个包。产测 Dongle 每收到一包，都会回环式返回。如果模组收到的数据包，与自身发送的裸数据包内容相同，则会认为其成功接收了一个回环数据包。

RF 测试结束后，模组会发送 RF 测试结果（含接收的有效数据包个数）给 MCU，MCU 可以评估模组的发送和接收能力。但该命令暂未对信号强度进行检测。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x06
数据长度	2	0x0001
数据	1	信道号（11 ~ 26），默认第 11 号信道
校验和	1	xx

示例：55 AA 02 xx xx 06 00 01 0B xx 在第 11 号信道进行 RF 产测。

模组回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x06
数据长度	2	0x0002
数据	2	RF 测试结果
校验和	1	xx

RF 测试结果（状态 1 字节，回环数据包个数 1 字节）：

• Data[0] = 0x00，表示测试失败。Data[1] = 0x00，表示未接收到回环的数据包。
• Data[0] = 0x01，表示测试成功。Data[1] = 回环数据包个数（1 ~ 100）。

示例：55 AA 02 xx xx 06 00 02 01 62 xx 表示 RF 测试成功，发送了 100 个数据包，收到了 98 个数据包。

查询所有三级设备状态（0x07）

当配网成功后或网关重启后，网关会向模组发出同步子设备 DP 状态命令，模组则发送该命令通知 MCU。

当 MCU 收到该指令后需要将三级子设备的状态上报，上报的数据不能超出 62 字节，若 DP 数据过长需分多包上报。

模组发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x07
数据长度	2	0x0000
数据	0	无
校验和	1	xx

示例：55 AA 02 xx xx 07 00 00 xx

三级设备命令下发（0x08）

网关对三级子设备下发控制命令，模组透传三级子设备地址及 DP 消息给 MCU。

模组发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x08
数据长度	2	N：取决于 DP 消息类型与个数 + 子设备地址长度
数据	N	子设备地址（2 字节） + DP 消息
校验和	1	xx

DP 消息格式：

1 个 DP 消息可能会包含多个 DP 数据，每 1 个 DP 数据的格式如下：

• DP ID：对应该产品 ( PID ) 在涂鸦开发者平台的 DP ID。
• Type：对应该 DP ID 的数据类型，部分数据类型的 Length 是固定的。
• Length：Value 的数据长度。
• Value：DP 有效数据。

Type 格式：

Type	DP 类型	数据长度	说明
0x00	Raw	N	Raw 数据，Hex 格式，可自定义每个字节的含义
0x01	Bool	1	布尔型，0x00/0x01
0x02	Value	4	数值型，例如 1、23、104
0x03	String	N	字符串，可自由定义含义
0x04	Enum	1	枚举型，范围 0-255
0x05	Bitmap	1/2/4	Bitmap 型，主要用于错误码上报等

示例：55 AA 02 xx xx 08 00 07 00 01 03 01 00 01 01 xx 模组收到 DP 消息，包含 1 个 DP 数据，如下所示：

• 三级子设备地址：00 01
• DP ID：03
• Type：01
• Length：00 01
• Value：01

MCU 回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x08
数据长度	2	0x0000
数据	0	无
校验和	1	xx

示例：55 AA 02 xx xx 08 00 00 xx

三级设备状态上报（0x09）

当三级子设备状态发生变化时, 可以通过此命令上报，以同步 App 端设备状态。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x09
数据长度	2	N：取决于 DP 消息类型与个数 + 子设备地址长度
数据	N	子设备地址（2 字节）+ DP 消息
校验和	1	xx

本例展示 MCU 上报一个三级子设备 DP 数据：

• 三级子设备地址：00 01
• DP ID：03
• DP Type：01
• DP Length：00 01
• DP Value：01

模组回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x09
数据长度	2	0x0003
数据	3	子设备地址（2 字节）+ 结果（1 字节）
校验和	1	xx

结果：

• 0x00：成功
• 0x01：失败

示例：55 AA 02 xx xx 09 00 03 00 01 00 xx

MCU 删除三级子设备（0x0A）

MCU 可以通过主动发送该命令移除指定三级子设备。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x0A
数据长度	2	0x0002
数据	2	待删除子设备地址
校验和	1	xx

示例：55 AA 02 xx xx 0A 00 02 00 01 xx 表示删除子设备地址为 00 01 的三级子设备。

模组回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x0A
数据长度	2	0x0003
数据	3	子设备地址（2 字节）+ 结果（1 字节）
校验和	1	xx

结果：

• 0x00：成功
• 0x01：失败

示例：55 AA 02 xx xx 0A 00 03 00 01 00 xx

查询 MCU 版本（0x0B）

当模组收到来自网关的查询命令，模组会主动发送此命令给 MCU，MCU 需要应答 MCU 当前的固件版本号。例如，判断是否推送 OTA。

MCU 也可以通过此命令，主动发送 MCU 当前的固件版本号给模组，例如模组配网成功、MCU 固件 OTA 升级成功。

模组获取到 MCU 当前的固件版本号后，会同步 MCU 当前的固件版本号给涂鸦云端，用于展示或者 OTA 升级的判断。

模组发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x0B
数据长度	2	0x0000
数据	0	无
校验和	1	xx

示例：55 AA 02 xx xx 0B 00 00 xx 查询 MCU 的当前版本号。

MCU 回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x0B
数据长度	2	0x0001
数据	1	MCU 固件版本号（1 字节）
校验和	1	xx

MCU 固件版本号，1 字节，8 个 Bits 按二进制 xx.yy.zzzz 格式。例如 0x40 二进制为 01 00 0000，表示版本号 1.0.0。由于字节限制，最大版本号为 3.3.15。

示例：55 AA 02 xx xx 0B 00 01 53 xx 表示当前版本号为 0x53，二进制为 01 01 0011，即 1.1.3。

OTA 升级通知（0x0C）

在涂鸦开发者平台配置了设备 MCU 升级，并开启了推送后，如果设备满足升级条件，则会在客户端 App 上进行提示，或者无提示自动升级。在面板上开启 MCU 固件升级后，网关会通知模组。

模组收到通知后，模组会发送此命令给 MCU，通知 MCU 准备 OTA 升级。

模组发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x0C
数据长度	2	0x0011
数据	17	PID（8 字节）+ 新固件版本号（1 字节）+ 固件大小（4 字节）+ 固件校验和（4 字节）
校验和	1	xx

• PID（8 字节）：与当前设备相同的 PID，例如 AIp08kLI。
• 新固件版本号（1 字节）：例如 0x41，表示 1.0.1。
• 固件大小（4 字节）：单位为字节数。
• 固件校验和（4 字节）：从固件第一个字节开始对整个固件的校验和。

示例：55 AA 02 xx xx 0C 00 11 41 49 70 30 38 6B 4C 49 41 00 00 78 00 30 31 32 33 XX OTA 升级通知，内容为：

• PID：41 49 70 30 38 6B 4C 49，即 AIp08kLI。
• 新固件版本号：0x41，表示 1.0.1。
• 固件大小：0x00007800，即 30 KB。
• 固件校验和：0x30313233

MCU 回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x0C
数据长度	2	0x0001
数据	1	0x00：检查失败 0x01：检查成功
校验和	1	xx

示例：55 AA 02 xx xx 0C 00 01 01 xx

OTA 固件内容请求（0x0D）

在 MCU 收到 OTA 升级通知 命令，且 OTA 升级信息检查结果为正确的前提下，MCU 可以主动发送此命令给模组，让模组向网关请求获取 OTA 文件（即下载 OTA 文件）。

下载过程是由设备端控制的，即设备发送文件数据请求命令，包含数据偏移量和数据包大小。网关收到后根据设备端的请求信息，将 OTA 文件中对应位置和长度的数据包返回给设备。该命令由 MCU 端发起，模组收到后发送给网关，由于 Zigbee 无线协议单帧长度限制, 加上一些必要的额外开销，MCU 每次请求数据包长度不能超过 48 字节，直到所有数据包请求完成。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x0D
数据长度	2	0x000E
数据	14	PID（8 字节）+ 新固件版本号（1 字节）+ 数据包偏移量（4 字节）+ 数据包大小（1 字节）
校验和	1	xx

• PID（8 字节）：与当前设备相同的 PID，例如 AIp08kLI。
• 新固件版本号（1 字节）：例如 0x41，表示 1.0.1。
• 数据包偏移量（4 字节）：单位字节数，即本次请求的数据，在 OTA 文件中的偏移量。
• 数据包大小（1 字节）：单位字节数，即本次请求的数据包的大小，不能超过 48 字节。

示例：55 AA 02 xx xx 0D 00 0E 41 49 70 30 38 6B 4C 49 41 00 00 10 00 30 XX 表示请求 4096 位置开始的 48 字节数据包。

• PID：0x41 49 70 30 38 6B 4C 49，即 AIp08kLI。
• 新固件版本号：0x41，表示 1.0.1。
• 数据包偏移量：0x00001000，即偏移量为 4096 位置。
• 数据包大小：0x30，即请求 48 字节的数据。

模组回复：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x0D
数据长度	2	N
数据	N	请求结果（1 字节）+ PID（8 字节）+ 新固件版本号（1 字节）+ 数据包偏移量（4 字节）+ 数据包内容
校验和	1	xx

• 请求结果：

  • 0x00：请求成功。
  • 0x01：请求失败。如果请求失败，则后面的数据不存在。

• PID（8 字节）：与当前设备相同的 PID，例如 AIp08kLI。

• 新固件版本号（1 字节）：例如 0x41，表示 1.0.1。

• 数据包偏移量（4 字节）：单位字节，即本次请求的数据，在 OTA 文件中的偏移量。

• 数据包内容（N 字节）：本次返回的数据包的内容。

示例：55 AA 02 xx xx 0D xx xx 00 41 49 70 30 38 6b 4c 49 41 00 00 00 32 … xx 表示请求成功（数据部分用省略号表示）。

OTA 升级结果上报（0x0E）

在 MCU OTA 升级完成后，MCU 可以主动发送此命令给模组，让模组将 OTA 升级结果上报给网关, 无论升级成功还是失败，都应上报。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x0E
数据长度	2	0x000A
数据	10	升级结果（1 字节）+ PID（8 字节）+ 新固件版本号（1 字节）
校验和	1	xx

• 升级结果（1 字节）：

  • 0x00：升级成功。
  • 0x01：升级失败。

示例：55 AA 02 xx xx 0E 00 0A 00 41 49 70 30 38 6B 4C 49 41 xx 表示设备 MCU OTA 成功。

• 升级结果：0x00 表示成功。
• PID：0x41 49 70 30 38 6B 4C 49，即 AIp08kLI。
• 新固件版本号：0x41，表示 1.0.1。

模组响应：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x0E
数据长度	2	0x0001
数据	1	0x00：上报成功 0x01：上报失败
校验和	1	xx

示例：55 AA 02 xx xx 0E 00 01 00 xx

二级设备命令下发 (0x10)

Zigbee 模组支持命令下发给二级设备 MCU。

• 功能命令或状态数据部分除 raw 类型外，其他类型均属于 obj 型。
• obj 型功能支持下发多条命令。
• raw 型功能仅支持下发单条命令。
• raw 类型数据不能和 obj 型数据同时上报。
• 0x10 命令下发为异步处理协议，对应于 0x11 状态上报（被动） 和 0x12 状态上报（主动）。

模组发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x10
数据长度	2	N
数据	N	DP 消息格式
校验和	1	xx

数据段请参考 0x08 命令 DP 消息格式。

示例：55 AA 02 xx xx 10 00 05 03 01 00 01 01 xx 模组收到下发给二级设备的 DP 消息，包含 1 个 DP 数据，如下所示：

• DP ID：03
• Type：01
• Length：00 01
• Value：01

二级设备状态上报（被动）(0x11)

当 MCU 接收模组端下发的命令，并执行相应动作后，需要将新的状态上报至模组端，状态正确执行之后，仅上报执行操作的功能状态。

• 状态上报（被动）为同步处理协议，模组端接收功能状态后，立即返回确认字符（ACK）至 MCU。
• 状态上报（被动）可包含多个 obj 型功能命令。
• raw 类型数据不能和 obj 型数据同时上报。
• 被动上报是否成功并不表示数据是否到达网关。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x11
数据长度	2	N
数据	N	DP 消息格式
校验和	1	xx

数据段请参考 0x08 命令 DP 消息格式。

示例：55 AA 02 xx xx 11 00 05 03 01 00 01 01 xx MCU 被动上报 DP 消息：

• DP ID：03
• Type：01
• Length：00 01
• Value：01

模组返回：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x11
数据长度	2	0x0001
数据	1	0x00：状态上报失败 0x01：状态上报成功
校验和	1	xx

二级设备状态上报（主动）（0x12）

MCU 主动检测到功能状态有变化，需要将变化后的功能状态发送至模组。

• 正常变化时，只上报有变化的功能状态。
• 状态上报（主动） 为异步处理协议，模组端收到 MCU 通过命令字 0x12 发送的 DP 数据时，模组会上报到 Zigbee 网关。当收到 Zigbee 网关的回复后，会将状态返回给 MCU。
  • 如果网关返回，模组异步返回 MCU 上报成功。
  • 如果网关未返回，模组在等待超时后返回 MCU 上报失败。
  • 如果模组未在网，模组立即返回 MCU 上报失败。
  • MCU 可根据模组回复判断模组与网关的链路是否通畅。
• 功能命令或状态数据部分除 raw 类型外，其他类型均属于 obj 型。
• obj 型功能支持多条命令上报，最多不超过 10 个 DP 数据。
• raw 型功能仅支持单条命令上报。
• 通过命令字 0x12 上报的 DP 数据会触发联动。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x12
数据长度	2	N
数据	N	DP 消息格式
校验和	1	xx

数据段请参考 0x08 命令 DP 消息格式。

示例：55 AA 02 xx xx 12 00 05 03 01 00 01 01 xx MCU 主动上报 DP 消息：

• DP ID：03
• Type：01
• Length：00 01
• Value：01

模组返回：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x12
数据长度	2	0x0001
数据	1	0x00：状态上报失败 0x01：状态上报成功
校验和	1	xx

示例：55 AA 02 xx xx 12 00 01 01 xx

时间同步（0x24）

MCU 可以主动发送此命令给模组，让模组向网关请求时间信息。

网关回复模组后，模组通过本命令通知 MCU。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x24
数据长度	2	0x0000
数据	0	无
校验和	1	xx

示例：55 AA 02 xx xx 24 00 00 xx MCU 请求时间同步。

模组返回：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x24
数据长度	2	0x0008
数据	8	标准时间戳（4 字节）+ 本地时间戳（4 字节）
校验和	1	xx

• 标准时间戳：格林威治时间，以 1970.01.01 00:00:00 为起点到现在的总秒数。
• 本地时间戳：考虑时区和夏令时的本地时间，即标准时间 ± 时差。一般设备以本地时间为准。

示例：55 AA 02 xx xx 24 00 08 66 45 DB F0 66 46 4C 70 xx

• 标准时间：0x6645DBF0
• 本地时间：0x66464C70

群组广播 (0x44)

MCU 可以主动发送此命令给模组，让模组以组播方式向群组发送标准命令，以控制群组中支持标准命令的设备。

这里的标准命令由 Zigbee 3.0 规范定义，通常的格式为：Cluster ID + Command ID + Payload。

群组广播只是触发群组执行动作，主控设备的状态仍然需要自行上报，即和群组广播独立上报。

MCU 发送：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x44
数据长度	2	N
数据	N	Group ID（2）+ 标准命令格式（Cluster ID + Command ID + Payload）
校验和	1	xx

标准命令格式：

如果想获取每个标准命令的 Payload 定义，请参考 Zigbee 官方文档 Zigbee Cluster Library Specification R8。本链接由 CSA 联盟提供，后面可能会更新。

示例：55 AA 02 xx xx 44 00 05 2A 08 00 06 01 xx 组播发送一条标准命令，命令内容如下：

• Group ID：0x2A08
• Cluster ID：0x0006（onoff cluster）
• Command ID：0x01（on）
• Payload：null

模组返回：

字段	字节数	说明
帧头	2	0x55AA
版本	1	0x02
序列号	2	xx xx
命令字	1	0x44
数据长度	2	0x0001
数据	1	0x00：发送失败 0x01：发送成功
校验和	1	xx

示例：55 AA 02 xx xx 44 00 01 01 xx 组播标准命令发送成功。

更新记录

主要变更	修订日期	修订说明
优化文档	20260224	优化文档，添加协议交互图
修订文档	20240606	1. 增加通用对接透传功能支持 0x10、0x11、0x12 2. 增加组控支持 0x44
优化文档	20240603	文档勘误，增加说明
优化文档	20221215	优化文档
创建文档	20221130	创建文档