Version: 1.1.5 (first release), 2014-11-01

Device2EM

This data structure encapsulates all information transmitted by the device to the Energy Management System

DeviceInfo (DeviceInfoType) [0 .. unbounded]

A DeviceInfo encapsulates all static information about a device such as identification, capabilities, restrictions, etc.
Type: DeviceInfoType

Identification (IdentificationType)

General information for identifying the device.
Type: IdentificationType

DeviceId (DeviceIdType)

Unique identification of the device.
Type: DeviceIdType
Type for unique device IDs. A device ID consists of a vendor ID type (VID type), a vendor ID (VID), a serial number and sub-device ID.

The vendor ID should be globally unique. For this purpose either IANA PEN or IEEE OUI (known from MAC addresses) should be used. Although it is possible to define non-globally unique vendor IDs this option must not be used for products. The kind of vendor ID is defined by the vendor ID type. The following types are defined:

  • 0x0: IANA PEN (32 bit, Format: 0xXXXXXXXX)
  • 0x1: IEEE OUI (24 bit, Format: 0x00XXXXXX)
  • 0xF: non-unique ID in local address space (32 bit). IMPORTANT: Use only for demos, examples or testing, not for products.

The serial number can be freely defined by the vendor as it specific to the vendor's address space. It must be unique for each of the vendor's devices.

The sub-device ID can be used to point out, that a physical device consists of multiple virtual devices. The virtual device with sub-device ID 0 should be the main device. This information is only used to group devices in GUIs at the moment.

Format: [VID Type:4bit]-[VID:32bit]-[Serial:48bit]-[SubDev-ID:8bit] Example 1: "0-00008CAD-112233445566-00" (IANA PEN: 36013) Example 2: "F-11223344-112233445566-00" (local address, only for testing, demos, examples)

Pattern: [a-fA-F0-9]{1}-[a-fA-F0-9]{8}-[a-fA-F0-9]{12}-[a-fA-F0-9]{2}

DeviceName (xs:string)

Human readable device name
Type: xs:string

DeviceType (xs:string)

Human readable type of the device. See DeviceTypeRefType for well-known types.
Type: xs:string

Predefined values (DeviceTypeRefType):

Enumeration:
  • AirConditioning
  • Charger
  • DishWasher
  • Dryer
  • ElectricVehicle
  • EVCharger
  • Freezer
  • Fridge
  • Heater
  • HeatPump
  • Motor
  • Pump
  • WashingMachine
  • Other

DeviceSerial (xs:string)

Vendor specific serial number of the device
Type: xs:string

DeviceVendor (xs:string)

Human readable name of the device vendor
Type: xs:string

DeviceURL (xs:string) [0 .. 1]

Configuration URL of the device.
Type: xs:string

Characteristics (CharacteristicsType)

Information on the characteristics of the device.
Type: CharacteristicsType

MaxPowerConsumption (xs:int)

Nominal maximum power consumption of the device in Watts. If the device is controllable with regard to power consumption, the recommendation of the energy management system will never exceed this value.
Type: xs:int

MinOnTime (xs:int) [0 .. 1]

If the device is switched on, it has to remain in this status for at least MinOnTime seconds.
Type: xs:int

MinOffTime (xs:int) [0 .. 1]

If the device is switched off, it has to remain in this status for at least MinOffTime seconds.
Type: xs:int

Capabilities (CapabilitiesType)

This element encapsulates information about the capabilities of the device
Type: CapabilitiesType

CurrentPower (CapPowerMeasurementType)

Capability of the device with regard to deriving information about its current power consumption, e.g. measurement or estimation
Type: CapPowerMeasurementType

Method (xs:string)

String that defines the method of deriving information of the current power consumption. A device with a (built-in) power meter should use "Measurement". If it estimates the power consumption by look-up tables or other mechanisms select "Estimation". If it is not able to determine the power at all, "None" should be used.

This information provides a hint about the quality of the power values provided in the device status section. It can be used to determine whether the power data can be used for learning device profile or to decide if it is suitable to be displayed.

See PowerMeasurementMethodRefType for known values.

Type: xs:string

Predefined values (PowerMeasurementMethodRefType):

