Identify Cluster

This chapter describes the Identify cluster which allows a device to identify itself (for example, by flashing an LED on the node).

The Identify cluster has a Cluster ID of 0x0003.

Overview

The Identify cluster allows the host device to be put into identification mode in which the node highlights itself in some way to an observer (in order to distinguish itself from other nodes in the network). It is recommended that identification mode should involve flashing a light with a period of 0.5 seconds.

To use the functionality of this cluster, you must include the file Identify.h in your application and enable the cluster by defining CLD_IDENTIFY in the zcl_options.h file.

It is also necessary to enable the cluster as a server or client, or as both:

  • The cluster server is able to receive commands to start and stop identification mode on the local device.

  • The cluster client is able to send the above commands to the server (and therefore control identification mode on the remote device)

The inclusion of the client or server software must be pre-defined in compile-time options of the application. In addition, if the cluster is to reside on a custom endpoint then the role of client or server must also be specified when creating the cluster instance.

The compile-time options for the Identify cluster are fully detailed in Section 11.9.

Note: The Identify cluster contains optional functionality for the EZ-mode Commissioning module, which is part of the ZigBee Base Device functionality and is described in the ZigBee Devices User Guide (JNUG3131).

Parent topic:Identify Cluster

Identify Cluster Structure and Attribute

The structure definition for the Identify cluster is:

typedef struct
{
#ifdef IDENTIFY_SERVER    
    zuint16                 u16IdentifyTime;
#ifdef CLD_IDENTIFY_ATTR_COMMISSION_STATE
    zbmap8                  u8CommissionState;
#endif  
#endif
    zuint16                 u16ClusterRevision;
} tsCLD_Identify;

Where:

  • u16IdentifyTime is a mandatory attribute specifying the remaining length of time, in seconds, that the device continues in identification mode. Setting the attribute to a non-zero value puts the device into identification mode and the attribute is then decremented every second.

  • u8CommissionState is an optional attribute for use with EZ-mode Commissioning (see Chapter 40) to indicate the network status and operational status of the node - this information is contained in a bitmap, as follows:

Bits

Description

0

Network State

  • 1 if in the correct network (must be 1 if Operational State bit is 1)

  • 0 if not in a network, or in a temporary network, or network status is unknown

| |1|Operational State

  • 1 if commissioned for operation (Network State bit is set to 1)

  • 0 if not commissioned for operation

| |2 - 7|Reserved|

u16ClusterRevision is a mandatory attribute that specifies the revision of the cluster specification on which this 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 (see Section 2.4).

Parent topic:Identify Cluster

Initialization

The function eCLD_IdentifyCreateIdentify() is used to create an instance of the Identify cluster. This function is called by the initialization function for the host device but can alternatively be used directly by the application in setting up a custom endpoint which supports the Identify cluster (among others).

Parent topic:Identify Cluster

Sending Commands

The NXP implementation of the ZCL provides functions for sending commands between an Identify cluster client and server.

Starting and Stopping Identification Mode

The function eCLD_IdentifyCommandIdentifyRequestSend() is used on the cluster client to send a command to the cluster server requesting identification mode to be started or stopped on the server device. The required action is contained in the payload of the command (see Section 11.7.2):

  • Setting the payload element u16IdentifyTime to a non-zero value has the effect of requesting that the server device enters identification mode for a time (in seconds) corresponding to the specified value.

  • Setting the payload element u16IdentifyTime to zero has the effect of requesting the immediate termination of any identification mode that is in progress on the server device.

Identification mode can alternatively be started and stopped on a light of a remote node as described in Section 11.4.2.

Parent topic:Sending Commands

Requesting Identification Effects

The function eCLD_IdentifyCommandTriggerEffectSend() can be used to request a particular identification effect or behavior on a light of a remote node. This function can be used for entering and leaving identification mode instead of eCLD_IdentifyCommandIdentifyRequestSend().

