Zigbee 对接规范

将 Zigbee 设备连接涂鸦开发者平台，实现与 App 和云端交互之前，需要遵循涂鸦设备端到云端的一系列规范。本文主要讲解此部分内容及相关示例。

名词解释

本文涉及的概念如下表所示：

名词	说明
PID	即产品 ID（Product ID）。在涂鸦，产品是一系列具有同样配置和属性的智能设备的集合，方便您批量管理设备。当您在 涂鸦开发者平台 创建了一个产品后，平台赋予该产品一个 PID，用来表示产品的注册标识。
DP	产品的数据模型，描述设备的 产品功能。
固件 Key	PID 下绑定的固件标识。
授权码	也叫做生产凭证，设备与涂鸦开发者平台建立连接传输数据的认证信息。
配网	设备连接网关 App 和涂鸦开发者平台的交互过程。
EndPoint	EndPoint （端点）是协议栈应用层的入口，即入口地址，也可以理解应用对象存在的地方，它是为实现一个设备描述而定义的一组群集。
OEM 固件	可实现同一固件用于同品类下多个不同 PID 的产品。
Mode ID	这个字段是 Zigbee 子设备与 Zigbee 网关之间的一个约定，用于网关快速识别入网的 Zigbee 设备类型。
Attribute	Attribute （属性）是一个反映物理数量或状态的数据值。
Cluster	Cluster （群集）是包含一个或多个属性（Attribute）的群集。
Device ID	Zigbee 中为每一种设备定义的序号。
弱电设备	是指使用电池供电的设备，在 Zigbee 协议中被称为 Sleep End Device 的设备。
强电设备	是指使用市电或者从市电稳压后的电源供电的设备，在 Zigbee 协议中被称为 Router 的设备。

系统框架图

如图所示，涂鸦 Zigbee 子设备通过 Zigbee 网关接入云端后可以通过 App 进行控制，并且可以借助云端实现子设备之间的联动控制，联动是可以跨通信协议类型的。

例如在 App 上，将 Zigbee 开关 1 可以与 蓝牙 Mesh 灯具 1 建立联动关系，例如：

• 当 Zigbee 开关 1 上报开时，使 蓝牙 Mesh 灯具 1 打开。
• 当 Zigbee 开关 1 上报关时，使 蓝牙 Mesh 灯具 1 关闭。

PID

产品的唯一标识，相当于产品的身份证，云端端通过设备端上报的 PID 信息识别出产品并进行相关的交互显示。PID 是非常重要的信息，在创建产品时产生，通常需要将此信息填写在固件代码中。

对于 Zigbee 设备，PID 需要存储在 Basic cluster 下，Manufacturer Name 属性中。如下图所示：

DP

产品的数据模型，描述 产品功能，用于设备与 App 和云端通信。在配置产品功能时产生，分为以下两种：

• 标准功能：产品品类的常用的功能，可直接选用。
• 自定义功能：标准功能不能满足产品功能定义时，需要使用自定义功能自行配置。

DPID 是对功能进行编号，一个子设备与云端进行交互，基本都是通过 DP 进行数据下发和上报的。

固件 Key

固件的标识信息，在涂鸦开发者平台硬件开发步骤选择 新增自定义固件 时产生，绑定在 PID 下，包含固件标识名、固件版本、芯片平台、固件类型和升级通道等信息。

通常情况下，您不需要关注固件 Key，当存在同一个固件要绑定到多个 PID 的情况时，才需要将此信息填入到代码内，并打开 OEM 设置。

固件 Key 描述	说明
固件标识名	使用脚本编译时写入的固件名称。
固件类型	根据产品类型选择，蓝牙协议选择蓝牙固件。
芯片平台	根据选择的模组自动生成。
固件版本	脚本编译时写入的固件版本，上传生产固件时填写。

授权码

授权码是设备与涂鸦开发者平台建立连接传输数据的认证信息，需要预先烧录到设备中。