Enumeration:
  • Measurement
  • Estimation
  • None

Timestamps (CapTimestampType) [0 .. 1]

Specifies if the device is able to deal with absolute timestamps or only with relative timestamps. Devices that do not have a synchronized clock (with time server protocols like NTP or radio control like DCF77) or do not have a reliable absolute time source should use relative timestamps.
Type: CapTimestampType

AbsoluteTimestamps (xs:boolean)

Bool that indicates if the device is able to deal with absolute timestamps or only with relative timestamps
Type: xs:boolean

Default: false

Interruptions (CapInterruptionsType) [0 .. 1]

Specifies if a run of the device can be interrupted or not.
Type: CapInterruptionsType

InterruptionsAllowed (xs:boolean)

Bool that indicates if a run of the device can be interrupted (paused) or not.

Allowing interruptions helps the EM to manage energy more flexibly. For instance the EM can interrupt a device in case of unpredictable bad weather conditions or when the user switches on a device with conflicting energy needs and restart it afterwards.

Not all devices are able to handle interruptions during their runtime. In this case, the device will only be started by the EM and run until it is done.

Type: xs:boolean

Default: false

Requests (CapRequestsType) [0 .. 1]

Specifies options related to planning requests.
Type: CapRequestsType

OptionalEnergy (xs:boolean)

This capability must be set to "true", if the device uses timeframes in planning requests with minRunningTime!=maxRunningTime. This is the case if the device is capable of consuming more (not essentially needed) energy if energy is cheap (e.g. by storing it). Otherwise it should be set to "false".

As optional energy needs are defined by planning requests it is not possible for the EM to auto-detect this capability until the first optional demand was requested by the device.

The information whether optional energy is requested is helpful as an EM might provide additional configuration options in a GUI when a device supports consuming optional energy. This might for example include constraints that define under which circumstances (price or ecological limits) optional energy is assigned to the device. Defining that a device is not capable of using optional energy helps the GUI to hide the complexity of defining these constraints from the user.

Type: xs:boolean

Default: false

DeviceStatus (DeviceStatusType) [0 .. unbounded]

A DeviceStatus encapsulates the status information of a device, i.e. all measurements and properties representing the current status of the device
Type: DeviceStatusType

DeviceId (DeviceIdType)

Unique identification of the device.
Type: DeviceIdType
Type for unique device IDs. A device ID consists of a vendor ID type (VID type), a vendor ID (VID), a serial number and sub-device ID.

The vendor ID should be globally unique. For this purpose either IANA PEN or IEEE OUI (known from MAC addresses) should be used. Although it is possible to define non-globally unique vendor IDs this option must not be used for products. The kind of vendor ID is defined by the vendor ID type. The following types are defined:

  • 0x0: IANA PEN (32 bit, Format: 0xXXXXXXXX)
  • 0x1: IEEE OUI (24 bit, Format: 0x00XXXXXX)
  • 0xF: non-unique ID in local address space (32 bit). IMPORTANT: Use only for demos, examples or testing, not for products.

The serial number can be freely defined by the vendor as it specific to the vendor's address space. It must be unique for each of the vendor's devices.

The sub-device ID can be used to point out, that a physical device consists of multiple virtual devices. The virtual device with sub-device ID 0 should be the main device. This information is only used to group devices in GUIs at the moment.

Format: [VID Type:4bit]-[VID:32bit]-[Serial:48bit]-[SubDev-ID:8bit] Example 1: "0-00008CAD-112233445566-00" (IANA PEN: 36013) Example 2: "F-11223344-112233445566-00" (local address, only for testing, demos, examples)

Pattern: [a-fA-F0-9]{1}-[a-fA-F0-9]{8}-[a-fA-F0-9]{12}-[a-fA-F0-9]{2}

EMSignalsAccepted (xs:boolean)

Bool that indicates if the device is currently considering the control signals or recommendations provided by the energy manager or if it is in a mode which ignores the signals or recommendations
Type: xs:boolean

Status (xs:string)

String that provides information of the current status of the device (Offline, On, Off). See StatusRefType for known values.
Type: xs:string

Predefined values (StatusRefType):

