Appendix B.3: Configuring attribute reporting

If attribute reporting is to be used by a cluster then the feature must be enabled at compile-time, as detailed in Appendix B.3.1. Then:

If automatic attribute reporting is to be implemented then the reports must be configured as described in Appendix B.3.5.
If default reporting is to be implemented then the reports must be configured as described in Appendix B.3.6.

The ZCL configuration for attribute reporting is described in Appendix B.3.7 for users who wish to modify this configuration.

B.3.1: Compile-time Options

Attribute reporting is enabled at compile-time by setting the appropriate macros in zcl_options.h. The compile-time options relevant to the cluster server and client are listed separately below.

Parent topic:Appendix B.3: Configuring attribute reporting

B.3.2: Server Options

Generate Attribute Reports

To enable a server to generate attribute reports according to configured reporting rules, add the following option:

#define ZCL_ATTRIBUTE_REPORTING_SERVER_SUPPORTED

Note: Attribute reporting does not need to be enabled with this macro if the reports are generated only via function calls.

Handle ‘Configure Reporting’ Commands

To enable a server to handle ‘configure reporting’ commands and reply with ‘configure reporting’ responses, add the following option:

#define ZCL_CONFIGURE_ATTRIBUTE_REPORTING_SERVER_SUPPORTED

Handle ‘Read Reporting Configuration’ Commands

To enable a server to handle ‘read reporting configuration’ commands and reply with ‘read reporting configuration’ responses, add the following option:

#define ZCL_READ_ATTRIBUTE_REPORTING_CONFIGURATION_SERVER_SUPPORTED

Number of Attribute Reports

The number of reportable attributes can be set (to n) using the following line:

#define ZCL_NUMBER_OF_REPORTS   n

The default value is 10.

Number of String Attribute Reports

The number of reportable string attributes can be set (to n) using the following line:

#define ZCL_NUMBER_OF_STRING_REPORTS   n

The default value is 0 (meaning that string attribute reports are disabled by default).

Maximum Size of Reportable String Attribute

The maximum size, in bytes, of a string attribute that can be reported can be set (to n) using the following line:

#define ZCL_ATTRIBUTE_REPORT_STRING_MAXIMUM_SIZE   n

The default value is 32 bytes.

Minimum Attribute Reporting Interval

The minimum time-interval, in seconds, between consecutive attribute reports can be set (to n) using the following line:

#define ZCL_SYSTEM_MIN_REPORT_INTERVAL   n

The default value is 1 second.

Maximum Attribute Reporting Interval

The maximum time-interval, in seconds, between consecutive attribute reports can be set (to n) using the following line:

#define ZCL_SYSTEM_MAX_REPORT_INTERVAL   n

The default value is 61 seconds.

Parent topic:Appendix B.3: Configuring attribute reporting

B.3.3: Client Options

Receive Attribute Reports

To enable a client to receive attribute reports from a server, add the following option:

#define ZCL_ATTRIBUTE_REPORTING_CLIENT_SUPPORTED

Send ‘Configure Reporting’ Commands

To enable a client to send ‘configure reporting’ commands and handle the ‘configure reporting’ responses, add the following option:

#define ZCL_CONFIGURE_ATTRIBUTE_REPORTING_CLIENT_SUPPORTED

Send ‘Read Reporting Configuration’ Commands

To enable a client to send ‘read reporting configuration’ commands and handle the ‘read reporting configuration’ responses, add the following option:

#define ZCL_READ_ATTRIBUTE_REPORTING_CONFIGURATION_CLIENT_SUPPORTED

Parent topic:Appendix B.3: Configuring attribute reporting

B.3.4: General (Server and Client) Options

If attribute reporting is to report any attributes of the ‘floating point’ type, the following macro must also be enabled in zcl_options.h on both the server and client:

#define ZCL_ENABLE_FLOAT

This enables the use of the floating point library to calculate differences in attribute values. If this library is not already used by the application code, enabling it in this way increases the build size of the application by approximately 5 Kbytes.

Parent topic:Appendix B.3: Configuring attribute reporting

B.3.5: Configuring Automatic Attribute Reports (from Client)

If automatic attribute reporting is to be employed between a cluster server and client, the reporting rules must be configured. These rules include the following parameters for each attribute:

Time-interval between consecutive reports in periodic reporting
Minimum time-interval between consecutive triggered attribute reports
Minimum change in the attribute value that will trigger an attribute report

Note 1: Setting the periodic reporting time-interval to the special value of 0x0000 disables periodic reporting for the attribute. Setting this time-interval to the special value of 0xFFFF disables automatic reporting completely (periodic and triggered) for the attribute.

