Appliance Events and Alerts Cluster

This chapter outlines the Appliance Events and Alerts cluster, which provides an interface for the notification of significant events and alert situations.

The Appliance Events and Alerts cluster has a Cluster ID of 0x0B02.

Overview

The Appliance Events and Alerts cluster provides an interface for sending notifications of appliance events (for example, target temperature reached) and alerts (for example, alarms).

The cluster is enabled by defining CLD_APPLIANCE_EVENTS_AND_ALERTS in the zcl_options.h file. Further compile-time options for the Appliance Events and Alerts cluster are detailed in Section 47.9.

Events are notified in terms of header and event identifier fields (an event may occur when the appliance reaches a certain state, such as the end of its operational cycle).

Alerts are notified in terms of the following fields:

Alert identification value
Alert category, one of: Warning, Danger, Failure
Presence/recovery flag (indicating alert has been either detected or recovered)

Parent topic:Appliance Events and Alerts Cluster

Cluster structure and attribute

The structure definition for the Appliance Events and Alerts cluster (server) is.

typedef struct
{
 zuint16   u16ClusterRevision;
} tsCLD_ApplianceEventsAndAlerts;

where u16ClusterRevision is a mandatory attribute that specifies the revision of the cluster specification on which this cluster instance is based. The cluster specification in the ZCL r6 corresponds to a cluster revision of 1. The value is incremented by one for each subsequent revision of the cluster specification. This attribute is also described in Section 2.4.

Parent topic:Appliance Events and Alerts Cluster

Sending Messages

The Appliance Events and Alerts cluster server resides on the appliance (for example, a washing machine) and the cluster client resides on a controlling device (normally a remote control unit).

Messages can be sent between the client and the server in the following ways:

Alerts that are active on the appliance can be requested by the client by sending a ‘Get Alerts’ message to the server (which replies with a ‘Get Alerts Response’ message).
Alerts that are active on the appliance can be sent unsolicited from the server to the client in an ‘Alerts Notification’ message.
The server can notify the client of an appliance event by sending an unsolicited ‘Event Notification’ message to the client

Sending the above messages is described in the sub-sections below.

‘Get Alerts’ Messages from Client to Server

The application on the cluster client can request the alerts that are currently active on the appliance by sending a ‘Get Alerts’ message to the server - this message is sent by calling the function eCLD_AEAAGetAlertsSend(). This function returns immediately and the requested alerts are later returned in an E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_GET_ALERTS event, which is generated when a response arrives from the server (Appliance Events and Alerts events are described in Section 47.4).

Note: The cluster server handles the ‘Get Alerts’ message automatically and returns the requested alerts in a ‘Get Alerts Response’ message to the client.

The appliance alerts from the message payload are contained in the above event - for details of this payload and the alert information, refer to Section 47.8.2. Up to 15 alerts can be reported in a single response.

Parent topic:Sending Messages

‘Alerts Notification’ Messages from Server to Client

The cluster server on the appliance can send unsolicited alert notifications to the client in ‘Alerts Notification’ messages. The application on the server can send a message of this kind by calling either of the following functions:

eCLD_AEAAAlertsNotificationSend()
eCLD_AEAAGetAlertsResponseORAlertsNotificationSend()

Note: The latter function is also used internally by the cluster server to send a ‘Get Alerts Response’ message - see Section 47.3.1.

The appliance status information from the ‘Alerts Notification’ message is reported to the application on the cluster client through the event E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_ALERTS_NOTIFICATION, which is generated when the notification arrives from the server (Appliance Events and Alerts events are described in Section 47.4). The appliance alerts from the message payload are contained in the above event - for details of this payload and the alert information, refer to Section 47.8.2. Up to 15 alerts can be reported in a single notification.

Parent topic:Sending Messages

‘Event Notification’ Messages from Server to Client

The cluster server on the appliance can send unsolicited event notifications to the client in ‘Event Notification’ messages, where each message reports a single appliance event (for example, oven has reached its target temperature). A message of this kind can be sent by the application on the server by calling the function eCLD_AEAAEventNotificationSend().

The appliance event information from the ‘Event Notification’ message is reported to the application on the cluster client through the event E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_ALERTS_NOTIFICATION, which is generated when the notification arrives from the server (Appliance Events and Alerts events are described in Section 47.4). The appliance event from the message payload is contained in the above client event - for details of this payload and the embedded appliance event information, refer to Section 47.8.3.

