串口协议

涂鸦 Zigbee 串口通用协议结构和串口硬件连接如下图所示。

串口通信参数

• 波特率：9600/115200

• 数据位：8

• 奇偶校验：无

• 停止位：1

• 数据流控：无

• 供电电压：Zigbee 模组和 MCU 主控均采用 DC 3.3V

• 各模组对应的串口 IO 和唤醒 IO 如下表所示：

  模组型号	模组 TX 引脚	模组 RX 引脚	模组唤醒 MCU IO 引脚(低功耗版本)	MCU 唤醒模组 IO 引脚(低功耗版本)
  ZS3L	PA5	PA6	PC1	PA3
  TYZS3	PA0	PA1	PF5	PA2
  TYZS5	PA0	PA1	PA4	PA3
  ZTU	PB1	PB7	PB4	PB5/PD2
  ZT5	PB1	PB7	PB4	PB5/PD2
  ZT3L	PB1	PB7	PB4	PB5/PD2

串口通信休眠唤醒

• 支持休眠功能的低功耗设备：Zigbee 模组与 MCU 之间预留两个 GPIO 口供 MCU 和模组唤醒时使用，唤醒方式为电平触发。Zigbee 模组或 MCU 每次主动发起命令之前，都需要完成一次握手连接，具体唤醒方法参考下图。

  

• 不支持休眠功能的强电设备：串口处于长监听状态，硬件不需要连接 I/O1 和 I/O2。

• 由于模组和 MCU 唤醒后初始化时长可能不一致，目前支持电平触发后到串口发送数据间隔时间可配置 3~300ms，默认 5ms。

• MCU 唤醒模组：唤醒引脚电平拉低 1~10 ms 之后方可发送数据，保持唤醒引脚持续低电平，模组会持续处于唤醒状态，但最长唤醒时间为 2min。当电平拉高之后，模组会在约 300~550ms 之后进入休眠，减少不必要的唤醒时间，降低功耗。

• 模组持续唤醒时长超过 2min 后，会自动重启。

• ZT 系列模组，MCU 唤醒模组需要在唤醒 IO 上下拉至少 10ms 时间才可以发送数据。

  
  固件支持脉冲唤醒的方式，即 MCU 每次发送串口数据之前都需要先在唤醒口上发送一个低脉冲，时间为 1~5 ms，ZT 系列模组低脉冲时间为 10ms，然后再发送串口数据。长时间拉低唤醒会导致模组功耗偏高，因此优化为脉冲方式唤醒模组,示例代码如下：

  set_gpio_low();
  delay(1);
  set_gpio_high();
  uart_send_buffer();
  

波特率自适应

模组在首次与 MCU 通讯与整机产测阶段，需要确认与 MCU 之间通讯的波特率。模组会先在 9600 波特率下发送查询产品 PID 和 MCU 版本信息命令。因此，请尽量避免在此之前唤醒和发送数据给 Zigbee 模组。

• 如果能收到 MCU 的正确回复，则以后会将波特率固定在 9600。
• 如果没有收到回复，则会且换到 115200，继续发送查询产品 PID 和 MCU 版本信息命令，如果收到 MCU 的正确回复，则以后会固定波特率在 115200，没有收到正确回复，会继续切换波特率到 9600，以此规律间隔 1s 一次反复发送查询命令。
• 当模组确认波特率后，无法修改当前波特率。

帧格式说明

通讯帧格式如下：

Front	Ver	Cmd	Length	Data	Check
帧头	版本	命令字	数据长度	数据	校验和
字段	字节数	说明
----	----	—
Front	2	固定为 0x55aa
Ver	1	串口通信协议版本，升级扩展用
seq	2	传输数据序列号，范围 0~0xfff0，到达 0xfff0 之后重新回到 0
Cmd	1	具体帧类型
Length	2	传输的有效数据长度
Data	取决于具体数据	传输的有效数据
Check	1	数据校验，从帧头开始按字节求和得出的结果对 256 求余

命令字索引

