LCE Handling

LCEs are handled on the DRLC cluster server and clients as described in Section41.5.1 and Section 41.5.2 respectively. Canceling LCEs is described in Section41.5.3.

Note: The DRLC callback events referred to in this section are further described in Section 41.7 and are handled by the callback function that is registered as part of the device endpoint registration.

LCE Handling on Server

When a new LCE is received from the utility company, it is the responsibility of the application on the ESP (DRLC cluster server) to add this LCE to the local ‘Scheduled’ list (or to the ‘Active’ list, if the LCE has a ‘start-time of now’). This addition is performed using the function eSE_DRLCAddLoadControlEvent(), which also sends the LCE (unsolicited) to the cluster clients. The LCE should normally be sent to all client endpoints with which the cluster server has been bound (see Section 41.3).

Note:

  1. **Note 1:**Following the initial reception of LCEs from the utility company, the addition of these LCEs to the list(s) through **eSE_DRLCAddLoadControlEvent()**can be done after calling eSE_RegisterEspMeterEndPoint() or eSE_RegisterEspEndPoint() but before calling ZPS_eAplZdoStartStack().

  2. Note 2: On receiving an LCE, the client checks the device class and enrollment group specified within the LCE, and only accepts the LCE if these values match the corresponding DRLC cluster attributes held locally (see Section 41.2).

The cluster server also automatically responds to Get Scheduled Events messages from cluster clients that need current and future LCEs (see Section 41.5.2.2).

Parent topic:LCE Handling

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

Canceling LCEs

An LCE can be canceled, in which case it is moved to the ‘Deallocated’ list (possibly via the ‘Cancelled’ list - see below). A cancellation can only be performed from the DRLC cluster server and is normally sent to all client endpoints that have been bound to the server. Two functions are provided which can be called on the cluster server to perform LCE cancelations:

  • eSE_DRLCCancelLoadControlEvent() is used to cancel a particular LCE

  • eSE_DRLCCancelAllLoadControlEvents() is used to cancel all LCEs

Cancellation involves removing the LCE(s) from the ‘Scheduled’ or ‘Active’ lists on the cluster server and clients, which is done automatically by the cluster. As a result, the callback event E_SE_DRLC_EVENT_COMMAND is generated, containing a LOAD_CONTROL_EVENT_CANCEL or LOAD_CONTROL_EVENT_CANCEL_ALL command, as appropriate. This indicates whether the cancellation with immediate effect or a random delay is applied:

  • If the cancellation is with immediate effect, the application should stop load control for the relevant device(s).

  • If a random delay is to be applied to the cancellation, the cluster puts the LCE in the ‘Cancelled’ list until the delay has expired, when the LCE is moved to the ‘Deallocated’ list. Another E_SE_DRLC_EVENT_COMMAND callback event containing the command LOAD_CONTROL_EVENT_CANCEL or LOAD_CONTROL_EVENT_CANCEL_ALL is then generated, this time indicating immediate cancellation. The application should now stop load control for the relevant device(s).

Parent topic:LCE Handling

Parent topic:Demand-Response and Load Control Cluster