Functions

The Poll Control cluster functions are described in the following three sub-sections, according to the side(s) of the cluster on which they can be used:

Server/Client Function

The following Poll Control cluster function can be used on either a cluster server or cluster client:

eCLD_PollControlCreatePollControl

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

Description

This function creates an instance of the Poll Control 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 should only 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 will create a Poll Control cluster instance on the endpoint, but instances of other clusters may also be created on the same endpoint by calling their corresponding creation functions. For more details of creating cluster instances on custom endpoints, refer to Appendix D.

Note: This function must 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 from those described in the ZigBee Devices User Guide (JNUG3131).

When used, this function must be the first Poll Control 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 is automatically adjusted by the compiler using the following declaration:

uint8 au8PollControlAttributeControlBits
[(sizeof(asCLD_PollControlClusterAttrDefs) / sizeof(tsZCL_AttributeDefinition))];

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 Poll Control cluster. This parameter can refer to a pre-filled structure called sCLD_PollControl which is provided in the PollControl.h file.

  • pvEndPointSharedStructPtr: Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_PollControl which defines the attributes of the Poll Control 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). For a cluster client, set this pointer to NULL.

  • psCustomDataStructure: Pointer to a structure containing the storage for internal functions of the cluster (see Section 20.9.5).

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_INVALID_VALUE

Parent topic:Server/Client Function

Parent topic:Functions

Server Functions

The following Poll Control cluster functions can be used on a cluster server only:

eCLD_PollControlUpdate

teZCL_Status eCLD_PollControlUpdate(void);

Description

This function can be used on a cluster server to update the timing status for the following periodic activities:

  • polling of the parent for a data packet

  • ‘check-ins’ with the client to check for a required change in the poll mode

The function should be called once per quarter-second and the application should provide a 250-ms timer to prompt these function calls.

Any poll or check-in that is due when this function is called are automatically performed by the cluster server.

Parameters

  • None

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

Parent topic:Server Functions

eCLD_PollControlSetAttribute

teZCL_Status eCLD_PollControlSetAttribute(
    uint8 u8SourceEndPointId,
    uint8 u8AttributeId,
    uint32 u32AttributeValue);*

Description

This function can be used on a cluster server to write to an attribute of the Poll Control cluster. The function writes to the relevant field of the tsCLD_PollControlstructure (detailed in Section 20.2). The attribute to be accessed is specified using its attribute identifier - enumerations are provided (see Section 20.8.1).

Therefore, this function can be used to change the configuration of the Poll Control cluster. The change takes effect immediately. So, for example, if the End Device is in normal poll mode when the ‘long poll interval’ is modified, the polling period is immediately re-timed to the new value. If the modified attribute is not related to the currently operating poll mode, the change is implemented the next time the relevant poll mode is started.

The specified value of the attribute is validated by the function. If this value is out-of-range for the attribute, the status E_ZCL_ERR_INVALID_VALUE is returned.

Parameters

  • u8SourceEndPointId: Number of local endpoint on which cluster resides

  • u8AttributeId : Identifier of attribute to be written to (see Section 20.8.1)

  • u32AttributeValue: Value to be written to attribute

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

  • E_ZCL_ERR_INVALID_VALUE

  • E_ZCL_DENY_ATTRIBUTE_ACCESS

Parent topic:Server Functions

eCLD_PollControlUpdateSleepInterval

teZCL_Status eCLD_PollControlUpdateSleepInterval(
    uint32 u32QuarterSecondsAsleep);

Description

This function can be used on a cluster server to provide the updated ticks back into PollControl cluster for the time the device was sleeping in terms of quarter second.

This function updates the Checkin period based on the ticks provided.

Parameters

  • u32QuarterSecondsAsleep: Number of Quarter seconds the device has slept for

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

Parent topic:Server Functions

Parent topic:Functions

Client Functions

The following Poll Control cluster functions can be used on a cluster client only:

  1. eCLD_PollControlSetLongPollIntervalSend

  2. eCLD_PollControlSetShortPollIntervalSend

  3. eCLD_PollControlFastPollStopSend

eCLD_PollControlSetLongPollIntervalSend

teZCL_Status eCLD_PollControlSetLongPollIntervalSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_PollControl_SetLongPollIntervalPayload
    *psPayload);

Description

This function can be used on a cluster client to send a ‘Set Long Poll Interval’ command to the cluster server. This command requests the ‘long poll interval’ for normal poll mode on the End Device to be set to the specified value.

On receiving the command, the ‘long poll interval’ attribute is only modified by the server if the specified value is within the valid range for the attribute (including greater than or equal to the optional user-defined minimum, if set) - see Section 20.2. If this is not the case, the server replies to the client with a ZCL ‘default response’ indicating an invalid value.

The change takes effect immediately. So, if the End Device is in normal poll mode when the ‘long poll interval’ is modified, the polling period is immediately re-timed to the new value.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the message. 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 local endpoint on which cluster client resides

  • u8DestinationEndPointId: Number of remote endpoint on which cluster server resides

  • psDestinationAddress: Pointer to a structure containing the destination address of the server node

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

  • psPayload: Pointer to structure containing the payload for the command (see Section 20.9.3), including the desired long poll interval

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

  • 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

Parent topic:Client Functions

eCLD_PollControlSetShortPollIntervalSend

teZCL_Status eCLD_PollControlSetShortPollIntervalSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_PollControl_SetShortPollIntervalPayload *psPayload);

Description

This function can be used on a cluster client to send a ‘Set Short Poll Interval’ command to the cluster server. This command requests the ‘short poll interval’ for fast poll mode on the End Device to be set to the specified value.

On receiving the command, the ‘short poll interval’ attribute is only modified by the server if the specified value is within the valid range for the attribute (including greater than or equal to the optional user-defined minimum, if set) - see Section 20.2. If this is not the case, the server replies to the client with a ZCL ‘default response’ indicating an invalid value.

The change takes effect immediately. So, if the End Device is in fast poll mode when the ‘short poll interval’ is modified, the polling period is immediately re-timed to the new value.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the message. 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 local endpoint on which cluster client resides

  • u8DestinationEndPointId: Number of remote endpoint on which cluster server resides

  • psDestinationAddress: Pointer to a structure containing the destination address of the server node

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

  • psPayload: Pointer to a structure containing the payload for the command (see Section 20.9.4), including the desired short poll interval

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

  • 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

Parent topic:Client Functions

eCLD_PollControlFastPollStopSend

teZCL_Status eCLD_PollControlFastPollStopSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
uint8 *pu8TransactionSequenceNumber);

Description

This function can be used on a cluster client to send a ‘Fast Poll Stop’ command to the cluster server. This command is intended to abort a fast poll mode episode which has been started on the server as the result of a ‘Check-in Response’. Therefore, the command allows fast poll mode to be exited before the mode’s timeout is reached.

The cluster server only stops fast poll mode on the destination End Device if a matching ‘Fast Poll Stop’ command has been received for every request to start the current episode of fast poll mode. Therefore, if the current fast poll mode episode resulted from multiple start requests from multiple clients, the episode cannot be prematurely stopped (before the timeout is reached) unless a ‘Fast Poll Stop’ command is received from each of those clients.

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the message. 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 local endpoints on which the cluster client resides

  • u8DestinationEndPointId: Number of remote endpoints on which the cluster server resides

  • psDestinationAddress: Pointer to a structure containing the destination address of the server node

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

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

  • 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

Parent topic:Client Functions

Parent topic:Functions

Parent topic:Poll Control Cluster