Zigbee 三级架构 UART 通信协议

涂鸦 Zigbee 三级结构串口通用协议为涂鸦定制的 Zigbee 模组和三级子设备控制器之间的串口通用协议，主要用于涂鸦 Zigbee 模组与其它 MCU 中继器直连做串口通信。中继器又可以通过有线方式下挂其它终端设备，其架构框图如下图所示。

硬件连接

涂鸦 Zigbee 模组和MCU端主控均采用 DC3.3V 电压供电。涂鸦 Zigbee 模组与MCU之间 UART 通信波特率设置为 115200-8-N-1，并且无数据流控。UART 接口引脚采用标准逻辑，在空闲状态下，TXD 和 RXD 引脚均为高电平，以低电平作为起始位，以高电平作为停止位。即使设备进入休眠状态，引脚也维持高电平。

串口通信

帧格式

涂鸦 Zigbee 模组与MCU之间的UART通信数据帧由帧头（Front），版本（Ver），命令字（Cmd），数据长度（Length），数据（Data）和校验和（Check）组成，定义和描述如下所示：

Octets：2	1	2	1	2	Variable	1
Front	Ver	Seq	Cmd	Length	Data	Check

帧格式说明

帧格式说明：

字段	说明
帧头（Front）	2个字节的前导符，固定为0x55aa
版本（Ver）	串口通信协议版本，升级扩展用
序列号（seq）	传输数据序列号，范围1-0xfff0，其他序号可能会做特殊功能，保留
命令字（Cmd）	具体帧类型，参考表2
数据长度（Length）	传输的有效数据长度。 单帧数据长度不超过100个字节
数据（Data）	传输的有效数据
校验和（Check）	数据校验，从帧头开始按字节求和得出的结果对256求余

Cmd描述表：

Cmd ID	说明
0x01	产品信息查询/上报
0x02	设备状态查询/上报
0x03	Zigbee 设备重置
0x04	终端设备添加请求
0x05	终端设备添加请求
0x06	RF测试
0x07	通知MCU同步数据
0x08	控制命令下发
0x09	设备状态上报
0x0B	版本查询
0x0C	OTA通知
0x0D	OTA请求
0x0E	OTA结束通知
0x0C-0x23	reserved
0x24	时间同步

• 所有大于1个字节的数据均采用大端模式传输。

• 一般情况下，采用命令字一发一收同步机制，即一方发出命令，另一方应答，若发送方超时未收到正确的响应包，则传输超时，如下图所示：

  

  说明：具体通信方式以 “协议详述” 章节中为准。

• 模组控制命令下发及MCU状态上报则采用异步模式，假设模组控制命令下发“命令字”为x，MCU状态上报“命令字”为y，如下所示：

  模组控制命令下发：

  

  MCU状态上报：

  MCU状态上报由模组端发送数据命令给MCU，MCU执行之后将状态返回。

  

协议详述

查询MCU中控器产品信息

产品信息由product ID和MCU软件版本构成。

• product ID：对应涂鸦开发者平台PID(产品标识)，由涂鸦云开发者平台生成，用于云端记录产品相关信息。

• MCU软件版本号格式定义：采用点分十进制形式，”X.X.X”（实际MCU版本采用一个字节表示，位分配为 xx.xx.xxxx，即可以表示的最高版本为3.3.15），X为十进制数。

模组发送

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

例：0x55aa 02 N 01 0000 xx

MCU返回

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x01
数据长度	2	N
数据	N	{“p”:”AIp08kLI”, “v”:”1.0.0” }
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：{“p”:” AIp08kLI”, “v”:”2.0.0” }

p表示产品ID为AIp08kLI

v表示MCU版本为2.0.0

0x55aa 02 N 01 00 1c 7b2270223a2241497031386b4c49222c2276223a22312e302e30227d xx

报告Zigbee模组网络状态

设备状态ID	描述
0x00	设备为未入网状态
0x01	设备为已入网状态
0x02	设备网络状态异常
0x03	设备为配网中状态

• 设备未入网状态：设备第一次上电、或者入网失败、或者离网的情况下，设备状态为未入网状态。并将该状态下发至MCU。

• 设备为已入网状态：设备入网成功之后，设备状态为已入网状态。并将该状态下发至MCU。

• 当模组重启或者断电再上电，则主动下发模组网络状态至MCU。

