Commissioning Utility functions

The following Commissioning Utility functions are provided:

  1. eCLD_ZllUtilityCreateUtility

  2. eCLD_ZllUtilityCommandEndpointInformationCommandSend

  3. eCLD_ZllUtilityCommandGetGroupIdReqCommandSend

  4. eCLD_ZllUtilityCommandGetGroupIdRspCommandSend

  5. eCLD_ZllUtilityCommandGetEndpointListReqCommandSend

  6. eCLD_ZllUtilityCommandGetEndpointListRspCommandSend

  7. eCLD_ZllUtilityCommandHandler

eCLD_ZllUtilityCreateUtility

teZCL_Status eCLD_ZllUtilityCreateUtility(
        tsZCL_ClusterInstance *psClusterInstance,
        bool_t bIsServer,
        tsZCL_ClusterDefinition *psClusterDefinition,
        void *pvSharedStructPtr,
        tsZCL_AttributeStatus psAttributeStatus,
        tsCLD_ZllUtilityCustomDataStructure
    *psCustomDataStructure);

Description

This function creates a Touchlink Commissioning cluster instance for the Commissioning Utility. The cluster instance is created on the endpoint of the calling application, which should be the main application on the node. The type of cluster instance (server or client) to be created must be specified.

Parameters

  • psClusterInstance Pointer to cluster instance structure on local endpoint

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

  • TRUE - server

  • FALSE - client

  • psClusterDefinition Pointer to cluster definition structure containing information about the cluster

  • pvSharedStructPtr Pointer to structure containing the shared storage for the cluster

  • psAttributeStatus Pointer to a structure containing the storage for each attribute’s status

  • psCustomDataStructure Pointer to custom data to be provided to the cluster (see Section 44.8.20)

Returns

  • E_ZCL_SUCCESS

Parent topic:Commissioning Utility functions

eCLD_ZllUtilityCommandEndpointInformationCommandSend

teZCL_Status eCLD_ZllUtilityCommandEndpointInformationCommandSend(
        uint8 u8SrcEndpoint,
        uint8 u8DstEndpoint,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        tsCLD_ZllUtility_EndpointInformationCommandPayload
*psPayload);

Description

This function is used to send an Endpoint Information command to provide a remote endpoint with general information about the local endpoint (this may prompt the remote endpoint to request further information about the local endpoint). The function would typically be used to send local endpoint information from a ‘teacher’ node to a ‘learner’ node, in order to facilitate two-way communication between the Commissioning Utilities on the two nodes.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the command. The TSN in the response is set to match the specified TSN, allowing an incoming response to be paired with the original command. This is useful when sending more than one command to the same destination endpoint.

Parameters

  • u8SrcEndpoint Number of local endpoint (1-240)

  • u8DstEndpoint Number of destination endpoint (1-240)

  • psDestinationAddress Pointer to stucture containing address information for target node

  • pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the command

  • psPayload Pointer to structure to contain payload data for the Endpoint Information command (see Section 44.8.20)

Returns

  • E_ZCL_SUCCESS

Parent topic:Commissioning Utility functions

eCLD_ZllUtilityCommandGetGroupIdReqCommandSend

teZCL_Status eCLD_ZllUtilityCommandGetGroupIdReqCommandSend(
        uint8 u8Srcendpoint,
        uint8 u8DstEndpoint,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        uint8 u8StartIndex);

Description

This function is used to send a Get Group Identifiers Request command to obtain information about the groups (of lights) that have been configured on a remote endpoint. The function would typically be used on a ‘learner’ node to request the groups that have been configured on a ‘teacher’ node.

The first group from the groups list to be included in the returned information must be specified in terms of an index.

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

  • u8SrcEndpoint Number of local endpoint (1-240)

  • u8DstEndpoint Number of destination endpoint (1-240)

  • psDestinationAddress Pointer to stucture containing address information for target node

  • pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request

  • u8StartIndex Index in group list of the first group to include in the returned information

Returns

  • E_ZCL_SUCCESS

Parent topic:Commissioning Utility functions

eCLD_ZllUtilityCommandGetGroupIdRspCommandSend

PUBLIC teZCL_Status   eCLD_ZllUtilityCommandGetGroupIdRspCommandSend(
        uint8 u8SrcEndpoint,
        uint8 u8DstEndpoint,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        uint8 u8StartIndex);

