ZCL Interface¶
The following are the RPC requests and responses added by the RPC_ZCL_Interface class. These methods perform common actions related to communications using the ZigBee Cluster Library (ZCL) protocol.
ZCL is built around communication between server (input) and client (output) clusters which share the same cluster ID. Generally, when sending a message to a server cluster, the message must be sent from a client cluster, and similarly when sending to a client the message must be sent from a server. Attempting to send to a server cluster when the corresponding client does not exist, or vice versa, will generate an error. It may be necessary to instantiate ZCL clusters on the gateway in order to talk with corresponding clusters on other devices (see add_cluster).
The above restriction does not apply when the gateway sends a message to itself and the source and destination endpoints of the message are the same. In this case, if an instance of the opposite cluster type is not present, the cluster will simply send the ZCL message to itself. However, if an instance of the opposite cluster type is present, communication will function as normal.
It is worth noting that some device manufacturers are not careful with correctly setting the direction bit in ZCL messages, which controls whether the message is for a server or client cluster. By default, the gateway will attempt to automatically correct direction bit errors in received messages; see “ZCL_Endpoint.enable_direction_bit_correction” in Registry Settings.
Note
Addressing for most ZCL commands was updated in version 1.4.0 to allow automatic lookup of many parameters based on prior discovery information. In many cases, this allows you to remove much of the required addressing information. This information may still be provided if disambiguation is necessary.
Example
Before 1.5.0:
<read_attributes> <destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address> <destination_endpoint_id>0x10</destination_endpoint_id> <source_endpoint_id>0x5E</source_endpoint_id> <cluster_id>0x0000</cluster_id> <server_or_client>0</server_or_client> <record_list type="list"> <item type="ReadAttributeRecord"> <attribute_id>0</attribute_id> </item> </record_list> </read_attributes>As of 1.5.0:
<read_attributes> <destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address> <cluster_id>0x0000</cluster_id> </read_attributes>
read_attributes¶
Reads the values of ZCL attributes from the given cluster.
Note
Additional functionality for reading all attributes added in version 1.5.0.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| cluster_id | int | 16-bit identifier of the cluster over which the ZCL command will be sent. |
| record_list* | list | List of ReadAttributeRecord which will make up the payload of the ZCL command. As of 1.5.0: If not provided, all discoverable attributes on the cluster will be read. |
| destination_address* | MAC | 64-bit extended address of the device to which the ZCL command will be sent. If not provided, the command will be sent to the local device. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the target device containing the target cluster. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device from which the ZCL command will be sent. Before 1.4.0: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| profile_id* | int | As of 1.4.0:16-bit profile identifier of the target endpoint. If provided, this can help disambiguate endpoints during automatic lookup. |
| server_or_client* | int | Whether the target cluster is a server (0) or client (1) cluster. As of 1.4.0: If not provided, the correct value is guessed based on the gateway’s discovery information. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes to be read. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source_address | MAC | 64-bit extended address of the device which sent the response. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the device which sent the response. |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device which received the response. |
| profile_id | int | 16-bit identifier of the profile of the response. |
| cluster_id | int | 16-bit identifier of the cluster that received the response. |
| server_or_client | int | Whether the cluster that sent the response is a server (0) or client (1) cluster. |
| record_list | list | List of ReadAttributeStatusRecord derived from the payload of the ZCL response. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes that were read. |
Example
Read the Manufacturer Name and Model Identifier attributes from the ZCL Basic cluster on device 11:22:33:44:55:66:77:88, endpoint 0x10.
<read_attributes>
<destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<cluster_id>0x0000</cluster_id>
<server_or_client>0</server_or_client>
<record_list type="list">
<item type="ReadAttributeRecord">
<attribute_id>4</attribute_id>
</item>
<item type="ReadAttributeRecord">
<attribute_id>5</attribute_id>
</item>
</record_list>
</read_attributes>
<read_attributes_response>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<destination_endpoint_id type="int">0x5E</destination_endpoint_id>
<profile_id>0x109</profile_id>
<cluster_id type="int">0x0</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<record_list type="list">
<item type="ReadAttributeStatusRecord">
<attribute_id type="int">0x4</attribute_id>
<status type="int">0x0</status>
<attribute_type type="int">0x42</attribute_type>
<value type="string">Digi International</value>
</item>
<item type="ReadAttributeStatusRecord">
<attribute_id type="int">0x5</attribute_id>
<status type="int">0x0</status>
<attribute_type type="int">0x42</attribute_type>
<value type="string">ConnectPort X2 for Smart Energy</value>
</item>
</record_list>
</read_attributes_response>
write_attributes¶
Writes to ZCL attributes on the given cluster. A write may optionally be an undivided write, in which case the writes will only be performed if they will all succeed. Otherwise, writes are performed independently.
Note
Some ZCL attributes are read-only. However, read-only attributes on the local device may still be written with this RPC command.
As of 1.5.0: Local writes no longer require the “attribute_type” parameter in the WriteAttributeRecord.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| cluster_id | int | 16-bit identifier of the cluster over which the ZCL command will be sent. |
| record_list | list | List of WriteAttributeRecord which will make up the payload of the ZCL command. |
| destination_address* | MAC | 64-bit extended address of the device to which the ZCL command will be sent. If not provided, the command will be sent to the local device. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the target device containing the target cluster. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device from which the ZCL command will be sent. Before 1.4.0: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| profile_id* | int | As of 1.4.0: 16-bit profile identifier of the target endpoint. If provided, this can help disambiguate endpoints during automatic lookup. |
| server_or_client* | int | Whether the target cluster is a server (0) or client (1) cluster. As of 1.4.0: If not provided, the correct value is guessed based on the gateway’s discovery information. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes to be written. |
| command_identifier* | int | If provided, the write command will use this ZCL command identifier. Use 0x03 for an undivided write. Defaults to 0x02 (normal write). |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source_address | MAC | 64-bit extended address of the device which sent the response. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the device which sent the response. |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device which received the response. |
| profile_id | int | 16-bit identifier of the profile of the response. |
| cluster_id | int | 16-bit identifier of the cluster that received the response. |
| server_or_client | int | Whether the cluster that sent the response is a server (0) or client (1) cluster. |
| record_list | list | List of WriteAttributeResponseRecord derived from the payload of the ZCL response. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes that were written. |
Example
Write to the Physical Environment attribute and invalid attribute 0xFF on the ZCL Basic cluster on device 11:22:33:44:55:66:77:88, endpoint 0x10.
<write_attributes>
<destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<cluster_id>0x0000</cluster_id>
<server_or_client>0</server_or_client>
<record_list type="list">
<item type="WriteAttributeRecord">
<attribute_id>0xA</attribute_id>
<attribute_type>0x42</attribute_type>
<value type="string">On a boat</value>
</item>
<item type="WriteAttributeRecord">
<attribute_id>0xFF</attribute_id>
<attribute_type>0x30</attribute_type>
<value>3</value>
</item>
</record_list>
</write_attributes>
<write_attributes_response>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<destination_endpoint_id type="int">0x5E</destination_endpoint_id>
<profile_id>0x109</profile_id>
<cluster_id type="int">0x0</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<record_list type="list">
<item type="WriteAttributeResponseRecord">
<attribute_id type="int">0xA</attribute_id>
<status type="int">0x0</status>
<attribute_type type="int">0x42</attribute_type>
<value type="string">On a boat</value>
</item>
<item type="WriteAttributeResponseRecord">
<attribute_id type="int">0xFF</attribute_id>
<status type="int">0x86</status>
<attribute_type type="int">0x30</attribute_type>
<value type="int">0x3</value>
</item>
</record_list>
</write_attributes_response>
discover_attributes¶
Discovers all ZCL attributes on the given cluster. Should there be more attributes than can be discovered with a single ZCL discover attributes command, additional commands will be sent automatically and the net result returned in the RPC response.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| cluster_id | int | 16-bit identifier of the cluster over which the ZCL command will be sent. |
| destination_address* | MAC | 64-bit extended address of the device to which the ZCL command will be sent. If not provided, the command will be sent to the local device. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the target device containing the target cluster. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device from which the ZCL command will be sent. Before 1.4.0: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| profile_id* | int | As of 1.4.0: 16-bit profile identifier of the target endpoint. If provided, this can help disambiguate endpoints during automatic lookup. |
| server_or_client* | int | Whether the target cluster is a server (0) or client (1) cluster. As of 1.4.0: If not provided, the correct value is guessed based on the gateway’s discovery information. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes to be discovered. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source_address | MAC | 64-bit extended address of the device which sent the response. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the device which sent the response. |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device which received the response. |
| profile_id | int | 16-bit identifier of the profile of the response. |
| cluster_id | int | 16-bit identifier of the cluster that received the response. |
| server_or_client | int | Whether the cluster that sent the response is a server (0) or client (1) cluster. |
| record_list | list | List of AttributeInformationRecord derived from the payload of the ZCL response. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes that were discovered. |
Example
Discover which attributes are on the ZCL Basic cluster on device 11:22:33:44:55:66:77:88, endpoint 0x10.
<discover_attributes>
<destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<cluster_id>0x0000</cluster_id>
<server_or_client>0</server_or_client>
</discover_attributes>
<discover_attributes_response>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<destination_endpoint_id type="int">0x5E</destination_endpoint_id>
<profile_id>0x109</profile_id>
<cluster_id type="int">0x0</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<record_list type="list">
<item type="AttributeInformationRecord">
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x20</attribute_type>
</item>
<item type="AttributeInformationRecord">
<attribute_id type="int">0x1</attribute_id>
<attribute_type type="int">0x20</attribute_type>
</item>
<item type="AttributeInformationRecord">
<attribute_id type="int">0x2</attribute_id>
<attribute_type type="int">0x20</attribute_type>
</item>
<item type="AttributeInformationRecord">
<attribute_id type="int">0x4</attribute_id>
<attribute_type type="int">0x42</attribute_type>
</item>
<item type="AttributeInformationRecord">
<attribute_id type="int">0x5</attribute_id>
<attribute_type type="int">0x42</attribute_type>
</item>
<item type="AttributeInformationRecord">
<attribute_id type="int">0x7</attribute_id>
<attribute_type type="int">0x30</attribute_type>
</item>
<item type="AttributeInformationRecord">
<attribute_id type="int">0x10</attribute_id>
<attribute_type type="int">0x42</attribute_type>
</item>
<item type="AttributeInformationRecord">
<attribute_id type="int">0x11</attribute_id>
<attribute_type type="int">0x30</attribute_type>
</item>
</record_list>
</discover_attributes_response>
start_reports¶
Creates a reporting group for gathering ZCL attribute reports for a set of specified attributes. Unlike most ZCL commands, this request can address multiple target clusters across multiple devices because its addressing information is contained in each record. See Reporting for additional details on reporting, and StartReportRecord for additional details on configuration parameters.
Note
- Reporting configurations are stored in flash and stay active until one of the following:
- All reporting configurations for the group are removed.
- stop_reports command can remove all or some of the reporting configurations in a group.
- Reporting configurations can also be removed by setting the max_interval in the AttributeReportingConfigurationRecord to 0xFFFF. This is a special value in ZigBee that means to stop reporting.
The gateway leaves the network (there are various ways this can happen. See: leave_network, configure_zigbee_network, and xbee_AT.
remove_endpoint and remove_cluster commands do NOT remove reporting configurations.
Note
Added in version 1.6.0 to replace start_receiving_reports.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| record_list | list | List of StartReportRecord which specify the configurations to add to the group. |
| group_id* | string or int | Identifier of the group to be created or modified. If not specified, a new group will be created using the next default group ID. |
| collection_schedule* | cron | Cron string specifying when collections of attribute reports should be pushed to Device Cloud. |
| collection_schedule_jitter* | int | If a collection schedule string is provided, this is the maximum number of seconds to randomly adjust the scheduled push time by. If not specified, a default jitter will be assumed (see Registry Settings, ReportCollection.default_jitter). |
| storage_priority* | int | If provided, the relative priority that this group’s reports should have when storing data in RAM and flash; defaults to 0. See Buffer Manager for more information. |
| force_configuration* | bool | If there is an error during creation of a reporting group, its creation is aborted by default (force_configuration=False). Setting this parameter to true causes the reporting group to be created even if some devices are not reachable. Communication will be retried every 5 minutes until success. This is useful for creating a reporting configuration before the network exists. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| record_list | list | List of StartReportStatusRecord which give the status of the configurations added to the group. |
| group_id | string or int | Identifier of the group that was created or modified. |
| storage_priority | int | The relative priority that the group’s reports will have when storing data in RAM and flash. |
| collection_schedule* | cron | Included if the group specifies a collection schedule. |
| collection_schedule_jitter* | int | Included if the group specified a collection jitter. |
Example Creating a group to gather some reports for the same cluster on two devices every 15 seconds, and push the collected results every five minutes.
<start_reports>
<collection_schedule type="cron">0 */5 * * * *</collection_schedule>
<record_list type="list">
<item type="StartReportRecord">
<schedule type="cron">*/15 * * * * *</schedule>
<destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<cluster_id>0x0702</cluster_id>
<server_or_client>0</server_or_client>
<attribute_id>0x0000</attribute_id>
</item>
<item type="StartReportRecord">
<schedule type="cron">*/15 * * * * *</schedule>
<destination_address type="MAC">11:22:33:44:55:66:77:99</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<cluster_id>0x0702</cluster_id>
<server_or_client>0</server_or_client>
<attribute_id>0x0000</attribute_id>
</item>
</record_list>
</start_reports>
<start_reports_response>
<group_id type="string">default_group_name_1</group_id>
<collection_schedule type="cron">0 */5 * * * *</collection_schedule>
<record_list type="list">
<item type="StartReportStatusRecord">
<status type="int">0x0</status>
<schedule type="cron">*/15 * * * * *</schedule>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x25</attribute_type>
</item>
<item type="StartReportStatusRecord">
<status type="int">0x0</status>
<schedule type="cron">*/15 * * * * *</schedule>
<source_address type="MAC">11:22:33:44:55:66:77:99</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x25</attribute_type>
</item>
</record_list>
</start_reports_response>
stop_reports¶
Stops a reporting group or subset of a group. See Reporting for additional details on reporting, and StopReportRecord for additional details on configuration parameters.
| Parameter | Type | Description |
|---|---|---|
| group_id* | string or int | Identifier of the group to be stopped. If specified and record_list is not provided, all configurations in the group will be stopped. If not specified, all elements in record_list must correspond to configurations in the same group. |
| record_list* | list | List of StopReportRecord which specify the configurations to remove from the group. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| group_id | string or int | Identifier of the group that was modified. |
| record_list | list | List of StopReportStatusRecord which give the status of stopping the given configurations of the group. |
Example
<stop_reports>
<group_id type="string">default_group_name_1</group_id>
</stop_reports>
<stop_reports_response>
<group_id type="string">default_group_name_1</group_id>
<record_list type="list">
<item type="StopReportStatusRecord">
<status type="int">0x0</status>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x25</attribute_type>
</item>
<item type="StopReportStatusRecord">
<status type="int">0x0</status>
<source_address type="MAC">11:22:33:44:55:66:77:99</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x25</attribute_type>
</item>
</record_list>
</stop_reports_response>
received_attribute_report_collection*¶
Response only. Generated when a reporting group created by start_reports pushes its collected reports. This response contains one or more reports, each report with a value for all attributes in the group at the time the report was generated. Any attribute that could not be successfully retrieved when the report was generated will instead be given the most recent known value or indicated as unread if there is no recent known value. See start_reports and Reporting for additional details.
Note
Added in version 1.6.0 as the equivalent of received_attribute_report* for reporting groups.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| group_id | string or int | Identifier of the group which generated these reports. |
| header | list | List of ReportHeaderRecord which give the information about the attributes being reported. |
| data | list | List of reports, each report a list of ReportDataRecord with attribute data points. The ordering of elements in each report list exactly corresponds to the ordering of attribute information in the header. |
Example
<received_attribute_report_collection>
<group_id type="string">default_group_name_1</group_id>
<header type="list">
<item type="ReportHeaderRecord">
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x25</attribute_type>
</item>
<item type="ReportHeaderRecord">
<source_address type="MAC">11:22:33:44:55:66:77:99</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x25</attribute_type>
</item>
</header>
<data type="list">
<item type="list">
<item type="ReportDataRecord">
<timestamp type="int">0x4F000000</timestamp>
<value type="int">0x12345678</value>
</item>
<item type="ReportDataRecord">
<timestamp type="int">0x4F000000</timestamp>
<value type="int">0x87654321</value>
</item>
</item>
<item type="list">
<item type="ReportDataRecord">
<timestamp type="int">0x4F00000F</timestamp>
<value type="int">0x12345679</value>
</item>
<item type="ReportDataRecord">
<timestamp type="int">0x4F00000F</timestamp>
<value type="int">0x87654322</value>
</item>
</item>
<item type="list">
<item type="ReportDataRecord">
<timestamp type="int">0x4F00001E</timestamp>
<value type="int">0x1234567A</value>
</item>
<item type="ReportDataRecord">
<timestamp type="int">0x4F00001E</timestamp>
<value type="int">0x87654323</value>
</item>
</item>
<item type="list">
<item type="ReportDataRecord">
<timestamp type="int">0x4F00002D</timestamp>
<value type="int">0x1234567B</value>
</item>
<item type="ReportDataRecord">
<timestamp type="int">0x4F00002D</timestamp>
<value type="int">0x87654324</value>
</item>
</item>
</data>
</received_attribute_report_collection>
flush_reports¶
When attribute data is being collected by a reporting group, this will force that group to push all of its collected data. See Reporting for additional details on reporting.
Note
Added in version 1.6.0.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| group_id* | string or int | Identifier of the reporting group which should flush its reports. If not provided, all reporting groups will flush their reports. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| group_id_list | list | List of group IDs for the groups which flushed their reports. |
Example
<flush_reports>
<group_id type="string">default_group_name_1</group_id>
</flush_reports>
<flush_reports_response>
<group_id_list type="list">
<item type="string">default_group_name_1</item>
</group_id_list>
</flush_reports_response>
start_receiving_reports¶
Configures the given cluster to being sending ZCL attribute reports for the specified attributes to the local device.
Many devices do not natively support ZCL reporting. It is possible to use a simulated reporting mode called “pseudo reporting” which internally sends periodic ZCL attribute reads and generates RPC responses. This makes it appear as though the device has ZCL reporting configured.
Note
- Reporting configurations are stored in flash and stay active until one of the following:
- stop_receiving_reports command removes the reporting configuration.
- Reporting is configured with the max_interval in the AttributeReportingConfigurationRecord set to 0xFFFF. This is a special value in ZigBee that means to stop reporting.
- Prior to 1.6.0: remove_cluster command removes the local cluster for the reporting configuration.
- Prior to 1.6.0: remove_endpoint command removes the local endpoint hosting the cluster for the reporting configuration.
- The gateway leaves the network (there are various ways this can happen. See: leave_network, configure_zigbee_network, and xbee_AT.
Note
- As of 1.5.0:
- The parameter attribute_type is no longer required in the AttributeReportingConfigurationRecord when pseudo_reporting is set to True.
- The parameter “max_interval” in the WriteAttributeRecord can be larger than 0xFFFE when pseudo_reporting is set to True.
Note
As of 1.6.0: This command is deprecated but still available for compatibilty. It is recommended that you use start_reports instead.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| cluster_id | int | 16-bit identifier of the cluster over which the ZCL command will be sent. |
| record_list | list | List of AttributeReportingConfigurationRecord which will make up the payload of the ZCL command. |
| destination_address* | MAC | 64-bit extended address of the device to which the ZCL command will be sent. If not provided, the command will be sent to the local device. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the target device containing the target cluster. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device from which the ZCL command will be sent. Before 1.4.0: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| profile_id* | int | As of 1.4.0: 16-bit profile identifier of the target endpoint. If provided, this can help disambiguate endpoints during automatic lookup. |
| server_or_client* | int | Whether the target cluster is a server (0) or client (1) cluster. As of 1.4.0: If not provided, the correct value is guessed based on the gateway’s discovery information. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes to be configured for reporting. |
| pseudo_reporting* | bool | If TRUE, pseudo reporting will be used. If FALSE, normal ZCL reporting will be used. If not provided, normal ZCL reporting will be attempted, and if configuration fails pseudo reporting will be used instead. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source_address | MAC | 64-bit extended address of the device which sent the response. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the device which sent the response. |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device which received the response. |
| profile_id | int | 16-bit identifier of the profile of the response. |
| cluster_id | int | 16-bit identifier of the cluster that received the response. |
| server_or_client | int | Whether the cluster that sent the response is a server (0) or client (1) cluster. |
| record_list | list | List of AttributeReportingConfigurationResponseRecord derived from the payload of the ZCL response. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes that were configured for reporting. |
Example
Start receiving reports for the Current Summation Delivered attribute on the Metering server on device 11:22:33:44:55:66:77:88, endpoint 0x10.
<start_receiving_reports>
<destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<cluster_id>0x0702</cluster_id>
<server_or_client>0</server_or_client>
<record_list type="list">
<item type="AttributeReportingConfigurationRecord">
<attribute_id>0x0000</attribute_id>
<attribute_type>0x25</attribute_type>
<min_interval>5</min_interval>
<max_interval>60</max_interval>
<reportable_change>1</reportable_change>
<timeout>120</timeout>
</item>
</record_list>
</start_receiving_reports>
<start_receiving_reports_response>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<destination_endpoint_id type="int">0x5E</destination_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<record_list type="list">
<item type="AttributeReportingConfigurationResponseRecord">
<status type="int">0x0</status>
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x25</attribute_type>
<min_interval type="int">0x5</min_interval>
<max_interval type="int">0x3C</max_interval>
<reportable_change type="int">0x1</reportable_change>
<timeout type="int">0x78</timeout>
</item>
</record_list>
</start_receiving_reports_response>
stop_receiving_reports¶
Configures the given cluster to stop sending ZCL attribute reports for the specified attributes to the local device.
Note
As of 1.6.0: This command is deprecated but still available for compatibilty. It is recommended that you use stop_reports instead.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| cluster_id | int | 16-bit identifier of the cluster over which the ZCL command will be sent. |
| record_list | list | List of StopReportingRecord which will be used to generate the payload of the ZCL command. |
| destination_address* | MAC | 64-bit extended address of the device to which the ZCL command will be sent. If not provided, the command will be sent to the local device. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the target device containing the target cluster. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device from which the ZCL command will be sent. Before 1.4.0: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| profile_id* | int | As of 1.4.0: 16-bit profile identifier of the target endpoint. If provided, this can help disambiguate endpoints during automatic lookup. |
| server_or_client* | int | Whether the target cluster is a server (0) or client (1) cluster. As of 1.4.0: If not provided, the correct value is guessed based on the gateway’s discovery information. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes to be configured to stop reporting. |
| pseudo_reporting* | bool | If TRUE, the reporting behavior to be stopped is pseudo reporting. If FALSE, the reporting behavior to be stopped is normal ZCL reporting. If not provided and report receiving was previously configured, defaults to the existing reporting behavior. If not provided and report receiving was not previously configured, defaults to FALSE. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source_address | MAC | 64-bit extended address of the device which sent the response. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the device which sent the response. |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device which received the response. |
| profile_id | int | 16-bit identifier of the profile of the response. |
| cluster_id | int | 16-bit identifier of the cluster that received the response. |
| server_or_client | int | Whether the cluster that sent the response is a server (0) or client (1) cluster. |
| record_list | list | List of StopReportingStatusRecord derived from the payload of the ZCL response. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes that were configured to stop reporting. |
Example
Stop receiving reports for the Current Summation Delivered attribute on the Metering server on device 11:22:33:44:55:66:77:88, endpoint 0x10.
<stop_receiving_reports>
<destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<cluster_id>0x0702</cluster_id>
<server_or_client>0</server_or_client>
<record_list type="list">
<item type="StopReportingRecord">
<attribute_id>0x0000</attribute_id>
</item>
</record_list>
</stop_receiving_reports>
<stop_receiving_reports_response>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<destination_endpoint_id type="int">0x5E</destination_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<record_list type="list">
<item type="StopReportingStatusRecord">
<status type="int">0x0</status>
<attribute_id type="int">0x0</attribute_id>
</item>
</record_list>
</stop_receiving_reports_response>
received_attribute_report*¶
Response only. Generated when a ZCL Report Attributes command is received. These commands are automatically generated by a device which has been configured for ZCL attribute reporting. If instead reporting behavior is simulated using pseudo reporting, the local device will generate this RPC response as though ZCL Report Attribute commands were received.
Note
If multiple records are contained in a single ZCL Report Attributes command, one RPC response will be generated per record.
Note
As of 1.6.0: This command is deprecated but will still be generated for reporting configurations created using start_receiving_reports.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source_address | MAC | 64-bit extended address of the device which sent the response. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the device which sent the response. |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device which received the response. |
| profile_id | int | 16-bit identifier of the profile of the response. |
| cluster_id | int | 16-bit identifier of the cluster that received the response. |
| server_or_client | int | Whether the cluster that sent the response is a server (0) or client (1) cluster. |
| record | AttributeReportRecord | The record derived from the payload of the ZCL response. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attribute that was reported. |
Example
A received report for the Current Summation Delivered attribute from the Metering server on device 11:22:33:44:55:66:77:88, endpoint 0x10.
<received_attribute_report>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<destination_endpoint_id type="int">0x5E</destination_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<record type="AttributeReportRecord">
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x25</attribute_type>
<value type="int">0x12345678</value>
</record>
</received_attribute_report>
stop_sending_reports¶
Configures the local device to stop sending ZCL Report Attributes commands on the specified attributes to the given cluster. Also sets the reporting timeout on the given cluster to 0 for those attributes.
Note
It is currently not possible within ZCL to notify a device that reports will no longer being generated. Setting the reporting timeout to 0 is the closest approximation available.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| cluster_id | int | 16-bit identifier of the cluster over which the ZCL command will be sent. |
| record_list | list | List of StopReportingRecord which will be used to generate the payload of the ZCL command. |
| destination_address* | MAC | 64-bit extended address of the device to which the ZCL command will be sent. If not provided, the command will be sent to the local device. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the target device containing the target cluster. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device from which the ZCL command will be sent. Before 1.4.0: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| profile_id* | int | As of 1.4.0: 16-bit profile identifier of the target endpoint. If provided, this can help disambiguate endpoints during automatic lookup. |
| server_or_client* | int | Whether the target cluster is a server (0) or client (1) cluster. As of 1.4.0: If not provided, the correct value is guessed based on the gateway’s discovery information. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes to be configured to stop reporting. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source_address | MAC | 64-bit extended address of the device which sent the response. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the device which sent the response. |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device which received the response. |
| profile_id | int | 16-bit identifier of the profile of the response. |
| cluster_id | int | 16-bit identifier of the cluster that received the response. |
| server_or_client | int | Whether the cluster that sent the response is a server (0) or client (1) cluster. |
| record_list | list | List of StopReportingStatusRecord derived from the payload of the ZCL response. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes that were configured to stop reporting. |
Example
Stop sending reports on attribute 0x100 to server cluster 0x1234 on device 11:22:33:44:55:66:77:88, endpoint 0x10.
<stop_sending_reports>
<destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<cluster_id>0x1234</cluster_id>
<server_or_client>0</server_or_client>
<record_list type="list">
<item type="StopReportingRecord">
<attribute_id>0x0100</attribute_id>
</item>
</record_list>
</stop_sending_reports>
<stop_sending_reports_response>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<destination_endpoint_id type="int">0x5E</destination_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x1234</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<record_list type="list">
<item type="StopReportingStatusRecord">
<status type="int">0x0</status>
<attribute_id type="int">0x100</attribute_id>
</item>
</record_list>
</stop_sending_reports_response>
read_reporting_configuration¶
Retrieves the ZCL attribute reporting configurations for the specified attributes on the given cluster. To better understand the parameters, keep in mind that reporting always involves a transmitter and a receiver, one of which will always be the local device. Both devices will have reporting configurations which may be queried.
Note
A request parameter was deprecated in version 1.4.0: .
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| cluster_id | int | 16-bit identifier of the target cluster. |
| record_list | list | List of ReadReportingConfigurationRecord which will be used to generate the payload of the ZCL command. |
| reporting_direction | int | The direction of attribute reporting, from the perspective of the device being queried. Can be transmitting (0) or receiving (1). |
| destination_address | MAC | 64-bit extended address of the device with which reporting has been configured. |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the other device with which reporting has been configured. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device from which the ZCL command will be sent. Before 1.4.0: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| server_or_client | int | Whether the target cluster is a server (0) or client (1) cluster. As of 1.4.0: If not provided, the correct value is guessed based on the gateway’s discovery information. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes whose reporting configurations will be queried. |
| remote_configuration* | bool | If TRUE, the configuration of the other device involved with reporting will be queried. If FALSE, the configuration of the local device will be queried. Defaults to FALSE. As of 1.4.0: Depricated. Use get_local_reporting_configurations instead. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| reporting_direction | int | The direction of attribute reporting, from the perspective of the device that was queried. Can be transmitting (0) or receiving (1). |
| remote_configuration | bool | If TRUE, the configuration of the other device involved with reporting was queried. If FALSE, the configuration of the local device was queried. |
| source_address | MAC | 64-bit extended address of the device with which reporting has been configured. If remote_configuration is TRUE, the ZCL response was received from this device. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the other device with which reporting has been configured. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the local device that received the ZCL response. |
| cluster_id | int | 16-bit identifier of the target cluster. |
| server_or_client | int | Whether the target cluster was a server (0) or client (1) cluster. |
| record_list | list | List of ReadReportingConfigurationResponseRecord derived from the payload of of the ZCL command. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes whose reporting configurations were queried. |
Example
Read the report sending configuration from the Metering server on device 11:22:33:44:55:66:77:88, endpoint 0x10 for its Current Summation Delivered attribute.
<read_reporting_configuration>
<reporting_direction>0</reporting_direction>
<remote_configuration type="bool">TRUE</remote_configuration>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<cluster_id>0x0702</cluster_id>
<server_or_client>0</server_or_client>
<record_list type="list">
<item type="ReadReportingConfigurationRecord">
<attribute_id>0x0000</attribute_id>
</item>
</record_list>
</read_reporting_configuration>
<read_reporting_configuration_response>
<reporting_direction type="int">0</reporting_direction>
<remote_configuration type="bool">TRUE</remote_configuration>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<destination_endpoint_id type="int">0x5E</destination_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<record_list type="list">
<item type="ReadReportingConfigurationResponseRecord">
<status type="int">0x0</status>
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x25</attribute_type>
<min_interval type="int">0x5</min_interval>
<max_interval type="int">0x3C</max_interval>
<reportable_change type="int">1</reportable_change>
</item>
</record_list>
</read_reporting_configuration_response>
get_local_reporting_configurations¶
Returns all of the reporting configurations of the gateway. This includes configurations for gateway reporting to other devices and other devices reporting to the gateway. This command takes no parameters.
Request Parameters
None
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| record_list | list | List of LocalReportingConfigurationRecord describing all attribute reporting configurations on the local device. |
Example
Read the local reporting configurations from the local device. The local Metering client cluster has a configuration for receiving reports for the Current Summation Delivered attribute on the Metering server on device 11:22:33:44:55:66:77:88, endpoint 0x10.
<get_local_reporting_configurations/>
<get_local_reporting_configurations_response>
<record_list type="list">
<item type="LocalReportingConfigurationRecord">
<device_address type="MAC">11:22:33:44:55:66:77:88</device_address>
<device_endpoint_id type="int">0x10</device_endpoint_id>
<endpoint_id type="int">0x5E</endpoint_id>
<cluster_id type="int">0x702</cluster_id>
<server_or_client type="int">0x1</server_or_client>
<pseudo_reporting type="bool">FALSE</pseudo_reporting>
<reporting_direction type="int">0x1</reporting_direction>
<record type="AttributeReportingConfigurationRecord">
<attribute_id type="int">0x0</attribute_id>
<attribute_type type="int">0x25</attribute_type>
<min_interval type="int">0x5</min_interval>
<max_interval type="int">0x3C</max_interval>
<reportable_change type="int">0x1</reportable_change>
<timeout type="int">0x78</timeout>
</record>
</item>
</record_list>
</get_local_reporting_configurations_response>
identify¶
Instructs the given device to identify itself for some amount of time. How self-identification is implemented is up to the device manufacturer. For example, a Digi gateway will blink its association LED rapidly during self-identification.
This command requires the local device to have an Identify cluster client instantiated on an endpoint.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| identify_time | int | How long the device will identify itself for, in seconds. |
| destination_address* | MAC | 64-bit extended address of the device to which the ZCL command will be sent. If not provided, the command will be sent to the local device. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the target device containing the Identify server cluster (0x0003). As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device from which the ZCL command will be sent. Before 1.4.0: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source_address | MAC | 64-bit extended address of the device which sent the response. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the device which sent the response. |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device which received the response. |
| profile_id | int | 16-bit identifier of the profile of the response. |
| cluster_id | int | 16-bit identifier of the cluster that received the response. |
| server_or_client | int | Whether the cluster that sent the response is a server (0) or client (1) cluster. |
| status | int | The ZCL status code for the identify operation. |
| identify_time | int | How long the device will identify itself for, in seconds. |
Example
Instruct device 11:22:33:44:55:66:77:88 to identify itself for 30 seconds.
<identify>
<destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<identify_time>0x100</identify_time>
</identify>
<identify_response>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<destination_endpoint_id type="int">0x5E</destination_endpoint_id>
<profile_id type="int">0x109</profile_id>
<cluster_id type="int">0x3</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<status type="int">0x0</status>
<identify_time type="int">0x100</identify_time>
</identify_response>
send_ZCL¶
Sends a raw ZCL command with the given header information and payload to a given cluster on a device. Typically this is used for message pass-through behavior on clusters which support ZCL.
Note
Additional request parameter added in version 1.4.0.
Note
Default Response is a ZigBee Cluster Library (ZCL) General Command with ID=0x0B sent in response to a unicast command.
Default Response indicates error when the status code is non-zero. Commands may use Default Response rather than define a custom error response.
Default Response indicates success when the status code is zero. Commands may use Default Response rather than define a custom success response. In this case the Default Response provides assurance that the original command was both received and processed successfully.
Default Response can be disabled for the success case only. A Default Response will always be returned on error if there isn’t a custom error response defined.
The send_ZCL RPC function can be configured per the ZCL (see disable_default_response below) to disable Default Response.
When Default Response is disabled and no response command is defined (see response_command_type and response_command_identifier below) then send_ZCL will terminate immediately upon verifying the send was successful.
When Default response is not disabled then send_ZCL will wait until a response is received or a timeout occurs.
If the send_ZCL command frequently receives a timeout then check configuration of disable_default_response. The remote device may be failing to send an expected Default Response. In such cases setting disable_default_response to TRUE can be used to workaround the remote device failure and protect send_ZCL from timing out.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| cluster_id | int | 16-bit identifier of the cluster over which the ZCL command will be sent. |
| payload | base16, base64, record or list of records | Used to generate the ZCL payload of the ZCL command. |
| command_identifier | int | 8-bit ZCL command identifier of the command. |
| destination_address* | MAC | 64-bit extended address of the device to which the ZCL command will be sent. If not provided, the command will be sent to the local device. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the target device containing the target cluster As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device from which the ZCL command will be sent. Before 1.4.0: Required if destination_address is provided. Otherwise, if not provided, defaults to destination_endpoint_id. As of 1.4.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| server_or_client | int | Whether the target cluster is a server (0) or client (1) cluster. As of 1.4.0: If not provided, the correct value is guessed based on the gateway’s discovery information. |
| command_type* | int | Whether the command is a general (0) or cluster-specific (1) command. Defaults to cluster-specific. |
| response_command_identifier* | int | If provided, the 8-bit ZCL command identifier of the response message to the generated ZCL command. If not provided, any command identifier is allowed. Note that ZCL default responses are always allowed as response messages. |
| response_command_type* | int | Whether the response message will be a general (0) or cluster-specific (1) command. Defaults to cluster-specific. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL command. |
| enable_APS_encryption* | bool | If TRUE, the message will be sent using APS encryption. If FALSE, the message will not use APS encryption. If not provided, the default setting of the cluster will be used. |
| disable_default_response* | bool | As of 1.4.0: If TRUE, the message will have the disable default response bit set. If FALSE, the bit will not be set. If not provided, the value of the global registry setting ZCL_Cluster.disable_default_response will be used. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source_address | MAC | 64-bit extended address of the device which sent the response. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the device which sent the response. |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device which received the response. |
| profile_id | int | 16-bit identifier of the profile of the response. |
| cluster_id | int | 16-bit identifier of the cluster that received the response. |
| server_or_client | int | Whether the cluster that sent the response is a server (0) or client (1) cluster. |
| payload | base16 or base64 | The ZCL payload of the response. If the original request encoded the payload in base64, this will be of type base64. Otherwise, it will be of type base16. |
| command_identifier | int | 8-bit ZCL command identifier of the response. |
| command_type | int | Whether the response is a general (0) or cluster-specific (1) command. |
| manufacturer_code* | int | If provided, the 16-bit manufacturer code of the ZCL attributes that were read. |
| enable_APS_encryption | bool | If TRUE, the message was sent using APS encryption. If FALSE, the message did not use APS encryption. |
Example
Sends a manufacturer-specific command and receives a manufacturer-specific response.
<send_ZCL>
<destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<cluster_id>0xFCAA</cluster_id>
<server_or_client>0</server_or_client>
<payload type="base16">AABB11223344</payload>
<command_identifier>0x03</command_identifier>
<response_command_identifier>0x04</response_command_identifier>
<manufacturer_code>0xBEEF</manufacturer_code>
</send_ZCL>
<send_ZCL_response>
<source_address type="MAC">11:22:33:44:55:66:77:88</source_address>
<source_endpoint_id type="int">0x10</source_endpoint_id>
<destination_endpoint_id type="int">0x5E</destination_endpoint_id>
<cluster_id type="int">0xFCAA</cluster_id>
<server_or_client type="int">0x0</server_or_client>
<payload type="base16">DDEE</payload>
<command_identifier type="int">0x04</command_identifier>
<command_type type="int">0x1</command_type>
<manufacturer_code type="int">0xBEEF</manufacturer_code>
<enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
</send_ZCL_response>