Parent topic:Sending Messages

Parent topic:Appliance Events and Alerts Cluster

Appliance Events and Alerts Events

The Appliance Events and Alerts cluster has its own events that are handled through the callback mechanism described in Chapter 3. The cluster contains its own event handler. If a device uses this cluster then application-specific Appliance Events and Alerts event handling must be included in the user-defined callback function for the associated endpoint, where this callback function is registered through the relevant endpoint registration function. This callback function is then invoked when an Appliance Events and Alerts event occurs and needs the attention of the application.

For an Appliance Events and Alerts event, the eEventType field of the tsZCL_CallBackEvent structure is set to E_ZCL_CBET_CLUSTER_CUSTOM. This event structure also contains an element sClusterCustomMessage, which is itself a structure containing a field pvCustomData. This field is a pointer to the following tsCLD_ApplianceEventsAndAlertsCallBackMessage structure:

typedef struct
{
  uint8  u8CommandId
  union
  {
  tsCLD_AEAA_GetAlertsResponseORAlertsNotificationPayload
  *psGetAlertsResponseORAlertsNotificationPayload;
  tsCLD_AEAA_EventNotificationPayload    
  *psEventNotificationPayload;
  }uMessage;
} tsCLD_ApplianceEventsAndAlertsCallBackMessage;

When an Appliance Events and Alerts event occurs, one of four command types could have been received. The relevant command type is specified through the u8CommandId field of the tsSM_CallBackMessage structure. The possible command types are detailed the tables below for events generated on a server and a client.

u8CommandId Enumeration	Description
E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_GET_ALERTS	A ‘Get Alerts’ request has been received by the server (appliance)

u8CommandId Enumeration	Description
E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_GET_ALERTS	A response to a ‘Get Alerts’ request has been received by the client, containing the requested alerts (up to 15)
E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_ALERTS_NOTIFICATION	An ‘Alerts Notification’ message has been received by the client, containing unsolicited alerts (up to 15)
E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_EVENT_NOTIFICATION	An ‘Event Notification’ message has been received by the client

Parent topic:Appliance Events and Alerts Cluster

Functions

The following Appliance Events and Alerts cluster functions are provided:

eCLD_ApplianceEventsAndAlertsCreateApplianceEventsAndAlerts

teZCL_Status eCLD_ApplianceEventsAndAlertsCreateApplianceEventsAndAlerts(
    tsZCL_ClusterInstance *psClusterInstance,
    bool_t bIsServer,
    tsZCL_ClusterDefinition *psClusterDefinition,
    oid *pvEndPointSharedStructPtr,
    uint8 *pu8AttributeControlBits,
    tsCLD_ApplianceEventsAndAlertsCustomDataStructure
*psCustomDataStructure);

Description

This function creates an instance of the Appliance Events and Alerts cluster on an endpoint. The cluster instance is created on the endpoint which is associated with the supplied tsZCL_ClusterInstance structure and can act as a server or a client, as specified.

The function should only be called when setting up a custom endpoint containing one or more selected clusters (rather than the whole set of clusters supported by a standard ZigBee device). This function creates an Appliance Events and Alerts cluster instance on the endpoint, but instances of other clusters may also be created on the same endpoint by calling their corresponding creation functions. For more details of creating cluster instances on custom endpoints, refer to Appendix D.

Note: This function must not be called for an endpoint on which a standard ZigBee device is used. In this case, the device and its supported clusters must be registered on the endpoint using the relevant device registration function from those described in the ZigBee Devices User Guide*(JNUG3131)*.

When used, this function must be the first Appliance Events and Alerts cluster function called in the application, and must be called after the stack has been started and after the ZCL has been initialized.

The function requires an array to be declared for internal use, which contains one element (of type uint8) for each attribute of the cluster. The array length is automatically adjusted by the compiler using the following declaration:

uint8 au8ApplianceEventsAndAlertsAttributeControlBits 
    [(sizeof(asCLD_ApplianceEventsAndAlertsClusterAttributeDefinitions) 
    / sizeof(tsZCL_AttributeDefinition))];

Parameters

Returns

Parent topic:Functions

eCLD_AEAAGetAlertsSend

teZCL_Status eCLD_AEAAGetAlertsSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber);

Description

This function can be used on an Appliance Events and Alerts cluster client to send a ‘Get Alerts’ message to a cluster server (appliance).

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the message. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