Description

This function is used to send a Get Group Identifiers Response command containing information about the groups (of lights) that have been configured on the local endpoint. The function would typically be used on a ‘teacher’ node to respond to a Get Group Identifiers Request from a ‘learner’ node.

The first group from the groups list to be included in the returned information must be specified in terms of an index. The returned information includes this index, the number of (consecutive) groups included and the identifier of each group.

The specified Transaction Sequence Number (TSN) of the response must match the TSN of the corresponding request, as this will allow the response to be paired with the request at the destination.

Parameters

  • u8SrcEndpoint Number of local endpoint (1-240)

  • u8DstEndpoint Number of destination endpoint (1-240)

  • psDestinationAddress Pointer to stucture containing address information for target node

  • pu8TransactionSequenceNumber Pointer to location containing the Transaction Sequence Number (TSN) of the response

  • u8StartIndex Index in group list of the first group to include in the returned information

Returns

  • E_ZCL_SUCCESS

Parent topic:Commissioning Utility functions

eCLD_ZllUtilityCommandGetEndpointListReqCommandSend

teZCL_Status eCLD_ZllUtilityCommandGetEndpointListReqCommandSend(
        uint8 u8SrcEndpoint,
        uint8 u8DstEndpoint,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        uint8 u8StartIndex);

Description

This function is used to send a Get Endpoint List Request command to obtain information about controlled endpoints. The function would typically be used on a ‘learner’ node to request the remote endpoints that a ‘teacher’ node controls.

The first endpoint from the endpoints list to be included in the returned information must be specified in terms of an index.

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

  • u8SrcEndpoint Number of local endpoint (1-240)

  • u8DstEndpoint Number of destination endpoint (1-240)

  • psDestinationAddress Pointer to stucture containing address information for target node

  • pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request

  • u8StartIndex Index in endpoint list of the first endpoint to include in the returned information

Returns

  • E_ZCL_SUCCESS

Parent topic:Commissioning Utility functions

eCLD_ZllUtilityCommandGetEndpointListRspCommandSend

PUBLIC teZCL_Status eCLD_ZllUtilityCommandGetEndpointListRspCommandSend(
        uint8 u8SrcEndpoint,
        uint8 u8DstEndpoint,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        uint8 u8StartIndex);

Description

This function is used to send a Get Endpoint List Response command containing information about controlled endpoints. The function would typically be used on a ‘teacher’ node to respond to a Get Endpoint List Request from a ‘learner’ node.

The first endpoint from the endpoints list to be included in the returned information must be specified in terms of an index. The returned information will include this index, the number of (consecutive) endpoints included and the information about each endpoint (including endpoint number, identifier of resident ZigBee device and version of this device).

The specified Transaction Sequence Number (TSN) of the response must match the TSN of the corresponding request, as this will allow the response to be paired with the request at the destination.

Parameters

  • u8SrcEndpoint Number of local endpoint (1-240)

  • u8DstEndpoint Number of destination endpoint (1-240)

  • psDestinationAddress Pointer to stucture containing address information for target node

  • pu8TransactionSequenceNumber Pointer to location containing the Transaction Sequence Number (TSN) of the response

  • u8StartIndex Index in endpoint list of the first endpoint to include in the returned information

Returns

  • E_ZCL_SUCCESS

Parent topic:Commissioning Utility functions

eCLD_ZllUtilityCommandHandler

teZCL_Status eCLD_ZllUtilityCommandHandler(
    ZPS_tsAfEvent *pZPSevent,
    tsZCL_EndPointDefinition *psEndPointDefinition,
    tsZCL_ClusterInstance *psClusterInstance);

Description

This function parses a ZigBee PRO event and invokes the user-defined callback function that has been registered for the device (using the relevant endpoint registration function).

The registered user-defined callback function must be designed to handle events associated with the Commissioning Utility.

Parameters

  • pZPSevent        Pointer to received ZigBee PRO event

  • psEndPointDefinition        Pointer to structure which defines endpoint on which the Commissioning Utility resides

  • psClusterInstance        Pointer to Touchlink Commissioning cluster instance structure

Returns

  • E_ZCL_SUCCESS

Parent topic:Commissioning Utility functions

Parent topic:Functions