命令字	说明	强电版本	低功耗版本	场景版本
0x00	App 恢复出厂设置通知	√	√	√
0x01	查询产品信息	√	√	√
0x02	报告模组网络状态	√	√	√
0x03	配置 Zigbee 模组	√	√	√
0x04	下发命令	√	√	√
0x05	下发命令应答	√	√	√
0x06	状态主动上报	√	√	√
0x07	预留命令字	√	√	√
0x08	模组 RF 性能测试	√	√	√
0x09	查询按键信息	×	×	×
0x0a	唤醒场景	×	×	√
0x0b	MCU 版本查询请求	√	√	√
0x0c	OTA 升级通知	√	√	√
0x0d	OTA 固件内容请求	√	√	√
0x0e	OTA 升级结果上报	√	√	√
0x20	查询模组网络状态	√	√	√
0x24	同步时间	√	√	√
0x25	MCU 查询网关联网状态	√	√	×
0x26	配置 Zigbee 网络策略参数	√	√	×
0x27	MCU 广播数据上报	√	√	√
0x28	读取 DP 数据	√	√	√
0x29	信标产测通知	√	√	√
0x2a	群控下发	√	√	×
0x2b	模组唤醒 MCU 后等待时间配置	×	√	×
0x41	下发 kid gid sid	×	×	√
0x42	标准命令群组广播	×	×	√
0x43	私有命令群组广播	×	×	√

串口通信模式介绍

命令字通信模式

通常命令字采用一发一收的同步模式，即发送方发送命令，接收方应答，如下图所示。

模组下发命令通信模式

模组控制命令下发采用异步模式。

• 模组控制命令下发

  
  上图假设模组控制命令下发命令字为 X，MCU 状态上报命令字为 Y。

• 下发流程

  1. 模组通过 0x04 指令下发命令，内容为可下发的 DP 数据。
  2. MCU 接收到 0x04 指令之后，进行回复，表示串口接收到该命令。
  3. MCU 通过 0x05 指令将执行的结果上报至云端。
  4. 验证 0x05 指令的序列号和 0x04 指令是否保持一致。

MCU 上报状态通信模式

MCU 状态上报采用异步模式。MCU 状态上报分为被动上报和主动上报两种情况。

• 被动上报：模组端发送数据命令至 MCU，MCU 执行后返回状态。

  

• 主动上报：MCU 状态发生改变（例如物理操作或者断电重启等）时，将主动上报当前状态至模组。MCU 主动上报为异步操作，如果 MCU 未在指定时间内接收状态上报应答帧，或者接收到的应答帧中状态为不成功，MCU 需要重新上报状态。

  

典型流程举例

上电

模组通电后，会向 MCU 请求 PID 与版本号信息。MCU 超时不回复，模组会继续发送产品信息请求命令。

配网

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

串口协议命令字详解

App 端解绑并清除数据通知（0x00）

模组下发

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x00
数据长度	2	0x0001
数据	1	01 表示恢复出厂
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 回复

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x00
数据长度	2	0x0001
数据	1	01 表示恢复出厂成功
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

查询产品信息（0x01）

产品信息由产品 ID 和 MCU 软件版本号构成。当模组复位后，主动查询产品信息。如果 MCU 没有回复，或者回复内容有误，将会间隔 5 秒重复查询。

• 产品 ID：对应 涂鸦 IoT 平台 上产品的 PID，在创建产品时由涂鸦 IoT 平台自动生成，用于云端记录产品相关信息。

• MCU 软件版本号：采用点分十进制形式，格式为 x.x.x，x 为十进制数。

  OTA 相关命令用单字节表示 MCU 版本时，最大版本由于字节长度限制，最大版本号为 3.3.15。

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x01
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 01 0000 xx

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x01
数据长度	2	N
数据	N	数据示例：{"p":"AIp08kLI","v":"2.0.0","g":1 } 参数说明： p（必选）：产品 ID。 v（必选）：MCU 版本号。 g（可选）：bit0 位设置为 1 表示模组会区分单控和群控，单控使用命令字 0x04 下发，群控使用 0x2a 下发。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 01 00 1c 7b2270223a2241497031386b4c49222c2276223a22312e302e30227d xx

报告模组网络状态(0x02)

网络状态是指 Zigbee 模组的网络的状态，当模组配网成功之后，即设备已加入网络，不因网关断电，父节点丢失等原因变更网络状态。当模组的网络状态发生变化，则主动下发模组网络状态至 MCU。

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x02
数据长度	2	0x0001
数据	1	模组网络状态： 0x00：未入网。通常以下状态被识别为未入网： 设备第一次上电 设备入网失败 设备离线 0x01：已入网 0x02：网络异常 0x03：配网中
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 02 0001 00 xx

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x02
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 02 0000 xx

