Reading Attributes

A ZigBee 3.0 application might require to read attribute values from a remote device. Attributes are read by sending a ‘read attributes’ request, normally from a client cluster to a server cluster. This request can be sent using a general ZCL function (see below) or using a function which is specific to the target cluster. The cluster-specific functions for reading attributes are covered in the chapters of this manual that describe the supported clusters.

Note: Users should enable read access to cluster attributes explicitly at compile-time as described in Section 1.3.

A ZCL function is provided for reading a set of attributes of a remote cluster instance, as described in Section 2.3.2.1. A function is also provided for reading a local cluster attribute value, as described in Section 2.3.2.2.

Reading a set of attributes of a remote cluster

This section describes the use of the function eZCL_SendReadAttributesRequest() to send a ‘read attributes’ request to a remote cluster in order to obtain the values of selected attributes. The resulting activities on the source and destination nodes are outlined below and illustrated in the figure ‘Write Attributes’ Request and Response below. The events generated from a ‘read attributes’ request are further described in Chapter 3.

Note: The described sequence is similar when using the cluster-specific ‘read attributes’ functions.

1. On Source Node

The function eZCL_SendReadAttributesRequest() is called to submit a request to read one or more attributes on a cluster on a remote node. The information required by this function includes the following:

  • Source endpoint (from which the read request is to be sent)

  • Address of destination node for request

  • Destination endpoint (on destination node)

  • Identifier of the cluster containing the attributes [enumerations provided]

  • Number of attributes to be read

  • Array of identifiers of attributes to be read [enumerations provided]

2. On Destination Node

On receiving the ‘read attributes’ request, the ZCL software on the destination node performs the following steps:

  1. Generates an E_ZCL_CBET_READ_REQUEST event for the destination endpoint callback function which, if required, can update the shared device structure that contains the attributes to be read, before the read takes place.

  2. If tasks within the application are not cooperative, the ZCL generates an E_ZCL_CBET_LOCK_MUTEX event for the endpoint callback function, which should lock the mutex that protects the shared device structure - for information on mutexes, refer to Appendix A.

  3. Reads the relevant attribute values from the shared device structure and creates a ‘read attributes’ response message containing the read values.

  4. If tasks within the application are not cooperative, the ZCL generates an E_ZCL_CBET_UNLOCK_MUTEXevent for the endpoint callback function, which should now unlock the mutex that protects the shared device structure (other application tasks can now access the structure).

  5. Sends the ‘read attributes’ response to the source node of the request.

3. On Source Node

On receiving the ‘read attributes’ response, the ZCL software on the source node performs the following steps:

  1. For each attribute listed in the ‘read attributes’ response, it generates an E_ZCL_CBET_READ_INDIVIDUAL_ATTRIBUTE_RESPONSE message for the source endpoint callback function, which may or may not take action on this message.

  2. On completion of the parsing of the ‘read attributes’ response, it generates a single E_ZCL_CBET_READ_ATTRIBUTES_RESPONSE message for the source endpoint callback function, which may or may not take action on this message. ‘Read Attributes’ Request and Response ||

Note: The ‘read attributes’ requests and responses arrive at their destinations as data messages. Such a message triggers a stack event of the type ZPS_EVENT_APS_DATA_INDICATION, which is handled as described in Section 3.2.

Parent topic:Reading Attributes

Reading an Attribute of a Local Cluster

An individual attribute of a cluster on the local node can be read using the function eZCL_ReadLocalAttributeValue(). The read value is returned by the function (in a memory location for which a pointer must be provided).

Parent topic:Reading Attributes

Parent topic:Accessing Attributes