Z-Stack Home Developer's Guide—6. Clusters, Commands and Attributes中文翻译【Z-Stack Home 1.2.0的开发文档】

落日映苍穹つ 2022-05-18 02:45 100阅读 0赞

这篇文章将翻译Z-Stack Home Developer’s Guide开发文档中的6. Clusters, Commands and Attributes部分，在Z-Stack中Cluster、Commands、Attribute是非常重要的概念。  
中文翻译如下:

# 6. 族,命令和属性 #

每一个应用程序都支持某些族。**我们可以认为（a cluster）一个族就是一个对象，包含方法（命令）和数据（属性）**。  
每一个族可以有0个或多个命令。命令可以进一步的分为服务端的命令和客户端的命令。命令可以执行动作或者生产一个响应。

每一个族可以有0个或者多个属性。所有的属性可以在zcl\_sampleapp\_data.c文件中找到，“sampleapp”可以被替换为给到的样例程序（比如 在 on/off light switch 样例程序中的zcl\_samplesw\_data.c）。属性描述这当前设备的状态，或者提供了关于设备的信息，比如 一个灯当前是开着还是关着。

所有的族和属性都被定义在 ZCL开发手册(ZigBee Cluster Library specification)，或者在HA手册中(ZigBee Home Automation Specification)。

## 6.1属性 ##

属性可以在 zcl\_sampleapp\_data.c文件中的zcl\_zclSampleApp\_Attrs\[ \]数组中找到。每一个属性实体都需要初始化类型和值，并且包含着一个指向属性数据的指针。属性数据的类型可以在zcl.h中找到。

属性一定要使用zcl\_registerAttrList ( )函数进行注册，在应用程序初始化的时候。  
每一个属性都有数据类型，已经被Zigbee定义了（比如 UINT8,INT32等等）。每一条属性记录包含属性类型和一个指向属性实际数据的指针。只读数据能够被终端节点共享。一个终端节点的属性数据是唯一的，应该用一个唯一的C变量。

所有的属性都可读。一些属性还可写。一些属性是可报告的（可以自动的发送到目的地在属性改变的时候或者设置定时）。一些属性还可以被保存作为场景的一部分，场景就是之后可以被唤醒重新设置设备的特有状态（比如电灯的开或关）。属性访问是通过属性结构体的一个字段进行控制的。

存储一个属性到 非易失性内存（重启之后仍然有效）参考 8.2章节。

## 6.2添加属性举例 ##

添加一个属性到这个工程，参考属性信息 ，在ZHA手册（the Home Automation  
Specification）。使用DoorLock族举例，下面将展示如何添加 “Max PIN Code Length”属性到 DoorLock项目。这个过程在所有的 Home Automation的项目中都是通用的。

所有被应用程序使用到的属性都在zcl\_sampleapplication\_data.c文件中定义。以DoorLock举例，zcl\_sampledoorlock\_data.c是数据文件。找到属性定义的位置，用下面的格式添加到文件中：

{
    ZCL_CLUSTER_ID_CLOSURES_DOOR_LOCK,
    { // Attribute record
    ATTRID_DOORLOCK_NUM_OF_MAX_PIN_LENGTH,
    ZCL_DATATYPE_UINT8,
    ACCESS_CONTROL_READ,
    (void *)&zclSampleDoorLock_NumOfMaxPINLength
    }
    },

第2行表示着 cluster ID，第4行表示 attribute ID，第5行是数据类型，第6行表示属性是可读还是可写，第7行是 在应用程序中使用的指针变量。

cluster ID可以在zcl.h中找到。attribute ID可以在zcl\_closures.h中找到，剩下的信息都是来自Home Automation 手册。

在这个属性列表中添加这个属性，设备可以通过这个属性影响其他的设备。属性列表中的数量一定不能超过在 zcl\_sampledoorlock.h文件中的SAMPLEDOORLOCK\_MAX\_ATTRIBUTES宏变量。在zcl\_sampledoorlock.h这个文件中用下面的格式定义一个external变量：  
extern uint8 zclSampleDoorLock\_NumOfMaxPinLength

最后，定义的这个变量会被应用程序在zcl\_sampledoorlock.c文件中使用。注意这个变量的默认值和有效范围 在手册中。

## 6.3初始化族 ##

