SE Records¶
These records either directly correspond or are related to definitions in the Smart Energy (SE) specification, and are used primarily by methods in the SE Interface. Refer to the specification for further information about specific record parameters.
LoadControlEventRecord¶
Specifies the parameters of a DRLC event, contained in an SE create_DRLC_event command. When instantiated, optional parameters will use default values if not included.
Parameters
| Parameter | Type | Description |
|---|---|---|
| issuer_event_id | int | 32-bit identifier of the DRLC event. |
| duration_in_minutes | int | 16-bit number of minutes for which the event will last. |
| device_class* | int | 16-bit bitmap of device classes which are affected by this event. Defaults to 0x0FFF, meaning all non-reserved device classes are affected. |
| utility_enrollment_group* | int | 8-bit identifier of which enrollment group this event applies to. Defaults to 0x00, meaning the event applies to all groups. |
| start_time* | int | 32-bit UTC (2000) specifying when the event will start. Defaults to 0, a special value meaning the event starts immediately rather than at a specified time. |
| criticality_level* | int | 8-bit enumerated criticality level of this event. Defaults to 0x01, which is the lowest non-reserved priority. |
| cooling_temperature_offset* | int | 8-bit offset to apply to the normal cooling setpoint, in units of 0.1 degrees C. Defaults to 0xFF, a reserved value meaning this parameter isn’t used. |
| heating_temperature_offset* | int | 8-bit offset to apply to the normal heating setpoint, in units of 0.1 degrees C. Defaults to 0xFF, a reserved value meaning this parameter isn’t used. |
| cooling_temperature_set_point* | int | 16-bit signed value of the cooling setpoint to apply, in units of 0.01 degrees C. Defaults to -0x8000, a reserved value meaning this parameter isn’t used. |
| heating_temperature_set_point* | int | 16-bit signed value of the heating setpoint to apply, in units of 0.01 degrees C. Defaults to -0x8000, a reserved value meaning this parameter isn’t used. |
| average_load_adjustment_percentage* | int | 8-bit energy usage limit to adjust to, as a percentage of the average usage, with values from +100% to -100%. Defaults to -0x80, a reserved value meaning this parameter isn’t used. |
| duty_cycle* | int | 8-bit maximum On state duty cycle as a percentage, with values from 0% to 100%. Defaults to 0xFF, a reserved value meaning this parameter isn’t used. |
| event_control* | int | 8-bit value of additional control options for the event. Defaults to 0x03, meaning start and end times may be randomized by the receiving device. |
Example
This event tells DRLC clients connected to HVAC compressors and furnaces to set their cooling setpoint at 18 degrees C and heating setpoint at 27 degrees C, with maximum duty cycle of 50%, for two hours starting at time 0x12345678.
<record type="LoadControlEventRecord">
<issuer_event_id type="int">0xABCDEF</issuer_event_id>
<device_class type="int">0x0001</device_class>
<utility_enrollment_group type="int">0x00</utility_enrollment_group>
<start_time type="int">0x12345678</start_time>
<duration_in_minutes type="int">120</duration_in_minutes>
<criticality_level type="int">0x01</criticality_level>
<cooling_temperature_set_point type="int">1800</cooling_temperature_set_point>
<heating_temperature_set_point type="int">2700</heating_temperature_set_point>
<duty_cycle type="int">50</duty_cycle>
</record>
CancelLoadControlEventRecord¶
Specifies the cancellation of an existing DRLC event, contained in an SE cancel_DRLC_event command. When instantiated, optional parameters will use default values if not included.
Parameters
| Parameter | Type | Description |
|---|---|---|
| issuer_event_id | int | 32-bit identifier of the DRLC event. |
| device_class* | int | 16-bit bitmap of device classes which are affected by this cancellation. Defaults to 0x0FFF, meaning all non-reserved device classes are affected. |
| utility_enrollment_group* | int | 8-bit identifier of which enrollment group this cancellation applies to. Defaults to 0x00, meaning the cancellation applies to all groups. |
| cancel_control* | int | 8-bit value of control options for this cancellation. Defaults to 0x01, meaning the randomization settings from the cancelled event is used. |
| effective_time* | int | 32-bit UTC (2000) specifying when the cancellation should be applied. Defaults to 0, meaning the cancellation should be applied immediately. |
Example
<record type="CancelLoadControlEventRecord">
<issuer_event_id type="int">0xABCDEF</issuer_event_id>
<device_class type="int">0x0001</device_class>
<utility_enrollment_group type="int">0x00</utility_enrollment_group>
</record>
CancelAllLoadControlEventsRecord¶
Specifies the cancellation of all DRLC events, contained in an SE cancel_all_DRLC_events command. When instantiated, optional parameters will use default values if not included.
Parameters
| Parameter | Type | Description |
|---|---|---|
| cancel_control* | int | 8-bit value of control options for this cancellation. Defaults to 0x01, meaning the randomization settings from the cancelled events will be used. |
Example
<record type="CancelLoadControlEventRecord">
<cancel_control type="int">0x00</cancel_control>
</record>
ReportEventStatusRecord¶
Specifies the status of a DRLC event which has been received by a client device, contained in an SE received_report_event_status* command.
Parameters
| Parameter | Type | Description |
|---|---|---|
| issuer_event_id | int | 32-bit identifier of the DRLC event. |
| event_status | int | 8-bit enumeration of the event’s status. |
| event_status_time | int | 32-bit UTC (2000) of when this status was generated. |
| criticality_level_applied | int | 8-bit enumeration indicating the criticality level that was applied for the event. |
| cooling_temperature_set_point_applied | int | 16-bit signed value of the cooling setpoint that was applied, in units of 0.01 degrees C. |
| heating_temperature_set_point_applied | int | 16-bit signed value of the heating setpoint that was applied, in units of 0.01 degrees C. |
| average_load_adjustment_percentage_applied | int | 8-bit energy usage limit adjustment that was applied, as a percentage of the average usage. |
| duty_cycle_applied | int | 8-bit maximum On state duty cycle that was applied, as a percentage. |
| event_control | int | 8-bit value of additional control options for the event. |
| signature_type | int | 8-bit enumeration of the signature type. Currently only 0x01 (ECDSA) is used. |
| signature* | base16 | 42-byte non-repudiation signature for the event status report. As of ref:1_5_0: Only included if the SE Report Event Status command contained a signature. |
Example
Event 0xABCDEF started at time 0x12345678, with an applied criticality of 0x01, applied cooling setpoint of 0x708 and applied heating setpoint of 0xA8C. Average load adjustment percentage and duty cycle were not applied.
<record type="ReportEventStatusRecord">
<issuer_event_id type="int">0xABCDEF</issuer_event_id>
<event_status type="int">0x2</event_status>
<event_status_time type="int">0x12345678</event_status_time>
<criticality_level_applied type="int">0x1</criticality_level_applied>
<cooling_temperature_set_point_applied type="int">0x708</cooling_temperature_set_point_applied>
<heating_temperature_set_point_applied type="int">0xA8C</heating_temperature_set_point_applied>
<average_load_adjustment_percentage_applied type="int">-0x80</average_load_adjustment_percentage_applied>
<duty_cycle_applied type="int">0xFF</duty_cycle_applied>
<event_control type="int">0x3</event_control>
<signature_type type="int">0x1</signature_type>
<signature type="base16">000000000000000000000000000000000000000000000000000000000000000000000000000000000000</signature>
</record>
GetScheduledEventsRecord¶
Specifies the retrieval of DRLC events from the DRLC server, contained in an SE get_scheduled_DRLC_events command. When instantiated, optional parameters will use default values if not included.
Parameters
| Parameter | Type | Description |
|---|---|---|
| start_time* | int | 32-bit UTC (2000) specifying the earliest time at which an event to be retrieved can start. Defaults to 0, meaning there is effectively no restriction on event start time. |
| number_of_events* | int | 8-bit maximum number of events that can be retrieved. Defaults to 0, meaning there is no limit on the number of events. |
Example
Get up to five events, starting from the earliest event which is still valid.
<record type="GetScheduledEventsRecord">
<start_time type="int">0</start_time>
<number_of_events type="int">5</number_of_events>
</record>
DisplayMessageRecord¶
Specifies the parameters of a Message event, contained in an SE create_message_event command. When instantiated, optional parameters will use default values if not included.
Parameters
| Parameter | Type | Description |
|---|---|---|
| message_id | int | 32-bit identifier of the Message event. |
| message | string | The contents of the message. |
| duration_in_minutes | int | 16-bit number of minutes for which the event will last. |
| start_time* | int | 32-bit UTC (2000) specifying when the event will start. Defaults to 0, a special value meaning the event starts immediately rather than at a specified time. |
| message_control* | int | 8-bit bitmap specifying message control options. Common values are 0x00 (normal message) and 0x80 (user confirmation required). Defaults to 0. |
| cancel_message_control* | int | 8-bit bitmap specifying cancel control options of this message. This parameter is only included when a Messaging client device receives a cancellation for a message and the cancellation itself requires confirmation. In this case, the record contained in the client’s updated_active_message* RPC response will contain this parameter. This parameter should not be included in the server’s create_message_event RPC request. |
Example
This event tells Messaging clients to display the text “Please confirm this message” for up to two hours, or until the user confirms the message.
<record type="DisplayMessageRecord">
<message_id type="int">0x55AA55AA</message_id>
<message_control type="int">0x80</message_control>
<start_time type="int">0</start_time>
<duration_in_minutes type="int">120</duration_in_minutes>
<message type="string">Please confirm this message.</message>
</record>
CancelMessageRecord¶
Specifies the cancellation of a Message event, contained in an SE cancel_message_event record. When instantiated, optional parameters will use default values if not included.
Parameters
| Parameter | Type | Description |
|---|---|---|
| message_id | int | 32-bit identifier of the Message event. |
| message_control* | int | 8-bit bitmap specifying cancel control options. Defaults to 0, which means the cancellation is normal. |
Example
<record type="CancelMessageRecord">
<message_id>0x55AA55AA</message_id>
</record>
MessageConfirmationRecord¶
Specifies that a Message event has been confirmed by a user, contained in an SE confirm_message_event command. When instantiated, optional parameters will use default values if not included.
Parameters
| Parameter | Type | Description |
|---|---|---|
| message_id* | int | 32-bit identifier of the Message event. Defaults to the currently active Message event if one exists. |
| confirmation_time* | int | 32-bit UTC (2000) of when the confirmation occurred. Defaults to the current time. |
Example
<record type="MessageConfirmationRecord">
<message_id type="int">0x55AA55AA</message_id>
<confirmation_time type="int">0x12345678</confirmation_time>
</record>
PublishPriceRecord¶
Specifies the parameters of a Price event, contained in an SE create_price_event command. When instantiated, optional parameters will use default values if not included.
Note
The SE record contains a current time parameter. This value is set automatically by the Price server when the event is sent to clients.
Parameters
| Parameter | Type | Description |
|---|---|---|
| issuer_event_id | int | 32-bit identifier of the Price event. |
| price | int | 32-bit value of the price of the commodity being delivered to the premise. |
| duration_in_minutes | int | 16-bit number of minutes for which the event will last. |
| start_time* | int | 32-bit UTC (2000) specifying when the event will start. Defaults to 0, a special value meaning the event starts immediately rather than at a specified time. |
| provider_id* | int | 32-bit identifier of the price provider. Defaults to 0xFFFFFFFF, meaning the parameter is not used. |
| rate_label* | string | String description of the price rate. Defaults to an empty string. |
| unit_of_measure* | int | 8-bit enumeration of the unit of measure associated with the price. Defaults to 0x00, meaning kW and kWh. |
| currency* | int | 16-bit enumeration of the currency associated with the price. Defaults to 840, meaning US dollars. |
| price_trailing_digit_and_price_tier* | int | 8-bit field indicating the number of digits to the right of the decimal point as well as the current price tier. Defaults to 0x20, meaning two digits to the right of the decimal and no related tier. |
| number_of_price_tiers_and_register_tier* | int | 8-bit field indicating the number of available tiers and register tier. Defaults to 0x00, meaning no price tiers and no related tier. |
| price_ratio* | int | 8-bit ratio of the given price to the normal price, after being multiplied by 10. Defaults to 0xFF, meaning this parameter isn’t used. |
| generation_price* | int | 32-bit value of the price of the commodity being generated by the premise. Defaults to 0xFFFFFFFF, meaning this parameter isn’t used. |
| generation_price_ratio* | int | The 8-bit ratio of the given generation price to the normal generation price, after being multiplied by 10. Defaults to 0xFF, meaning this parameter isn’t used. |
| alternate_cost_delivered* | int | 32-bit alternative cost of energy being delivered to the premise. Defaults to 0xFFFFFFFF, meaning this parameter isn’t used. |
| alternate_cost_unit* | int | 8-bit enumeration of the unit of measure associated with the alternate cost. Defaults to 0x1, meaning kg of CO2. |
| alternate_cost_trailing_digit* | int | 8-bit field indicating the number of digits to the right of the decimal point for alternate cost. Defaults to 0xFF, meaning this parameter isn’t used. |
Example
This record specifies a price with label “SamplePrice” which is $0.10 per kWh, lasting for two hours starting at time 0x12345678. The provider is 0xABCD and there is no related price tier.
<record type="PublishPriceRecord">
<issuer_event_id type="int">0x55AA55AA</issuer_event_id>
<price type="int">10</price>
<duration_in_minutes type="int">0x78</duration_in_minutes>
<start_time type="int">0x12345678</start_time>
<provider_id type="int">0xABCD</provider_id>
<rate_label type="string">SamplePrice</rate_label>
<unit_of_measure type="int">0x00</unit_of_measure>
<currency type="int">840</currency>
<price_trailing_digit_and_price_tier type="int">0x20</price_trailing_digit_and_price_tier>
</record>
GetScheduledPricesRecord¶
Specifies the retrieval of Price events from the Price server, contained in an SE get_scheduled_price_events command. When instantiated, optional parameters will use default values if not included.
Parameters
| Parameter | Type | Description |
|---|---|---|
| start_time* | int | 32-bit UTC (2000) specifying the earliest time at which an event to be retrieved can start. Defaults to 0, meaning there is effectively no restriction on event start time. |
| number_of_events* | int | 8-bit maximum number of events that can be retrieved. Defaults to 0, meaning there is no limit on the number of events. |
Example
Get up to three events that start at or after time 0x12345678.
<record type="GetScheduledPricesRecord">
<start_time type="int">0x12345678</start_time>
<number_of_events type="int">3</number_of_events>
</record>
GetProfileRecord¶
- Specifies which Metering profile information will be retrieved, contained in an SE get_meter_profile command. There are three parameters that specify the time span to retrieve meter profile data from:
- start_time
- end_time
- number_of_periods
At a minimum, either start_time or number_of_periods must be included (end_time will default to the current time). The profile data will be retrieved starting at the end_time, until either the number_of_periods are retrieved, or the start time is reached (whichever comes first).
Note
Additional parameters in version 1.5.0. Intervals are retrieved starting from end_time and go until either number_of_periods or start_time is reached, whichever comes first. Also, as of 1.5.0 it is legal to specify more periods than can be returned in a single over-the-air command; additional commands will be automatically sent as needed.
Parameters
| Parameter | Type | Description |
|---|---|---|
| interval_channel* | int | Whether the profile information will be for consumption delivered to the premise (0) or received from the premise (1). Defaults to 0, consumption delivered to the premise. |
| end_time* | int | 32-bit UTC (2000) ending time of the profile interval block to retrieve. Defaults to 0, a special value indicating the most recent interval block. |
| number_of_periods* | int | 8-bit maximum number of periods, or intervals, to retrieve. Before 1.5.0: Required parameter. As of 1.5.0: Must provide either this or start_time, or both. |
| start_time* | int | As of 1.5.0: 32-bit UTC (2000) starting time of the profile interval block to retrieve. Must provide either this or number_of_periods, or both. |
Example
<record type="GetProfileRecord">
<interval_channel>0</interval_channel>
<end_time>0x12345678</end_time>
<number_of_periods>10</number_of_periods>
<start_time>0x12345000</start_time>
</record>
GetProfileResponseRecord¶
Specifies Metering profile information which has been retrieved, contained in the response to a SE get_meter_profile command.
Parameters
| Parameter | Type | Description |
|---|---|---|
| end_time | int | 32-bit UTC (2000) of the most recent interval which was retrieved. |
| status | int | 8-bit enumeration of the status of retrieving the Metering profile. |
| profile_interval_period | int | 8-bit enumeration of the amount of time between retrieved intervals. |
| profile_interval_periods_seconds | int | As of 1.5.0: Number of seconds that the 8-bit enumeration profile_interval_period represents. |
| intervals | list | List of 24-bit integers corresponding to retrieved intervals in reverse chronological order. Invalid intervals will have the value 0xFFFFFF. |
Example
Eight intervals were retrieved, with each interval being one day long.
<record type="GetProfileResponseRecord">
<end_time type="int">0x12345678</end_time>
<status type="int">0x0</status>
<profile_interval_period type="int">0x0</profile_interval_period>
<profile_interval_period_seconds type="int">86400</profile_interval_period_seconds>
<intervals type="list">
<item type="int">0xAB8000</item>
<item type="int">0xAB7000</item>
<item type="int">0xAB6000</item>
<item type="int">0xAB5000</item>
<item type="int">0xAB4000</item>
<item type="int">0xAB3000</item>
<item type="int">0xAB2000</item>
<item type="int">0xAB1000</item>
</intervals>
</record>
RequestFastPollModeRecord¶
Specifies the duration and update rate for a fast polling request, contained in an SE request_fast_poll_mode command.
Parameters
| Parameter | Type | Description |
|---|---|---|
| fast_poll_update_period* | int | The requested number of seconds between meter updates. If not provided, defaults to 30. |
| duration_in_minutes* | int | How long fast poll mode will last, in minutes. If not provided, defaults to 15. |
Example
<record type="RequestFastPollModeRecord">
<fast_poll_update_period>10</fast_poll_update_period>
<duration_in_minutes>5</duration_in_minutes>
</record>
FastPollModeResponseRecord¶
Specifies the ending time and actual update rate for a fast polling window, contained in the response to an SE request_fast_poll_mode command.
Parameters
| Parameter | Type | Description |
|---|---|---|
| applied_update_period | int | The actual number of seconds between meter updates. |
| end_time | int | 32-bit UTC (2000) of when the fast polling window will end. |
Example
<record type="FastPollModeResponseRecord">
<applied_update_period type="int">10</applied_update_period>
<end_time type="int">12345678</end_time>
</record>