Functions

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

eCLD_GroupsCreateGroups

teZCL_Status eCLD_GroupsCreateGroups(
    tsZCL_ClusterInstance *psClusterInstance,
    bool_t bIsServer,
    tsZCL_ClusterDefinition *psClusterDefinition,
    void *pvEndPointSharedStructPtr,
    tsCLD_GroupsCustomDataStructure
    *psCustomDataStructure,
    tsZCL_EndPointDefinition *psEndPointDefinition);

Description

This function creates an instance of the Groups 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 a Groups 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: Do not call this function 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 Groups 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 retrieves any group IDs already stored in the Application Information Base (AIB) of the ZigBee PRO stack. However, the AIB does not store group names. If name support is required, the application should store the group names using the NVM module, so that they can be retrieved following a power outage.

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 Groups cluster. This parameter can refer to a pre-filled structure called sCLD_Groups which is provided in the Groups.h file.
pvEndPointSharedStructPtr: Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_Groups which defines the attributes of Groups cluster. The function initializes the attributes with default values.
psCustomDataStructure: Pointer to a structure containing the storage for internal functions of the cluster (see [Section 12.6.1](custom_data_structure.md #id_1d50fd17-874c-48c4-b748-e26925fd08d3)).
psEndPointDefinition: Pointer to the ZCL endpoint definition structure for the application (see Section 6.1.1).

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_NULL

Parent topic:Functions

eCLD_GroupsAdd

teZCL_Status eCLD_GroupsAdd(uint8 u8SourceEndPointId,
    uint16 u16GroupId,
    uint8 *pu8GroupName);

Description

This function adds the specified endpoint on the local node to the group with the specified group ID/address and specified group name. The relevant entry is modified in the Group table on the local endpoint (of the calling application). If the group does not currently exist, it is created by adding a new entry for the group to the Group table.

Note that the number of entries in the Group table must not exceed the value of CLD_GROUPS_MAX_NUMBER_OF_GROUPS defined at compile time (see Section 12.8).

Parameters

u8SourceEndPointId: Number of local endpoint to be added to group.
u16GroupId: 16-bit group ID/address of group.
pu8GroupName: Pointer to character string representing name of group.

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

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_GroupsCommandAddGroupRequestSend

teZCL_Status eCLD_GroupsCommandAddGroupRequestSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_Groups_AddGroupRequestPayload
    *psPayload);

Description

This function sends an Add Group command to a remote device, requesting that the specified endpoints on the target device be added to a group. The group ID/address and name (if supported) are specified in the payload of the message, and must be added to the Group table on the target node along with the associated endpoint numbers.

The device receiving this message generates a callback event on the endpoint on which the Groups cluster is registered. Also, add the group to its Group table before sending a response indicating success or failure (see Section 12.6.4).

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 this message (see Section 12.6.3).

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_GroupsCommandViewGroupRequestSend

teZCL_Status eCLD_GroupsCommandViewGroupRequestSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_Groups_ViewGroupRequestPayload
    *psPayload);

Description

This function sends a View Group command to a remote device, requesting the name of the group with the specified group ID (address) on the destination endpoint.

The device receiving this message generates a callback event on the endpoint on which the Groups cluster was registered and generates a View Group response containing the group name (see Section 12.6.4).

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 this message (see Section 12.6.3).

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_GroupsCommandGetGroupMembershipRequestSend

teZCL_Status eCLD_GroupsCommandGetGroupMembershipRequestSend
    (uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_Groups_GetGroupMembershipRequestPayload
    *psPayload);

Description

This function sends a Get Group Membership command to inquire whether the target endpoint is a member of any of the groups specified in a list contained in the command payload.

The device receiving this message generates a callback event on the endpoint on which the Groups cluster is registered and generates a Get Group Membership response containing the required information (see Section 12.6.4).

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 this message (see Section 12.6.3).

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_GroupsCommandRemoveGroupRequestSend

teZCL_Status eCLD_GroupsCommandRemoveGroupRequestSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_Groups_RemoveGroupRequestPayload
    *psPayload);

Description

This function sends a Remove Group command to request that the target device deletes membership of the destination endpoints from a particular group - that is, remove the endpoints from the entry of the group in the Group table on the device and, if no other endpoints remain in the group, remove the group from the table.

The device receiving this message generates a callback event on the endpoint on which the Groups cluster is registered. If the group becomes empty following the deletion, the device removes the group ID and group name from its Group table. It then generates an appropriate Remove Group response indicating success or failure (see Section 12.6.4).

If the target endpoint belongs to a scene associated with the group to be removed (requiring the Scenes cluster - see Chapter 13), the endpoint is also removed from this scene as a result of this function call - that is, the relevant scene entry is deleted from the Scene table on the target device.

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: The 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 this message (see Section 12.6.3).

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_GroupsCommandRemoveAllGroupsRequestSend

teZCL_Status eCLD_GroupsCommandRemoveAllGroupsRequestSend
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber);

Description

This function sends a Remove All Groups command to request that the target device removes all group memberships of the destination endpoints. Issuing this command removes the endpoints from all group entries in the Group table on the device. If no other endpoints remain in a group, the function removes the group from the table.

The device receiving this message generates a callback event on the endpoint on which the Groups cluster is registered. If a group becomes empty following the deletion, the device removes the group ID and group name from its Group table.

If the target endpoint belongs to scenes associated with the groups to be removed, calling this function also removes the endpoint from the scenes. The relevant scene entries are deleted from the Scene table on the target device. (For details about the Scenes cluster - refer to Chapter 13).

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: The 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

The eCLD_GroupsCommandRemoveAllGroupsRequestSend function invokes the ZigBee PRO stack function to transmit the data. If the ZigBee PRO stack function returns an error, the same can be obtained by calling the eZCL_GetLastZpsError() function.

Parent topic:Functions

eCLD_GroupsCommandAddGroupIfIdentifyingRequestSend

teZCL_Status eCLD_GroupsCommandAddGroupIfIdentifyingRequestSend
    (uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_Groups_AddGroupRequestPayload
    *psPayload);

Description

This function sends an Add Group If Identifying command to a remote device, requesting that the specified endpoints on the target device be added to a particular group on the condition that the remote device is identifying itself. The group ID/address and name (if supported) are specified in the payload of the message, and must be added to the Group table on the target node along with the associated endpoint numbers. The identifying functionality is controlled using the Identify cluster (see Chapter 11).

The device receiving this message generates a callback event on the endpoint on which the Groups cluster is registered and then checks whether the device is identifying itself. If so, the device (if possible) adds the group ID and group name to its Group table. If the device is not identifying itself, then no action is taken.

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 this message (see Section 12.6.3).

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:Groups Cluster