应用程序和族相互影响着，族的编译标志能被激活(如果应用程序需要这个cluster)在项目的配置文件中并且，在IAR的工作空间中 族的源文件一定要添加到项目的描述文件夹中。举个简单的例子，在SampleDoorLockApp中，请看图片3。在f8wZCL.cfg有一个cluster compile flag列表。  
![这里写图片描述][70]  
图3 - List of Cluster Source Files in Profile Folder

## 6.4族的架构 ##

所有的族遵循相同的架构。  
族负责格式的转换，将本地格式转换为无线格式，根据zigbee。所有的应用程序同cluster交换都是通过本地格式。  
它们都有以下函数：

*  Send - 在一个族中允许发送的一系列命令。
 *  ProcessIn - 这个函数处理传入的命令。  
    每个命令通常都有一个发送函数。这个send 函数是用来设置一系列参数或者设置一个结构体。  
    如果应用程序注册了回调函数，这个ProcessIn函数将管理这个命令(在转换成本地格式后) 执行这个命令的应用程序的回调函数。

## 6.5族回调函数举例 ##

回调被使用，以便应用程序能够在给定的传入族命令中执行期望的行为。这取决于应用程序在适当的时候发送响应。Z-Stack提供了解析，但它取决于执行工作的应用程序。

族的回调函数在应用程序的初始化函数中注册，包括应用程序的端点和在注册命令回调函数中的一个回调记录的指针。图4展示一个general cluster的回调记录列表。这些命令在他们各种的回调函数中进行注册，这些回调函数定义在 族的描述文件中。

举个例子，BasicReset 命令一旦到达设备的应用层，这个族的回调记录列表有中指向BasicReset命令的回调函数：zclSampleDoorLockController\_BasicResetCB。这个重置命令能够将数据返回到出厂默认值。

应用程序中的回调函数提供了特定于此的命令的附加处理应用程序。如果响应是正确的，这些回调函数将与对传入命令的响应一起工作。  
![这里写图片描述][70 1]  
图4 - Cluster Callbacks Example

# 英文原文 #

# 6. Clusters, Commands and Attributes #

Each application supports a certain number of clusters. Think of a cluster as an object containing both methods  
(commands) and data (attributes).  
Each cluster may have zero or more commands. Commands are further divided into Server and Client-side  
commands. Commands cause action, or generates a response.  
Each cluster may have zero or more attributes. All of the attributes can be found in the zcl\_sampleapp\_data.c file,  
where “sampleapp” is replaced with the given sample application (e.g. samplesw\_data.c for the sample on/off light  
Z-Stack Home Developer’s Guide SWRA441 Version 1.0  
17 Copyright © 2013 Texas Instruments, Inc. All rights reserved.  
switch). Attributes describe the current state of the device, or provide information about the device, such as whether  
a light is currently on or off.  
All clusters and attributes are defined either in the ZigBee Cluster Library specification, or the ZigBee Home  
Automation Specification.

## 6.1 Attributes ##

Attributes are found in a single list called zclSampleApp\_Attrs\[ \], in the zcl\_sampleapp\_data.c file. Each  
attribute entry is initialized to a type and value, and contains a pointer to the attribute data. Attribute data types can  
be found in the ZigBee Cluster Library.  
The attributes must be registered using the zcl\_registerAttrList ( ) function during application  
initialization, one per application endpoint.  
Each attribute has a data type, as defined by ZigBee (such as UINT8, INT32, etc…). Each attribute record contains  
an attribute type and a pointer to the actual data for the attribute. Read-only data can be shared across endpoints.  
Data that is unique to an endpoint (such as the OnOff attribute state of the light) should have a unique C variable.  
All attributes can be read. Some attributes can be written. Some attributes are reportable (can be automatically sent  
to a destination based on time or change in attribute). Some attributes are saved as part of a “scene” that can later be  
recalled to set the device to a particular state (such as a light on or off). The attribute access is controlled through a  
field in the attribute structure.  
To store an attribute in non-volatile memory (to be preserved across reboots) refer to section 8.2.

## 6.2 Adding an Attribute Example ##

