简体中文
简体中文
English
联系我们
注册
登录

串口协议

更新时间:2022-12-14 04:00:22下载pdf

更新记录

主要变更 修订日期 修订说明
创建文档 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 优化协议排版,优化内容描述

串口硬件与参数

串口硬件连接示意图

涂鸦 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 发送数据,只要保持唤醒口持续低电平,模组会一直处于唤醒状态。当电平拉高之后,模组会在约 300~550ms 之后进入休眠,减少不必要的唤醒时间,降低功耗。

  • 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 求余

帧中的数据长度(Length)由 Zigbee 模组单个空中数据包的长度决定,涂鸦会对 Zigbee 空中数据格式重新封装,目前支持的数据上限为 62 字节。

命令字索引

命令字 说明 强电版本 低功耗版本 场景版本
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 私有命令群组广播 × ×

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

串口通信模式介绍

命令字通信模式

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

串口协议

具体通信方式以 协议详述 章节中为准。

模组下发命令通信模式

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

  • 模组控制命令下发

    串口协议

    上图假设模组控制命令下发命令字为 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)

在 App 上将设备解除并清除数据时,会通知 MCU。MCU 收到该通知后,可以清除之前的默认配置,即恢复出厂设置状态,MCU 可自己决定是否恢复出厂设置。

模组下发

字段 字节数 说明
帧头 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

03 01 0001 01 表示 3 号功能系统开关,使用 bool 型变量,开机数值为 1。

状态上报(被动)(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

05 02 0004 0000001e 表示 5 号功能上报湿度,使用 Value 型变量,湿度为 30%。

模组返回

字段 字节数 说明
帧头 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

05 02 0004 0000001e 表示 5 号功能上报湿度,使用 Value 型变量,湿度为 30%。

模组返回

字段 字节数 说明
帧头 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 值,返回扫描结果和信号强度百分比。本命令必须在设备未配网情况下才可正常运行,单次测试完成之后必须重启模组。

默认使用 11 信道,MCU 发送 时,直接选择 11 信道。

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

无效信道取默认 11 信道。

场景开关

在场景开关设备中,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 数据请求逻辑需要增加超时机制。即当发出数据请求在一段时间内没有回复时,需要重新发送该请求。

建议设置超时时长为 3~5 秒,超时次数为 5 次。即当连续 5 次及以上的响应时长超过 3~5 秒,则认为 OTA 升级异常,取消 OTA 升级。

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 相关命令用单字节表示 MCU 版本时,由于字节长度限制,最大版本号为 3.3.15

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。
  • 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 数据,可根据自身产品的特性,将一些可上报可下发的 DP。

设备离线之后重新上线用于状态同步使用。但需要注意,如果上报的 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 网络阻塞。

  • 模组发送时和 0x04 命令字的 payload 的格式相同。
  • MCU 返回后,上报状态的策略需 MCU 端自行设计,上报依旧使用 0x050x06 命令字。

模组发送

字段 字节数 说明
帧头 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

0x41、0x42、0x43 命令使用环境:

  • 必选 scene_switch 标识符的 DP。
  • 要选择具有八分组功能的面板。无线开关品类创建的,要找涂鸦产品经理加白名单才能选到,仅用于调试。

下发 kid gid sid(0x41)

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

  • kid:key ID 按键标识。
  • gid:group ID 为 Zigbee 群组的标识。
  • sid:scene ID 为 Zigbee 场景的标识。
  • 前提条件是模组使用场景版本并且绑定面板支持八分组功能。
  • 如果子设备入网后下发中 sid 值为 0,表示无 scene ID。
  • 下发后需 MCU 自行储存管理。

模组发送

字段 字节数 说明
帧头 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 对接方式的其他子设备。

  • 对接需要清楚被控设备的 DP 格式和内容。
  • 群组广播只是触发群组执行动作,主控设备的状态仍然需要自行上报,即和群组广播独立上报。

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