Parameter

Returns

Parent topic:Functions

eCLD_AEAAGetAlertsResponseORAlertsNotificationSend

teZCL_Status eCLD_AEAAGetAlertsResponseORAlertsNotificationSend(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
uint8 *pu8TransactionSequenceNumber,
teCLD_ApplianceEventsAndAlerts_CommandId eCommandId,
tsCLD_AEAA_GetAlertsResponseORAlertsNotificationPayload
*psPayload);

Description

This function can be used on an Appliance Events and Alerts cluster server to send a ‘Get Alerts Response’ message (in reply to a ‘Get Alerts’ message) or an unsolicited ‘Alerts Notification’ message to a cluster client.

The command to be sent must be specified as one of:

E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_GET_ALERTS
E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_ALERTS_NOTIFICATION

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the message. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

Parameters

Returns

Parent topic:Functions

eCLD_AEAAAlertsNotificationSend

teZCL_Status eCLD_AEAAAlertsNotificationSend(
uint8 u8SourceEndPointId,
uint8 u8DestinationEndPointId,
tsZCL_Address *psDestinationAddress,
uint8 *pu8TransactionSequenceNumber,
tsCLD_AEAA_GetAlertsResponseORAlertsNotificationPayload
*psPayload);

Description

This function can be used on an Appliance Events and Alerts cluster server to send an unsolicited ‘Alerts Notification’ message to a cluster client. The function is an alternative to eCLD_AEAAGetAlertsResponseORAlertsNotificationSend().

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the message. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

Parameters

Returns

Parent topic:Functions

eCLD_AEAAEventNotificationSend

teZCL_Status eCLD_AEAAEventNotificationSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_AEAA_EventNotificationPayload *psPayload);

Description

This function can be used on an Appliance Events and Alerts cluster server (appliance) to send an ‘Event Notification’ message to a cluster client, to indicate that an incident has occurred.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the message. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

Parameters

Returns

Parent topic:Functions

Parent topic:Appliance Events and Alerts Cluster

Return codes

The Appliance Events and Alerts cluster functions use the ZCL return codes, listed in Section 7.2.

Parent topic:Appliance Events and Alerts Cluster

Enumerations

‘Command ID’ Enumerations

The following enumerations are used in commands received on a cluster server or client.

typedef enum PACK
{
   E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_GET_ALERTS = 0x00,
   E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_ALERTS_NOTIFICATION,
   E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_EVENT_NOTIFICATION 
} teCLD_ApplianceEventsAndAlerts_CommandId;

The above enumerations are described in the table below.

Enumeration	Description
E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_GET_ALERTS	‘Get Alerts’ request (on server) or response (on client)
E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_ALERTS_NOTIFICATION	Alerts notification (on client)
E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_EVENT_NOTIFICATION	Events notification (on server)

Parent topic:Enumerations

Parent topic:Appliance Events and Alerts Cluster

Structures

tsCLD_ApplianceEventsAndAlertsCallBackMessage

For an Appliance Events and Alerts event, the eEventType field of the tsZCL_CallBackEvent structure is set to E_ZCL_CBET_CLUSTER_CUSTOM. This event structure also contains an element sClusterCustomMessage, which is itself a structure containing a field pvCustomData. This field is a pointer to the following tsCLD_ApplianceEventsAndAlertsCallBackMessage structure:

typedef struct
{
 uint8     u8CommandId
 union
 {
 tsCLD_AEAA_GetAlertsResponseORAlertsNotificationPayload            
         *psGetAlertsResponseORAlertsNotificationPayload;
 tsCLD_AEAA_EventNotificationPayload                                
         *psEventNotificationPayload;
 } uMessage;
} tsCLD_ApplianceEventsAndAlertsCallBackMessage; 

where:

u``8CommandId indicates the type of Appliance Events and Alerts command that has been received, one of:
- E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_GET_ALERTS
- E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_ALERTS_NOTIFICATION
- E_CLD_APPLIANCE_EVENTS_AND_ALERTS_CMD_EVENT_NOTIFICATION
u``Message is a union containing the command payload as one of (depending on the value of u8CommandId):
- psGetAlertsResponseORAlertsNotificationPayload is a pointer to the payload of an “Get Alerts” response message or an alerts notification message (see Section 47.8.2)
- psEventNotificationPayload is a pointer to the payload of an events notification message (see Section 47.8.3)