To add an additional attribute to a project, refer to the attribute’s information within the Home Automation  
Specification \[1\]. Using the DoorLock cluster as an example, the following will show how to add the “Max PIN  
Code Length” attribute to the DoorLock project. This process can be replicated across all Home Automation  
projects.  
All attributes in use by an application are defined within the project source file’s zcl\_sampleapplication\_data.c file.  
For this DoorLock example, this data file is: zcl\_sampledoorlock\_data.c. Locate the section defined as Attribute  
Definitions and include the “Max PIN Code Length” attribute using the format:  
1 \{  
2 ZCL\_CLUSTER\_ID\_CLOSURES\_DOOR\_LOCK,  
3 \{ // Attribute record  
4 ATTRID\_DOORLOCK\_NUM\_OF\_MAX\_PIN\_LENGTH,  
5 ZCL\_DATATYPE\_UINT8,  
6 ACCESS\_CONTROL\_READ,  
7 (void \*)&zclSampleDoorLock\_NumOfMaxPINLength  
8 \}  
9 \},  
Figure 2 - Example of Number of Max PIN Length Attribute Record  
Line 2 represents the cluster ID, line 4 represents the attribute ID, line 5 the data type, line 6 the read/write attribute,  
and line 7 the pointer to the variable used within the application.  
The cluster ID can be retrieved from the zcl.h file, the attribute ID can be found within the (in this case)  
zcl\_closures.h file, and the remaining information from the Home Automation Specification \[1\].  
Z-Stack Home Developer’s Guide SWRA441 Version 1.0  
18 Copyright © 2013 Texas Instruments, Inc. All rights reserved.  
By including the attribute within this list, devices are able to interact with the attributes on other devices. This  
addition in the attribute list must be reflected in the SAMPLEDOORLOCK\_MAX\_ATTRIBUTES macro in the  
zcl\_sampledoorlock.h file. Also within that file, define the external variable using proper coding conventions:  
extern uint8 zclSampleDoorLock\_NumOfMaxPinLength  
Finally, define the variable within zcl\_sampledoorlock.c to be used by the application. Note the default value and  
valid range of the variable in the specification.

## 6.3 Initializing Clusters ##

For the application to interact with a cluster, the cluster’s compile flag must be enabled (if applicable to the cluster)  
in the project’s configuration and the cluster’s source file must be added to the project’s Profile folder within the  
IAR Workspace. An example of this can be seen in Figure 3 for the SampleDoorLock app. See f8wZCL.cfg for a list  
of cluster compile flags.  
Once enabled, the cluster’s callbacks can be registered within the application (refer to section 6.5).  
Figure 3 - List of Cluster Source Files in Profile Folder

## 6.4 Cluster Architecture ##

All clusters follow the same architecture.  
The clusters take care of converting the structures passed from native format to over-the-air format, as required by  
ZigBee. All application interaction with clusters takes place in native format.  
They all have the following functions:  
 Send – This group of commands allows various commands to be send on a cluster  
 ProcessIn – This function processes incoming commands.  
Z-Stack Home Developer’s Guide SWRA441 Version 1.0  
19 Copyright © 2013 Texas Instruments, Inc. All rights reserved.  
There is usually one send function for each command. The send function has either a set of parameters or a specific  
structure for the command.  
If the application has registered callback functions, then the ProcessIn will direct the command (after it’s converted  
to native form) to the application callback for that command.

## 6.5 Cluster Callbacks Example ##

Callbacks are used so that the application can perform the expected behavior on a given incoming cluster command.  
It is up to the application to send a response as appropriate. Z-Stack provides the parsing, but it is up to the  
application to perform the work.  
A cluster’s callback functions are registered within the application’s initialization function by including the  
application’s endpoint and a pointer to the callback record within a register commands callback function. Figure 4  
shows an example of the general cluster’s callback record list. The commands are registered to their respective  
callback functions as defined within the cluster’s profile.  
As an example, once a BasicReset command reaches the application layer on a device, the cluster’s callback record  
list points the command to the BasicReset callback function:  
zclSampleDoorLockController\_BasicResetCB. The application reset command can then reset all data  
back to Factory New defaults.  
The callback function in an application provides additional processing of a command that is specific to that  
application. These callback functions work alongside the response to the incoming command, if a response is  
appropriate.  
Figure 4 - Cluster Callbacks Example

[70]: /images/20220518/4e5b2e9062cd46cdb40d1000640c0343.png
[70 1]: /images/20220518/72c57186750a4f9e89dbd87a1f2ac212.png