LCE Handling on Clients

The sub-sections below describe the various LCE handling activities that take place on a DRLC cluster client.

LCE Activation and De-activation

On receiving a new LCE from the DRLC cluster server, a cluster client first checks the device class and enrollment group specified within the LCE. If they do not match those of the local device (see DRLC attributes in Section 41.2), the LCE is discarded.

Note: A DRLC cluster client can opt out of an individual LCE using the eSE_DRLCSetEventUserOption() function.

Generally, a valid LCE received from the cluster server is automatically added to the ‘Scheduled’ list on the client - the E_SE_DRLC_EVENT_COMMAND callback event containing the command SE_DRLC_LOAD_CONTROL_EVENT is generated on the client to indicate that this has been done. However, if the LCE has a ‘start-time of now’, it is added directly to the ‘Active’ list, provided that the start-time is not randomized (see below).

If a new LCE is successfully added to the Scheduled (or Active) list, the client sends a Report Event Status message to the server to confirm acceptance of the LCE.

When the start-time of an LCE in the ‘Scheduled’ list is reached, the LCE is automatically moved to the ‘Active’ list. The E_SE_DRLC_EVENT_ACTIVE callback event is generated on the client to indicate that this has been done, allowing the application to make the required load adjustment. However, if a randomized start-time is enabled (in the LCE), the move to the ‘Active’ list is delayed by a random time interval that is no greater than the maximum defined by the cluster attribute u8StartRandomizeMinutes (see Section 41.2).

When the duration of the active LCE has expired, the LCE is automatically moved to the ‘De-allocated’ list - the E_SE_DRLC_EVENT_EXPIRED callback event is generated on the client to indicate that this has been done, allowing the application to restore the load to the previous level. However, if a randomized end-time is enabled (in the LCE), the move to the ‘Deallocated’ list is delayed by a random time interval that is no greater than the maximum defined by the cluster attribute u8StopRandomizeMinutes (see Section 41.2).

Note: The above randomize attributes of the DRLC cluster also allow LCE start-time and end-time randomization to be disabled for all LCEs on the local device. If this is the case, randomization settings within the LCE itself are ignored.

Parent topic:LCE Handling on Clients

Getting Scheduled Events

The application on the DRLC cluster client can send a Get Scheduled Events message to the cluster server in order to obtain relevant current and future LCEs. This message may be used in the following situations:

  • On a non-sleeping device, the application may send this message:

    • immediately after binding with the cluster server in order to get the initial LCEs (subsequent LCEs are received unsolicited from the server).

    • at other times in order to top up its LCE list, if it has previously discarded an LCE due to lack of storage.

  • On a sleeping device (End Device), the application may send this message on waking from sleep in order to obtain new LCEs that were distributed by the cluster server during sleep (and therefore not received).

The Get Scheduled Events message can be sent from a client using the function eSE_DRLCGetScheduledEventsSend(). The message includes the earliest start-time of the LCEs of interest, where zero is used to indicate all LCEs - for a sleeping End Device, this time should be set to zero or the current time, in case there are replacements on the server for LCEs already in the client’s lists. The message also allows the maximum number of returned LCEs to be specified, where zero is used to indicate all LCEs.

Note: The arrival of the Get Scheduled Events message results in the generation of the E_SE_DRLC_EVENT_COMMAND callback event, containing a DRLC_GET_SCHEDULED_EVENTS command on the cluster server. However, the cluster responds to the message automatically.

On receiving the requested LCEs from the cluster server, the cluster client automatically updates the local LCE lists with the reported LCEs.

Parent topic:LCE Handling on Clients

Reporting LCE Actions to Server

By default, a DRLC cluster client sends a Report Event Status message to the cluster server when an LCE is actioned on the client - that is, when an LCE is moved between lists on the client, such as from ‘Scheduled’ to ‘Active’ or from ‘Active’ to ‘Deallocated’ (see Section 41.4.2). Details of the actioned LCE are sent in a tsSE_DRLCReportEvent structure (see Section 41.11.4). The nature of the action is indicated in this structure using an enumeration (see Section 41.10.8).

Note: The DRLC cluster server is informed of the arrival of a Report Event Status message via the callback event E_SE_DRLC_EVENT_COMMAND, containing a SE_DRLC_REPORT_EVENT_STATUS command. The ESP/server may inform the utility company of the reported status - if the message cannot be forwarded immediately then it must be buffered by the application.

If a DRLC cluster client opts out of a particular LCE using the function eSE_DRLCSetEventUserOption(), a Report Event Status message is sent to the cluster server to indicate this. On reaching the end-time of the LCE, another Report Event Status message is sent to the server to confirm that the LCE has completed without the participation of the local client.

Parent topic:LCE Handling on Clients

Over-riding LCE Settings

The client application can over-ride certain aspects of an LCE using the function eSE_DRLCSetEventUserData(), which allows load control data values to be modified, including:

  • Criticality level

  • Cooling temperature set-point

  • Heating temperature set-point

  • Load adjustment percentage

  • Duty cycle

For example, the ESP/server may request an HVAC device to set its cooling level to 24oC, but the user may choose to over-ride this with a cooling level of 20oC. The above data values and their formats are detailed in the LCE structure description in Section 41.11.1.

The function eSE_DRLCSetEventUserData() modifies one load control data value on each call. Therefore, in order to modify more than one data value, the function must be called multiple times.

When a change is made, the cluster client automatically notifies the cluster server by sending a Report Event Status message containing the change.

Parent topic:LCE Handling on Clients

Parent topic:LCE Handling