Poll Control Cluster

This chapter describes the Poll Control cluster which provides an interface for remotely controlling the rate at which a ZigBee End Device polls its parent for data.

The Poll Control cluster has a Cluster ID of 0x0020.

Overview

An End Device cannot receive data packets directly, as it might be asleep when a packet arrives. The data packets for an End Device are therefore buffered by the device’s parent and the End Device polls its parent for data while awake. An individual data packet is only held on the parent node for a maximum of 7.68 seconds and if many packets for the End Device are expected over a short period of time, the End Device should retrieve these packets as quickly as possible. An End Device can implement two polling modes, which are dependent on the poll interval (time-period between consecutive polls):

• Normal poll mode: A long poll interval is used - this mode is appropriate when the End Device is not expecting data packets.

• Fast poll mode: A short poll interval is used - this mode is appropriate when the End Device is expecting data packets.

The End Device may enable fast poll mode itself when it is expecting data packets (for example, after it has requested data from remote nodes). The Poll Control cluster allows fast poll mode to be selected from a remote control device to force the End Device to be more receptive to data packets (for example, when a download to the End Device involving a large number of unsolicited data packets is to be initiated).

The two sides of the cluster are located as follows:

• The cluster server is implemented on the End Device to be controlled

• The cluster client is implemented on the remote controller device

The cluster server (End Device) periodically checks whether the cluster client (remote controller) requires the poll mode to be changed. This ‘check-in’ method is used since an unsolicited instruction from the controller may arrive when the End Device is asleep. The automatic ‘check-ins’ are conducted with all the remote endpoints (on controller nodes) to which the local endpoint (on which the cluster resides) is bound.

The cluster is enabled by defining CLD_POLL_CONTROL in the zcl_options.h file. Further compile-time options for the Poll Control cluster are detailed in Section 20.10.

Parent topic:Poll Control Cluster

Cluster structure and attributes

The structure definition for the Poll Control cluster (server) is:

typedef struct
{
#ifdef POLL_CONTROL_SERVER
    zuint32     u32CheckinInterval;
    zuint32     u32LongPollInterval;
    zuint16     u16ShortPollInterval;
    zuint16     u16FastPollTimeout;
#ifdef CLD_POLL_CONTROL_ATTR_CHECKIN_INTERVAL_MIN
    zuint32     u32CheckinIntervalMin;
#endif
#ifdef CLD_POLL_CONTROL_ATTR_LONG_POLL_INTERVAL_MIN
    zuint32     u32LongPollIntervalMin;
#endif
#ifdef CLD_POLL_CONTROL_ATTR_FAST_POLL_TIMEOUT_MAX
    zuint16     u16FastPollTimeoutMax;
#endif
#endif
    zuint16     u16ClusterRevision;
} tsCLD_PollControl;

where:

• u32CheckinInterval is the ‘check-in interval’, used by the server in checking whether a client requires the poll mode to be changed - this is the period, in quarter-seconds, between consecutive checks. The valid range of values is 1 to 7208960. A user-defined minimum value for this attribute can be set via the optional attribute u32CheckinIntervalMin (see below). Zero is a special value indicating that the Poll Control cluster server is disabled. The default value is 14400 (1 hour).

• u32LongPollInterval is the ‘long poll interval’ of the End Device, employed when operating in normal poll mode - this is the period, in quarter-seconds, between consecutive polls of the parent for data. The valid range of values is 4 to 7208960. A user-defined minimum value for this attribute can be set via the optional attribute u32LongPollIntervalMin (see below). 0xFFFF is a special value indicating that the long poll interval is unknown/undefined. The default value is 20 (5 seconds).

• u16ShortPollInterval is the ‘short poll interval’ of the End Device, employed when operating in fast poll mode - this is the period, in quarter-seconds, between consecutive polls of the parent for data. The valid range of values is 1 to 65535 and the default value is 2 (0.5 seconds).

• u16FastPollTimeout is the ‘fast poll timeout’ representing the time-interval, in quarter-seconds, for which the server should normally stay in fast poll mode (unless over-ridden by a client command). The valid range of values is 1 to 65535. It is recommended that this timeout is greater than 7.68 seconds. A user-defined maximum value for this attribute can be set via the optional attribute u16FastPollTimeoutMax (see below). The default value is 40

  (10 seconds).

