Cluster Reference¶
This section documents the standard cluster classes which may be instantiated. See add_cluster for help on instantiating new clusters.
The default cluster ID, cluster type (server or client) and APS encryption settings of each cluster are listed. Additionally, some ZCL clusters define attributes. When present, these are listed as follows:
| Name | ID | Type | R/W | Description |
|---|---|---|---|---|
| common name | 16-bit ID | 8-bit ZCL type ID | read/write | description of attribute |
Refer to the ZCL specification for additional information about these attributes.
Cluster¶
Does not support a specific protocol. The Cluster class is mainly used to support generic ZigBee pass-through behavior (see send_zigbee and received_zigbee*).
ID: Unspecified
Type: Unspecified
APS Encryption: Before 1.6.0: False. As of 1.6.0: None (defaults to endpoint’s encryption level).
ZCL_Cluster¶
Supports the ZCL protocol. The ZCL_Cluster class is mainly used to communicate with remote instances of clusters when a more specific cluster class does not exist. For example, if a remote server cluster with ID 0x1234 exists and supports ZCL, a ZCL_Cluster client with ID 0x1234 could be instantiated locally.
This class has handlers for the following standard ZCL commands:
- Read Attributes (0x00)
- Read Attributes Response (0x01)
- Write Attributes (0x02)
- Write Attributes Undivided (0x03)
- Write Attributes Response (0x04)
- Write Attributes, No Response (0x05)
- Configure Reporting (0x06)
- Configure Reporting Response (0x07)
- Read Reporting Configuration (0x08)
- Read Reporting Configuration Response (0x09)
- Report Attributes (0x0A)
- Default Response (0x0B)
- Discover Attributes (0x0C)
- Discover Attributes Response (0x0D)
ID: Unspecified
Type: Unspecified
APS Encryption: Before 1.6.0: False. As of 1.6.0: None (defaults to endpoint’s encryption level).
Attributes: None
ZCL_BasicCluster_server¶
This is a ZCL cluster class which contains basic information about the local device. Attribute values on this cluster will be saved to file to protect against power failure. These files will be automatically read when the local device restarts. Additionally, attribute values on this cluster are shared across all instances of the cluster on endpoints of the local device. In other words, if this cluster is instantiated on more than one endpoint, changes to attribute values on one cluster instance will affect all other instances as well.
ID: 0x0000
Type: Server
APS Encryption: False
Attributes:
| Name | ID | Type | R/W | Description |
|---|---|---|---|---|
| ZCL Version | 0x0000 | 0x20 | R | The ZCL version that the local device conforms to. |
| Application Version | 0x0001 | 0x20 | R | The version of the framework code used by the local device. The high four bits indicate the major revision and the low four bits indicate the minor revision. For example, 0x13 would indicate version 1.3 |
| Stack Version | 0x0002 | 0x20 | R | The low eight bits of the local XBee radio’s firmware version. For example, if the XBee is running 3326 firmware, this value will be 0x26. |
| Manufacturer Name | 0x0004 | 0x42 | R | The string description of the local device’s manufacturer, up to 32 characters. Defaults to: Digi International |
| Model Identifier | 0x0005 | 0x42 | R | The string description of the local device, up to 32 characters. Defaults to: ConnectPort X2 for Smart Energy |
| Power Source | 0x0007 | 0x30 | R | Enumeration of where the local device is getting power. This attribute is set to specify that the power source is unknown by default. |
| Local Description | 0x0010 | 0x42 | RW | A user-settable string describing the location of the local device, up to 16 characters. Defaults to an empty string. |
| Physical Environment | 0x0011 | 0x30 | RW | A user-settable, profile-specific enumeration describing the environment of the local device. |
ZCL_BasicCluster_client¶
This is a ZCL cluster class which is the corresponding client to the Basic cluster server. No additional functionality is provided.
ID: 0x0000
Type: Client
APS Encryption: False
Attributes: None
ZCL_IdentifyCluster_server¶
This is a ZCL cluster class which provides the interface for instructing the local device to identify itself. For example, when identifying themselves, Digi devices will blink an LED rapidly. Attribute values on this cluster are shared across all instances of the cluster on endpoints of the local device. In other words, if this cluster is instantiated on more than one endpoint, changes to attribute values on one cluster instance will affect all other instances as well.
The following cluster-specific command handlers are supported:
- Identify (0x00)
- Identify Query (0x01)
ID: 0x0003
Type: Server
APS Encryption: False
Attributes:
| Name | ID | Type | R/W | Description |
|---|---|---|---|---|
| Identify Time | 0x0000 | 0x21 | RW | The remaining number of seconds for which the local device will identify itself. Writing to this value is equivalent to sending an Identify command. |
ZCL_IdentifyCluster_client¶
This is a ZCL cluster class which is the corresponding client to the Identify cluster server.
The following cluster-specific command handlers are supported:
- Identify Query Response (0x00)
ID: 0x0003
Type: Client
APS Encryption: False
Attributes: None
ZCL_TimeCluster_server¶
This is a ZCL cluster class which presents the current time so that other devices on the network can synchronize to a common time value. Typically, if the local device has a Time server cluster, it will be using NTP to synchronize its time internally (see Time Synchronization). User-settable attribute values on this cluster will be saved to file to protect against power failure. These files will be automatically read when the local device restarts. Additionally, attribute values on this cluster are shared across all instances of the cluster on endpoints of the local device. In other words, if this cluster is instantiated on more than one endpoint, changes to attribute values on one cluster instance will affect all other instances as well.
ID: 0x000A
Type: Server
APS Encryption: True
Attributes:
| Name | ID | Type | R/W | Description |
|---|---|---|---|---|
| Time | 0x0000 | 0xE2 | R | The current time, in UTC 2000 (seconds since Jan 1, 2000). |
| Time Status | 0x0001 | 0x18 | R | Bitmap representing the the synchronization state of this time server. For example, 0x01 indicates that the time server is a master time source, and 0x02 indicates that it is synchronized but not a master. |
| Time Zone | 0x0002 | 0x2B | RW | User-settable, signed offset from UTC (in seconds) representing the local time zone. As of 1.5.0: Will be determined from time zone region in Python if operating system supports it (note: NDS does not support time zone regions). |
| Daylight Savings Start | 0x0003 | 0x23 | RW | User-settable UTC of when daylight savings time starts for the current year. As of 1.5.0: Will be determined from time zone region in Python if operating system supports it (note: NDS does not support time zone regions). |
| Daylight Savings End | 0x0004 | 0x23 | RW | User-settable UTC of when daylight savings time ends for the current year. As of 1.5.0: Will be determined from time zone region in Python if operating system supports it (note: NDS does not support time zone regions). |
| Daylight Savings Shift | 0x0005 | 0x2B | RW | User-settable, signet offset from standard time (in seconds) while daylight savings is in effect. As of 1.5.0: Will be determined from time zone region in Python if operating system supports it (note: NDS does not support time zone regions). |
| Standard Time | 0x0006 | 0x23 | R | The standard time of the local device (seconds since Jan 1, 2000), after adjusting for the time zone. As of 1.4.0: Attribute will only be present if Time Zone is set to a valid value. |
| Local Time | 0x0007 | 0x23 | R | The local time of the local device (seconds since Jan 1, 2000), after adjusting for the time zone and daylight savings. As of 1.4.0: Attribute will only be present if Time Zone, Daylight Savings Start, Daylight Savings End, and Daylight Savings Shift are set to a valid value. |
ZCL_TimeCluster_client¶
This is a ZCL cluster class which is used to synchronize time with a ZCL Time server cluster elsewhere on the local network. As such, if the local device has a Time client cluster it will typically be using ZCL to synchronize its time (see Time Synchronization). This means that the Time client will automatically query any Time servers it discovers, and will periodically re-query any known servers, in order to keep time on the local device synchronized. Specifically, a query involves reading the Time and Time Status attributes and checking if the status indicates that the server has a valid time. If so, the Time value is used to set the time on the local device.
ID: 0x000A
Type: Client
APS Encryption: True
Attributes: None
SE_KeyEstablishmentCluster_server¶
The following cluster-specific command handlers are supported:
- Initiate Key Establishment Request (0x00)
- Ephemeral Data Request (0x01)
- Confirm Key Data Request (0x02)
- Terminate Key Establishment (0x03)
ID: 0x0800
Type: Server
APS Encryption: False
Attributes:
| Name | ID | Type | R/W | Description |
|---|---|---|---|---|
| KeyEstablishmentSuite | 0x0000 | 0x31 | R | Speficies supported cryptographic schemes for key establishment on the device. |
SE_KeyEstablishmentCluster_client¶
The following cluster-specific command handlers are supported:
- Initiate Key Establishment Response (0x00)
- Ephemeral Data Response (0x01)
- Confirm Key Data Response (0x02)
- Terminate Key Establishment (0x03)
ID: 0x0800
Type: Client
APS Encryption: False
Attributes:
| Name | ID | Type | R/W | Description |
|---|---|---|---|---|
| KeyEstablishmentSuite | 0x0000 | 0x31 | R | Speficies supported cryptographic schemes for key establishment on the device. |
SE_PriceCluster_server¶
This is a ZCL cluster class which hosts SE Price events. Any events which have not yet expired will be stored to file to protect against power failure. These files will automatically be read when the local device restarts. Additionally, attribute values on this cluster will be saved to file to protect against power failure. These files will also be automatically read when the local device restarts.
The following cluster-specific command handlers are supported:
- Get Current Price (0x00)
- Get Scheduled Prices (0x01)
- Price Acknowledgment (0x02)
ID: 0x0700
Type: Server
APS Encryption: True
Attributes:
| Name | ID | Type | R/W | Description |
|---|---|---|---|---|
| Tier Label 1 | 0x0000 | 0x41 | RW | The label for price tier 1 as a string, up to 12 characters. |
| Tier Label 2 | 0x0001 | 0x41 | RW | The label for price tier 2 as a string, up to 12 characters. |
| Tier Label 3 | 0x0002 | 0x41 | RW | The label for price tier 3 as a string, up to 12 characters. |
| Tier Label 4 | 0x0003 | 0x41 | RW | The label for price tier 4 as a string, up to 12 characters. |
| Tier Label 5 | 0x0004 | 0x41 | RW | The label for price tier 5 as a string, up to 12 characters. |
| Tier Label 6 | 0x0005 | 0x41 | RW | The label for price tier 6 as a string, up to 12 characters. |
SE_PriceCluster_client¶
This is a ZCL cluster class which is the corresponding client to the Price cluster server. This class receives SE Price events, keeps track of their start and end times and generates RPC response messages as appropriate.
The following cluster-specific command handlers are supported:
- Publish Price (0x00)
ID: 0x0700
Type: Client
APS Encryption: True
Attributes: None
SE_DemandResponseLoadControlCluster_server¶
This is a ZCL cluster class which hosts SE DRLC events. Any events which have not yet expired will be stored to file to protect against power failure. These files will automatically be read when the local device restarts.
The following cluster-specific command handlers are supported:
- Report Event Status (0x00)
- Get Scheduled Events (0x01)
ID: 0x0701
Type: Server
APS Encryption: True
Attributes: None
SE_DemandResponseLoadControlCluster_client¶
This is a ZCL cluster class which is the corresponding client to the DRLC cluster server. This class receives SE DRLC events, keeps track of their start and end times and generates RPC response messages as appropriate.
The following cluster-specific command handlers are supported:
- Load Control Event (0x00)
- Cancel Load Control Event (0x01)
- Cancel All Load Control Events (0x02)
Note
This class is not currently intended to be part of a functioning DRLC implementation, and is only meant to provide notification of DRLC events on the network. Report Event Status commands will not be generated by this class even if the device class attribute is changed to a value other than its default of 0x0000.
ID: 0x0701
Type: Client
APS Encryption: True
Attributes:
| Name | ID | Type | R/W | Description |
|---|---|---|---|---|
| Utility Enrollment Group | 0x0000 | 0x20 | RW | The current utility enrollment group of this client, or 0x00 for no group. |
| Start Randomize Minutes | 0x0001 | 0x20 | RW | The client will wait a random number of minutes (up to this many) before taking action after a DRLC event starts. The client currently does not take action on DRLC events so this attribute has no effect. |
| Stop Randomize Minutes | 0x0002 | 0x20 | RW | The client will wait a random number of minutes (up to this many) before taking action after a DRLC event ends. The client currently does not take action on DRLC events so this attribute has no effect. |
| Device Class | 0x0003 | 0x21 | R | Bitmap representing DRLC device classes that this client corresponds to. Defaults to 0x0000, or no device classes. |
SE_MessageCluster_server¶
This is a ZCL cluster class which hosts SE Message events. Any events which have not yet expired will be stored to file to protect against power failure. These files will automatically be read when the local device restarts.
The following cluster-specific command handlers are supported:
- Get Last Message (0x00)
- Message Confirmation (0x01)
ID: 0x0703
Type: Server
APS Encryption: True
Attributes: None
SE_MessageCluster_client¶
This is a ZCL cluster class which is the corresponding client to the Messaging cluster server. This class receives SE Message events, keeps track of their start and end times and generates RPC response messages as appropriate.
The following cluster-specific command handlers are supported:
- Display Message (0x00)
- Cancel Message (0x01)
ID: 0x0703
Type: Client
APS Encryption: True
Attributes: None
SE_SimpleMeteringCluster_client¶
This is a ZCL cluster class which is the corresponding client to the Metering cluster server.
The following cluster-specific command handlers are supported:
- Get Profile Response (0x00)
- Request Fast Poll Mode Response(0x03)
ID: 0x0702
Type: Client
APS Encryption: True
Attributes: None
OTA_Cluster_Server¶
This is the ZCL cluster class which implements the ZigBee OTA Cluster and provides firmware images to client devices on the network.
The following cluster-specific command handlers are supported:
- Query Next Image Request (0x01)
- Image Block Request (0x03)
- Image Page Request (0x04)
- Upgrade End Request (0x06)
- Query Specific File Request (0x08)
ID: 0x0019
Type: Server
APS Encryption: True
Attributes: None