Functions

The following DRLC cluster functions are provided:

eSE_DRLCCreate

teZCL_Status eSE_DRLCCreate(
    bool_t bIsServer,
    uint8 u8NumberOfRecordEntries,
    uint8 *pu8AttributeControlBits,
    tsZCL_ClusterInstance *psClusterInstance,
    tsZCL_ClusterDefinition *psClusterDefinition,
    tsSE_DRLCCustomDataStructure
    *psCustomDataStructure,
    tsSE_DRLCLoadControlEventRecord
    *psDRLCLoadControlEventRecord,
    void *pvEndPointSharedStructPtr);

Description

This function creates an instance of the DRLC 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 creates a DRLC 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 (example, IPD) will be 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 DRLC 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 DRLC cluster.

The function initializes the array elements to zero.

Parameters

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

    • TRUE - server

    • FALSE - client

  • u8NumberOfRecordEntriesNumber of LCEs that can be stored in the LCE list, one of:

    • SE_DRLC_NUMBER_OF_SERVER_LOAD_CONTROL_ENTRIES

    • SE_DRLC_NUMBER_OF_CLIENT_LOAD_CONTROL_ENTRIES

  • pu8AttributeControlBitsPointer to an array of uint8 values, with one element for each attribute in the cluster (see above).

  • psClusterInstancePointer 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.

  • psClusterDefinitionPointer 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 DRLC cluster. This parameter can refer to a pre-filled structure called sCLD_DRLC which is provided in the DRLC.h file.

  • psCustomDataStructurePointer to structure which contains custom data for the DRLC cluster. This structure is used for internal data storage. No knowledge of the fields of this structure is required.

  • psDRLCLoadControlEventRecord

  • Pointer to a structure in which an LCE is stored

  • pvEndPointSharedStructPtrPointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_DRLC which defines the attributes of DRLC cluster. The function initializes the attributes with default values.

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eSE_DRLCAddLoadControlEvent

teSE_DRLCStatus eSE_DRLCAddLoadControlEvent(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address psDestinationAddress,
    tsSE_DRLCLoadControlEvent *psLoadControlEvent,
    uint8 *pu8TransactionSequenceNumber);

Description

This function can be used on the DRLC cluster server to add an LCE (received from the utility company) to the ‘Scheduled’ list. The function also sends the LCE to the specified DRLC cluster client endpoints, where it will also be added to the ‘Scheduled’ list. Note that the LCE will be added to the ‘Active’ lists on the relevant devices if a ‘start-time of now’ is specified in the LCE.

The LCE should normally be sent to client endpoints that have been previously bound to the cluster server. This is done by specifying an address type of E_ZCL_AM_BOUND in the tsZCL_Address structure - in this case, the address field of this structure and the destination endpoint in the function call are both ignored.

Parameters

  • u8SourceEndPointId: Number of the local endpoint through which the LCE is sent

  • u8DestinationEndPointId: Number of the remote endpoint to which the LCE is sent. Note that this parameter is ignored when sending to address types E_ZCL_AM_BOUND and E_ZCL_AM_GROUP

  • psDestinationAddress: Pointer to a ZCL structure containing the address of the remote node to which the LCE is sent

  • psLoadControlEvent: Pointer to a structure (see Section 41.11.1) which contains the LCE to be added and sent

  • pu8TransactionSequenceNumber: Pointer to a location to store the Transaction Sequence Number (TSN) of the packet sent

Returns

Any relevant DRLC return code listed in Section 41.9 or ZCL return code listed in Section 7.2

Parent topic:Functions

eSE_DRLCGetScheduledEventsSend

teSE_DRLCStatus eSE_DRLCGetScheduledEventsSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address psDestinationAddress,
    tsSE_DRLCGetScheduledEvents *psGetScheduledEvents,
    uint8 *pu8TransactionSequenceNumber);

Description

This function can be used on a DRLC cluster client to send a Get Scheduled Events message to the cluster server in order to request a list of scheduled (and active) LCEs. The function can be used to obtain the initial schedule of LCEs and to update the local LCE lists during operation (for example, if an End Device has been sleeping and has missed unsolicited LCE updates) - refer to Section 41.5.2.2 for more information on the use of this function.

As part of this function call, a tsSE_DRLCGetScheduledEvents structure must be provided which specifies the earliest start-time of the LCEs of interest and the maximum number of LCEs to be reported.

Parameters

  • u8SourceEndPointId: Number of the local endpoint through which the request is sent

  • u8DestinationEndPointId: Number of the remote endpoint to which the request is sent (this must be the DRLC cluster server endpoint)

  • psDestinationAddress: Pointer to a ZCL structure containing the address of the remote node to which the request is sent (this must be the address of the ESP)

  • psGetScheduledEvents: Pointer to a structure which contains the LCE requirements of the request (see Section 41.11.2)

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