Enumeration:
  • On
  • Off
  • Offline

ErrorCode (xs:int) [0 .. 1]

Identifies the current error state of the device. If the code is 0, no error is pending.
Type: xs:int

PowerConsumption (PowerConsumptionType) [0 .. 1]

Information about the current power consumption of the device, or the power consumption of the device since the last communication.
Type: PowerConsumptionType

PowerInfo (PowerInfoType) [1 .. 10]

Information about a power consumption.
Type: PowerInfoType

AveragePower (xs:int)

Real average power within the interval in Watts.
Type: xs:int

MinPower (xs:int) [0 .. 1]

Minimum power value within the interval in Watts.
Type: xs:int

MaxPower (xs:int) [0 .. 1]

Maximum power within the interval in Watts.
Type: xs:int

Timestamp (RelOrAbsTimeType)

Timestamp that represents the end of the averaging interval. Although this element is marked as optional it is mandatory in PowerConsumption:PowerInfo.
Type: RelOrAbsTimeType
Type representing timestamps that can either be relative (seconds relative to the current point of time) or absolute (Unix timestamp UTC in seconds since 01.01.1970). The device specifies the interpretation globally with the DeviceInfo.Capabilities.Timestamps element. Devices that do not have a synchronized clock (with time server protocols like NTP or radio control like DCF77) or do not have a reliable absolute time source should use relative timestamps.

AveragingInterval (xs:int)

Length of the averaging interval in seconds. Although this element is marked as optional it is mandatory in PowerConsumption:PowerInfo.
Type: xs:int

PlanningRequest (PlanningRequestType) [0 .. unbounded]

A PlanningRequest allows specification of the needs of the device with regard to energy and running time. As long as an energy need is pending, the gateway has to announce them in terms of PlanningRequests. PlanningRequests are not incremental, i.e. requests that sent to the EM in previous messages are discarded and replaced by the newest PlanningRequests. Missing timeframes or an empty PlanningRequest list are interpreted as if the energy needs are already satisfied.
Type: PlanningRequestType

Timeframe (TimeframeType) [1 .. unbounded]

Sequence of timeframes that constitute the planning request. Timeframes for one device must not overlap (in terms of earliestStart and latestEnd) as a device can only run once at a time. In case timeframes overlap the EM has to modify them (e.g. merge or strip) which might lead to unexpected behavior.
Type: TimeframeType

DeviceId (DeviceIdType)

Unique identification of the device.
Type: DeviceIdType
Type for unique device IDs. A device ID consists of a vendor ID type (VID type), a vendor ID (VID), a serial number and sub-device ID.

The vendor ID should be globally unique. For this purpose either IANA PEN or IEEE OUI (known from MAC addresses) should be used. Although it is possible to define non-globally unique vendor IDs this option must not be used for products. The kind of vendor ID is defined by the vendor ID type. The following types are defined:

  • 0x0: IANA PEN (32 bit, Format: 0xXXXXXXXX)
  • 0x1: IEEE OUI (24 bit, Format: 0x00XXXXXX)
  • 0xF: non-unique ID in local address space (32 bit). IMPORTANT: Use only for demos, examples or testing, not for products.

The serial number can be freely defined by the vendor as it specific to the vendor's address space. It must be unique for each of the vendor's devices.

The sub-device ID can be used to point out, that a physical device consists of multiple virtual devices. The virtual device with sub-device ID 0 should be the main device. This information is only used to group devices in GUIs at the moment.

Format: [VID Type:4bit]-[VID:32bit]-[Serial:48bit]-[SubDev-ID:8bit] Example 1: "0-00008CAD-112233445566-00" (IANA PEN: 36013) Example 2: "F-11223344-112233445566-00" (local address, only for testing, demos, examples)

Pattern: [a-fA-F0-9]{1}-[a-fA-F0-9]{8}-[a-fA-F0-9]{12}-[a-fA-F0-9]{2}

EarliestStart (RelOrAbsTimeType)