配置 Zigbee 模组(0x03)

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x03
数据长度	2	0x0001
数据	1	0x00：将模组软件复位 0x01：将模组配置为开始配网状态（先离网再配网）
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 03 0001 01 xx

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x03
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 03 0000 xx

命令下发(0x04)

Zigbee 模组支持命令下发。

• 功能命令或状态数据部分除 raw 类型外，其他类型均属于 obj 型。
• obj 型功能支持下发多条命令。
• 命令下发为异步处理协议，对应于 MCU 的状态上报。

命令下发帧格式：

功能格式：

数据字段属性	字节数	说明
dpid	1	功能序号
type	1	对应涂鸦 IoT 开发平台上功能具体的数据类型： raw：raw 型功能（模组输入） 表示值：0x00 字节数：N bool：布尔型，取值为 0x00 或 0x01 表示值：0x01 字节数：1 value：对应 int 类型，大端表示 表示值：0x02 字节数：4 string：对应字符串 表示值：0x03 字节数：N enum：枚举类型，取值范围 0~255 表示值：0x04 字节数：1 bitmap：故障型，长度大于 1 字节时，大端表示 表示值：0x05 字节数：1、2 或 4
len	2	长度对应 Value 的字节数（大端）
value	1/2/4/N	hex 表示，大于 1 字节采用大端传输

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x04
数据长度	2	无
数据	取决于具体数据	参见功能格式
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 04 0005 03 01 0001 01 xx

状态上报（被动）(0x05)

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

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

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x05
数据长度	2	取决于具体数据
数据	取决于具体数据	参见功能格式
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 05 00 08 05 02 0004 0000001e xx

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x05
数据长度	2	0x0001
数据	0	0x00：状态上报失败 0x01：状态上报成功
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55aa 02 N 05 0001 01 xx

状态上报（主动）(0x06)

• MCU 主动检测到功能状态有变化，或者 MCU 重启等情况下，需要将变化后的功能状态发送至模组。

  • 正常变化时，只上报有变化的功能状态。
  • 重启等异常情况下，需要上报所有的功能状态。

• 状态上报（主动） 为异步处理协议，模组端收到 Zigbee 网关的回复之后，会将状态返回给 MCU。如果状态返回超时，或者返回失败，MCU 需要重新上报。目前，MCU SDK 提供接口为只有 0x06 主动上报，相对于0x05 而言，通过 0x06，MCU 可根据模组回复判断模组与网关的链路是否通畅，并且 MCU 回复网关的广播消息时模组会自动添加随机延时。

• 状态上报（被动） 可包含多个 obj 型功能命令。

• raw 类型数据不能和 obj 型数据同时上报。

  如果需要在配网成功之后上报功能数据以同步 App 面板，建议增加 5 秒延时上报。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x06
数据长度	2	取决于具体数据
数据	取决于具体数据	参见功能格式
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 06 08 05 02 0004 0000001e xx

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x06
数据长度	2	0x0001
数据	0	0x00：状态上报失败 0x01：状态上报成功
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55aa 02 N 06 0001 01 xx

Zigbee 模组功能性测试(0x08)

Zigbee 模组支持扫描指定信道的 RSSI 值，返回扫描结果和信号强度百分比。本命令必须在设备未配网情况下才可正常运行，单次测试完成之后必须重启模组。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x08
数据长度	2	0x0001
数据	1	信道值（11~26）
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55aa 02 N 08 0001 0b xx 即 MCU 要求模组扫描 11 信道的 RSSI 值。

模组返回

字 段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x08
数据长度	2	0x0002
数据	2	Data[0]： 0x00：失败 0x01：成功 Data[1]： Data[0] 为 0x01：Data[1] 表示信号强度 (0-100，0 信号最差，100 信号最强) Data[0] 为 0x00： Data[1]为 0x00：表示未扫描到指定的 RSSI Data[1]为 0x01：表示模组未烧录授权 Key
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55aa 02 N 08 0002 01 64 xx

场景开关

在场景开关设备中，MCU 只需要通过串口透传协议告知 Zigbee 模组设备按键的个数以及当前操作的按键。

查询按键信息(0x09)

模组重启后会发送查询按键信息命令。