Parent topic:Structures

tsCLD_AEAA_GetAlertsResponseORAlertsNotificationPayload

This structure contains the payload for a ‘Get Alerts Response’ message or an ‘Alerts Notification’ message.

typedef struct
{
   zuint8  u8AlertsCount;
   zuint24 au24AlertStructure[
              CLD_APPLIANCE_EVENTS_AND_ALERTS_MAXIMUM_NUM_OF_ALERTS];
} tsCLD_AEAA_GetAlertsResponseORAlertsNotificationPayload;

where:

u8AlertsCount is an 8-bit bitmap containing the following alerts information:

Bits	Description
0-3	Number of reported alerts
4-7	Type of alert:

0x0: Unstructured
0x1-0xF: Reserved

|

au24AlertStructure[``] is an array of 24-bit bitmaps, with one bitmap for each reported alert, containing the following information:

Bits	Description
0-7	Alert ID:

0x0: Reserved
0x01-0x3F: Standardized
0x40-0x7F: Non-standardized
0x80-0xFF: Proprietary

| |8-11|Category:

0x0: Reserved
0x1: Warning
0x2: Danger
0x3: Failure
0x4–0xF: Reserved

| |12-13|Presence or recovery:

0x0: Presence (alert detected)
0x1: Recovery (alert recovered)
0x2–0x3: Reserved

| |14-15|Reserved (set to 0x0)| |16-23|Non-standardized or proprietary|

Parent topic:Structures

tsCLD_AEAA_EventNotificationPayload

This structure contains the payload for an ‘Event Notification’ message.

typedef struct
{
   zuint8           u8EventHeader;
   zuint8           u8EventIdentification;
} tsCLD_AEAA_EventNotificationPayload;

where:

u8EventHeader is reserved and set to 0
u8EventIdentification is the identifier of the event being notified:
- 0x01: End of operational cycle reached
- 0x02: Reserved
- 0x03: Reserved
- 0x04: Target temperature reached
- 0x05: End of cooking process reached
- 0x06: Switching off
- 0xF7: Wrong data
  - (Values 0x00 to 0x3F are standardised, 0x40 to 0x7F are non-standardised, and 0x80 to 0xFF except 0xF7 are proprietary)

Parent topic:Structures

tsCLD_ApplianceEventsAndAlertsCustomDataStructure

The Appliance Events and Alerts cluster requires extra storage space to be allocated to be used by internal functions. The structure definition for this storage is shown below:

typedef struct
{
    tsZCL_ReceiveEventAddress sReceiveEventAddress;
    tsZCL_CallBackEvent sCustomCallBackEvent;
    tsCLD_ApplianceEventsAndAlertsCallBackMessage sCallBackMessage;
} tsCLD_ApplianceEventsAndAlertsCustomDataStructure;

The fields are for internal use and no knowledge of them is required.

Parent topic:Structures

Parent topic:Appliance Events and Alerts Cluster

Compile-time options

This section describes the compile-time options that may be enabled in the zcl_options.h file of an application that uses the Appliance Events and Alerts cluster.

To enable the Appliance Events and Alerts cluster in the code to be built, it is necessary to add the following line to the file:

#define CLD_APPLIANCE_EVENTS_AND_ALERTS

In addition, to enable the cluster as a client or server, it is also necessary to add one of the following lines to the same file:

#define APPLIANCE_EVENTS_AND_ALERTS_SERVER
#define APPLIANCE_EVENTS_AND_ALERTS_CLIENT

The Appliance Identification cluster contains macros that may be optionally specified at compile-time by adding one or more of the following lines to the zcl_options.h file.

Maximum Number of Alerts Reported

The maximum number of alerts that can be reported in a response or notification can be defined (as n) using the following definition in the zcl_options.h file:

#define CLD_APPLIANCE_EVENTS_AND_ALERTS_MAXIMUM_NUM_OF_ALERTS n

The default value is 16, which is the upper limit on this value, and n must therefore not be greater than 16.

Global Attributes

Add this line to define the value (n) of the Cluster Revision attribute:

#define CLD_APPLIANCE_EVENTS_AND_ALERTS_CLUSTER_REVISION <n>

The default value is 1, which corresponds to the revision of the cluster in the ZCL r6 specification (see Section 2.4).

Parent topic:Appliance Events and Alerts Cluster