Represents the earliest possible time the device can be switched on by the EM. The combination of EarliestStart and LatestEnd specifies the interval in which the requested runtime or energy has to be allocated by the EM.
Type: RelOrAbsTimeType
Type representing timestamps that can either be relative (seconds relative to the current point of time) or absolute (Unix timestamp UTC in seconds since 01.01.1970). The device specifies the interpretation globally with the DeviceInfo.Capabilities.Timestamps element. Devices that do not have a synchronized clock (with time server protocols like NTP or radio control like DCF77) or do not have a reliable absolute time source should use relative timestamps.

LatestEnd (RelOrAbsTimeType)

Represents the latest possible end time the requested minimum runtime (MinRunningTime) must be allocated to the device. This means at the given time the device operation must be finished. If a runtime was requested, the latest possible start of operation is LatestEnd-MinRunningTime. The combination of EarliestStart and LatestEnd specifies the interval in which the requested runtime or energy has to be allocated by the EM.
Type: RelOrAbsTimeType
Type representing timestamps that can either be relative (seconds relative to the current point of time) or absolute (Unix timestamp UTC in seconds since 01.01.1970). The device specifies the interpretation globally with the DeviceInfo.Capabilities.Timestamps element. Devices that do not have a synchronized clock (with time server protocols like NTP or radio control like DCF77) or do not have a reliable absolute time source should use relative timestamps.

MinRunningTime (xs:int)

Minimum running time within the timeframe in seconds. If MinRunningTime is 0, the operation of the device in this timeframe is optional. Defaults to 0 if MaxRunningTime is set.
Type: xs:int

MaxRunningTime (xs:int)

Maximum running time within the timeframe in seconds. If MinRunningTime equals MaxRunningTime, all of the given runtime is required. If MinRunningTime is lower than MaxRunningTime, the amount of runtime given by MinRunningTime is required. The runtime difference between MinRunningTime and MaxRunningTime is optional. That means that the EM will only assign the optional runtime to the device if certain conditions like ecological constraints and/or price of energy are met. Defaults to MinRunningTime if MinRunningTime is set.
Type: xs:int

... (xsd:any) [0 .. unbounded]

Reserved for future use. Devices should ignore unknown elements.

EM2Device

This data structure encapsulates all information transmitted by the Energy Management System to the device

DeviceControl (DeviceControlType) [0 .. unbounded]

This element contains load control recommendations for a device.
Type: DeviceControlType

DeviceId (DeviceIdType)

Unique identification of the device.
Type: DeviceIdType
Type for unique device IDs. A device ID consists of a vendor ID type (VID type), a vendor ID (VID), a serial number and sub-device ID.

The vendor ID should be globally unique. For this purpose either IANA PEN or IEEE OUI (known from MAC addresses) should be used. Although it is possible to define non-globally unique vendor IDs this option must not be used for products. The kind of vendor ID is defined by the vendor ID type. The following types are defined:

  • 0x0: IANA PEN (32 bit, Format: 0xXXXXXXXX)
  • 0x1: IEEE OUI (24 bit, Format: 0x00XXXXXX)
  • 0xF: non-unique ID in local address space (32 bit). IMPORTANT: Use only for demos, examples or testing, not for products.

The serial number can be freely defined by the vendor as it specific to the vendor's address space. It must be unique for each of the vendor's devices.

The sub-device ID can be used to point out, that a physical device consists of multiple virtual devices. The virtual device with sub-device ID 0 should be the main device. This information is only used to group devices in GUIs at the moment.

Format: [VID Type:4bit]-[VID:32bit]-[Serial:48bit]-[SubDev-ID:8bit] Example 1: "0-00008CAD-112233445566-00" (IANA PEN: 36013) Example 2: "F-11223344-112233445566-00" (local address, only for testing, demos, examples)

Pattern: [a-fA-F0-9]{1}-[a-fA-F0-9]{8}-[a-fA-F0-9]{12}-[a-fA-F0-9]{2}

On (xs:boolean)

Switch on/off recommendation. If On=true, the EM recommends that the device should be switched on or run its program. For interruptible devices On=false is a switch-off recommendation indicating that the device should switch off or pause. A device should follow the recommendation as soon as possible. Otherwise the device might interfere with other devices managed by the EM. Note that the device should only accept a recommendation if stable operation is guaranteed (no risk of damage or safety issues).
Type: xs:boolean