• u32CheckinIntervalMin is an optional lower limit on the ‘check-in interval’ defined by u32CheckinInterval. This limit can be used to ensure that the interval is not inadvertently set to a low value which will quickly drain the energy resources of the End Device node.

• u32LongPollIntervalMin is an optional lower limit on the ‘long poll interval’ defined by u32LongPollInterval. This limit can be used to ensure that the interval is not inadvertently set (for example, by another device) to a low value which will quickly drain the energy resources of the End Device node.

• u16FastPollTimeoutMax is an optional upper limit on the ‘fast poll timeout’ defined by u16FastPollTimeout. This limit can be used to ensure that the interval is not inadvertently set (for example, by another device) to a high value which quickly drains the energy resources of the End Device node.

Note:

1. Valid ranges (maximum and minimum values) for the four mandatory attributes can alternatively be set using macros in the zcl_options.h file, as described in Section 20.10. Some of these macros can only be used when the equivalent optional attribute is disabled.

2. For general guidance on attribute settings, refer to Section 20.3. Configuration through the attributes is also described in Section 20.4.2.

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

Parent topic:Poll Control Cluster

Attribute Settings

In assigning user-defined values to the mandatory attributes, the following inequality should be obeyed:

u32CheckinInterval ≥ u32LongPollInterval ≥ u16ShortPollInterval

In addition, the mandatory attribute u16FastPollTimeout should not be set to an excessive value for self-powered nodes, as fast poll mode can rapidly drain the stored energy of a node (for example, the battery).

The three optional attributes can be used to ensure that the values of the corresponding mandatory attributes are kept within reasonable limits, to prevent the rapid depletion of the energy resources of the node. If required, the optional attributes must be enabled and initialized in the compile-time options (see Section 20.10).

Minimum and maximum values for all the mandatory attributes can alternatively be set using the compile-time options (again, refer to Section 20.10).

Parent topic:Poll Control Cluster

Poll Control Operations

This section describes the main operations to be performed on the Poll Control cluster server (End Device) and client (controller).

Initialization

The Poll Control cluster must be initialized on both the cluster server and client. This can be done using the function eCLD_PollControlCreatePollControl(), which creates an instance of the Poll Control cluster on a local endpoint.

If you are using a standard ZigBee device which includes the Poll Control cluster, the above function is automatically called by the initialization function for the device. You only need to call eCLD_PollControlCreatePollControl() explicitly 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).

Parent topic:Poll Control Operations

Configuration

When initialized, the Poll Control cluster adopts the attribute values that are pre-set in the tsCLD_PollControl structure (see Section 20.2). For the optional attributes, values can be set in the file zcl_options.h (see Section 20.10).

The mandatory attributes (and related optional attributes) are as follows:

• Long Poll Interval (**u32LongPollInterval**): This is the polling period used in normal poll mode, expressed in quarter-seconds, with a default value of 20 (5 seconds). The attribute has a valid range of 4 to 7208960 but a user-defined minimum value for this attribute can be set via the optional ‘long poll interval maximum’ attribute (u32LongPollIntervalMin). This limit can be used to ensure that the interval is not inadvertently set (for example, by another device) to a low value which quickly drains the energy resources of the End Device node. Alternatively, minimum and maximum values can be specified through the compile-time options (see Section 20.10).

• Short Poll Interval (**u16ShortPollInterval**): This is the polling period used in fast poll mode, expressed in quarter-seconds, with a default value of 2 (0.5 seconds). The attribute has a valid range of 1 to 65535. User-defined minimum and maximum values for this attribute can be specified through the compile-time options (see Section 20.10).