Note 2: Automatic attributes reports are normally produced on a timescale of seconds. However, reports generated on the change of an attribute value can be speeded up to occur on a timescale of milliseconds, as described in Appendix B.3.8.

Note 3: Before automatic reporting can be configured on an attribute, the ‘reportable flag’ must be set for the attribute on the cluster server using the function eZCL_SetReportableFlag().

This configuration is conducted on the cluster server but is normally directed from a remote device via ‘configure reporting’ commands.

The configuration of automatic attribute reporting follows the process:

The client sends a ‘configure reporting’ command to the server.
The server receives and processes the command, configures the attribute reporting and generates a ‘configure reporting’ response, which it sends back to the requesting client.
The client receives the ‘configure reporting’ response and the ZCL generates events to indicate the status of the request to the client.

These steps are described separately below.

1. Sending a ‘Configure Reporting’ Command (from Client)

The application on the cluster client device can configure attribute reporting for a set of attributes on the cluster server using the function eZCL_SendConfigureReportingCommand(). This function sends a ‘configure reporting’ command to the server.

In this function call, a pointer must be provided to an array of tsZCL_AttributeReportingConfigurationRecord structures, where each structure contains the configuration details for one attribute on which reporting is to be configured (see Section 6.1.5).

2. Receiving a ‘Configure Reporting’ Command (on Server)

The server will automatically process an incoming ‘configure reporting’ command and perform the required configuration without assistance from the application. For each attribute (in the configuration request), the reporting configuration values are parsed, after which the ZCL generates an event of the type:

E_ZCL_CBET_REPORT_INDIVIDUAL_ATTRIBUTES_CONFIGURE

In the tsZCL_CallBackEvent structure (see Section 6.2) for this event:

The uMessage field contains a structure of the type tsZCL_AttributeReportingConfigurationRecord (see Section 6.1.5).
The eZCL_Status field indicates the outcome of parsing the configuration values for the attribute (success or failure)

Thus, the configuration of reporting for a set of attributes will result in a sequence of events of the above type, one for each attribute. The application should copy the contents of the tsZCL_AttributeReportingConfigurationRecord structure for each attribute to RAM (for information on storage format, refer to Appendix B.7.2).

Note that the tsZCL_AttributeReportingConfigurationRecord structure for an attribute contains the field u16MaximumReportingInterval which specifies a time-period for periodic reporting. Periodic reporting should not be too frequent, since a sleepy device must wake to send a report and frequent reports are be a significant drain on power resources. Therefore, the period for periodic reporting is not allowed to be set to a value less than sConfig.u16SystemMaximumReportingInterval in the ZCL configuration (see Appendix B.3.7). If a ‘configure reporting’ command attempts to set a smaller (non-zero) value, the ZCL discards the reporting configuration for this attribute and set the status for this attribute configuration to E_ZCL_CMDS_INVALID_VALUE in the ‘configure reporting’ response (see below).

Once attribute reporting has been configured (or not) for all the attributes (in the request), a single event is generated of the type:

E_ZCL_CBET_REPORT_ATTRIBUTES_CONFIGURE

Finally, the server generates a ‘configure reporting’ response and sends it back to the requesting client.

Note: The application and ZCL hold the attribute reporting configuration data in RAM. To preserve this data through episodes of power loss, the application should also save the data to NVM, as described in Appendix B.7.

3. Receiving a ‘Configure Reporting’ Response (on Client)

A ‘configure reporting’ response from the cluster server contains an Attribute Status Record for each attribute that was included in the corresponding ‘configure reporting’ command. For each attribute in the response, the ZCL on the client generates an event of the type:

E_ZCL_CBET_REPORT_INDIVIDUAL_ATTRIBUTES_CONFIGURE_RESPONSE

In the tsZCL_CallBackEvent structure (see Section 6.2) for this event, the uMessage field contains a structure of the type tsZCL_AttributeReportingConfigurationResponse (see Section 6.1.6). In this structure:

The eCommandStatus field indicates the status of the attribute reporting configuration for the attribute.
The tsZCL_AttributeReportingConfigurationRecord structure (Section 6.1.5) contains other data but only the following fields are used:
- u16AttributeEnum which identifies the attribute
- u8DirectionIsReceived which should read 0x01 to indicate that reports of the attribute value are received by the client

Once the above event has been generated for each valid attribute in the response, a single E_ZCL_CBET_REPORT_ATTRIBUTES_CONFIGURE_RESPONSE event is generated to conclude the response.

Parent topic:Appendix B.3: Configuring attribute reporting

B.3.6: Configuring Default Reporting (on Server)