Returns

Any relevant DRLC return code listed in Section 41.9 or ZCL return code listed in Section 7.2

Parent topic:Functions

eSE_DRLCCancelLoadControlEvent

teSE_DRLCStatus eSE_DRLCCancelLoadControlEvent(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address psDestinationAddress,
    tsSE_DRLCCancelLoadControlEvent
    *psCancelLoadControlEvent,
    uint8 *pu8TransactionSequenceNumber);

Description

This function can be used on the DRLC cluster server to cancel an LCE. The LCE is cancelled locally and the cancellation is also sent to the specified DRLC cluster client endpoints. The LCE is ultimately moved to the ‘Deallocated’ list.

The cancellation request should normally be sent to client endpoints that have been previously bound to the cluster server. This is done by specifying an address type of E_ZCL_AM_BOUND in the tsZCL_Address structure - in this case, the address field of this structure and the destination endpoint in the function call are both ignored.

The LCE cancellation requirements are specified in the structure tsSE_DRLCCancelLoadControlEvent, including the applicable device class(es) and enrolment group(s), as well as an immediate or randomized end (for a full description of the end-time options, refer to Section 41.5.3).

Parameters

  • u8SourceEndPointId: Number of the local endpoint through which the request is sent

  • u8DestinationEndPointId: Number of the remote endpoint to which the request is sent. Note that this parameter is ignored when sending to address types E_ZCL_AM_BOUND and E_ZCL_AM_GROUP

  • psDestinationAddress: Pointer to a ZCL structure containing the address of the remote node to which the request is sent

  • psCancelLoadControlEvent: Pointer to a structure which contains the LCE cancellation requirements (see Section 41.11.3)

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

Returns

Any relevant DRLC return code listed in Section 41.9 or ZCL return code listed in Section 7.2

Parent topic:Functions

eSE_DRLCCancelAllLoadControlEvents

teSE_DRLCStatus eSE_DRLCCancelAllLoadControlEvents(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address psDestinationAddress,
    teSE_DRLCCancelControl eCancelEventControl,
    uint8 *pu8TransactionSequenceNumber);

Description

This function can be used on the DRLC cluster server to cancel all LCEs. The LCEs are cancelled locally and the cancellation is also sent to the specified DRLC cluster client endpoints. The LCEs are ultimately moved to the ‘Deallocated’ list.

The cancellation request should normally be sent to client endpoints that have been previously bound to the cluster server. This is done by specifying an address type of E_ZCL_AM_BOUND in the tsZCL_Address structure - in this case, the address field of this structure and the destination endpoint in the function call are both ignored.

The LCE cancellation end-time requirement must be specified as an immediate or randomized end (for a full description of the end-time options, refer to Section41.5.3).

Parameters

  • u8SourceEndPointId: Number of the local endpoint through which the request is sent

  • u8DestinationEndPointId: Number of the remote endpoint to which the request is sent. Note that this parameter is ignored when sending to address types E_ZCL_AM_BOUND and E_ZCL_AM_GROUP

  • psDestinationAddress: Pointer to a ZCL structure containing the address of the remote node to which the request is sent

  • eCancelEventControl: Enumeration indicating an immediate or randomized end, one of:

  • E_SE_DRLC_CANCEL_CONTROL_IMMEDIATE

  • E_SE_DRLC_CANCEL_CONTROL_USE_RANDOMISATION

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

Returns

Any relevant DRLC return code listed in Section 41.9 or ZCL return code listed in Section 7.2

Parent topic:Functions

eSE_DRLCSetEventUserOption

teSE_DRLCStatus eSE_DRLCSetEventUserOption(
    uint32 u32IssuerId,
    uint8 u8SourceEndPointId,
    teSE_DRLCUserEventOption eEventOption);

Description

This function can be used on a DRLC cluster client to choose to participate or not participate in an individual LCE. By default, a client participates in an LCE, so normally this function only needs to be called if the client is to opt out of the LCE.

The function could be called following a button-press which results from a user decision to opt out of the LCE (for which information is displayed on the IPD screen).

When this function is called, a Report Event Status message is sent to the cluster server in order to indicate that the local client has opted out of the LCE. Once the LCE end-time has been reached, another Report Event Status message is sent to the server in order to confirm that the LCE has completed without the participation of the local client.

Parameters

  • u32IssuerId: Identifier of the LCE (as issued by the utility company)

  • u8SourceEndPointId: Number of the local endpoint where the LCE is located (endpoint corresponding to the DRLC cluster)

  • eEventOption: Required option, one of:

    • E_SE_DRLC_EVENT_USER_OPT_IN (participate)

    • E_SE_DRLC_EVENT_USER_OPT_OUT (do not participate)

Returns

