Events

The events that are not cluster-specific are divided into four categories (Input, Read, Write, General), as shown in the following table. The ‘input events’ originate externally to the ZCL and are passed into the ZCL for processing (see Section 3.2). The remaining events are generated as part of this processing.

Note: Cluster-specific events are covered in the chapter for the relevant cluster.

Category

Event

Input Events

E_ZCL_ZIGBEE_EVENT

E_ZCL_CBET_TIMER

E_ZCL_CBET_TIMER_MS

Read Events

E_ZCL_CBET_READ_REQUEST

E_ZCL_CBET_READ_INDIVIDUAL_ATTRIBUTE_RESPONSE

E_ZCL_CBET_READ_ATTRIBUTES_RESPONSE

Write Events

E_ZCL_CBET_CHECK_ATTRIBUTE_RANGE

E_ZCL_CBET_WRITE_INDIVIDUAL_ATTRIBUTE

E_ZCL_CBET_WRITE_ATTRIBUTES

E_ZCL_CBET_WRITE_INDIVIDUAL_ATTRIBUTE_RESPONSE

E_ZCL_CBET_WRITE_ATTRIBUTES_RESPONSE

General Events

E_ZCL_CBET_LOCK_MUTEX

E_ZCL_CBET_UNLOCK_MUTEX

E_ZCL_CBET_DEFAULT_RESPONSE

E_ZCL_CBET_UNHANDLED_EVENT

E_ZCL_CBET_ERROR

E_ZCL_CBET_CLUSTER_UPDATE

The above events are described below.

Input Events

The ‘input events’ are generated externally to the ZCL. Such an event is received by the application, which wraps the event in a tsZCL_CallBackEvent structure and passes it into the ZCL using the function vZCL_EventHandler() - for further details of event processing, refer to Section 3.2.

  • E_ZCL_ZIGBEE_EVENT

    • All ZigBee PRO stack events to be processed by the ZCL are designated as this type of event by setting the eEventType field in the tsZCL_CallBackEvent structure to E_ZCL_ZIGBEE_EVENT.

  • E_ZCL_CBET_TIMER

    • A timer event (indicating that a timer has expired) which is to be processed by the ZCL is designated as this type of event by setting the eEventType field in the tsZCL_CallBackEvent structure to E_ZCL_CBET_TIMER.

  • E_ZCL_CBET_TIMER_MS

    • A millisecond timer event (indicating that a timer has expired) which is to be processed by the ZCL is designated as this type of event by setting the eEventType field in the tsZCL_CallBackEvent structure to E_ZCL_CBET_TIMER_MS.

Read Events

The ‘read events’ are generated as the result of a ‘read attributes’ request (see Section2.3.2). Some of these events are generated on the remote node and some of them are generated on the local (requesting) node, as indicated in the table below.

Generated on local node (client):

Generated on remote node (server):

E_ZCL_CBET_READ_REQUEST

E_ZCL_CBET_READ_INDIVIDUAL_ATTRIBUTE_RESPONSE

E_ZCL_CBET_READ_ATTRIBUTES_RESPONSE

The circumstances surrounding the generation of the ‘read events’ are outlined below:

  • E_ZCL_CBET_READ_REQUEST

    • When a ‘read attributes’ request has been received and passed to the ZCL (as a stack event), the ZCL generates the event E_ZCL_CBET_READ_REQUEST for the relevant endpoint to indicate that the endpoint’s shared device structure is going to be read. This gives an opportunity for the application to access the shared structure first, if required - for example, to update attribute values before they are read. This event may be ignored if the application reads the hardware asynchronously - for example, driven by a timer or interrupt.

  • E_ZCL_CBET_READ_INDIVIDUAL_ATTRIBUTE_RESPONSE

    • When a ‘read attributes’ response has been received by the requesting node and passed to the ZCL (as a stack event), the ZCL generates the event E_ZCL_CBET_READ_INDIVIDUAL_ATTRIBUTE_RESPONSE for each individual attribute in the response. Details of the attribute are incorporated in the structure tsZCL_ReadIndividualAttributesResponse, described in Section 6.2.

    • Note that this event is often ignored by the application, while the event E_ZCL_CBET_READ_ATTRIBUTES_RESPONSE (see next event) is handled.

  • E_ZCL_CBET_READ_ATTRIBUTES_RESPONSE

    • When a ‘read attributes’ response has been received by the requesting node and the ZCL has completed updating the local copy of the shared device structure, the ZCL generates the event E_ZCL_CBET_READ_ATTRIBUTES_RESPONSE. The transaction sequence number and cluster instance fields of the tsZCL_CallBackEvent structure are used by this event.