RecommendedPowerConsumption (xs:double) [0 .. 1]

Reserved for future use.
Type: xs:double

Timestamp (RelOrAbsTimeType)

Timestamp of the generation of the message. Note that this does not determine the activation time of the switch-on or power recommendation. Recommendations are supposed to be applied immediately by the device.
Type: RelOrAbsTimeType
Type representing timestamps that can either be relative (seconds relative to the current point of time) or absolute (Unix timestamp UTC in seconds since 01.01.1970). The device specifies the interpretation globally with the DeviceInfo.Capabilities.Timestamps element. Devices that do not have a synchronized clock (with time server protocols like NTP or radio control like DCF77) or do not have a reliable absolute time source should use relative timestamps.

Messages (MessageListType) [0 .. 1]

This element provides information about an error or event the device should be informed about.
Type: MessageListType

Message (MessageType) [1 .. unbounded]

This element encapsulates information about an error or event.
Type: MessageType

Type (xs:string)

The type of message used as a hint to interpret the message contents. See MessageTypeRefType for known values.
Type: xs:string

Predefined values (MessageTypeRefType):

Enumeration:
  • InvalidTimeframe
  • DeviceControlIgnored
  • Other

Level (xs:string) [0 .. 1]

The severity of the message. See MessageLevelRefType for known values ("Info", "Warn", "Error").
Type: xs:string

Predefined values (MessageLevelRefType):

Enumeration:
  • Info
  • Warn
  • Error

Data (MessageDataType) [0 .. 1]

Additional data describing the error or event (e.g. for automatic evaluation). For "InvalidTimeframe" the element DeviceId will be set. For "DeviceControlIgnored" the element DeviceId will be set.
Type: MessageDataType

DeviceId (DeviceIdType) [0 .. 1]

Unique identification of the device this message applies to.
Type: DeviceIdType
Type for unique device IDs. A device ID consists of a vendor ID type (VID type), a vendor ID (VID), a serial number and sub-device ID.

The vendor ID should be globally unique. For this purpose either IANA PEN or IEEE OUI (known from MAC addresses) should be used. Although it is possible to define non-globally unique vendor IDs this option must not be used for products. The kind of vendor ID is defined by the vendor ID type. The following types are defined:

  • 0x0: IANA PEN (32 bit, Format: 0xXXXXXXXX)
  • 0x1: IEEE OUI (24 bit, Format: 0x00XXXXXX)
  • 0xF: non-unique ID in local address space (32 bit). IMPORTANT: Use only for demos, examples or testing, not for products.

The serial number can be freely defined by the vendor as it specific to the vendor's address space. It must be unique for each of the vendor's devices.

The sub-device ID can be used to point out, that a physical device consists of multiple virtual devices. The virtual device with sub-device ID 0 should be the main device. This information is only used to group devices in GUIs at the moment.

Format: [VID Type:4bit]-[VID:32bit]-[Serial:48bit]-[SubDev-ID:8bit] Example 1: "0-00008CAD-112233445566-00" (IANA PEN: 36013) Example 2: "F-11223344-112233445566-00" (local address, only for testing, demos, examples)

Pattern: [a-fA-F0-9]{1}-[a-fA-F0-9]{8}-[a-fA-F0-9]{12}-[a-fA-F0-9]{2}

Timestamp (RelOrAbsTimeType) [0 .. 1]

Time of the occurrence of the error/event.
Type: RelOrAbsTimeType
Type representing timestamps that can either be relative (seconds relative to the current point of time) or absolute (Unix timestamp UTC in seconds since 01.01.1970). The device specifies the interpretation globally with the DeviceInfo.Capabilities.Timestamps element. Devices that do not have a synchronized clock (with time server protocols like NTP or radio control like DCF77) or do not have a reliable absolute time source should use relative timestamps.

... (xsd:any) [0 .. unbounded]

Reserved for future use. Devices should ignore unknown elements.

Text (xs:string) [0 .. 1]

Description of the error/event.
Type: xs:string

... (xsd:any) [0 .. unbounded]

Reserved for future use. Devices should ignore unknown elements.