• 支持的按键上限为 10，即可创建 10 个场景。
• 仅适用于场景面板，不支持其他功能和自定义功能。
• 创建产品时，需要选择的功能为场景 ID 组和场景编号（1~10）。
• 场景编号必须从小到大，从场景 1 开始。

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x09
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 09 0000 xx

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x09
数据长度	2	0x0001
数据	2	面板开关的按键总个数
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55aa 02 N 09 0001 02 xx

场景唤醒命令(0x0a)

场景唤醒命令能够触发场景面板执行场景化操作。MCU 发送请求后，模组返回的状态如下。

• 成功：该按键已在 App 绑定场景，且对应的场景已成功执行。
• 失败：该按键未在 App 绑定场景，场景不会被执行。

当按键按下时，场景面板还会向网关发送一个按键值，用于联动云端场景。当 MCU 有按键上报时，即会上报按键给网关，即如果该场景面板仅使用云端场景功能，模组无论回复成功和失败都可以认为 MCU 上报按键成功。

云端场景和本地场景的区别：

• 本地场景：即标准的 Zigbee 场景，满足 Zigbee 协议。

  目前，设备端保存的场景数据为指定属性值，部分命令不支持。这些不支持的功能需要通过云端场景实现。

• 云端场景：其本质是云端联动控制，是指通过云端功能实现的场景。

  目前，该命令仅支持本地场景。如果有 Wi-Fi、蓝牙等其他设备，需要通过云端场景实现。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x0A
数据长度	2	0x0001
数据	取决于具体数据	按键 ID。 说明：例如按键总个数为 4，则数据为 01 02 03 04。
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55aa 02 N 0A 0001 01 xx 即 MCU 要求模组执行按键 1 对应的场景。

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x0A
数据长度	2	0x0001
数据	1	0：场景唤醒失败 1：场景唤醒成功
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55aa 02 N 0A 0001 01 xx

MCU OTA 升级

OTA 的流程如下：

1. 云端发出 OTA 通知。
2. MCU 接收到通知后回复通知。
3. MCU 开始发起数据请求，数据请求的包大小最大为 50 字节，
4. 模组会将该请求转发给网关。
5. 网关根据当前偏移量和数据包大小回复数据。

为了完善 MCU 数据请求逻辑需要增加超时机制。即当发出数据请求在一段时间内没有回复时，需要重新发送该请求。

OTA 版本请求的数据格式(0x0b)

若支持 MCU 升级必须实现本命令。支持网关会主动查询和 MCU 主动上报两种方式。

• 网关查询场景：
  • 配网成功
  • MCU 升级过程异常
• MCU 上报场景：
  • 配网成功后（必须添加）
  • 升级结束

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	模组产生
命令字	1	0x0B
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55 AA 02 00 f0 0B 00 00 XX

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	MCU 下发的序号
命令字	1	0x0B
数据长度	2	0x0001
数据	1	当前版本号。例如（Bits）01.00.0001 表示 1.0.1。
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

55 AA 02 00 39 0B 00 01 40 XX

OTA 升级通知(0x0c)

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	模组产生
命令字	1	0x0C
数据长度	2	0x0011
数据	8	PID。Data[0]~ Data[7]。
数据	1	当前版本号。例如（Bits）01.00.0001 表示 1.0.1。
数据	4	固件大小。（目前如果连接涂鸦无线网关最新版本最大支持为 512K，如果连接涂鸦有线网关最新版本最大支持为 1M）。
数据	4	固件校验和：从固件第一个字节开始对整个固件的校验和。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余。

示例

0x55 AA 02 00 1C 0C 00 0F 30 31 32 33 34 35 36 37 40 00 01 00 00 30 31 32 33 XX

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	模组下发的序列号
命令字	1	0x0C
数据长度	2	0x0001
数据	1	0x00：OK 0x01：error
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55 AA 02 00 1C 0C 00 01 00 XX

OTA 固件内容请求(0x0d)

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	0x0000
命令字	1	0x0D
数据长度	2	0x000E
数据	8	PID
数据	1	当前版本号。例如（Bits）01.00.0001 表示 1.0.1。
数据	4	数据包的偏移量（固件的位置）
数据	1	数据包的大小（最大 50 字节）
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55 AA 02 00 00 0D 00 0E 30 31 32 33 34 35 36 37 40 00 00 00 01 32 XX