• 当模组的网络状态发生变化，则主动下发模组网络状态至MCU。

模组发送

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x02
数据长度	2	0x0001
数据	1	指示模组工作状态： 0x00:状态1 0x01:状态2
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：0x55aa 02 N 02 0001 00 xx

MCU返回

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

例：0x55aa 02 N 02 0000 xx

配置 Zigbee 模组

配置 Zigbee 模组命令分为两种。

注意：MCU发送配网指令之后，模组会清空之前的子设备，如需重新配网需在配网成功之后，重新添加子设备。

命令	说明
0x00	将模组软件复位
0x01	将模组配置为开始配网状态（先离网再配网）

MCU发送

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

例：0x55aa 02 N 03 0001 01 xx

模组返回

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

例：0x55aa 02 N 03 0000 xx

终端设备添加请求

该命令为MCU中控器用来向Zigbee网关端注册终端设备时使用。

注意：命令需要在模组配网成功之后发送。

MCU发送配网指令之后，模组会清空之前的子设备，如需重新配网需在配网成功之后，重新添加子设备。

MCU发送

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x04
数据长度	2	实际发送数据长度
设备个数	1	N（N<=10, 即单次批量注册设备不超过10个，如果实际设备大于10个设备，可分两帧发送）
终端设备1 PID	8	设备厂商号，由涂鸦提供
设备1地址	2	设备实际地址
终端设备2 PID	8	设备厂商号，由涂鸦提供
设备2地址	2	设备实际地址
…	…	…
终端设备N PID	8	设备厂商号，由涂鸦提供
设备N地址	2	设备实际地址
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回

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

终端设备添加请求（扩展）

该命令为MCU中控器用来向Zigbee网关端注册终端设备时使用。

注意：该命令需要在模组配网成功之后发送。

（该条协议为扩展功能，如果PID长度超出8个字节，请使用该命令，

子设备地址默认为2个字节，且Zigbee网关会将地址作为编号处理，因此即便是不同pid的设备，在同一个Zigbee网关中，地址需要唯一，不能出现相同的情况）

MCU发送配网指令之后，模组会清空之前的子设备，如需重新配网需在配网成功之后，重新添加子设备。

Mcu发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x05
数据长度	2	数据长度
PID长度	待定	PID长度
PID	待定	PID值
子设备数量	1	子设备数量(M)
子设备地址	2*M	注册子设备地址依次排列
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回

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

Zigbee设备功能测试

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

当信道不在11~26信道，默认为11信道。

MCU发送

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

模组返回

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

信道有效值为（11-26），无效信道会默认使用11信道。

通知MCU 同步子设备状态

• 配网成功之后，会发送该通知。

• 网关断电上电之后也会发送此通知。

• Mcu收到该命令之后，需要将子设备的状态上报，注意上报数据的数据长度不能超出62字节，如果上报的DP数据长度大于62，需分多包上报。

Zigbee发送

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

模组返回

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

控制命令下发

命令下发帧格式如下所示：

Octets：2	1	1	1	2	2	Variable	1
Front	Ver	Seq	Cmd	Date Length	Address		Check

Octets：Variable	Variable	Variable	…	Variable
CmdData Unit-1	CmdData Unit-2	CmdData Unit-3	…	CmdData Unit-n

Octets：1	1	2	Variable
Dpid	Type	Len	Value

• datapoint命令/状态数据单元如下所示：

  数据段	长度（byte）	说明
  Dpid	1	datapoint序号
  Type	1	对应开放平台上某datapoint具体的数据类型,通过如下“表示值”标识
  类型	表示值	长度（字节）	说明
  raw	0x00	N	对应于raw型datapoint（模组透传）
  bool	0x01	1	value范围：0x00/0x01
  value	0x02	4	对应int类型，大端表示
  string	0x03	N	对应于具体字符串
  enum	0x04	1	枚举类型，范围0-255
  bitmap	0x05	1/2/4	长度大于1字节时，大端表示
  Len	2	长度对应value的字节数
  Value	1/2/4/N	hex表示，大于1字节采用大端传输

• datapoint命令/状态数据单元除”raw”类型外，其他类型均属于“obj”型datapoint。

• “命令下发”可包含多个“obj”型datapoint“命令数据单元”。