配网时，设备连接到 Wi-Fi 路由器向涂鸦开发者平台注册时，会将此信息上报给云端。云端通过识别此信息，确认是涂鸦认证的设备，将设备连接到涂鸦开发者平台。

根据不同产品的烧录需求，涂鸦提供三种类型的授权码供自由选择，可以在授权码下单页面获取。（目前每个IOT账号可以免费领取两个激活码）

授权码名称	说明
生产凭证	加密后的授权码信息，使用涂鸦上位机通过授权协议烧录到设备内，常用于固件烧录+授权一体方案，会对固件 Key 包含的固件标识名、固件版本等信息进行校验，防止出现固件烧录错误、版本错误等现象，是涂鸦标准模组使用的烧录方式，也是涂鸦最推荐的烧录方式，不过需要涂鸦生产系统支持相应芯片的烧录，不适用于非涂鸦标准芯片。
生产凭证-仅授权	加密后的授权码信息，使用涂鸦上位机通过授权协议烧录到设备内，用于固件烧录+授权分立方案，不对固件 Key 包含的信息做校验，适用于非涂鸦标准芯片的授权。
授权码清单	授权码明文信息，由开发者自行开发上位机烧录到设备内，通常不建议使用。（目前 Zigbee SDK 不支持写入授权码明文信息）

OEM 固件

通常情况下，将产品的 PID 信息填写在固件中，这样编译生成的固件只适用于此 PID。

对于一些应用场景，比如多个 PID 的产品功能相同，固件共用同一个即可，无需针对每个 PID 单独编译固件，就需要使用到 OEM 逻辑。

OEM 固件将固件 Key 信息写在固件中，不包含 PID 信息，这样编译生成的固件，适用于同品类下多个不同的 PID。

Mode ID

Mode ID 是 Zigbee 子设备与 Zigbee 网关之间的一个约定，用于网关快速识别入网的 Zigbee 设备类型。

该字段存在 Zigbee basic cluster 的 mode id 属性中。例如，mode id = TS0505B，表示 5 路灯。

开关设备

设备名称	Mode ID
一路开关（零火）	TS0001
二路开关（零火）	TS0002
三路开关（零火）	TS0003
四路开关（零火）	TS0004
五路开关（零火）	TS0005
六路开关（零火）	TS0006
七路开关（零火）	TS0007
一路开关（零火）	TS0011
二路开关（单火）	TS0012
三路开关（单火）	TS0013
四路开关（单火）	TS0014
五路开关（单火）	TS0015
六路开关（单火）	TS0016
七路开关（单火）	TS0017
一路场景开关	TS0021
二路场景开关	TS0022
三路场景开关	TS0023
四路场景开关	TS0024
五路场景开关	TS0025
六路场景开关	TS0026
七路场景开关	TS0027
八路场景开关	TS0028
九路场景开关	TS0029
九路场景遥控器	TS002A
一路无线开关(电池)	TS0041
一路无线开关(电池)（1ep=>3DP场景版）	TS0041A
二路无线开关(电池)	TS0042
二路无线开关(电池)（1ep=>3DP场景版）	TS0042A
三路无线开关(电池)	TS0043
三路无线开关(电池)（1ep=>3DP场景版）	TS0043A
四路无线开关(电池)	TS0044
四路无线开关(电池)（1ep=>3DP场景版）	TS0044A
五路无线开关(电池)	TS0045
五路无线开关(电池)（1ep=>3DP场景版）	TS0045A
六路无线开关(电池)	TS0046
七路无线开关(电池)	TS0047
八路无线开关(电池)	TS0048
自研全功能开关	TS000F
自研模式切换三路无线开关	TS004F
自研1-6路场景开关	TS002F

插座