模组响应

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	0x0000
命令字	1	0x0D
数据长度	2	0x0006+N
数据	1	0x00：成功 0x01：失败
数据	8	PID
数据	1	目标版本号。例如（Bits）01.00.0001 表示 1.0.1。
数据	4	数据包的偏移量（固件的位置）
数据	N	数据
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

55 AA 02 00 39 0D XXXX 00 30 31 32 33 34 35 36 37 40 00 00 00 01 …. XX

OTA 固件升级结果上报(0x0e)

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	MCU 下发的序列号
命令字	1	0x0E
数据长度	2	0x000A
数据	1	0x00：成功 0x01：失败
数据	8	PID
数据	1	当前版本号。例如（Bits）01.00.0001 表示 1.0.1。
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55 AA 03 00 f0 0E 00 0A 00 30 31 32 33 34 35 36 37 40 26

模组响应

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	MCU 下发的序列号
命令字	1	0x0E
数据长度	2	0x0001
数据	1	0x00：OK 0x01：error
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

0x55 AA 02 00 1C 0E 00 01 00 XX

查询模组网络状态(0x20)

支持 MCU 查询 Zigbee 模组当前的网络状态。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x20
数据长度	2	0x0000
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 20 0000 xx

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x20
数据长度	2	0x0001
数据	1	模组网络状态： 0x00：未入网。通常以下状态被识别为未入网： 设备第一次上电 设备入网失败 设备离线 0x01：已入网 0x02：网络异常 0x03：配网中
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

0x55aa 02 N 20 0001 xx xx

时间同步(0x24)

时间同步功能将网关的网络时间同步至 MCU。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x24
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x024
数据长度	2	0x0008
数据	8	数据长度为 8 字节的时间值，格式为 4 字节标准时间戳 + 4 字节本地时间戳
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

• 标准时间戳为格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒起至现在的总秒数。
• 本地时间戳为标准时间戳 + 标准时间和本地时间相差的秒数（包含时区和夏令时）。

MCU 查询网关联网状态(0x25)

MCU 发送查询指令后，模组向 Zigbee 网关发送查询指令，网关回复模组（未收到则 3s 后超时），模组回复 MCU。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x25
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

55 aa 02 N 25 00 00 xx

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x025
数据长度	2	0x0001
数据	1	0x00：网关未联网 0x01：网关已联网 0x02：超时（3s）
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

55 aa 02 N 25 00 01 01 xx

MCU 配置 Zigbee 网络策略参数(0x26)

本指令可以在接收到模组发送的查询 PID 帧后，进行毫秒级延时，然后发送。

• 心跳时间

  心跳时间是用来维护设备和网关之间的数据链路是否正常的手段，强电设备的心跳时间默认为 150+random（30）秒，低功耗设备的心跳时间默认为 4 小时。仅支持修改低功耗设备的心跳时间。

  目前，涂鸦网关判断设备离线机制如下。对于低功耗设备，12 小时内网关未收到心跳。对于非低功耗设备，3 分钟内网关未收到心跳。

• 超时时间

  当 MCU 发送 配网指令之后，模组会执行一段时间的配网操作，并发送当前网络状态为配网状态。在一段时间内由于某些原因（例如附近没有开启配网的网络或者距离较远）导致模组没有加入到合适网络，则配网超时。配网超时之后，模组将处于未配网状态，同时也会将此状态发送给 MCU。

• 轮询（Poll）

  Poll 周期是指已经加入到网络的低功耗模组会在周期内唤醒。唤醒之后，低功耗模组会发送数据请求（Data request）至其父节点，用于告知父节点：其当前处于唤醒状态，父节点是否为其缓存数据。如果存在缓存数据，则父节点可以将数据发送给低功耗模组。

  • 不同产品 Poll 设置

    • 对实时性要求很高的产品：例如单火开关，可以将 Poll 值设置为 250ms。
    • 其他产品：例如传感器，只有当状态发生变化或者执行周期上报。即只需要上报数据时，就可以把 Poll 关闭，模组将收不到网关下发的控制指令。

  • 上电后 Poll 设置
    通常上电之后，设置一段时间的快速 Poll，可以在这个时间窗内将网关的配置命令下发。上电之后的快速 Poll 的时间默认为 30 秒，支持 MCU 设置。如果设备需要关闭 Poll，且有网关的配置需要下发，建议将快速 Poll 的时间窗增加。

  • 关闭 Poll
    网关会缓存数据。当模组上报数据时，会携带数据请求（Data request），此时网关会将数据发下给模组。

  Poll 值主要是影响功耗。唤醒周期越短，功耗越大。Poll 最小值为 200ms，小于最小值按照最小值处理。最大值建议 5 秒左右为宜。如果设置为 0 则关闭 Poll。