• Fast Poll Timeout (**u16FastPollTimeout**): This is the time-interval for which the server should normally stay in fast poll mode (unless over-ridden by a client command), expressed in quarter-seconds, with a default value of 40 (10 seconds). It is recommended that this timeout is greater than 7.68 seconds. The valid range of values is 1 to 65535 but a user-defined maximum value for this attribute can be set via the optional ‘fast poll timeout maximum’ attribute (u16FastPollTimeoutMax). This limit can be used to ensure that the interval is not inadvertently set (for example, by another device) to a high value which quickly drains the energy resources of the End Device node. Alternatively, minimum and maximum values can be specified through the compile-time options (see Section 20.10).

• Check-in Interval (**u32CheckinInterval**): This is the period between the server’s checks of whether a client requires the poll mode to be changed, expressed in quarter-seconds, with a default value of 14400 (1 hour). It should be greater than the ‘long poll interval’ (see above). Zero is a special value indicating that the Poll Control cluster server is disabled. Otherwise, the valid range of values is 1 to 7208960 but a user-defined minimum value for this attribute can be set via the optional ‘check-in interval minimum’ attribute (u32CheckinIntervalMin). This limit can be used to ensure that the interval is not inadvertently set to a low value which quickly drains the energy resources of the End Device node. Alternatively, minimum and maximum values can be specified through the compile-time options (see Section 20.10).

The Poll Control cluster server can also be configured by the server application at run-time by writing to the relevant attribute(s) using the eCLD_PollControlSetAttribute() function (which must be called separately for each attribute to be modified). If used, this function must be called after the cluster has been initialized (see Section 20.4.1).

Changes to certain attributes can also be initiated remotely from the cluster client (controller) using the following functions:

• eCLD_PollControlSetLongPollIntervalSend(): The client application can use this function to submit a request to set the ‘long poll interval’ attribute on the server to a specified value. This function causes a ‘Set Long Poll Interval’ command to be sent to the relevant End Device. If the new value is acceptable, the cluster server automatically updates the attribute.

• eCLD_PollControlSetShortPollIntervalSend(): The client application can use this function to submit a request to set the ‘short poll interval’ attribute on the server to a specified value. This function causes a ‘Set Short Poll Interval’ command to be sent to the relevant End Device. If the new value is acceptable, the cluster server automatically updates the attribute.

In both of the above cases, a response is only sent back to the client if the new value is not acceptable, in which case a ZCL ‘default response’ is sent indicating an invalid value.

Use of the above two functions requires the corresponding commands to be enabled in the compile-time options, as described in Section 20.10.

Note: Changes to attribute values initiated by either the server application or client application takes effect immediately. So, for example, if the End Device is operating in fast poll mode when the ‘short 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.

Before the first scheduled ‘check-in’ (after one hour, by default), the End Device application should set up bindings between the local endpoint on which the cluster resides and the relevant endpoint on each remote controller node with which the End Device operates. These bindings are used while sending the ‘Check-in’ commands.

Parent topic:Poll Control Operations

Operation

After initialization, the Poll Control cluster server on the End Device begins to operate in normal poll mode and performs the following activities (while the End Device is awake):

• Periodically poll the parent for data packets at a rate determined by the ‘long poll interval’.

• Periodically check whether any bound cluster clients require the server to enter fast poll mode, with ‘check-ins’ at a rate determined by the ‘check-in interval’.

The server application must provide the cluster with timing prompts for the above periodic activities. These prompts are produced by periodically calling the function eCLD_PollControlUpdate(). The periods of the above activities are defined in terms of quarter-seconds. Therefore, this function must be called every quarter-second and the application must provide a 250 ms software timer to schedule these calls. Any poll or check-in that is due when this function is called is automatically performed by the cluster server.

The End Device operates in normal poll mode until either it puts itself into fast poll mode (for example, when it is expecting responses to a request) or the controller (client) requests the End Device to enter fast poll mode (for example, when a data download to the End Device is going to be performed). As indicated above, such a request from the client is raised as the result of the server performing periodic ‘check-ins’ with the client.

On receiving a ‘check-in’ command, an E_CLD_POLL_CONTROL_CMD_CHECK_IN event is generated on the client. The client application must then fill in the tsCLD_PollControl_CheckinResponsePayload structure (see Section 20.9.2) of the event, indicating whether fast poll mode is required. A response is then automatically sent back to the server.