设备名称	Mode ID
一路10A不带计量（10A5孔墙插）	TS0101
一路10A带计量 (硬件带通断)）	TS0102
一路16A不带计量	TS0103
一路16A带计量(硬件带通断)	TS0104
1路10A不带按键计量插座（硬件无通断）	TS0105
1路16A不带按键计量插座（硬件无通断）	TS0106
2路10A不带按键计量插座(10A5孔带USB墙插)	TS0107
二路10A带计量（硬件带通断)	TS0108
二路16A不带计量(硬件带通断)	TS0109
二路16A带计量(硬件带通断)	TS010A
OEM一路插座不带计量	TS0111
OEM二路插座不带计量	TS0112
OEM三路插座不带计量	TS0113
OEM四路插座不带计量	TS0114
OEM五路插座不带计量	TS0115
OEM一路插座带计量	TS0121
二路10A不带计量插座(硬件带通断)	TS0122
1~8路全功能插座	TS011F

传感器

设备名称	Mode ID
温湿度	TS0201
PIR	TS0202
门窗磁	TS0203
燃气报警	TS0204
烟雾报警	TS0205
报警按钮（弱电）	TS0206
水浸传感器	TS0207
声音报警器	TS0208
光电报警器	TS0209
震动报警器	TS0210
SOS按钮	TS0211
一氧化碳报警	TS0212
报警按钮（强电）	TS0213
Zigbee小夜灯	TS0214
安防遥控器	TS0215
新版自研遥控器	TS0215A
SOS遥控器（强电版）	TS0215B
声光报警器	TS0216
空气质量传感器	TS0217
自研声光报警器	TS0219
PM2.5传感器	TS0221
亮度传感器	TS0222

窗帘

设备名称	Mode ID
电动窗帘	TS0301
1~N路窗帘开关（新版）	TS130F

控制器

设备名称	Mode ID
6路图形场景面板	TS0303
6路文字场景面板	TS0304
9路场景遥控器	TS002A
空调	TS0305
新风	TS0306
地暖	TS0307
温控器	TS0308
中央空调	TS0309
新风机	TS030A
地暖控制器	TS030B

锁

设备名称	Mode ID
指芯门锁	TS0401
涂鸦家庭锁	TY0A01
涂鸦公寓锁	TY0A02
涂鸦商用锁	TY0A03

灯

设备名称	Mode ID
一路调光灯	TS0501B
二路调光灯	TS0502B
三路调光灯	TS0503B
四路调光灯	TS0504B
五路调光灯	TS0505B

通用对接

设备名称	Mode ID
强电通用对接	TS0601
弱电通用对接	TS0601
强电场景	TS0602
弱电场景	TS0602
三级架构通用对接	TS0603
离线语音对接	TS0604

开关与场景混合设备

设备名称	Mode ID
1开关+3场景	TS0701
2开关+2场景	TS0702
3开关+1场景	TS0703
16开关+16场景	TS0716
1~6可配置混合场景开关	TS0726

特殊开关

设备名称	Mode ID
插卡取电开关	TS0801
智慧燃气开关	TS0802

遥控器

设备名称	Mode ID
自研调光遥控器	TS1001

开关与场景混合设备

设备名称	Mode ID
自研一路调光开关	TS1101
自研二路调光开关	TS1102
全功能自研调光开关（开关品类）	TS110E
全功能自研调光器（照明品类）	TS110D

万能遥控器

设备名称	Mode ID
带按键的红外遥控器	TS1200
不带按键的红外遥控器	TS1201

固件版本号

固件版本号采用的是 Zigbee 标准属性（basic: application version attr），该属性的长度是 1 字节。涂鸦通过将 1 字节数据按照 bit 进行拆分，形成版本号，1111 1111 表示 x.x.x。

例如 0100 0011 表示固件版本号为 1.0.3，如下图所示，Application Version = 67 转换成 2 进制即为 0100 0011，则该固件版本号实际上是 1.0.3。

子设备心跳

• 网关主动心跳：网关会根据设备数量，动态调整每个子设备的主动心跳间隔，网关会通过读取子设备的 basic cluser，application verison 属性，来判断子设备是否在线。

• 子设备主动心跳：是通过 report Basic cluster 下的 application version 属性实现的，心跳时间为 150 ~180 秒的随机时间。早期的网关没有网关主动心跳，后期网关基本的都加了主动心跳，因此子设备无需在维护主动心跳。