• 重连（Rejoin）

  Rejoin 即重新加入到网络，是一种专门用于低功耗设备在父节点丢失时，重新加入的网络的一种机制。

  Rejoin 这里不是指配网，无须网关开启配网模式。

  模组和父节点的交互流程如下：

  1. 模组发送数据请求（Data request）。
  2. 父节点回复。
     • 有缓存数据：将数据发送给模组。
     • 无缓存数据：仅回复 ACK。

  如果模组发送数据请求（Data request），但由于环境、距离、父节点断电等因素导致模组没有收到确认字符（ACK），则认为模组的轮询（Poll）失败。当累加到的一定的值时（Poll 失败次数），则认为模组丢失父节点，需要触发重连（Rejoin）。

  如果在累加的过程中重新收到父节点的 ACK，则累加清零。

  • Rejoin 触发
    目前提供 2 种独立的 Rejoin 触发方式：

    • 应用层发送数据
    • 定时触发：模组处于离线状态，周期性触发 Rejoin，直到模组重新加入到之前网络。
    Rejoin 成功只能表示其和父节点能够正常通信，数据能否到达网关需要根据网关和父节点的路由情况。目前这两个参数都可以由 MCU 灵活配置。

  • Rejoin 间隔时间
    即周期触发 Rejoin 的时间间隔。针对对数据要求严格或者低功耗要求的场景，可以减小 Rejoin 间隔，例如 3~5 秒。针对传感设备或者通过数据上报触发的场景，可以增加时间间隔，例如 1 小时。

  • Rejoin 尝试次数
    指设备触发 Rejoin 之后，模组可以发送 Rejoin 的次数。对于 Poll 时间较短的场合，以及 Rejoin 间隔短的应用，可以减少尝试次数，例如 1~2 次。对于 Rejoin 间隔较长的场合，可以将 Rejoin 尝试次数稍微增加，例如 3~4 次。

  如果设置的参数值不在取值范围内的，参数值不生效。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x26
数据长度	2	0x0e
数据	2	心跳时间（秒） 仅低功耗设备支持心跳修改。低功耗设备的心跳默认为 4 小时，设置范围为 10~5*3600 秒。 0xffff：当前值 0xfffe：默认值
	2	配网超时时间（秒） 配网超时时间默认为 180 秒，取值范围为 30~600。 0xffff：当前值 0xfffe：默认值
	2	Rejoin 间隔时间（秒） 取值范围 3~3600，默认值为 180 秒。即当设备丢失父节点时，会间隔 180 秒尝试 Rejoin。 0xffff：当前值 0xfffe：默认值
	2	Poll 时间（毫秒） 默认为 5000ms，取值范围 200~10000。模组会间隔 Poll 周期唤醒一次，用于确认父节点是否有数据发送。如果产品为传感类型，仅有数据上传，则可以将其设置为 0。 0：关闭 Poll 0xffff：当前值 0xfffe：默认值
	2	持续快速 Poll 的时间段（秒） 取值范围 10~3000。Poll 上电之后持续快速 Poll 的时长。快速 Poll 的时长为 250ms，到达后按照 Poll 设置的时间运行, 默认为 30 秒。 0xffff：当前值 0xfffe：默认值
	1	Poll 失败次数 取值范围 3 ~ 40。当达到最大值时且配置了 Rejoin 触发时间，则到达时间时会触发设备 Rejoin。 0xff：当前值 0xfe：默认值
	1	应用数据发送是否触发 Rejoin 0 表示不触发，1 表示触发。默认值为 1。 0xff：当前值 0xfe：默认值
	1	Rejoin 尝试次数 默认值为 1。取值范围为 1~10。 0xff：当前值 0xfe：默认值
	1	发射功率 默认值为 11。取值范围 3~19dB（泰林微、奉佳微发射功率 3-11db）。 0xff：当前值 0xfe：默认值
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x026
数据长度	2	0x0001
数据	1	0x00：失败 0x01：成功
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

MCU 广播数据(0x27)

MCU 需要将数据进行全网通知时，使用该帧数据。