The possible behaviors that can be requested are as follows:

  • Blink: Light is switched on and then off (once)

  • Breathe: Light is switched on and off by smoothly increasing and then decreasing its brightness over a 1 second period, and then this process is repeated 15 times.

  • Okay:

    • Colour light goes green for 1 second.

    • Monochrome light flashes twice in 1 second.

  • Channel change:

    • Colour light goes orange for 8 seconds.

    • Monochrome light switches to maximum brightness for 0.5 s and then to minimum brightness for 7.5 s.

  • Finish effect: Current stage of effect is completed and then identification mode is terminated (for example, for the Breathe effect, only the current 1 second cycle is completed).

  • Stop effect: Current effect and identification mode are terminated as soon as possible.

Parent topic:Sending Commands

Inquiring about Identification Mode

The function eCLD_IdentifyCommandIdentifyQueryRequestSend() is called on an Identify cluster client in order to request a response from a server cluster when it is in identification mode. This request should only be unicast.

Parent topic:Sending Commands

Using EZ-mode Commissioning Features

The Identify cluster also contains the following optional features that can be used with EZ-mode commissioning, which is a part of the ZigBee Base Device functionality and is described in the ZigBee Devices User Guide (JNUG3131).

‘EZ-mode Invoke’ Command

The ‘EZ-mode Invoke’ command is supported which allows a device to schedule and start one or more stages of EZ-mode commissioning on a remote device. The command is issued by calling the eCLD_IdentifyEZModeInvokeCommandSend() function and allows the following stages to be specified:

  1. Factory Reset: EZ-mode commissioning configuration of the destination device to be reset to ‘Factory Fresh’ settings.

  2. Network Steering: Destination device to be put into the ‘Network Steering’ phase.

  3. Find and Bind: Destination device to be put into the ‘Find and Bind’ phase.

On receiving the command, the event E_CLD_IDENTIFY_CMD_EZ_MODE_INVOKE is generated on the remote device, indicating one or more requested commissioning actions. The local application must perform these actions using the functions of the EZ-mode Commissioning module. If more than one stage is specified, they must be performed sequentially in the above order and must be contiguous.

If the ‘EZ-mode Invoke’ command is to be used by an application, its use must be enabled at compile time (see Section 11.9).

‘Commissioning State’ Attribute

The Identify cluster server contains an optional ‘Commissioning State’ attribute, u8CommissionState (see Section 11.2), which indicates whether the local device is:

  • a member of the (correct) network

  • in a commissioned state and ready for operation

If the ‘Commissioning State’ attribute is to be used by an application, its use must be enabled at compile time (see Section 11.9).

The EZ-mode initiator can send an ‘Update Commission State’ command to the target device in order to update the commissioning state of the target. The command is issued by calling the eCLD_IdentifyUpdateCommissionStateCommandSend() function. On receiving this command on the target, the ‘Commissioning State’ attribute is automatically updated. It is good practice for the EZ-mode initiator to send this command to notify the target device when commissioning is complete.

Parent topic:Sending Commands

Parent topic:Identify Cluster

Sleeping Devices in Identification Mode

In some cases, a device might sleep between activities (for example, a switch that is configured as a sleeping End Device) and is also operating in identification mode. In such a case, the device must wake once per second for the ZCL to decrement the u16IdentifyTime attribute (see Section 11.2), which represents the time remaining in identification mode. The device may also use this wake time to highlight itself, for example, flash an LED. The attribute is automatically updated by the ZCL when the application passes an E_ZCL_CBET_TIMER event to the ZCL via the vZCL_EventHandler() function. The ZCL also automatically increments ZCL time as a result of this event.

When in identification mode, it is not permissible for a device to sleep for longer than 1 second, and to generate one timer event on waking. Before entering sleep, the value of the u16IdentifyTime attribute can be checked. If this value is zero, the device is not in identification mode and is therefore allowed to sleep for longer than 1 second.

For details of updating ZCL time following a prolonged sleep, refer to Section 18.4.1.

Parent topic:Identify Cluster

Functions

The following Identify cluster functions are provided in the NXP implementation of the ZCL:

eCLD_IdentifyCreateIdentify

teZCL_Status eCLD_IdentifyCreateIdentify(
        tsZCL_ClusterInstance *psClusterInstance,
        bool_t bIsServer,
        tsZCL_ClusterDefinition *psClusterDefinition,
        void *pvEndPointSharedStructPtr,
        uint8 *pu8AttributeControlBits,
        tsCLD_IdentifyCustomDataStructure
    *psCustomDataStructure);

Description

