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>