Zigbee 门锁接入标准

门锁对接实现方式

由于门锁的功能相对比较多，而且门锁厂家之间的功能点都存在一定的差异，Zigbee 标准协议中定义的功能基本满足不了要求，因此采用私有协议实现。

Zigbee 设备主要的作用是充当 MCU 和 Zigbee 网关的传输通道，即把网关下发的数据按照串口协议的格式封装好，下发给 MCU。同时，把从串口中接收到的 MCU 数据封装成 Zigbee ZCL 层的数据格式，发送给 Zigbee 网关，再由网关完成和云服务的数据交互。简而言之，即利用 Zigbee 网络将 MCU 接入到云服务，从而实现门锁和涂鸦的对接。

Zigbee 设备功能描述

Zigbee 基本信息

参数	数值
Profile Id	0x0104
Device Id	0x000a

endpoint	描述
1	用于应用数据交互时的 endpoint

支持的 clusters、属性与命令

SMART_PLUG (0x0051)	Output clusters (Client)
Basic (0x0000)	OTA (0x0019)
Time (0x000A)	/
Private cluster (0XEF00)	/

Basic cluster

Attributes:

ID	Name	Data type	Range	Default
0x0000	ZCL Version	uint8-0x20	0x00-0xff	0x03
0x0001	Application Version	uint8-0x20	0x00-0xff	例如，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	Model 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

Private cluster

为满足通用对接的要求，采用一个私有的 cluster 并定义一类用于传输数据的私有 cluster command，来实现数据的交互。在 APS 层，Destination Endpoint: 0x01，ClusterID: 0xEF00，Profile ID: 0x0104，Source Endpoint: 0x01。

在 ZCL 层中，使用私有的 private command ID 来表示不同的数据交互命令。在 ZCL 的 payload 中定义私有的帧格式，采用 sequence number (2 bytes) + 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	保留

Private command ID

命令枚举	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，返回 MCU 的升级结果
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 (模组->网关)

Frame of command ID

DP 数据格式

数据段	长度（ byte ）	说明
DPID	1	Data point 序号
type	对应 涂鸦开发者平台 上某 data point 具体的数据类型,通过如下“表示值”标识
	类型	表示值	长度（字节）	说明
	raw	0x00	N	对应于 raw 型 data point（模组透传）
	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 字节采用大端传输

Over the air upgrade

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
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)

具体串口协议内容，请参考 通用 MCU 对接协议。