This function creates an instance of the Identify 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 must 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 Identify cluster instance on the endpoint, but instances of other clusters may also be created on the same endpoint by calling their corresponding creation functions.

Note: This function should 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.

When used, this function must be the first Identify 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 should therefore equate to the total number of attributes supported by the Identify cluster. The function initializes the array elements to zero.

Parameters

  • psClusterInstance: Pointer to structure containing information about the cluster instance to be created (see Section 6.1.16). This structure is updated by the function by initializing individual structure fields.

  • bIsServer: Type of cluster instance (server or client) to be created:

    • TRUE - server

    • FALSE - client

  • psClusterDefinition: Pointer to structure indicating the type of cluster to be created (see Section 6.1.2). In this case, this structure must contain the details of the Identify cluster. This parameter can refer to a pre-filled structure called sCLD_Identify which is provided in the Identify.h file.

  • pvEndPointSharedStructPtr: Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_Identify which defines the attributes of Identify cluster. The function initializes the attributes with default values.

  • pu8AttributeControlBits: Pointer to an array of uint8 values, with one element for each attribute in the cluster (see above).

  • psCustomDataStructure: Pointer to the structure that contains custom data for the Identify cluster (see Section 11.7.1). This structure is used for internal data storage. No knowledge of the fields of this structure is required.

Returns

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_SUCCESS

Parent topic:Functions

eCLD_IdentifyCommandIdentifyRequestSend

teZCL_Status eCLD_IdentifyCommandIdentifyRequestSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_Identify_IdentifyRequestPayload *psPayload);

Description

This function can be called on a client device to send a custom command requesting that the recipient server device either enters or exits identification mode. The required action (start or stop identification mode) must be specified in the payload of the custom command (see Section 11.7.2). The required duration of the identification mode is specified in the payload and this value replaces the value in the Identify cluster structure on the target device.

A device which receives this command generates a callback event on the endpoint on which the Identify cluster was registered.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. 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

  • u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the command and to identify the instance of the shared structure holding the required attribute values.

  • u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP.

  • psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent.

  • pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request.

  • psPayload: Pointer to a structure containing the payload for the command (see Section 11.7.2).

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_IdentifyCommandTriggerEffectSend

teZCL_Status eCLD_IdentifyCommandTriggerEffectSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    teCLD_Identify_EffectId eEffectId,
    uint8 u8EffectVariant);

Description

This function can be called on a client device to send a custom command to a server device, in order to control the identification effect on a light of the target node. Therefore, this function can be used to start and stop identification mode instead of eCLD_IdentifyCommandIdentifyRequestSend(). Use of the ‘Trigger Effect’ function must be enabled via a compile-time option, as described in Section 11.9.

The following effect commands can be sent using this function:

Effect command

Description

Blink

Light is switched on and then off (once)

Breathe

Light is switched on and off by smoothly increasing and then decreasing its brightness over a 1-second period, and then this is repeated 15 times

Okay

- Color light goes green for 1 second

  • Monochrome light flashes twice in 1 second

| |Channel change|- Color light goes orange for 8 seconds

  • Monochrome light switches to

maximum brightness for 0.5 s and then to

minimum brightness for 7.5 s

| |Finish effect|Current stage of effect is completed and then identification mode is terminated (for example, for the Breathe effect, only the current 1-second cycle is completed)| |Stop effect|Current effect and identification mode are terminated as soon as possible|

A variant of the selected effect can also be specified, but currently only the default (as described above) is available.

A device which receives this command generates a callback event on the endpoint on which the Identify cluster was registered.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. 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

  • u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values.

  • u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP.

  • psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent.

  • pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request.

  • eEffectId: Effect command to send (see above), one of:

    • E_CLD_IDENTIFY_EFFECT_BLINK

    • E_CLD_IDENTIFY_EFFECT_BREATHE

    • E_CLD_IDENTIFY_EFFECT_OKAY

    • E_CLD_IDENTIFY_EFFECT_CHANNEL_CHANGE

    • E_CLD_IDENTIFY_EFFECT_FINISH_EFFECT

    • E_CLD_IDENTIFY_EFFECT_STOP_EFFECT

  • u8EffectVariant: Required variant of specified effect - set to zero for default (as no variants are currently available).

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_IdentifyCommandIdentifyQueryRequestSend