• “命令下发”为异步处理协议，对应于MCU的datapoint“状态上报”。

模组发送

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x08
数据长度	2	取决于“命令数据单元”类型以及个数 + 子设备地址长度
子设备地址	2	设备实际地址
数据	N	“3.4命令数据单元”组
校验和	1	从帧头开始按字节求和得出的结果对256求余

MCU回复：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x08
数据长度	1	0x0003
子设备地址	2	设备实际地址
数据	1	0x00/0x01 00成功 01失败
校验和	1	从帧头开始按字节求和得出的结果对256求余

设备状态上报

1. 当MCU收到模组端下发的命令，并执行相应动作之后，需要将新的状态被动上报给模组端。

   状态正确执行之后，只上报执行了操作的datapoint状态。

2. “状态上报”为同步处理协议，模组端收到datapoint信息之后会立即返回ACK给MCU。

3. “状态上报”可包含多个datapoint 命令数据单元。

4. DP数据长度最大59字节。

MCU发送

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x09
数据长度	2	取决于“状态数据单元”类型以及个数+子设备地址长度
子设备地址	2	设备实际地址
数据	N	“3.4状态数据单元”组
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x09
数据长度	2	0x0003
子设备地址	2	设备实际地址
数据	0	0x00/0x01 0x00:状态上报成功 0x01:状态上报失败
校验和	1	从帧头开始按字节求和得出的结果对256求余

MCU版本查询

若支持MCU升级必须实现此命令，也可MCU侧主动上报。

• 查询场景：1.配网时 2.MCU升级过程异常时。

• 主动上报场景：1.配网成功后（必须添加）2.升级结束。

• 版本格式：最大可以表示的版本为3.3.15 版本用一个字节表示，即xx.xx.xxxx，所以可以表示的最高版本为3.3.15，但网关不会识别版本信息采用字符串形式，即后台可以随意输入版本信息，因此MCU端使用的版本数据不能超出3.3.15。

模组发送

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

MCU响应或模组发送

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

OTA 升级通知

模组发送

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	模组产生
命令字	1	0x0C
数据长度	2	0x0011
数据	8	Data[0]~ Data[7] PID
数据	1	版本号（升级版本） 01.00.0001 --》1.0.1
数据	4	固件大小 最大 256K
数据	4	固件校验和：从固件第一个字节按字节求和得出的结果对2^32求余
校验和	1	从帧头开始按字节求和得出的结果对256求余

MCU返回

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

OTA固件内容请求

MCU发送

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	0x0000
命令字	1	0x0D
数据长度	2	0x000c
数据	8	PID
数据	1	版本号（升级版本） 01.00.0001 --》1.0.1
数据	4	数据包的偏移量(固件的位置)
数据	1	数据包的大小
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组响应

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	0x0000
命令字	1	0x0D
数据长度	2	0x000e+N
数据	1	Status 0 成功 1：失败
数据	8	PID
数据	1	版本号（升级版本） 01.00.0001 --》 1.0.1
数据	4	数据包的偏移量(固件的位置)
数据	N	数据
校验和	1	从帧头开始按字节求和得出的结果对256求余

OTA 固件升级结果上报

MCU升级完成后上报此结果。不管MCU升级成功还是失败，只要是启动了升级的动作，就必须要通过结果上报命令终止升级流程。

MCU发送

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
业务序列号（Seq）	2	MCU下发的SEQ
命令字	1	0x0E
数据长度	2	0x000a
数据	1	Status 0 成功 1：失败
数据	8	PID
数据	1	版本号（升级后的当前版本） 01.00.0001 --》 1.0.1
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组响应

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

时间同步

时间同步用来MCU测同步网关的网络时间使用。

MCU发送

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

模组返回

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x02
序列号	2	N
命令字	1	0x024
数据长度	2	0x0002
数据	2	数据长度为8字节的时间值， 格式参考如下时间同步数据格式
校验和	1	从帧头开始按字节求和得出的结果对256求余

时间同步的数据格式，包含标准时间戳和本地时间戳。

Variable	Variable
标准时间戳(4 bytes)	本地时间戳(4 bytes)

时间同步数据格式：标准时间戳为格林威治时间1970年01月01日00时00分00秒起至现在的总秒数。

例如，本地时间戳=标准时间戳 + 标准时间和本地时间相差的秒数（包含时区和夏令时）。