這篇文章將翻譯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列表。

圖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。這個重置命令能夠將數據返回到出廠默認值。

應用程序中的回調函數提供了特定于此的命令的附加處理應用程序。如果響應是正確的，這些回調函數將與對傳入命令的響應一起工作。

圖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

總結

以上是生活随笔為你收集整理的Z-Stack Home Developer's Guide—6. Clusters, Commands and Attributes中文翻译【Z-Stack Home 1.2.0的开发文档】的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。