【ZigBee 系列】| 如何在 ZigBee 中添加 Cluster

鸣涧

【ZigBee 系列】| 如何在 ZigBee 中添加 Cluster


一、基本概念

Cluster 由属性(Attribute)以及命令(Command)组成。属性是一个数据集，由设备保存，可以在设备间传递。

例如一个 Thermostat cluster 包含的相关属性如下：

            A. 当前温度

            B. 最小温度

            C. 最大温度

Zigbee 联盟将定义好的标准 Cluster 收录到了 ZCL 库中，每个 Cluster 被分配了一个唯一的 16 位 Cluster ID，从 0xFC00 开始则是厂家自定义的 Cluster ID。

二、Cluster 中的 Server 和 Client

用于通过发送命令来操纵相应 Cluster Server 中的属性。通常使用“write”命令设置属性值，使用“read”命令获取属性值。

              

三、添加 ZCL 的 Cluster

恩智浦的 zigbee 3.0 协议栈中，已经实现了 zigbee 联盟定义的大部分标准 Cluster，用户可以直接使用接口开发。这些标准的 Cluster 可以和其他符合 zigbee 标准的厂商产品直接对接使用。但是有些客户想实现自己私有的 Cluster，NXP 的协议栈预留了相应的接口。

所有以下代码部分说明，均以恩智浦的 zigbee 3.0 协议栈(SDK)在 JN5169 上演示实现，请至恩智浦官网下载 JN-SW-4170 查看详细代码：

            https://www.nxp.com/webapp/swlicensing/sso/downloadSoftware.sp?catid=ZIGBEE-SDK

        增加 Cluster 的主要步骤如下：

        3.1 定义 Cluster 的相关文件 DemoCluster.c 和 DemoCluster.h

        ① 在 DemoCluster.h 中定义 CLUSTER_ID_Demo 的值为 0xFC00

            #define CLUSTER_ID_Demo  0xFC00

        ② 定义 Demo Cluster，例如：

                  

        ③ 定义需要发送的 Command，例如：

                    

        ④ 自定义发送 Payload 的类型，常见的有字符串，整形。可以是单个，也可以是数组，例如：

                    

        ⑤ 实现 Client 以及 Server 之间的发送和接收函数。

               

        3.2 在 Profile 中的 Endpoint 增加对应的 Cluster

        ① 在 Switch 的 Cluster 实例结构体中增加 Cluster 实例：

                        

        ② 在 dimmer_switch.h 中 Switch 的设备结构体 tsZLO_DimmerSwitchDevice 中增加下面的定义：

                    

        ③ 在 dimmer_switch.c 中的 eZLO_RegisterDimmerSwitchEndPoint 增加以下语句：

                    

        ④ 增加 Cluster 实例到 Coordinator 的 Cluster 实例结构体中：

                      

        ⑤ 在 control_bridge.h 中的设备结构体 tsZLO_ControlBridgeDevice 增加如下定义：

                    

        ⑥ 在 control_bridge.c 中 eZLO_RegisterControlBridgeEndPoint 增加以下语句：

                  

        3.3 在 ZPS Config 中增加 Cluster

               

        在“DimmableSwitch”中右键点击“End Point ‘SWITCH’ (1)”

        （1）右键点击 HOME_AUTOMATION profile

        （2）选择 New Child -> Input Cluster 以及 New Child -> Output Cluster

        （3）选择” undefined “，找到 Properties 一栏，将 Cluster 设置为 Demo

        （4）选择“apduZCL”作为接收的 APDU

        （5）同样在 Coordinator 的“End Point ‘ZLO’ (1)”中也添加 Demo Cluster

        3.4 修改 JN-AN-1216 中的 Coordinator 的 zcl_options.h

        增加宏定义 CLD_DEMO，DEMO_CLIENT，同样在 JN-AN-1219 中的 Switch 中增加 CLD_DEMO，DEMO_SERVER 宏定义，重新编译固件。

四、验证增加的 Cluster

        4.1 Coordinator 发送 Simple Descriptor Request

        通过 ubiqua 抓空中包，可以看到 Simple Descriptor Response 包含了定义的 Demo Cluster(0xFC00)。

           

        在 Sniffer Log 中可以看到，添加的自定义 Cluster 是 0xFC00，分别在 Application Input Clusters List 以及 Application Onput Clusters List 中。

        4.2 验证 Command 的发送和接收

        Coordinator 发送 Command 给 Switch，在 Coordinator 端调用定义好的发送函数 eCLD_DemoCommandClientSend，代码如下：

               

        通过 Sniffer，我们可以看到，Coordinator 发送的 Private Cluster 的包，以及 Switch 发送给 Coordinator 的 Default Response

               

        在 Private Cluster 包中的详细信息可以看到，Coordinator 发送的 Command 的值为 0，与上面定义的发送函数传递的参数一致。


                 

        4.3  Switch 发送带有 Payload 的 command 给 Coordinator

        Switch 发送 Command 给 Coordinator，在 Switch 端调用定义好的发送函数 eCLD_DemoCommandServerSend，另外 Payload 中 u8DemoId 和 u8DemoStatus 的值分别为 1 和 10。
  
                     

        通过 sniffer，我们可以看到，Switch 发送的 Private Cluster 的包，以及 Coordinator 发送给 Switch 的 Default Response。

                  

        在 Private Cluster 包中的详细信息可以看到，Switch 发送的 Command 的值为  2，Payload 包括是 01 和 0A，与上面发送函数传递的参数一致。

               

        至此，添加私有的 Cluster 已经可以实现 Client 和 Server 之间互相通信(发送和接收 Command)。

        另外关于恩智浦实现的 ZCL 库的代码，相当于是开源的，位于 SDK 目录下面。在目录中可以看到 ZCL 库实现的所有代码。

        实际上，不管是私有的，还是标准的 Cluster，NXP 都提供了相关的接口，例如：命令的发送实际上是由 yeZCL_CustomCommandSend 完成的，而命令的接收实际上是由 eZCL_CustomCommandReceive 完成的。

        注释：以上可以用 ON/OFF cluster 实例验证进行验证学习。

五、参考资料

       (1) JN-UG-3115-ZigBee Cluster Library (for ZigBee 3.0).pdf

       (2) ZigBee Cluster Library Specification Revision 6

       (3) JN-SW-4170