Write Events

The ‘write events’ are generated as the result of a ‘write attributes’ request (see Section 2.3.3). Some of these events are generated on the remote node and some of them are generated on the local (requesting) node, as indicated in the table below.

Generated on local node (client):

Generated on remote node (server):

E_ZCL_CBET_CHECK_ATTRIBUTE_RANGE

E_ZCL_CBET_WRITE_INDIVIDUAL_ATTRIBUTE

E_ZCL_CBET_WRITE_ATTRIBUTES

E_ZCL_CBET_WRITE_INDIVIDUAL_ATTRIBUTE_RESPONSE

E_ZCL_CBET_WRITE_ATTRIBUTES_RESPONSE

During the process of receiving and processing a ‘write attributes’ request, the receiving application maintains a tsZCL_IndividualAttributesResponse structure for each individual attribute in the request:

typedef struct PACK {
uint16                  u16AttributeEnum;
teZCL_ZCLAttributeType  eAttributeDataType;
teZCL_CommandStatus     eAttributeStatus;
void                    *pvAttributeData;
tsZCL_AttributeStatus   *psAttributeStatus;
} tsZCL_IndividualAttributesResponse;

The u16AttributeEnum field identifies the attribute.

The field eAttributeDataType is set to the ZCL data type of the attribute in the request, which is checked by the ZCL to ensure that the attribute type in the request matches the expected attribute type.

The above structure is fully detailed in Section 6.2.

The circumstances surrounding the generation of the ‘write events’ are outlined below:

  • E_ZCL_CBET_CHECK_ATTRIBUTE_RANGE

    When a ‘write attributes’ request has been received and passed to the ZCL (as a stack event), for each attribute in the request the ZCL generates the event E_ZCL_CBET_CHECK_ATTRIBUTE_RANGE for the relevant endpoint. This indicates that a ‘write attributes’ request has arrived and gives an opportunity for the application to do either or both of the following:

    • Check that the attribute value to be written falls within the valid range (range checking is not performed in the ZCL because the range may depend on application-specific rules).

    • Decide whether the requested write access to the attribute in the shared structure is allowed or not allowed.

  • The value to be written is pointed to by pvAttributeData in the above structure (this does not point to the field of the shared structure containing this attribute, as the shared structure field still has its existing value).

  • The attribute status field eAttributeStatus in the above structure is initially set to E_ZCL_SUCCESS. The application should set this field to E_ZCL_ERR_ATTRIBUTE_RANGE if the attribute value is out-of-range or to E_ZCL_DENY_ATTRIBUTE_ACCESS if it decides to disallow the write. Also note the following:

  • If a conventional ‘write attributes’ request is received and an attribute value fails the range check or write access to an attribute is denied, this attribute is left unchanged in the shared structure but other attributes are updated.

  • If an ‘undivided write attributes’ request is received and any attribute fails the range check or write access to any attribute is denied, no attribute values are updated in the shared structure.

  • E_ZCL_CBET_WRITE_INDIVIDUAL_ATTRIBUTE

    • Following an attempt to write an attribute value to the shared structure, the ZCL generates the event E_ZCL_CBET_WRITE_INDIVIDUAL_ATTRIBUTE for the relevant endpoint. The field eAttributeStatus in the structure tsZCL_IndividualAttributesResponse indicates to the application whether the attribute value was updated successfully:

    • If the write is successful, this status field is left as E_ZCL_SUCCESS.

    • If the write is unsuccessful, this status field is set to a suitable error status (see Section 7.1.4).

  • E_ZCL_CBET_WRITE_ATTRIBUTES

    • Once all the attributes in a ‘write attributes’ request have been processed, the ZCL generates the event E_ZCL_CBET_WRITE_ATTRIBUTES for the relevant endpoint.

  • E_ZCL_CBET_WRITE_INDIVIDUAL_ATTRIBUTE_RESPONSE

    • The E_ZCL_CBET_WRITE_INDIVIDUAL_ATTRIBUTE_RESPONSE event is generated for each attribute that is listed in an incoming ‘write attributes’ response message. Only attributes that have failed to be written are contained in the message. The field eAttributeStatus of the structure tsZCL_IndividualAttributesResponse indicates the reason for the failure (see Section 7.1.4).

  • E_ZCL_CBET_WRITE_ATTRIBUTES_RESPONSE

    • The E_ZCL_CBET_WRITE_ATTRIBUTES_RESPONSE event is generated when the parsing of an incoming ‘write attributes’ response message is complete. This event is particularly useful following a write where all the attributes have been written without errors since, in this case, no E_ZCL_CBET_WRITE_INDIVIDUAL_ATTRIBUTE_RESPONSE event is generated.