Default reporting is a form of automatic reporting for a restricted set of attributes (see Appendix B.2). It is configured on the cluster server.

An individual attribute can be configured as potentially reportable through default reporting by setting the ‘reportable flag’ E_ZCL_AF_RP in either of the following ways:

The flag can be incorporated in the line for the attribute in the tsZCL_AttributeDefinition structure for the cluster server. For example, in the following line of code, attribute reporting is enabled for the bOnOff attribute of the On/Off cluster:

E_CLD_ONOFF_ATTR_ID_ONOFF, (E_ZCL_AF_RD|E_ZCL_AF_SE|**E\_ZCL\_AF\_RP**), E_ZCL_BOOL,     
    (uint32)(&((tsCLD_OnOff*)(0))->bOnOff),0},

The flag can be set by the server application by calling the function eZCL_SetReportableFlag().

The reporting of these attributes can be configured by the server application by calling the function eZCL_CreateLocalReport() for each attribute. The configuration values are similar to those for automatic reporting, described in Appendix B.3.5. The reporting configuration is passed to the function in a sZCL_AttributeReportingConfigurationRecord structure. The application can then enable default reporting for reportable attributes using the function vZCL_SetDefaultReporting(), which checks whether the E_ZCL_AF_RP flag has been set for each attribute and, if so, sets the ‘default reporting flag’ E_ZCL_ACF_RP.

Parent topic:Appendix B.3: Configuring attribute reporting

B.3.7: ZCL Configuration for Attribute Reporting

This section describes aspects of ZCL configuration related to attribute reporting.

Note: The information in this section is only useful to developers who wish to adjust the standard ZCL configuration for attribute reporting.

Each attribute for which automatic reporting is enabled requires a tsZCL_ReportRecord structure. These structures are maintained internally by the ZCL and space for them is allocated on the ZCL heap. The heap is allocated using the u32ZCL_Heap macro - for example:

PRIVATE uint32 u32ZCL_Heap[
ZCL_HEAP_SIZE(ZCL_NUMBER_OF_ENDPOINTS,
ZCL_NUMBER_OF_TIMERS,
ZCL_NUMBER_OF_REPORTS)];

The number of reportable attributes and the maximum/minimum reporting intervals are passed into the internal eZCL_CreateZCL structure via the sConfig parameter - for example:

sConfig.u8NumberOfReports = ZCL_NUMBER_OF_REPORTS;
sConfig.u16SystemMinimumReportingInterval = 
                            ZCL_SYSTEM_MIN_REPORT_INTERVAL;
sConfig.u16SystemMaximumReportingInterval =   
                            ZCL_SYSTEM_MAX_REPORT_INTERVAL;

The above macros have default values that can be over-ridden in the application’s zcl_options.h file, as indicated in Appendix B.3.1.

A server that supports automatic attribute reporting should have the ‘reportable flag’ E_ZCL_AF_RP set for any attributes that are reportable. While creating a cluster instance, the vZCL_SetDefaultReporting() function should be called, which will set the ‘default reporting flag’ E_ZCL_ACF_RP to enable default reporting for all the attributes that have the E_ZCL_AF_RP flag set. If a server receives a ‘configure reporting’ command for an attribute that does not have E_ZCL_ACF_RP flag set, it will return an error and not allow the attribute to be reported. This bit setting is also required for attribute reports generated through calls to the function eZCL_ReportAllAttributes().

Attribute definitions will normally have the ‘reportable flag’ set only for the mandatory reportable attribute. The application on the server can set the E_ZCL_ACF_RP flag for those attributes on which reporting is not mandatory. This can be done using the function eZCL_SetReportableFlag().

Parent topic:Appendix B.3: Configuring attribute reporting

B.3.8: Speeding Up Automatic Attribute Reports

Automatic attribute reports (configured as described in Appendix B.3.5) that are produced on changes in attribute values can be speeded up to occur with millisecond resolution. Normally, these reports can occur on a timescale of seconds, as they are dependent on the E_ZCL_CBET_TIMER (one second) ticks for sampling. However, they can be made to occur on a timescale of milliseconds by providing E_ZCL_CBET_TIMER_MS (one millisecond) ticks.

In order to do this, the following code must be included in the application:

sCallBackEvent.eEventType = E_ZCL_CBET_TIMER_MS; 
vZCL_EventHandler(&sCallBackEvent);

Note that the E_ZCL_CBET_TIMER ticks still need to be generated, as they are used by UTC time and by the ZCL report manager to keep track of time.

Parent topic:Appendix B.3: Configuring attribute reporting

Parent topic:Appendix B: Attribute reporting