Functions

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

• eCLD_IdentifyCreateIdentify

• eCLD_IdentifyCommandIdentifyRequestSend

• eCLD_IdentifyCommandTriggerEffectSend

• eCLD_IdentifyCommandIdentifyQueryRequestSend

• eCLD_IdentifyEZModeInvokeCommandSend

• eCLD_IdentifyUpdateCommissionStateCommandSend

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