Zigbee 门锁对接是将门锁 mcu 和 Zigbee 设备通过串口协议完成数据交互，由于门锁的功能相对比较多，而且国内门锁厂家之间的功能点都存在一定的差异，Zigbee 标准协议中定义的功能已经满足不了要求，实现，因此采用私有协议实现。此时 Zigbee 设备主要的作用是充当 mcu 和 Zigbee 网关的传输通道，即把网关下发的数据按照串口协议的格式封装好，下发给 mcu，同时把从串口中接收到的 mcu 数据封装成 Zigbee zcl 层的数据格式发送给 Zigbee 网关，再由网关完成和涂鸦云的数据交互。简单的理解，即利用 Zigbee 网络将 mcu 接入到涂鸦云，从而实现门锁和涂鸦的对接。
| 名词 | 解释 |
|---|---|
| Zigbee SDK | 基于芯科 Zigbee 协议栈经过裁剪、优化后封装的涂鸦 ZigbeeSDK。 |
| Attribute | Attribute （属性）是一个反映物理数量或状态的数据值 |
| Cluster | Cluster （群集）是包含一个或多个属性（ attribute ）的群集 |
| EndPoint | EndPoint （端点）是协议栈应用层的入口，即入口地址，也可以理解应用对象存在的地方，它是为实现一个设备描述而定义的一组群集 |
| Device Id | Zigbee 中为每一种设备定义的序号 |
| 弱电设备 | 是指使用电池供电的设备，在 Zigbee 协议中被称为 sleep end device 的设备 |
| 强电设备 | 是指使用市电或者从市电稳压后的电源供电的设备，在 Zigbee 协议中被称为 router 的设备 |
| PID | product ID，在涂鸦 IoT 平台创建的每一个产品都会产生一个唯一的产品编号，关联了产品具体的功能点、APP 控制面板、出货信息等所有跟这个产品相关的信息。 |
| SOC | system on chip，硬件本身无 MCU，控制程序写入联网模块中。 |
| SDK | Software Development Kit，软件开发工具包，辅助开发某一类软件的相关文档、范例和工具的集合。为了鼓励开发者使用其系统或者语言，许多 SDK 是免费提供的，涂鸦的也是。 |
| 固件 | Firmware，就是写入 EROM（可擦写只读存储器）或 EEPROM (电可擦可编程只读存储器)中的程序。固件是指设备内部保存的设备“驱动程序”，通过固件，操作系统才能按照标准的设备驱动实现特定机器的运行动作，比如光驱、刻录机等都有内部固件。固件是担任着一个系统最基础最底层工作的软件。 |
| OTA | 固件空中升级，zigbee 模块固件可以通过 OTA 使用远程升级。 |
| mcu OTA | Mcu 的固件可以通过 zigbee 实现空中升级，需要 mcu 端支持该功能。 |
| DP | 用于和涂鸦云端实现数据交互定义的一套数据格式，具体格式参加下表。 |
产品为基于标准的 Zigbee 3.0 协议
| Profile Id | 0x0104 |
|---|---|
| Device Id | 0x000a |
| endpoint | 描述 |
|---|---|
| 1 | 用于应用数据交互时的 endpoint |
| SMART_PLUG (0x0051) | |
|---|---|
| SMART_PLUG (0x0051) | Output Clusters (Client) |
| Basic (0x0000) | OTA (0x0019) |
| Time (0x000A) | |
| Private cluster (0XEF00) | |
Attributes:
| ID | name | Data Type | Range | Default |
|---|---|---|---|---|
| 0x0000 | ZCL Version | uint8 -0x20 | 0x00-0xff | 0x03 |
| 0x0001 | Application Version | uint8 -0x20 | 0x00-0xff | ie: 0b 01 00 0001 = 1.0.1 即 0x41 为 1.0.1 OTA 功能会用到该版本号，在 OTA 开始阶段，网关会读取 OTA 包的版本号推送给设备。在 OTA 成功重启后，网关会读取版本号来确定是否升级成功。只能往更高的版本升级。 |
| 0x0002 | Stack Version | uint8 -0x20 | 0x00-0xff | 0x02 |
| 0x0003 | Hardware Version | uint8 -0x20 | 0x00-0xff | 0x01 |
| 0x0004 | Manufacturer Name | string -0x42 | 0-32 bytes | XXX…XXX (长度为 16 个字节，由 8 字节前缀和 8 字节的 PID 组成) 0-7 bytes：_TZF320_ 8-16 bytes：PID（由产品经理在平台或者自助创建和提供） |
| 0x0005 | Modle Identifier | string -0x42 | 0-32 bytes | TY0A02 该字段为了网关快速识别设备类型用，提升体验 |
| 0x0007 | Power Source | enum8-0x30 | 0x00-0xff | depends on your product |
| 0xfffd | Cluster Revision | uint16 -0x21 | 0x0000-0xffff | 0x0001 |
Commands:
| ID | name | Direction | Description |
|---|---|---|---|
| 0x00 | Reset to factory default | C->S | C: client S:server |
为满足通用对接的要求，采用一个私有的 cluster 并定义一类用于传输数据的私有 cluster command 实现数据的交互。其中 APS 层中的 Destination Endpoint : 0x01， ClusterID : 0xEF00，Profile ID : 0x0104，Source Endpoint : 0x01。
在 zcl 层中，使用私有的 private command id 来表示不同的数据交互命令，在 ZCL 的 payload 中 定义私有的帧格式， 采用 sequence number (2byte) + user data 的形式。
Zcl head 的帧格式可以参考下表。
| 字段 | 长度(bit) | value | 说明 |
|---|---|---|---|
| Frame type | 2 | 01 | Command is Specific to a Cluster |
| Manufacture specific | 1 | 0 | Manu Code Not included in zcl |
| Direction | 1 | 0/1 | 0: GW->Zigbee 1: Zigbee->GW |
| Disable default response | 1 | 0/1 | 默认为 1，只有设备数据主动上报时才为 0，此时网关会主动回一个 Response 报文，作为上报成功的标记 |
| Reserved | 3 | 000 | 保留 |
| 命令枚举 | Value | 说明 |
|---|---|---|
| TY_DATA_ REQUEST | 0x00 | 网关侧数据下发 |
| TY_DATA_RESPONE | 0x01 | mcu 侧对于数据请求的回 |
| TY_DATA_REPORT | 0x02 | MCU 侧数据主动上报 |
| TUYA_MCU_VERSION_REQ | 0x10 | Gw->Zigbee 网关查询 mcu 版本 |
| TUYA_MCU_VERSION_RSP | 0x11 | Zigbee->Gw mcu 返回版本或主动上报版本 |
| TUYA_MCU_OTA_NOTIFY | 0x12 | Gw->Zigbee 网关通知 mcu 升级 |
| TUYA_OTA_BLOCK_DATA_REQ | 0x13 | Zigbee->Gw 请求 mcu 的升级包 |
| TUYA_OTA_BLOCK_DATA_RSP | 0x14 | Gw->Zigbee 网关返回请求的升级包 |
| TUYA_MCU_OTA_RESULT | 0x15 | Zigbee->Gw 返回 muc 的升级结果 |
| TUYA_DYNA_PWD_KEY | 0x20 | 动态密码 key（双向） |
| TUYA_REPORT_LOG | 0x23 | 记录型状态上报（双向） |
| TUYA_MCU_SYNC_TIME | 0x24 | 时间同步（双向） |
| TUYA_INTERNET STATUS | 0x25 | 网关联网状态 |
| TUYA_ZCL_INTERNET_STAT_ACK | 0x26 | mcu 对网关的联网状态的 ack (模块->网关) |
| TUYA_ZCL_SESSIONE_KEY_REQ | 0x40 | sessionKey 请求(模块->网关) |
| TUYA_ZCL_SESSIONE_KEY_RSP | 0x41 | 网关发送密文 HMA_RA+AES_RB (网关->模块) |
| TUYA_ZCL_SESSIONE_KEY_ACK | 0x42 | 模块回复模块发送 HMAC_RB (双向) |
| TUYA_ZCL_DYNA_PWD_REQ | 0x43 | 请求获取动态密码 key (模块->网关) |
DP 数据格式
| 数据段 | 长度（ byte ） | 说明 | |||
|---|---|---|---|---|---|
| DPID | 1 | Datapoint 序号 | |||
| type | 对应开放平台上某 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 字节采用大端传输 | |||
Attributes:
| ID | name | Data Type | Range | Default |
|---|---|---|---|---|
| 0x0000 | Upgrade Server ID | EUI64-0xF0 | — | 0xffffffffffffffff |
| 0x0001 | File Offset | uint32-0x23 | — | 0x00000000 |
| 0x0002 | Current File Version | uint32-0x23 | — | 0x00000000 |
| 0x0006 | Image Upgrade Status | enum8-0x30 | — | 0x00 |
| 0x0007 | Manufacturer ID | uint16 -0x21 | — | 0x1002 |
| 0x0008 | Image Type ID | uint16 -0x21 | — | 0x1602 |
| 0x0009 | Min Block Request Period | uint16 -0x21 | — | 0x0000 |
| 0xfffd | Cluster revision | int16-0x29 | 0x0000 -0xffff | 0x0001 |
Commands:
| ID | name | Direction | Description |
|---|---|---|---|
| 0x00 | Image Notify | S->C | |
| 0x01 | Query Next Image Request | C->S | |
| 0x03 | Image Block Request | C->S | |
| 0x06 | Upgrade End Request | C->S |
涂鸦 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） | 串口通信协议版本，升级扩展用，当前版本为 0x03 |
| 业务序列号（Seq） | 业务的序列号（1~0xfff0） |
| 命令字（Cmd） | 具体帧类型，参见下表 |
| 数据长度（Length） | 传输的有效数据长度 |
| 数据（Data） | 传输的有效数据 |
| 校验和（Check） | 数据校验，从帧头开始按字节求和得出的结果对 256 求余 |
Cmd描述表
| CMD id | 说明 | 方向 |
|---|---|---|
| 0x00 | 睡眠唤醒 | (Zigbee<—>mcu) |
| 唤醒响应 | (mcu<—>zigbee) | |
| 0x01 | 产品信息查询 | (zigbee—>mcu) |
| 产品信息响应 | (mcu—>zigbee) | |
| 0x02 | 产品信息查询 | (zigbee—>mcu) |
| Zigbee 状态查询响应 | (zigbee—>mcu) | |
| 0x03 | Zigbee 设备重置 | (mcu—>zigbee) |
| Zigbee 设备重置响应 | (zigbee—>mcu) | |
| 0x04 | 数据指令下发 | (zigbee—>mcu) |
| 数据指令下发响应 | (mcu—>zigbee) | |
| 0x05 | 数据事物上报 | (zigbee—>mcu) |
| 数据事物上报相应 | (zigbee—>mcu) | |
| 0x06 | Zigbee 状态通知 | (zigbee—>mcu) |
| 0x07 | 请求动态密码 | (mcu—>zigbee) |
| 请求动态密码的响应 | (zigbee—>mcu) | |
| 0x08 | mcu 离线密码上报 | (zigbee—>mcu) |
| 离线密码响应 | (mcu—>zigbee) | |
| 0x09 | zigbee 模块功能测试 | (mcu—>zigbee) |
| 测试应答 | (zigbee—>mcu) | |
| 0x0a | zigbee 发送 mcu 版本查询 | (zigbee—>mcu) |
| mcu 应答 | (mcu—>zigbee) | |
| 0x0b | OTA 升级通知 | (zigbee—>mcu) |
| mcu 应答 | (mcu—>zigbee) | |
| 0x0c | OTA 固件内容请求 | (mcu—>zigbee) |
| zigbee 应答 | (zigbee—>mcu) | |
| 0x0d | OTA 固件升级结果上报 | (mcu—>zigbee) |
| zigbee 应答 | (zigbee—>mcu) | |
| 0x23 | 记录型状态上报的数据格式（包含时间戳） | (mcu—>zigbee) |
| 记录型状态上报的数据格式的响应 | (zigbee—>mcu) | |
| 0x24 | mcu 时间同步请求 | (mcu—>zigbee) |
| 网关时间同步的请求或响应 | (zigbee—>mcu) |
(1) Mcu 发送配置指令，开启模块配网
(2) Beacon request 信道扫描间隔大于 200ms，优先扫描优先信道
(3) 扫描时间不超过 3 分钟
(4) 配网成功之后，data request 时间为 250ms，持续 1 分钟，之后切换为 5s。
(1) 断电启动之后，需要重新同步网络状态给 mcu，同时需要请求时间戳，并把请求到的时间戳发送给 mcu。
(2) 如果存在离线数据（ mcu 在模块离线时，上传给模块的记录型数据），在模块上电并 rejoin 成功，且处于连接服务器状态时，将保存的数据逐一发送给网关。
(1) 模块需在 2 分钟左右时间内，上报心跳，心态内容为设备版本号
(1) 如果开启了 APS 层的重传建议把 Disable Default Response 设置成 1，避免太多 ack。
(2) 重传数据的 Transaction Sequence Number 需要保持一致
(3) 重传间隔大于 250ms，重传持续时间建议低于 3s
(4) 避免频繁 rejoin
基于涂鸦 Zigbee SDK 开发：
（1）你只需修改 demo 样例的模块型号和硬件配置即可完成上述功能，包括群组，场景均实现
（2）涂鸦提供完整的烧录，授权，产测流程和软硬件工具
自行开发-非涂鸦 Zigbee 模块：
（1） 需要完整实现上述技术细节
（2）完成设备授权
使用涂鸦完整授权工具授权
通过模块和上位机串口通信授权
串口通信实例代码
自行开发-涂鸦 Zigbee 模块：
（1）只需要实现固件功能细节
（2）购买授权过的涂鸦 Zigbee 模块即可