Any relevant DRLC return code listed in Section 41.9 or ZCL return code listed in Section 7.2

Parent topic:Functions

eSE_DRLCSetEventUserData

teSE_DRLCStatus eSE_DRLCSetEventUserData(
    uint32 u32IssuerId,
    uint8 u8SourceEndPointId,
    teSE_DRLCUserEventSet eUserEventSetID,
    uint16 u16EventData);

Description

This function can be used on a DRLC cluster client to locally modify the load control data of an LCE. Any one of the following data values can be changed:

  • Criticality level

  • Cooling temperature set-point

  • Heating temperature set-point

  • Load adjustment percentage

  • Duty cycle

The function can be called multiple times to modify more than one of the above values. The data values are fully described in Section 41.11.1.

Parameters

  • u32IssuerId: Identifier of the LCE (as issued by the utility company)

  • u8SourceEndPointId: Number of the local endpoint where the LCE is located (endpoint corresponding to the DRLC cluster)

  • eUserEventSetID: Identifier of the load control data item to be modified, one of:

    • E_SE_DRLC_CRITICALITY_LEVEL_APPLIED

    • E_SE_DRLC_COOLING_TEMPERATURE_SET_POINT_APPLIED

    • E_SE_DRLC_HEATING_TEMPERATURE_SET_POINT_APPLIED

    • E_SE_DRLC_AVERAGE_LOAD_ADJUSTMENT_PERCENTAGE_APPLIED

    • E_SE_DRLC_DUTY_CYCLE_APPLIED

  • u16EventData: Value to which the specified data item is to be set (for formats of data values, refer to descriptions in Section 41.11.1)

Returns

Any relevant DRLC return code listed in Section 41.9 or ZCL return code listed in Section 7.2

Parent topic:Functions

eSE_DRLCGetLoadControlEvent

teSE_DRLCStatus eDRLCGetLoadControlEvent(
    uint8 u8SourceEndPointId,
    uint8 u8TableIndex,
    teSE_DRLCEventList eEventList,
    tsSE_DRLCLoadControlEvent **ppsLoadControlEvent);

Description

This function can be used to obtain an LCE from a local LCE list.

The required list must be specified as one of ‘Scheduled’, ‘Active’, ‘Cancelled’ and ‘Deallocated’. The index of the required LCE in the list must also be specified. The index of zero is used to indicate that the LCE with the oldest start-time should be retrieved. To retrieve all the LCEs in a list, repeatedly call this function with index zero until the function indicates that there are no further LCEs in the list (returns E_SE_DRLC_EVENT_NOT_FOUND).

Parameters

  • u8SourceEndPointId: Number of the local endpoint from which the LCE is to be retrieved (endpoint corresponding to the DRLC cluster)

  • u8TableIndex: Index of required LCE in the specified LCE list (see below)

  • eEventList: LCE list from which the LCE is to be retrieved, one of:

    • E_SE_DRLC_EVENT_LIST_SCHEDULED

    • E_SE_DRLC_EVENT_LIST_ACTIVE

    • E_SE_DRLC_EVENT_LIST_CANCELLED

    • E_SE_DRLC_EVENT_LIST_DEALLOCATED

  • ppsLoadControlEventPointer to a pointer to a tsSE_DRLCLoadControlEvent structure to receive the obtained LCE (see Section 41.11.1)

Returns

Any relevant DRLC return code listed in Section 41.9 or ZCL return code listed in Section 7.2

Parent topic:Functions

eSE_DRLCFindLoadControlEvent

teSE_DRLCStatus eSE_DRLCFindLoadControlEvent(
uint8 u8SourceEndPointId,
uint32 u32IssuerId,
bool_t bIsServer,
tsSE_DRLCLoadControlEvent **ppsLoadControlEvent,
teSE_DRLCEventList *peEventList);

Description

This function can be used to obtain the specified LCE from the local LCE lists.

The required LCE must be specified in terms of its identifier issued by the utility company. The function will search all the local LCE lists, identify the list (if any) in which the LCE was found and return the found LCE.

Parameters

  • u8SourceEndPointId: Number of the local endpoint from which the LCE is to be retrieved (endpoint corresponding to the DRLC cluster)

  • u32IssuerId: Identifier of the LCE to be found (as issued by the utility company)

  • bIsServer: Cluster server or client:

    • TRUE - server

    • FALSE - client

  • ppsLoadControlEventPointer to a pointer to a tsSE_DRLCLoadControlEvent structure to receive the obtained LCE (see Section 41.11.1)

  • peEventList: Pointer to variable to receive enumerated value of the list in which the LCE was found (see Section 41.10.7)

Returns

Any relevant DRLC return code listed in Section 41.9 or ZCL return code listed in Section 7.2

Parent topic:Functions

Parent topic:Demand-Response and Load Control Cluster