tsZCL_Status eCLD_IdentifyCommandIdentifyQueryRequestSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber);

Description

This function can be called on a client device to send a custom command requesting a response from any server devices that are currently in identification mode.

A device which receives this command generates a callback event on the endpoint on which the Identify cluster is registered. If the receiving device is in identification mode, it returns a response containing the amount of time for which it continues in this mode (see Section 11.7.3).

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. 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

  • u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values.

  • u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP.

  • psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent.

  • pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request.

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_IdentifyEZModeInvokeCommandSend

teZCL_Status eCLD_IdentifyEZModeInvokeCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    bool bDirection,
    tsCLD_Identify_EZModeInvokePayload
    *psPayload);

Description

This function can be used to send an ‘EZ-mode Invoke’ to a remote device. The sent command requests one or more of the following stages of the EZ-mode commissioning process to be performed on the destination device. EZ-mode commissioning is a part of the ZigBee Base Device functionality and is described in the ZigBee Devices User Guide (JNUG3131).

  1. Factory Reset - clears all bindings, group table entries, and the u8CommissionState attribute, and reverts to the ‘Factory Fresh’ settings.

  2. Network Steering - puts the destination device into the ‘Network Steering’ phase.

  3. Find and Bind - puts the destination device into the ‘Find and Bind’ phase.

The required stages are specified in a bitmap in the command payload structure tsCLD_Identify_EZModeInvokePayload (see Section 11.7.4). If more than one stage is specified, they must be performed in the above order and be contiguous.

On receiving the ‘EZ-mode Invoke’ command on the destination device, an E_CLD_IDENTIFY_CMD_EZ_MODE_INVOKE event is generated with the required commissioning actions specified in the u8Action field of the tsCLD_Identify_EZModeInvokePayload structure. It is the responsibility of the local application to perform the requested actions using the functions of the EZ-mode Commissioning module (see Section 40.6).

Note that the ‘EZ-mode Invoke’ command is optional and, if necessary, must be enabled in the compile-time options (see Section 11.9).

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. 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

  • u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values.

  • u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP.

  • psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent.

  • pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request.

  • bDirection: Boolean indicating the direction of the command, as follows (this should always be set to TRUE):

    • TRUE - Identify cluster client to server

    • FALSE - Identify cluster server to client

  • psPayload: Pointer to a structure containing the payload for the command (see Section 11.7.4).

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_IdentifyUpdateCommissionStateCommandSend

teZCL_Status eCLD_IdentifyUpdateCommissionStateCommandSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_Identify_UpdateCommissionStatePayload
*psPayload);

Description

This function can be used to send an ‘Update Commission State’ command from an EZ-mode initiator device (cluster client) to a target device (cluster server) in order to update the (optional) u8CommissionState attribute (see Section 11.2) which is used for EZ-mode commissioning (which is part of the ZigBee Base Device functionality and is described in the ZigBee Devices User Guide (JNUG3131)). The command allows individual bits of u8CommissionState to be set or cleared (see Section 11.7.4).

On receiving the ‘Update Commission State’ command on the target device, an event is generated and the requested update is automatically performed.

Note that the u8CommissionState attribute is optional and, if necessary, must be enabled in the compile-time options (see Section 11.9).

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. 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

  • u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values.

  • u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP.

  • psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent.

  • pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request.

  • psPayload: Pointer to a structure containing the payload for the command (see Section 11.7.4).

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

Parent topic:Identify Cluster

Structures

Custom Data Structure

The Identity 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_IdentifyCallBackMessage         sCallBackMessage;
        } tsCLD_IdentifyCustomDataStructure;

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

Parent topic:Structures

Custom Command Payloads

The following structure contains the payload for an Identify cluster custom command (sent using the function eCLD_IdentifyCommandIdentifyRequestSend()):

/* Identify request command payload */
typedef struct
{
    zuint16                 u16IdentifyTime;
} tsCLD_Identify_IdentifyRequestPayload;

where u16IdentifyTime is the amount of time, in seconds, for which the target device is to remain in identification mode. If this element is set to 0x0000 and the target device is in identification mode, the mode is terminated immediately.

Parent topic:Structures

Custom Command Responses