After sending the initial Check-in command, the server waits for up to 7.68 seconds for a response (if no response is received in this time, the server is free to continue in normal poll mode). If a response is received from a client, the event E_CLD_POLL_CONTROL_CMD_CHECK_IN is generated on the server, where this event indicates the processing status of the received response. The server also sends this status back to the responding client in a ZCL default response.

• If the response was received from a bound client within the timeout period of the initial Check-in command, the status is ZCL_SUCCESS. In this case, the End Device is automatically put into fast poll mode.

• If the response is invalid for some reason, an error status is indicated as described below in Section 20.4.3.2, and fast poll mode is not entered.

When the End Device is in fast poll mode, the client application can request the cluster server to exit fast poll mode immediately (before the timeout expires) by calling the function eCLD_PollControlFastPollStopSend().

Fast Poll Mode Timeout

In the Check-in response from a client, the payload (see Section 20.9.2) may contain an optional timeout value which, if used, specifies the length of time that the device should remain in fast poll mode (this timeout value will be used instead of the one specified through the ‘fast poll timeout’ attribute). If the response payload specifies an out-of-range timeout value, the server will send a ZCL default response with status INVALID_VALUE to the client (see Section 20.4.3.2). In the case of multiple clients (controllers) that have specified different timeout values, the server will use the largest timeout value received.

Parent topic:Operation

Invalid Check-in Responses

The server may receive Check-in responses which cannot result in fast poll mode. In these cases, the server sends a ZCL default response indicating the relevant error status (which is not ZCL_SUCCESS) back to the originating client. The following circumstances will lead to such a default response:

• The Check-in response is from an unbound client. In this case, the Default Response will contain the status ACTION_DENIED.

• The Check-in response is from a bound client but requests an invalid fast poll timeout value (see Section 20.4.3.1). In this case, the default response will contain the status INVALID_VALUE.

• The Check-in response is from a bound client but arrives after the timeout period of the original Check-in command. In this case, the default response will contain the status TIMEOUT.

Parent topic:Operation

Parent topic:Poll Control Operations

Parent topic:Poll Control Cluster

Poll Control Events

The Poll Control cluster has its own events that are handled through the callback mechanism described in Chapter 3. The cluster contains its own event handler. However, if a device uses this cluster then application-specific Poll Control event handling must be included in the user-defined callback function for the associated endpoint, where this callback function is registered through the relevant endpoint registration function. This callback function will then be invoked when a Poll Control event occurs and needs the attention of the application.

For a Poll Control event, the eEventType field of the tsZCL_CallBackEvent structure is set to E_ZCL_CBET_CLUSTER_CUSTOM. This event structure also contains an element sClusterCustomMessage, which is itself a structure containing a field pvCustomData. This field is a pointer to the following tsCLD_PollControlCallBackMessage structure:

typedef struct
{
 uint8 u8CommandId;
 union
 {
 tsCLD_PollControl_CheckinResponsePayload *psCheckinResponsePayload;
 #ifdef CLD_POLL_CONTROL_CMD_SET_LONG_POLL_INTERVAL 
 tsCLD_PollControl_SetLongPollIntervalPayload    
            *psSetLongPollIntervalPayload;
 #endif
 #ifdef CLD_POLL_CONTROL_CMD_SET_SHORT_POLL_INTERVAL    
       tsCLD_PollControl_SetShortPollIntervalPayload  
    *psSetShortPollIntervalPayload;
 #endif
 } uMessage;
} tsCLD_PollControlCallBackMessage;

The above structure is fully described in Section 20.9.1.

When a Poll Control event occurs, one of the command types listed in Table 29 is specified through the u8CommandId field of the structure tsCLD_PollControlCallBackMessage. This command type determines which command payload is used from the union uMessage.

u8CommandId Enumeration	Description/Payload Type
On Client
E_CLD_POLL_CONTROL_CMD_CHECK_IN	A Check-in command has been received by the client.
On Server
E_CLD_POLL_CONTROL_CMD_CHECK_IN	A Check-in Response has been received by the server, following a previously sent Check-In command.

tsCLD_PollControl_CheckinResponsePayload

