Reporting

Overview

The gateway’s reporting feature provides extended data gathering functionality on top of basic ZigBee Cluster Library (ZCL) support. Attribute values can be gathered at given intervals and if required the results filtered based on delta change, with the results pushed to Device Cloud without further user intervention. Additionally, results can be collected and only pushed according to a specified schedule if desired.

Over the air, there are two basic ways for reporting to function. The ZCL specification describes reporting commands which configure a ZigBee device to automatically send reports to the requestor; this type of reporting is referred to as “real” reporting in this documentation. Because this type of reporting is not a mandatory ZCL feature and is not usually supported by device vendors, a simulated version of real reporting is also supported by the gateway. This uses standard ZCL read attribute commands under the hood and replicates the behavior that the remote device would have were it to be configured for real reporting; this type of reporting is referred to as “pseudo” reporting.

ZCL reporting is traditionally configured as “differential” reporting, using three parameters:

• minimum interval: reports may not be generated more often than this, regardless of value change
• maximum interval: reports must be generated at least this often, regardless of value change
• reportable change: if between minimum and maximum interval and the value has changed by at least this much since the last report, generate a report

This type of reporting puts restrictions on the rate of received data but is not intended to specify regular data gathering. As of 1.6.0, pseudo reporting may also use a “scheduled” reporting configuration, where a cron string is used to specify exactly when data should be gathered instead of using min/max interval and reportable change.

Important

Note that cron strings in 1.6.0 start with a “seconds” field, NOT with a “minutes” field as is the case with some other cron implementations. For example, “*/5 * * * * *” means “every fifth second.”

Groups

As of framework version 1.6.0, reporting configurations may be combined into reporting groups. By definition, if any member of a group is ready to report its data, all other members of the group will also report their data. The intention is to provide a snapshot of values for the specified ZCL attributes whenever any of the monitored values reaches its triggering condition. Groups may include any number of reporting configurations of any type, and configurations may be for different clusters, endpoints and devices. For consistency, all reporting configurations are technically assigned to groups, even if those groups contain only a single configuration.

Whenever an attribute report would be generated by any of the group’s members, ZCL reads are issued for all of the other pseudo reporting configurations in the group in order to get the most recent values for those attributes. Once all of these additional reads complete, the group results will be generated. Note that ZCL reads are not sent for any real reporting configurations in this case; it is assumed that devices which are configured to use real reporting might not support frequent communication and so should not be sent reads. Instead, the most recently-known values for these attributes will be reported in the group results.

Note

It is explicitly disallowed for more than one group to have a reporting configuration for a given attribute.

Power Safety

Group configurations are power safe, which is consistent with pre-1.6.0 behavior for reporting configurations. On startup, if any reporting configurations saved by previous framework versions are found, they will be converted to use the most recent format but otherwise will continue to function as they did previously.

Report Collection

As of framework version 1.6.0, group results may be buffered or “collected” on the gateway and sent in larger chunks, rather than a report being sent every time a group read occurs. When used, the configuration for sending report collections is always given by a cron string. This buffering is handled through standard buffer management, and so can use the gateway’s available flash as either overflow space or a power-safe mirror, as appropriate. See Buffer Manager for details on configuring the gateway’s buffer management system.

Technically, all groups collect data internally, even those which have not specified that they wish to use collection; these groups will simply attempt to push any data immediately after it is generated. As a result, if such a group is not able to push its data to Device Cloud for some period of time, it will continue to collect data until the push succeeds.

Report Jitter

Because report collections may be set up to gather a large amount of data before pushing it to Device Cloud, an optional jitter may be set which will randomize the push time. The intention is that if many gateways are all configured to push data at the same time, using a jitter will reduce the risk of traffic collision and resulting backoffs, which can in turn improve overall system performance. Set “ReportCollection.default_jitter” in Registry Settings to configure report jitter.

RPC Interface

Reporting Methods

As of 1.6.0 the following methods are available:

• start_reports creates or modifies a reporting group.
• stop_reports stops all or part of a reporting group.
• received_attribute_report_collection* contains reported attribute data for a group.
• get_local_reporting_configurations returns what reporting configurations have been set up on the gateway.
• flush_reports instructs either a specified reporting group or all groups to immediately push their collected data to Device Cloud, added in 1.6.0.

The following legacy or otherwise uncommon methods are also available if needed:

• start_receiving_reports creates or modifies reporting configurations.
• stop_receiving_reports stops reporting configurations.
• received_attribute_report* was the format used for returning individual attribute results prior to 1.6.0, and is still used for reporting configurations created using start_receiving_reports.
• stop_sending_reports is used if another device on the network has instructed the gateway to send it real ZCL reports and this behavior needs to be stopped.
• read_reporting_configuration is used to query the real ZCL reporting configuration from another device on the network.