diff --git a/.project b/.project
new file mode 100644
index 0000000000000000000000000000000000000000..86aedf53e4ebbfe4fe9084a4a07fb2a46f6a13b5
--- /dev/null
+++ b/.project
@@ -0,0 +1,11 @@
+
+
+ saref4ener
+
+
+
+
+
+
+
+
diff --git a/documentation/abstract.md b/documentation/abstract.md
index 7ec77d7af1503e7ae0369d8ae501db6ce6adb8a5..702f8a3eaf76ca3163359cc96024b734b9f9c3a4 100644
--- a/documentation/abstract.md
+++ b/documentation/abstract.md
@@ -1 +1 @@
-The present document is a technical specification of SAREF4ENER, an extension of SAREF [[2]](#[2]) that was created in collaboration with Energy@Home ([http://www.energy-home.it](http://www.energy-home.it)) and EEBus ([http://www.eebus.org/en](http://www.eebus.org/en)), the major Italy- and Germany-based industry associations, to enable the interconnection of their (different) data models.
\ No newline at end of file
+The present document is a technical specification of SAREF4ENER, an extension of SAREF [[2]](#[2]) that was created in collaboration with EEBus ([http://www.eebus.org/en](http://www.eebus.org/en)), the major Germany-based industry association, and the Flexiblepower Alliance Network (FAN, [https://flexible-energy.eu/](https://flexible-energy.eu/)) to enable the interconnection of their (different) data models.
\ No newline at end of file
diff --git a/documentation/contributors.html b/documentation/contributors.html
new file mode 100644
index 0000000000000000000000000000000000000000..94c956696a4bf73e078ffec01731cf8e61a38169
--- /dev/null
+++ b/documentation/contributors.html
@@ -0,0 +1,10 @@
+
+
+
This documentation is a technical specification of SAREF4ENER, an extension of SAREF [1] for the energy domain. The present document was created based on the CENELEC standards EN 50631:2023, parts 1-4 [2] and EN 50491 12 2 [3], in collaboration with the Horizon 2020 project Interconnect [i.8], and with industry associations such as EEBus (http://www.eebus.org/en), Energy@Home (http://www.energy-home.it), KNX (https://www.knx.org/), and the Flexible power Alliance Network (FAN, https://flexible-energy.eu/).
+
The SAREF4ENER extension should be used to annotate (or generate) a neutral (protocol-independent) set of messages to be directly adopted by the various smart appliance manufacturers, or mapped to from their domain specific protocols of choice. These messages can be exchanged by energy smart appliances with an Energy Management System (EMS) to efficiently optimize energy consumption and production within the constraints set by the user.
+
Two international domain standards guided the work of developing the SAREF4ENER extension: EN 50631 series [2] with a set of data elements called SPINE and SPINE IoT resources and EN 50491-12-2 [3] with data elements called S2 resources [i.5] and [i.6]. Furthermore, new requirements as well as EN 50631:2023, parts 1-4 [2] and EN 50491 12 2 [3] concepts have been elaborated, implemented, and tested in the European Horizon 2020 project InterConnect within about 15 large scale pilots in 7 countries.
-
An overview of the SAREF4ENER ontology is provided in Figure 1, where rectangles containing an orange circle are used to denote classes created in SAREF4ENER, while rectangles containing a faded orange circle denote classes reused from other ontologies, such as SAREF. For all the entities described in the present document, it is indicated whether they are defined in the SAREF4ENER extension or elsewhere by the prefix included before their identifier, i.e. if the element is defined in SAREF4ENER the prefix is s4ener:, while if the element is reused from another ontology it is indicated in the Namespace Declarations section.
-
Arrows with white triangles on top represent the rdfs:subClassOf relation between two classes. The origin of the arrow is the class to be declared as subclass of the class at the destination of the arrow.
-
Directed arrows are used to represent properties between classes.
-
Rectangles that contain a list of values between square brackets denote an enumeration of individuals.
-
Note that Figure 1 aims at showing a global overview of the main classes of SAREF4ENER and their mutual relations. More details on the different parts of Figure 1 are provided below.
+
The main addition that SAREF4ENER provides on top of SAREF Core is a set of saref:Profiles that describe the energy flexibility capabilities of a device (see clause 4.2.3). These profiles are drawn from the SPINE/SPINE IoT [2] and the S2 data model [3], with some occurring in both and some in either. For example, the Power Profile flexibility type is described in both S2 and SPINE/IoT, so is merged into a single SAREF representation (see clause 4.2.3.6). The S2 Power Envelope and SPINE Power Limits also show enough similarities for an implementation with several shared concepts (see clause 4.2.3.5). The remaining types of flexibility are unique to either S2 or SPINE: Incentive Tables are defined in SPINE, whereas Operation Mode, Fill Rate Based, and Demand Driven energy flexibility are control types defined in S2 [i.5].
+
+
The SAREF4ENER extension additionally describes flexibility instructions (see clause 4.2.5) separately from the flexibility profiles. These instructions describe the communication taking place between a device and the EMS to decide on the energy flexibility plan, such as offers from the device and requests from a EMS. A real-time check on the monitoring of power consumption is facilitated via the reuse of the main SAREF module and the load control use case (see clause 4.2.4). Finally, the SAREF4ENER extension provides a modelling approach for data points and time series (see clause 4.2.6), which is necessary for modelling the various forecasts and data elements involved.
+
+
An overview of the SAREF4ENER (V1.2.1) ontology is provided in Figure 1. In the image, classes are represented as rectangles. Relationships (object properties) between entities are represented as arrows. Arrows are additionally used to represent some RDF, RDF-S and OWL constructs, more precisely: plain arrows with white triangles represent the rdfs:subClassOf relation between two classes. The origin of the arrow shall be considered as the subclass of the entity at the destination of the arrow. Dashed arrows accompanied by the expression rdf:type are used to indicate that the individual at the origin of the arrow is an instance of the class placed at the end of the arrow. Datatype properties and class restrictions are presented as plain text and positioned within the boxes of the rectangles. The green color is used to distinguish SAREF core entities. The blue color is used for highlighting the classes and properties already existing in the previous version of SAREF4ENER (V1.1.2). The white color is used to denote the classes and properties that have been added in the SAREF4ENER version specified in the present document (V1.2.1). Note that Figure 1 aims at showing a global overview of the main classes of SAREF4ENER and their mutual relations. More details on the different parts of Figure 1 are provided in the other subclauses of clause 4.2.
@@ -14,60 +17,102 @@
-
Figure 2 shows the hierarchy of classes and properties defined in SAREF4ENER.
-
Orange circles represent classes of SAREF4ENER, while faded orange circles represent classes that are reused from other ontologies. Object properties - which are properties between two classes - are denoted by blue rectangles, while datatype properties - which are properties between a class and a data type, such as xsd:string or xsd:dateTime - are denoted by green rectangles. Faded blue and green rectangles denote object properties and datatype properties that are reused from other ontologies.
+
Device
+
+
A s4ener:Device is a subclass of a saref:Device, i.e. it inherits the properties of the more general saref:Device and extends it with additional properties that are specific for SAREF4ENER. The s4ener:Device class is shown in Figure 3.
+
+
Demand Driven Profile
+
The s4ener:DemandDrivenProfile can be used for devices that can consume different types of energy resources such as electricity or natural gas, but that lack a way of buffering that energy. This may for example be a hybrid heat pump that is powered using either electricity of gas. The power demand is determined by the device, but the customer energy manager can choose how to generate that power.
+
The profile contains a set of saref:Actuators that describe the various ways that the demanded energy can be provided. These actuators may be (part of) the actual saref:Device that offers this profile. The forecast of the average demand rate (i.e. the amount of energy, heat, and any other resource that needs to be produced by a device in the near future) can be expressed by defining time series (s4ener:TimeSeries).
-
- Figure 2: SAREF4ENER class and property hierarchy
+
+ Figure 2: Demand Driven Profile overview
+
Fill Rate Based Profile
-
Device
+
The s4ener:FillRateBasedProfile can be used for devices that can store energy (s4ener:Storage), such as heat pumps with a buffer, EVs, batteries, and even fridges and freezers. The saref:Actuators associated with this fill rate based profile can consume energy to fill the buffer. The information regarding the leakage behaviour of the storage and its fill level (i.e. a measure expressing how full the storage is) can respectively be defined through the classes s4ener:LeakageBehaviour and saref:Measurement via the properties s4ener:hasLeakageBehaviour and s4ener:presentFillLevel, respectively. The s4ener:LeakageBehaviour is always associated with an element detailing the leakage behaviour of the storage (s4ener:LeakageBehaviourElement). Ultimately, certain storage devices might have a fill-level target profile (s4ener:FillLevelTargetProfile) with its associated s4ener:FillLevelTargetProfileElement.
-
A s4ener:Device is a subclass of a saref:Device, i.e. it inherits the properties of the more general saref:Device and extends it with additional properties that are specific for SAREF4ENER. The s4ener:Device class is shown in Figure 3.
+
+
+ Figure 2: Fill Rate Profile overview
+
+
+
Operation Mode Based Profile
+
+
Devices that offer the s4ener:operationModeProfile can control the amount of power that they generate and/or consume, such as diesel generators and variable electrical resistors. The states in which devices fall in, such as "running at reduced power" or "running at full power", can be described as operation modes (s4ener:OperationMode). These operation modes have therefore been modelled as subclasses of saref:State. Transitions between operation modes can be defined as s4ener:Transition with associated timers (s4ener:Timer) that specify the minimum duration of a particular operation model.
-
- Figure 3: Device class
+
+ Figure 2: Operation Mode Based Profile overview
-
Power Profile and Alternatives Group
+
Incentive Table Based Profile
-
This clause presents the classes of interest for smart energy management. These classes are used to schedule devices in certain modes and preferred times using power profiles to optimize energy efficiency and accommodate the customer's preferences (i.e. use case 2). These classes are s4ener:PowerProfile, s4ener:Alternative, s4ener:PowerSequence and s4ener:Slot, which are shown in Figure 4.
The s4ener:IncentiveTableBasedProfile can be used to describe an incentive table, compiled of incentive table slots (s4ener:IncentiveTableSlot) as well as a power plan (s4ener:PowerPlan). Both are used to negotiate the allocation of upcoming energy usage of a device between the energy manager and the device. The incentive table is used by the energy manager to express the availability of energy via real and/or artificial incentives or costs over time. The device itself uses the table to negotiate the own demand and request the allocation by sending the resulting power plan to the energy manager.
+
Incentive types can be expressed in the form of relative costs (s4ener:RelativeCost), absolute costs (s4ener:AbsoluteCost), CO2 emissions (s4ener:CO2Emission), and renewable energy percentage (s4ener:RenewableEnergyPercentage). An incentive table also defines a scope type (s4ener:ScopeType) to indicate whether it is a preliminary (s4ener:Preliminary) or committed version (s4ener:Committed).
+
An incentive table consists of a number of slots (s4ener:IncentiveTableSlot) where each slot may contain a series of incentives (s4ener:Incentive) representing various tiers (s4ener:Tier). Each tier may be linked to a particular energy source, such as the grid, solar panels, or surplus power. Each incentive describes the cost, expressed as a unit applicable to the s4ener:IncentiveType, for that power source in the particular (time) slot. The lower and optional upper boundary (s4ener:DataPoint) describe for each incentive at which level of power consumption it becomes applicable.
+
The power plan of a device is defined by a series of sets of data points (s4ener:TimeSeries). Each set of data points contains a time interval (time:Interval), a relation to a property (s4ener:Power), a binding to a minimum (s4ener:Minimum), average (s4ener:Average) or maximum (s4ener:Maximum) value and the value itself (saref:Measurement). Finally, it also contains a scope type (s4ener:ScopeType) to indicate whether it is a preliminary (s4ener:Preliminary) or committed value (s4ener:Committed).
+
An incentive table based profile can be used with any type of device.
-
- Figure 4: Power Profile and Alternatives Group
+
+ Figure 2: Incentive Table Based Profile overview
-
A saref:Device offers a s4ener:PowerEnvelopeBasedProfile when the device is operating within a minimum and maximum amount of power for energy production and/or consumption per time block, but the production or consumption cannot be directly regulated by the energy manager. A PV panels inverter is a typical example, because the energy produced is dependent on the amount of sunshine. The EMS may constrain the power production of the PV panels below its potential to lower a peak.
+
The minimum and maximum amount of power that can be generated and/or spent by a device in a certain timespan can be set by instantiating the s4ener:PowerEnvelope and its corresponding s4ener:PowerConstraint. Power constraints are always bound to the allowed power limit ranges of a device (s4ener:AllowedLimitRange). The energy level of the s4ener:PowerEnvelope can be defined by using s4ener:TimeSeries. The type of the allowed limit ranges of a device (i.e. upper limit or lower limit) can be defined through the class s4ener:PowerEnvelopeLimitType. Commodity quantities relating to s4ener:PowerEnvelope can be described through the class s4ener:CommodityQuantity.
-
- Figure 5: Power Sequence
+
+ Figure 2: Power Envelope Based Profile overview
+
Power Limit Profile
-
Slot
+
SAREF4ENER further specifies allowed limit ranges through the classes s4ener:ContractualPowerLimit, s4ener:NominalPowerLimit, and s4ener:FailsafePowerLimit. They are all subclasses of s4ener:PowerLimit which is the general upper-class of power limits. Power limits can be toggled active or inactive via the s4ener:isActive property. A device has nominal power consumption and/or production values (s4ener:NominalPowerLimit) when the manufacturers define quantifiable and measurable limits that has not to be exceeded. The failsafe values provided by the manufacturers has to be given as instances of saref:Measurement. In case the communication between a device and the energy manager is interrupted, the device enters a fail-safe state (s4ener:FailsafeState). Fail-safe values (s4ener:FailsafePowerLimit) apply until the communication is re established, with an optional minimal duration of the fail-safe state given in the s4ener:hasFailsafeDuration. Ultimately, a saref:Device is always bound to a s4ener:ContractualPowerLimit (which is defined in a specification by the manufacturers) and limited by a s4ener:FailsafePowerLimit.
+
+
+
+ Figure 2: Power Limit Based Profile overview
+
+
+
Power Profile
+
+
This clause presents the classes of interest for smart energy management. These classes are used to schedule devices in certain modes and preferred times using power profiles to optimize energy efficiency and accommodate the customer's preferences (i.e. use case 2). These classes are s4ener:PowerProfile, s4ener:Alternative, s4ener:PowerSequence and s4ener:Slot, which are shown in Figure 4.
The s4ener: LoadControlEventData class is used to represent overload warning severity level and related load control commands to a device. It is characterized by an event ID and a timestamp that represents the time the event information instance was created or received, and the time period that denotes the period of validity of the event. For example, 5 minutes ago an event was received which says that it shall take effect tomorrow from 14:00 to 15:30. In this event the timestamp is "5 minutes ago" and time period is "tomorrow from 14:00 to 15:30".
diff --git a/documentation/diagrams/DataPoint.png b/documentation/diagrams/DataPoint.png
new file mode 100644
index 0000000000000000000000000000000000000000..9959cd1bb38de52d9a0ec6ab513ba696303e8418
Binary files /dev/null and b/documentation/diagrams/DataPoint.png differ
diff --git a/documentation/diagrams/DemandDriven.png b/documentation/diagrams/DemandDriven.png
new file mode 100644
index 0000000000000000000000000000000000000000..abed01334033903a8e41b0fb0f81c5456cab4a4d
Binary files /dev/null and b/documentation/diagrams/DemandDriven.png differ
diff --git a/documentation/diagrams/Device.png b/documentation/diagrams/Device.png
deleted file mode 100644
index 922d229dc38b0afba8217d49dbc279560d048538..0000000000000000000000000000000000000000
Binary files a/documentation/diagrams/Device.png and /dev/null differ
diff --git a/documentation/diagrams/FillRate.png b/documentation/diagrams/FillRate.png
new file mode 100644
index 0000000000000000000000000000000000000000..554ed16986ea5d013c15cf6081c61be8618911e4
Binary files /dev/null and b/documentation/diagrams/FillRate.png differ
diff --git a/documentation/diagrams/FlexibilityInstruction.png b/documentation/diagrams/FlexibilityInstruction.png
new file mode 100644
index 0000000000000000000000000000000000000000..1db9cff0ab98cb6a4b86862be2fe529c5b2f362a
Binary files /dev/null and b/documentation/diagrams/FlexibilityInstruction.png differ
diff --git a/documentation/diagrams/FlexibilityOffer.png b/documentation/diagrams/FlexibilityOffer.png
new file mode 100644
index 0000000000000000000000000000000000000000..7694ede72a1cd4016eaa57b9968a5e23793ba13a
Binary files /dev/null and b/documentation/diagrams/FlexibilityOffer.png differ
diff --git a/documentation/diagrams/FlexibilityProfiles.png b/documentation/diagrams/FlexibilityProfiles.png
new file mode 100644
index 0000000000000000000000000000000000000000..dfffe933dd96e04892d5afb82279d2c0980e2b43
Binary files /dev/null and b/documentation/diagrams/FlexibilityProfiles.png differ
diff --git a/documentation/diagrams/FlexibilityRequest.png b/documentation/diagrams/FlexibilityRequest.png
new file mode 100644
index 0000000000000000000000000000000000000000..388986f6a0130f80c37275b2a5f209d066b4427b
Binary files /dev/null and b/documentation/diagrams/FlexibilityRequest.png differ
diff --git a/documentation/diagrams/Hierarchy.png b/documentation/diagrams/Hierarchy.png
deleted file mode 100644
index 83cf62f62aad70e7dc4b4acb717fe82a2d99ccdd..0000000000000000000000000000000000000000
Binary files a/documentation/diagrams/Hierarchy.png and /dev/null differ
diff --git a/documentation/diagrams/IncentiveTable.png b/documentation/diagrams/IncentiveTable.png
new file mode 100644
index 0000000000000000000000000000000000000000..6f70b3e6e8f1de58cf6f5d3c5c3c532326c953f3
Binary files /dev/null and b/documentation/diagrams/IncentiveTable.png differ
diff --git a/documentation/diagrams/LoadControl.png b/documentation/diagrams/LoadControl.png
index cd31d347ebb8edde30e117379646d2b90df061ad..1a76900b20c5209d314513352bc18b650b2dd82a 100644
Binary files a/documentation/diagrams/LoadControl.png and b/documentation/diagrams/LoadControl.png differ
diff --git a/documentation/diagrams/OperationMode.png b/documentation/diagrams/OperationMode.png
new file mode 100644
index 0000000000000000000000000000000000000000..7bde41a217a806d5d44c222576d94b9dbff57143
Binary files /dev/null and b/documentation/diagrams/OperationMode.png differ
diff --git a/documentation/diagrams/Overview.png b/documentation/diagrams/Overview.png
index 8aa5a535c035203a1170b566167647cdf668748f..f33832d0e76cbc2fe11bd26fdddb2bc684106676 100644
Binary files a/documentation/diagrams/Overview.png and b/documentation/diagrams/Overview.png differ
diff --git a/documentation/diagrams/PowerEnvelope.png b/documentation/diagrams/PowerEnvelope.png
new file mode 100644
index 0000000000000000000000000000000000000000..34c4325460b5c00c0b1f1950f6b0989c191fda83
Binary files /dev/null and b/documentation/diagrams/PowerEnvelope.png differ
diff --git a/documentation/diagrams/PowerLimit.png b/documentation/diagrams/PowerLimit.png
new file mode 100644
index 0000000000000000000000000000000000000000..0827f417ebddafa24be42a52381288b2e5f96340
Binary files /dev/null and b/documentation/diagrams/PowerLimit.png differ
diff --git a/documentation/diagrams/PowerPlan.png b/documentation/diagrams/PowerPlan.png
new file mode 100644
index 0000000000000000000000000000000000000000..f3d62089cc6da5cbb13fee772c7c238e3dc7a267
Binary files /dev/null and b/documentation/diagrams/PowerPlan.png differ
diff --git a/documentation/diagrams/PowerProfile.png b/documentation/diagrams/PowerProfile.png
deleted file mode 100644
index 23439e01c0aad30151cd9b09a420a3500c32de00..0000000000000000000000000000000000000000
Binary files a/documentation/diagrams/PowerProfile.png and /dev/null differ
diff --git a/documentation/diagrams/PowerProfileAlternativesGroup.png b/documentation/diagrams/PowerProfileAlternativesGroup.png
new file mode 100644
index 0000000000000000000000000000000000000000..ea2fcd9a81d89844e42e2345ad4f8f0af7e16fd7
Binary files /dev/null and b/documentation/diagrams/PowerProfileAlternativesGroup.png differ
diff --git a/documentation/diagrams/PowerProfileOverview.png b/documentation/diagrams/PowerProfileOverview.png
new file mode 100644
index 0000000000000000000000000000000000000000..4620394ecc07cc2ca266320560eb7654a5a0a816
Binary files /dev/null and b/documentation/diagrams/PowerProfileOverview.png differ
diff --git a/documentation/diagrams/PowerSequence.png b/documentation/diagrams/PowerSequence.png
deleted file mode 100644
index 9ea037cfcafefd6005a38546106182c427d9311f..0000000000000000000000000000000000000000
Binary files a/documentation/diagrams/PowerSequence.png and /dev/null differ
diff --git a/documentation/diagrams/Slot.png b/documentation/diagrams/Slot.png
deleted file mode 100644
index e584f63431c1c5e4046ed34e3536020bad0abd7f..0000000000000000000000000000000000000000
Binary files a/documentation/diagrams/Slot.png and /dev/null differ
diff --git a/documentation/references.html b/documentation/references.html
index 8dae51972fdd07e221d6bdeee68f13953ad76480..9e8f7e1d14801214f7c8f0d9af051d090295e838 100644
--- a/documentation/references.html
+++ b/documentation/references.html
@@ -1,9 +1,10 @@
[2] EN 50631:2023, parts 1-4: "Household appliances network and grid connectivity" (produced by CENELEC).
+
[3] EN 50491-12-2:2022: "General requirements for Home and Building Electronic Systems (HBES) and Building Automation and Control Systems (BACS) - Part 12-2: Smart grid - Application specification - Interface and framework for customer - Interface between the Home / Building CEM and Resource manager(s) - Data model and messaging" (produced by CENELEC).
Informative references
@@ -16,4 +17,8 @@
[i.3] IEC TR 62746-2:2015: "Systems interface between customer energy management system and the power management system - Part 2: Use cases and requirements".
NOTE: Available at https://webstore.iec.ch/publication/22279.
@@ -14,60 +17,102 @@
- 
+ 
+ 
- 
+ 
- 
+ 
- 
+ 
+ 
- 
+ 
+