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:
 

Parameter	Type	Description
destination_address	MAC	64-bit extended address of the target device.
source_endpoint_id*	int	8-bit identifier of the endpoint on the local device from which the ZCL commands will be sent. Only provided if explicitly specified.
destination_endpoint_id	int	8-bit identifier of the endpoint on the target device containing the target cluster.
profile_id	int	16-bit profile identifier of the target endpoint.
server_or_client	int	Whether the target cluster is a server (0) or client (1) cluster.
cluster_id	int	16-bit identifier of the cluster over which the ZCL command will be sent.
manufacturer_code*	int	If applicable, the 16-bit manufacturer code of the ZCL attribute.
attribute_id	int	16-bit identifier of the attribute to be reported.
force_configuration	bool	If True, this reporting configuration will continue to be reattempted until successful, rather than being dropped after the first failure.
status	int	The 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:
 

Parameter	Type	Description
pseudo_reporting	bool	Will return False.
min_interval	int	16-bit minimum time between attribute reports, in seconds
max_interval	int	16-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*	int	The 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*	int	ZCL type of the attribute to be reported. Required if reportable_change is specified; otherwise defaults to 0xFF, or “unknown type”.
timeout	int	The 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