| |E_CLD_POLL_CONTROL_CMD_FAST_POLL_STOP|A ‘Fast Poll Stop’ command has been received by the server.| |E_CLD_POLL_CONTROL_CMD_SET_LONG_POLL_INTERVAL|A ‘Set Long Poll Interval’ command has been received by the server.

tsCLD_PollControl_SetLongPollIntervalPayload

| |E_CLD_POLL_CONTROL_CMD_SET_SHORT_POLL_INTERVAL|A ‘Set Short Poll Interval’ command has been received by the server.

tsCLD_PollControl_SetShortPollIntervalPayload

|

Parent topic:Poll Control Cluster

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 functions are described in Section 20.6.1

• Server functions are described in Section 20.6.2

• Client functions are described in Section 20.6.3

Server/Client Function

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

• eCLD_PollControlCreatePollControl

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

• eCLD_PollControlSetAttribute

• eCLD_PollControlUpdateSleepInterval

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

Return codes

The Poll Control cluster functions use the ZCL return codes, listed in Section 7.2.

Parent topic:Poll Control Cluster

Enumerations

‘Attribute ID’ enumerations

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

 typedef enum PACK
{
 E_CLD_POLL_CONTROL_ATTR_ID_CHECKIN_INTERVAL 0x0000,
 E_CLD_POLL_CONTROL_ATTR_ID_LONG_POLL_INTERVAL,
 E_CLD_POLL_CONTROL_ATTR_ID_SHORT_POLL_INTERVAL,
 E_CLD_POLL_CONTROL_ATTR_ID_FAST_POLL_TIMEOUT,
 E_CLD_POLL_CONTROL_ATTR_ID_CHECKIN_INTERVAL_MIN,
 E_CLD_POLL_CONTROL_ATTR_ID_LONG_POLL_INTERVAL_MIN,
 E_CLD_POLL_CONTROL_ATTR_ID_FAST_POLL_TIMEOUT_MAX;
}teCLD_PollControl_Cluster_AttrID;

Parent topic:Enumerations

‘Command’ Enumerations

The following enumerations represent the commands that the Poll Control cluster generates.

typedef enum PACK
{
  E_CLD_POLL_CONTROL_CMD_CHECK_IN = 0x00,
  E_CLD_POLL_CONTROL_CMD_FAST_POLL_STOP,
  E_CLD_POLL_CONTROL_CMD_SET_LONG_POLL_INTERVAL,
  E_CLD_POLL_CONTROL_CMD_SET_SHORT_POLL_INTERVAL,
} teCLD_PollControl_CommandID;

The above enumerations are used to indicate types of Poll Control cluster events and are described in Section 20.5.

Parent topic:Enumerations

Parent topic:Poll Control Cluster

Structures

tsCLD_PPCallBackMessage

For a Poll Control event, the eEventType field of the tsZCL_CallBackEvent structure is set to E_ZCL_CBET_CLUSTER_CUSTOM. This event structure also contains an element sClusterCustomMessage, which is itself a structure containing a field pvCustomData. This field is a pointer to the following tsCLD_PollControlCallBackMessage structure:

typedef struct
{
 uint8 u8CommandId;
 union
 {
 tsCLD_PollControl_CheckinResponsePayload *psCheckinResponsePayload;
 #ifdef CLD_POLL_CONTROL_CMD_SET_LONG_POLL_INTERVAL      
 tsCLD_PollControl_SetLongPollIntervalPayload           
        *psSetLongPollIntervalPayload;
  #endif
  #ifdef CLD_POLL_CONTROL_CMD_SET_SHORT_POLL_INTERVAL    
  tsCLD_PollControl_SetShortPollIntervalPayload   
        *psSetShortPollIntervalPayload;
  #endif
 } uMessage;
} tsCLD_PollControlCallBackMessage;

where:

• u``8CommandId indicates the type of Poll Control command that has been received, one of:

  • E_CLD_POLL_CONTROL_CMD_CHECK_IN

  • E_CLD_POLL_CONTROL_CMD_FAST_POLL_STOP

  • E_CLD_POLL_CONTROL_CMD_SET_LONG_POLL_INTERVAL

  • E_CLD_POLL_CONTROL_CMD_SET_SHORT_POLL_INTERVAL

    • If they are required, the last two commands must be enabled in the compile-time options, as described in Section 20.10.