MCU 广播数据可以让全网络中的设备接收到。如果存在低功耗设备，该设备需要处于周期唤醒的状态，且唤醒周期需要小于广播周期。否认在唤醒前，下一条广播数据就会将之前的广播数据覆盖。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x27
数据长度	2	N
数据	取决于具体数据	具体功能格式
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

模组返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x027
数据长度	2	0x0001
数据	1	00 上报失败，01 上报成功
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

网关读取 DP 数据(0x28)

触发 MCU 把当前全部 DP 上报或者部分 DP 上报，目的是为了同步 App 状态和 MCU 实际状态。

当数据内容为 空 时，表示需要上报全部 DP 数据，或将 DP ID 放到 payload 里面。例如 payload 里面的数据为 0x01、0x02，表示 MCU 需要上报 DP1、dp2。最大为 10 个 DP，如果 MCU 上报时，数据长度超出 64 字节，必须分帧上报。上报数据的命令使用 0x06。

设备离线之后重新上线用于状态同步使用。但需要注意，如果上报的 DP 配置了联动，需要慎重上报，否则可能导致不必要的联动。

模组 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x28
数据长度	2	N
数据	N	实际 DP ID 或者空
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x028
数据长度	2	0x0001
数据	1	00 失败 01 成功
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

信标产测通知(0x29)

如果模组旁边有信标 dongle，未配网的设备上电之后即会进入信标产测，此时模组会通知 MCU 开始产测。

主要用于 MCU 无有效手段开启产测时，可使用信标产测模式进入产测。例如灯具内部，MCU 无法通过外部按键或者其他方式进入产测，可以由模组通知 MCU 进入产测模式。上电后，接收到信标帧之后，模组会立刻发送信标产测通知。通知采用 9600 波特率，当没有收到回复时，将采用 115200 波特率通知，没有应答时，每个波特率重发 2 次，间隔 100ms。如没有收到该通知，需要重新上电重启，此刻模组不响应 MCU 的其他串口命令，需要在无信标的环境下重启模组才会正常。

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x29
数据长度	2	1
数据	1	00
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x029
数据长度	2	0x0001
数据	1	00 失败 01 成功
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

群控下发(0x2a)

Zigbee 网络中出现群控（广播），用于 MCU 区分单控和群控使用，MCU 可根据单控和群控的命令字区分，来做不同策略上报状态。该命令需要在模组向 MCU 查询产品信息时(0x01)命令时带上是否支持群控功能。

例如，网络中经常使用群控命令控制的应用场景，可在群控后不上报状态，等待网关查询后来同步更新状态，或者可在群控后自行加随机延时上报状态，避免 Zigbee 网络阻塞。

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	模组产生
命令字	1	0x2A
数据长度	2	N
数据	取决于具体数据	参见功能格式
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

55 AA 02 00 01 2A 00 04 01 01 00 01 01 34

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x2A
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

55 aa 02 00 01 2A 00 00 2C

模组唤醒 MCU 后等待时间配置(0x2b)

低功耗系列，模组向 MCU 发送数据时，需唤醒并延时等待 MCU 初始化串口完毕后发送串口数据。等待时长可以通过 MCU 配置更改。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	MCU 下发的序列号
命令字	1	0x2B
数据长度	2	0x0002
数据	2	等待时长，单位 ms。默认值为 5，取值范围 3-300，使用 0xFFFE 则为默认值
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

55 AA 02 00 01 2B 00 02 00 64 93

模组响应

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	MCU 下发的序列号
命令字	1	0x2B
数据长度	2	0x0001
数据	1	0x00：失败 0x01：成功
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

55 AA 02 00 01 2B 00 01 01 2F

下发 kid gid sid(0x41)

模组使用场景版本并且绑定面板支持八分组功能的（0x41、0x42 和 0x43 命令字能使用的条件），设备入网成功后，云端下发带 group ID 和按键信息，通过模组整理后统一按格式 kid+gid+sid 发送给 MCU。

• kid：key ID 按键标识。
• gid：group ID 为 Zigbee 群组的标识。
• sid：scene ID 为 Zigbee 场景的标识。

模组发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	模组产生
命令字	1	0x41
数据长度	2	0x0004
数据	1	kid（1-8）
数据	2	gid
数据	1	sid
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余。

示例

55 AA 02 00 01 41 00 04 01 2A 08 00 7A

MCU 返回

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x41
数据长度	2	0x0001
数据	1	0x00：失败 0x01：成功
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例