The following structure contains the response to a query whether a device is in identification mode (the original query is sent using the function eCLD_IdentifyCommandIdentifyQueryRequestSend()):

/* Identify query response command payload */
typedef struct
{
    zuint16                 u16Timeout;
} tsCLD_Identify_IdentifyQueryResponsePayload;

where u16Timeout is the amount of time, in seconds, that the responding device remains in identification mode.

Parent topic:Structures

EZ-mode Commissioning Command Payloads

The structures described below may be used when the Identify cluster is used with EZ-mode commissioning (which is part of the ZigBee Base Device functionality and is described in the ZigBee Devices User Guide (JNUG3131)).

‘EZ-Mode Invoke’ Command Payload

The following structure is used when sending an ‘EZ-mode Invoke’ command (using the eCLD_IdentifyEZModeInvokeCommandSend() function).

typedef struct
{
    zbmap8    u8Action;
} tsCLD_Identify_EZModeInvokePayload;

where u8Action is a bitmap specifying the EZ-mode commissioning actions to be performed on the destination device - a bit is set to ‘1’ if the corresponding action is required, or to ‘0’ if it is not required:

Bits

Action

0

Factory Reset - clears all bindings, group table entries, and the u8CommissionState attribute, and reverts to the ‘Factory Fresh’ settings

1

Network Steering - puts the device into the ‘Network Steering’ phase

2

Find and Bind - puts the device into the ‘Find and Bind’ phase

3 - 7

Reserved

‘Update Commission State’ Command Payload

The following structure is used when sending an ‘Update Commission State’ command (using the eCLD_IdentifyUpdateCommissionStateCommandSend() function), which requests an update to the value of the u8CommissionState attribute (for the definition of the attribute, refer to Section 11.2).

typedef struct
{
    zenum8    u8Action;
    zbmap8    u8CommissionStateMask;
} tsCLD_Identify_UpdateCommissionStatePayload;

where:

  • u8Action is a value specifying the action to perform (set or clear) on the u8CommissionState bits specified through u8CommissionStateMask:

    • 1: Set the specified bits to ‘1’.

    • 2: Clear the specified bits to ‘0’.

      • All other values are reserved.

  • u8CommissionStateMask is a bitmap in which the bits correspond to the bits of the u8CommissionState attribute. A bit of this field indicates whether the corresponding attribute bit is to be updated (according to the action specified in u8Action):

    • If a bit is set to ‘1’, the corresponding u8CommissionState bit should be updated.

    • If a bit is set to ‘0’, the corresponding u8CommissionState bit should not be updated.

Parent topic:Structures

Parent topic:Identify Cluster

Enumerations

teCLD_Identify_ClusterID

The following structure contains the enumerations used to identify the attributes of the Identify cluster.

typedef enum 
{
    E_CLD_IDENTIFY_ATTR_ID_IDENTIFY_TIME = 0x0000,   /* Mandatory */
    E_CLD_IDENTIFY_ATTR_ID_COMMISSION_STATE          /* Optional */
 } teCLD_Identify_ClusterID;

Parent topic:Enumerations

Parent topic:Identify Cluster

Compile-time options

To enable the Identify cluster in the code to be built, it is necessary to add the following to the zcl_options.h file:

#define CLD_IDENTIFY

In addition, to include the software for a cluster client or server or both, it is necessary to add one or both of the following to the same file:

#define IDENTIFY_CLIENT
#define IDENTIFY_SERVER

The following cluster functionality can be enabled or configured in zcl_options.h.

Cluster Revision

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

#define CLD_IDENTIFY_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).

Trigger Effect

Add this line to enable use of the eCLD_IdentifyCommandTriggerEffectSend() function to remotely start/stop identification mode:

#define CLD_IDENTIFY_CMD_TRIGGER_EFFECT

Enhanced Functionality for EZ-mode Commissioning

To enable the optional ‘Commission State’ attribute, you must include:

#define CLD_IDENTIFY_ATTR_COMMISSION_STATE

To enable the optional ‘EZ-mode Invoke’ command, you must include:

#define CLD_IDENTIFY_CMD_EZ_MODE_INVOKE

EZ-mode commissioning is part of the ZigBee Base Device functionality and is described in the ZigBee Devices User Guide (JNUG3131).

Parent topic:Identify Cluster