• uMessage is a union containing the command payload, as one of (depending on the value of u8CommandId):

  • psCheckinResponsePayload is a pointer to the payload of a ‘Check-in Response’ (see Section 20.9.2)

  • psSetLongPollIntervalPayload is a pointer to the payload of a ‘Set Long Poll Interval’ command (see Section 20.9.3)

  • psSetShortPollIntervalPayload is a pointer to the payload of a ‘Set Short Poll Interval’ command (see Section 20.9.4)

The command payload for each command type is indicated in Table 29 in Section 20.5.

Parent topic:Structures

tsCLD_PollControl_CheckinResponsePayload

This structure contains the payload of a ‘Check-in Response’, which is sent from the client to the server in reply to a ‘Check-in’ command from the server.

typedef struct
{
  zbool   bStartFastPolling;
  zuint16  u16FastPollTimeout;
}tsCLD_PollControl_CheckinResponsePayload;

where:

• bStartFastPolling is a boolean indicating whether or not the End Device is required to enter fast poll mode:

  • TRUE: Enter fast poll mode

  • FALSE: Continue in normal poll mode

• u16FastPollTimeout is an optional fast poll mode timeout, in quarter-seconds, in the range 1 to 65535 - that is, the period of time for which the End Device should remain in fast poll mode (if this mode is requested through bStartFastPolling). Zero is a special value which indicates that the value of the ‘fast poll timeout’ attribute should be used instead (see Section 20.2). If a non-zero value is specified then this value over-rides the ‘fast poll timeout’ attribute (but does not over-write it).

Parent topic:Structures

tsCLD_PollControl_SetLongPollIntervalPayload

This structure contains the payload of a ‘Set Long Poll Interval’ command, which is sent from the client to the server to request a new ‘long poll interval’ for use in normal poll mode.

typedef struct
{
 zuint32  u32NewLongPollInterval;
}tsCLD_PollControl_SetLongPollIntervalPayload;

where u32NewLongPollInterval is the required value of the ‘long poll interval’, in quarter-seconds, in the range 4 to 7208960. This value is used to over-write the corresponding cluster attribute 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).

To use the ‘Set Long Poll Interval’ command, it must be enabled in the compile-time options, as described in Section 20.10.

Parent topic:Structures

tsCLD_PollControl_SetShortPollIntervalPayload

This structure contains the payload of a ‘Set Short Poll Interval’ command, which is sent from the client to the server to request a new ‘short poll interval’ for use in fast poll mode.

typedef struct
{
 zuint16  u16NewShortPollInterval;
}tsCLD_PollControl_SetShortPollIntervalPayload;

where u16NewShortPollInterval is the required value of the ‘short poll interval’, in quarter-seconds, in the range 1 to 65535. This value is used to over-write the corresponding cluster attribute 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).

To use the ‘Set Short Poll Interval’ command, it must be enabled in the compile-time options, as described in Section 20.10.

Parent topic:Structures

tsCLD_PollControlCustomDataStructure

The Poll Control 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
{
#ifdef POLL_CONTROL_SERVER 
    tsCLD_PollControlParameters         sControlParameters;
#endif    
    tsZCL_ReceiveEventAddress           sReceiveEventAddress;
    tsZCL_CallBackEvent                 sCustomCallBackEvent;
    tsCLD_PollControlCallBackMessage    sCallBackMessage;
} tsCLD_PollControlCustomDataStructure;

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

Parent topic:Structures

Parent topic:Poll Control Cluster

Compile-time Options

This section describes the compile-time options that may be configured in the zcl_options.h file of an application that uses the Poll Control cluster.

To enable the Poll Control cluster in the code to be built, it is necessary to add the following line to the file:

#define CLD_POLL_CONTROL

In addition, to enable the cluster as a client or server, it is also necessary to add one of the following lines to the same file:

#define POLL_CONTROL_SERVER
#define POLL_CONTROL_CLIENT

The following options can also be configured at compile-time in the zcl_options.h file.

