Overview

Reports can be set up on a reporting device when the device is required to periodically send out reports. The plugin relies on bindings. Each report is an asynchronous message sent out from the reporting device, when a local ZCL attribute has changed, to corresponding entries in the binding table. Either the node sending the reports, the node receiving the reports, or another third-party configuration device may create the binding table entry(s) on the reporting node. This plugin supports both requesting reports from another device and sending out attribute reports when the device has been configured to do so. If the application will receive reports from multiple sources, the device should be configured as a concentrator.

Reporting table

The result of the two supported reporting configurations is two types of reporting entries. The ’default entries’ are the ones based on the endpoint, cluster configuration in the ZCL Clusters tab of App builder. The ’free entries’ are the ones that can be configured with CLI commands or through the reception of ZCL messages.

The number of free entries can be set in AppBuilder under the Plugins tab in the Reporting plugin option: ’Reporting table size’ or through changing the defined value of EMBER_AF_PLUGIN_REPORTING_TABLE_SIZE in your project's header file.

The number of ’default entries’ depends on the endpoint/cluster configuration and it is added to the number of free entries. Thus the Maximum size of the reporting table is free entries + default entries. This value can be accessed through the REPORT_TABLE_SIZE macro.

The following code snippet is an example of how to get the active entries from the reporting table:

EmberAfPluginReportingEntry entry;
for(int i = 0; i < REPORT_TABLE_SIZE; i++){
    emAfPluginReportingGetEntry(i,&entry);
    if(entry.endpoint != EMBER_AF_PLUGIN_REPORTING_UNUSED_ENDPOINT_ID){
              //do stuff with valid entry
    }
}

Note: Post GSDK 3.0 you can use the emAfPluginReportingNumEntries to retrieve entries that are actively used.

This plugin implements the ZigBee Cluster Library's standard binding-based approach of reporting in which reports are sent to corresponding entries in the binding table. Either the node sending the reports, the node receiving the reports, or another third-party configuration device may create the binding table entry(s) on the reporting node. (Note: The binding table needs to be large enough to accommodate all report targets.) Reports are sent to destinations of all bindings with matching clusterID and source endpoint for the attribute being reported. To pair devices, the nodes need to be entered into a provisioning mode. More information on the binding process can be found in our Fundamentals: Design Choices (UG103.3) guide under Section 3.3: "Device Discovery and Provisioning".

Reporting entries

An example of setting up bindings can be found in ZigBee 3.0 Tutorial - Light and Switch from Scratch - Step 5. To create an entry into the reporting table, check out EmberAfPluginReportingEntry Struct Reference on docs.silabs.com

The following code is an example of setting up a reporting entry: 

EmberAfPluginReportingEntry reportingEntry;


reportingEntry.direction = EMBER_ZCL_REPORTING_DIRECTION_REPORTED;
reportingEntry.endpoint = emberAfPrimaryEndpoint();
reportingEntry.clusterId = ZCL_ON_OFF_CLUSTER_ID;
reportingEntry.attributeId = ZCL_ON_OFF_ATTRIBUTE_ID;
reportingEntry.mask = CLUSTER_MASK_SERVER;
reportingEntry.manufacturerCode = EMBER_AF_NULL_MANUFACTURER_CODE;
reportingEntry.data.reported.minInterval = MIN_INTERVAL_S;
reportingEntry.data.reported.maxInterval = MAX_INTERVAL_S;
reportingEntry.data.reported.reportableChange = 0;

emberAfPluginReportingConfigureReportedAttribute(&reportingEntry);

A few notes on reportingEntry:
  direction - Specifies whether values of the attribute are reported or received.
  attributeId - Contains the identifier of the attribute to be reported.
  data.reported.minInterval - The minimum interval in seconds between issuing reports.
  data.reported.maxInterval - The maximum interval in seconds between issuing reports.
  data.reported.reportableChange - The minimum change to the attribute that will result in a report being issued. This value is ignored for discrete (Boolean) attributes as those will generate reports on any change. If this is 0 any change can be reported. 

 
The plugin will only send a report for actively reported attributes and only if a reportable change has occurred and the minimum interval has elapsed or if the maximum interval is set and has elapsed. For more details on the plugin, please refer to the Ember Application Framework Developer Guide section 15.4 Reporting Plugin.