55 aa 02 00 01 41 00 01 01 45

标准命令群组广播(0x42)

MCU 通过模组使用标准指令群组广播到 Zigbee 网络的 group 中。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	MCU 下发的序列号
命令字	1	0x42
数据长度	2	数据长度 n 字节
数据	n	gid+标准命令格式（格式见下表介绍）
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

55 AA 02 00 01 42 00 05 2A 08 00 06 01 82

模组响应

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	MCU 下发的序列号
命令字	1	0x42
数据长度	2	0x0001
数据	1	0x00：失败 0x01：成功
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

55 AA 02 00 01 42 00 01 01 46

目前支持的 cluster 和命令如下：
On/off cluster

• On
• Off
• Toggle

Level cluster

• Move to level
• Move
• Step
• Stop
• Move to level (with on/off)
• Move (with on/off)
• Step (with on/off)
• Stop

Color control cluster

• Move to hue
• Move hue
• Step hue
• Move to saturation
• Move saturation
• Step saturation
• Move to hue and saturation
• Move to color
• Move color
• Step color
• Move to color temperature
• Move color temperature
• Step color temperature
• Stop move step

Window covering cluster

• Up/open
• Down/close
• Stop
• Go to lift value
• Go to lift percentage
• Go to tilt value
• Go to tilt percentage

Scene cluster

• Recall scene

标准命令格式：

cluster id	cmd id	zcl payload	说明
0x0006	0x00	无	on/off cluster off
0x0006	0x01	无	on/off cluster on
0x0006	0x02	无	on/off cluster toggle
0x0008	0x00	0x64 00 32	level cluster move to level 并且 level 为 0x64，transition time 为 0x0032
…	…	…	…

私有命令群组广播(0x43)

MCU 通过模组使用私有指令群组广播到指定的 group 中，目的可以群组广播 Tuya MCU SDK 对接方式的其他子设备。

MCU 发送

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	MCU 下发的序列号
命令字	1	0x43
数据长度	2	数据长度 n 字节
数据	n	gid+DP 格式（格式见下面介绍）
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

55 AA 02 00 01 43 00 07 2A 08 01 01 00 01 01 82

模组响应

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	MCU 下发的序列号
命令字	1	0x43
数据长度	2	0x0001
数据	1	0x00：失败 0x01：成功
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

示例

55 AA 02 00 01 43 00 01 01 47

DP 格式如下：

dpid(1byte) + type(1byte) + len(2byte) + value(nbyte)

type：

数值	类型
0x00	raw
0x01	bool
0x02	value
0x03	string
0x04	enum
0x05	bitmap

更新记录

主要变更	修订日期	修订说明
创建文档	20180623	协议初版
修订文档	20180628	1. 修改超时时间 2. 修改被动上报方式 3. 修改模组配置方式
修订文档	20180702	1. 添加被动上报以及超时重传机制 2. 增加硬件握手 IO
修订文档	20180731	1. 添加场景开关协议
修订文档	20181029	1. 添加可靠性传输 2. 添加休眠设备唤醒机制
添加配网中网络状态	20200204	需求：模组增加配网状态的状态发送。 说明：现在阶段，协议没有对配网状态做出指示，客户的配网指示灯的逻辑没有把控。
优化协议内容	20200715	1. seq 的范围 2. 数据长度修改为 62 3. RF 测试时，当传入的信道非法时，默认 11 信道 4. 增加协议描述
增加协议	20200801	1. 增加模组查询 MCU 类型帧 2. 增加 MCU 设置模组网络参数帧
优化协议	20201118	1. 明确 MCU 唤醒模组和模组唤醒 MCU 的方式为电平或脉冲，兼容 2. 明确网络参数配置中 Rejoin 的时间是长期 Rejoin 失败的时间
优化协议	20211214	1. 增加 App，恢复出厂设置通知，MCU 配置 Zigbee 网络参数，MCU 广播数据上报，读取 DP 数据的协议
优化协议	20220322	1. 修改波特率自适应部分描述
增加协议	20220817	1. 增加 0x2A、0x2B、0x41、0x42、0x43 命令字及其功能 2. 强电版本增加发射功率可配 3. 产品信息新增可选 g 键值及其功能介绍
增加协议	20220902	1. 增加 MCU 查询网关联网状态
优化协议	20221114	优化协议排版，优化内容描述