Optional Server Attributes

To enable and assign a value (t quarter-seconds) to the optional Check-in Interval Minimum (u32CheckinIntervalMin) attribute, add the line:

#define CLD_POLL_CONTROL_ATTR_CHECKIN_INTERVAL_MIN t

To enable and assign a value (t quarter-seconds) to the optional Long Poll Interval Minimum (u32LongPollIntervalMin) attribute, add the line:

#define CLD_POLL_CONTROL_ATTR_LONG_POLL_INTERVAL_MIN t

To enable and assign a value (t quarter-seconds) to the optional Fast Poll Timeout Maximum (u16FastPollTimeoutMax) attribute, add the line:

#define CLD_POLL_CONTROL_ATTR_FAST_POLL_TIMEOUT_MAX t

Note: For further information on the above optional server attributes, refer to Section 20.2.

Global Attributes

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

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

Set Valid Range for ‘Check-in Interval’

To set the maximum possible ‘check-in interval’ (to t quarter-seconds), add the line:

#define CLD_POLL_CONTROL_CHECKIN_INTERVAL_MAX t

The default value is 7208960.

To set the minimum possible ‘check-in interval’ (to t quarter-seconds), add the line:

#define CLD_POLL_CONTROL_CHECKIN_INTERVAL_MIN t

The default value is 0.

This minimum value is only applied if the Check-in Interval Minimum attribute (u32CheckinIntervalMin) is not enabled.

Set Valid Range for ‘Fast Poll Timeout’

To set the maximum possible ‘fast poll timeout’ (to t quarter-seconds), add the line:

#define CLD_POLL_CONTROL_FAST_POLL_TIMEOUT_MAX t

The default value is 65535.

To set the minimum possible ‘fast poll timeout’ (to t quarter-seconds), add the line:

#define CLD_POLL_CONTROL_FAST_POLL_TIMEOUT_MIN t

The default value is 1.

This maximum value is only applied if the Fast Poll Timeout Maximum attribute (u16FastPollTimeoutMax) is not enabled.

Set Valid Range for ‘Long Poll Interval’

To set the maximum possible ‘long poll interval’ (to t quarter-seconds), add the line:

#define CLD_POLL_CONTROL_LONG_POLL_INTERVAL_MAX t

The default value is 7208960.

To set the minimum possible ‘long poll interval’ (to t quarter-seconds), add the line:

#define CLD_POLL_CONTROL_LONG_POLL_INTERVAL_MIN t

The default value is 4.

This minimum value is only applied if the Long Poll Interval Minimum attribute (u32LongPollIntervalMin) is not enabled.

Set Valid Range for ‘Short Poll Interval’

To set the maximum possible ‘short poll interval’ (to t quarter-seconds), add the line:

#define CLD_POLL_CONTROL_SHORT_POLL_INTERVAL_MAX t

The default value is 65535.

To set the minimum possible ‘short poll interval’ (to t quarter-seconds), add the line:

#define CLD_POLL_CONTROL_SHORT_POLL_INTERVAL_MIN t

The default value is 1.

Optional Commands

To enable the optional ‘Set Long Poll Interval’ command, add the line:

#define CLD_POLL_CONTROL_CMD_SET_LONG_POLL_INTERVAL        

To enable the optional ‘Set Short Poll Interval’ command, add the line:

#define CLD_POLL_CONTROL_CMD_SET_SHORT_POLL_INTERVAL 

Maximum Number of Clients

To set the maximum number of clients for a server to n, add the line:

#define CLD_POLL_CONTROL_NUMBER_OF_MULTIPLE_CLIENTS n

This is the maximum number of clients from which the server can handle Check-in Responses. It should be equal to the capacity (number of entries) of the binding table created on the server device to accommodate bindings to client devices (where this size is set in a ZigBee network parameter using the ZPS Configuration Editor).

Disable APS Acknowledgments for Bound Transmissions

To disable APS acknowledgments for bound transmissions from this cluster, add the line:

#define CLD_POLL_CONTROL_BOUND_TX_WITH_APS_ACK_DISABLED

Parent topic:Poll Control Cluster