HOW TO: Configure ZCL (real) Reporting on the ConnectPort X2e for Smart Energy

Introduction:

The ZCL or "real" reporting method is where a Smart Energy device (example: Programmable Communicating Thermostat or PCT) is configured to report attribute information about itself to the Gateway, based on the amount of change to the value of a specified attribute.  Very few Smart Energy devices on the market support this method of reporting, and of those devices which claim to support it, an even smaller subset report ZCL values correctly.  The only way to determine whether or not a particular Smart Energy device supports ZCL attribute reporting is to contact the manufacturer of the device in question.

Note:  When a ZCL Reporting configuration is used, the configuration is requested/sent from the Gateway, but is created and stored on the Smart Energy device itself.  Since the reporting configuration is stored on the device, performing a <get_local_reporting_configurations> request on the Gateway will not show the presence of ZCL reporting configurations.  
 

Available ZCL Reporting configuration parameters:

The tables below, found within the Smart Energy Framework User Guide for the ConnectPort X2e for Smart Energy documentation, describe the parameter options used in a <start_reports> request when creating a ZCL Reporting configuration.  In the tables below, a parameter type of int = integer, and bool = a value of True or False.  Parameters listed with * specify optional parameters):
 

Common parameters for all types of reporting:
 

ParameterTypeDescription
destination_addressMAC64-bit extended address of the target device.
source_endpoint_id*int8-bit identifier of the endpoint on the local device from which the ZCL commands will be sent. Only provided if explicitly specified.
destination_endpoint_idint8-bit identifier of the endpoint on the target device containing the target cluster.
profile_idint16-bit profile identifier of the target endpoint.
server_or_clientintWhether the target cluster is a server (0) or client (1) cluster.
cluster_idint16-bit identifier of the cluster over which the ZCL command will be sent.
manufacturer_code*intIf applicable, the 16-bit manufacturer code of the ZCL attribute.
attribute_idint16-bit identifier of the attribute to be reported.
force_configurationboolIf True, this reporting configuration will continue to be reattempted until successful, rather than being dropped after the first failure.
statusintThe status of the configuration operation, which may be 0 (“success”), some other ZCL status code (e.g. 0x86 “attribute not found”) or some internal status code (e.g. 0x202 “conversation timeout”).
 

Parameters specific to ZCL reporting:
 

ParameterTypeDescription
pseudo_reportingboolWill return False.
min_intervalint16-bit minimum time between attribute reports, in seconds
max_intervalint16-bit maximum time between attribute reports, in seconds. An attribute report will be generated after this much time has passed since the last attribute report, even if the attribute value has not changed more than reportable_change. The exception is if this value is 0, in which case reports will only be generated due to reportable_change.
reportable_change*intThe minimum value by which the attributes value must change before a report will be generated, excluding min and max interval restrictions. The type of this parameter corresponds with the ZCL type of the attribute. Note that this value is only meaningful for analog ZCL types; for discrete types any change is considered a reportable change.
attribute_type*intZCL type of the attribute to be reported. Required if reportable_change is specified; otherwise defaults to 0xFF, or “unknown type”.
timeoutintThe maximum time that the report receiver (i.e. the local device) will wait for a report from the device before timing out. If a report is not received within this many seconds, the configuration will be re-sent to the target device.
 

How to configure ZCL or "real" attribute reporting:

The following <start_reports> request example would configure a PCT (Programmable Communicating Thermostat) to report on the Current Temperature attribute (0x0) of the Temperature server cluster (0x201) under endpoint 0x9, when the attribute value changes by a minimum of 1.

In the following example, 00:11:22:33:44:55:66:77 represents the EUI-64 address of the PCT being configured:

<start_reports>
  <record_list type="list">
    <item type="StartReportRecord">
      <destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
      <destination_endpoint_id>0x09</destination_endpoint_id>
      <cluster_id>0x201</cluster_id>
      <server_or_client>0</server_or_client>
      <attribute_id>0x0</attribute_id>
      <pseudo_reporting type="bool">False</pseudo_reporting>
      <min_interval>0</min_interval>
      <max_interval>0</max_interval>
      <reportable_change>1</reportable_change>
      <attribute_type>0x29</attribute_type>
      <timeout>0</timeout>
    </item>
  </record_list>
</start_reports>
 

What did the request do?

We can dissect the request above to see what is happening....

destination_address - the EUI-64 address of the PCT
destination_endpoint_id - ID of the PCT endpoint under which the "interesting data" (i.e. temperature) will be found
cluster_id - the ID of the Temperature server cluster (found under the destination_endpoint specified above)
server_or_client - the type of cluster on the PCT, for cluster_id above (0 = server cluster, 1 = client cluster)
attribute_id - the ID of the Current Temperature attribute found under cluster_id
pseudo_reporting - since we want true ZCL reporting, pseudo_reporting = FALSE
min_interval - reports will not be generated more often than this many seconds, regardless of value change (0 means "no minimum", since we want real-time reporting)
max_interval - reports must be generated at least this often, regardless of value change
reportable_change - the amount of change which is meaningful to generate an attribute report
attribute_type - attribute type for the attribute being reported on (required when the reportable_change value is specified.  This value can be obtained by looking under the readable attribute for this endpoint/cluster/attribute on Device Cloud --- Device Manager --- XBee Networks)
timeout - if a report is not received within this many seconds, the configuration will be re-sent to the Gateway (default = 0 or no timeout).  Time should be greater than max_interval if used


Conclusion:

The <start_reports> configuration above can be used to report on the readable ZCL attribute(s) of any Smart Energy device which supports ZCL or "real" attribute reporting (please check with the manufacturer of your device for details).  For devices which don't support ZCL attribute reporting, the Pseudo Reporting or Scheduled Reporting methods are available (see below for link).

Additional Information:

HOW TO: Configure Scheduled (cron) Reporting on the ConnectPort X2e for Smart Energy
HOW TO: Configure Pseudo (differential) Reporting on the ConnectPort X2e for Smart Energy
HOW TO: Run Smart Energy Framework RPC commands from Digi Device Cloud Web Services
Last updated: Jan 01, 2024

Filed Under

Digi Remote Manager

Recently Viewed

No recently viewed articles

Did you find this article helpful?