General Events

  • E_ZCL_CBET_LOCK_MUTEX and E_ZCL_CBET_UNLOCK_MUTEX

    • When an application task accesses the shared device structure of an endpoint, a mutex should be used by the task to protect the shared structure from conflicting accesses. Thus, the ZCL may need to lock or unlock a mutex in handling an event - for example, when a “read attributes” request has been received and passed to the ZCL (as a stack event). In these circumstances, the ZCL generates the following events:

    • E_ZCL_CBET_LOCK_MUTEX when a mutex is to be locked

    • E_ZCL_CBET_UNLOCK_MUTEX when a mutex is to be unlocked

    • The ZCL specifies one of the above events in invoking the callback function for the endpoint. Thus, the endpoint callback function must include the necessary code to lock and unlock a mutex - for further information, refer to Appendix A.

    • The locking and unlocking of a mutex are useful if the tasks in the application are non-cooperative while sharing the same resource. To optimize the code, the above events are not generated when the tasks are in a cooperative group. Tasks are cooperative by default and, if not required, this feature can be disabled in the zcl_options.h file (see Section 1.3).

  • E_ZCL_CBET_DEFAULT_RESPONSE

    • The E_ZCL_CBET_DEFAULT_RESPONSE event is generated when a ZCL default response message has been received. These messages indicate that either an error has occurred or a message has been processed. The payload of the default response message is contained in the structure tsZCL_DefaultResponseMessage below:

typedef struct PACK {
    uint8         u8CommandId;
    uint8         u8StatusCode;
} tsZCL_DefaultResponseMessage;

  • u8CommandId is the ZCL command identifier of the command which triggered the default response message.

  • u8StatusCode is the status code from the default response message. It is set to 0x00 for OK or to an error code defined in the ZCL Specification.

  • E_ZCL_CBET_UNHANDLED_EVENT and E_ZCL_CBET_ERROR

  • The E_ZCL_CBET_UNHANDLED_EVENT and E_ZCL_CBET_ERROR events indicate that a stack message has been received which cannot be handled by the ZCL. The *pZPSevent field of the tsZCL_CallBackEvent structure points to the stack event that caused the event.

  • E_ZCL_CBET_CLUSTER_UPDATE

  • The E_ZCL_CBET_CLUSTER_UPDATE event indicates that one or more attribute values for a cluster on the local device may have changed.

Note: ZCL error events and default responses (see Section 6.1.9) may be generated when problems occur in receiving commands. The possible ZCL status codes contained in the events and responses are detailed in Section 4.2.

Parent topic:Event Handling