5.1.7.3.1 ZCL_AttributeReq Function

Syntax

void ZCL_AttributeReq(ZCL_Request_t *req);

Description

This function sends a general ZCL command related to attributes to a remote device.

The application can use this function to read/write attributes from a remote device, report local attributes and discover attributes supported by a particular cluster on a remote device.

The commands parameters include addressing information, callback functions, the command’s ID and the payload. The payload can be formed using the ZCL_PutNextElement() function and an instance of the ZCL_NextElement_t type. Use the command to perform actions on multiple attributes simultaneously. For example, it can read several attributes from a remote device.

In general, the application sends attribute-related commands to specific short or extended addresses. Sending such commands to bound devices (employing APS_NO_ADDRESS mode) can not be as efficient because in case of receiving responses from more than one device, the ZCL component is going to process only the first one.

The callback function specified in the req->ZCL_Notify field is called twice for most commands (excluding reporting).
  1. To confirm that the command was sent.
  2. After receiving the response command.

To differentiate these, the callback’s argument includes the ZCL_Notify_t-id field, which equals ZCL_APS_CONFIRM_ID in the first case and the ZCL_ZCL_RESPONSE_ID in the second.

The common uses of the function include sending the following commands (ensure to assign the following the command’s ID to the req->id field):
  • ZCL_READ_ATTRIBUTES_COMMAND_ID – Reading remote attributes (obtaining values)
  • ZCL_WRITE_ATTRIBUTES_COMMAND_ID – Writing remote attributes (assigning new values)
  • ZCL_REPORT_ATTRIBUTES_COMMAND_ID – Reporting local attributes to remote devices (sending current attribute’s values)
  • ZCL_DISCOVER_ATTRIBUTES_COMMAND_ID – Discovering attributes of a remote device (obtaining data types and IDs of attributes supported by a particular cluster)
  • ZCL_DISCOVER_COMMANDS_RECEIVED_COMMAND_ID – Discovering the commands received (obtaining the list of commands those can be received and processed)
  • ZCL_DISCOVER_COMMANDS_GENEARATED_COMMAND_ID – Discovering the commands generated (obtaining the list of commands those can be generated and processed)
  • ZCL_DISCOVER_ATTRIBUTES_EXTENDED_COMMAND_ID – Discovering attributes of a remote device (obtaining data types, access control and IDs of attributes supported by a particular cluster)

The response statuses, accessed via the argument’s ZCL_Notify_t-status field of the callback function specified in the req->ZCL_Notify field, are as follows:

  • All commands:
    • ZCL_SUCCESS_STATUS (0x00) – The request is executed successfully (all attributes are written, read or reported and more).
    • ZCL_INSUFFICIENT_SPACE_STATUS (0x89) – The ZCL buffer is not big enough to hold the request’s payload.
    • ZCL_UNSUPPORTED_ATTRIBUTE_STATUS (0x86) – An attribute specified in the request is not supported by the destination node.
    • ZCL_INVALID_FIELD_STATUS (0x85) – A command’s field contains an incorrect value.
    • ZCL_INVALID_DATA_TYPE_STATUS (0x8D) – Wrong attribute type was specified.
    • ZCL_TIMEOUT_STATUS (0x94) – The response command is expected but not received in time; the timeout, based on network parameters (such as max network depth), occurred.
  • Write attributes command:
    • ZCL_WRITE_ATTRIBUTES_FAILURE_STATUS (0x0F) – Not all attributes are written; see individual statuses of attribute records to check each attribute.
  • Report attributes command:
    • ZCL_UNREPORTABLE_ATTRIBUTE_STATUS (0x8C) – The requested attribute is not reportable.
Input Parameters
Parameter NameDescription
reqCommand parameters
Return Type and Values
  • None