diff --git a/documentation/abstract.md b/documentation/abstract.md new file mode 100644 index 0000000000000000000000000000000000000000..7c25a4016a915e930f7ca38fc0db9801dd806e43 --- /dev/null +++ b/documentation/abstract.md @@ -0,0 +1,16 @@ +
NOTE: The text in this section is extracted from ETSI TS 103 410-12 (V2.1.1) [0], and therefore falls inside the ETSI IPR Policy
+ +[The technical specification ETSI TS 103 410-12](#[0]) is a technical specification of SAREF4GRID, an extension of SAREF for the Smart Grid domain. This extension has been created by investigating resources from potential stakeholders of the ontology, such as standardization initiatives, associations, and existing ontologies and standards, as reported in ETSI TR 103 904 [[i.1]](#[i.1]). In addition, the use cases defined in ETSI TR 103 904 [[i.1]](#[i.1]) were also considered, namely: + +* **Use case 1**: Remote management of meters. +* **Use case 2**: Management of tertiary sensor devices. +* **Use case 3**: Management of OLTC transformers. +* **Use case 4**: Detection of meter connectivity. + +SAREF4GRID is an OWL ontology that extends SAREF and reuses two other ontologies. SAREF4GRID includes 56 classes (41 defined in SAREF4GRID and 15 reused from the SAREF and oneM2M), 50 object properties (28 defined in SAREF4GRID and 22 reused SAREF from and oneM2M), 45 data type properties (43 defined in SAREF4GRID and 2 reused from SAREF and oneM2M), and 28 individuals. + +SAREF4GRID focuses on extending SAREF in order to create a common core of general concepts for smart grid data oriented to the IoT field. The main idea is to identify the core components, as mentioned, that could be extended for particular smart grid subdomains, for example, for high voltage networks. + +The prefixes and namespaces used in SAREF4GRID and in [the technical specification ETSI TS 103 410-12](#[0]) are listed in [the Namespace Declarations section](#namespacedeclarations). + + diff --git a/documentation/creators.md b/documentation/creators.md new file mode 100644 index 0000000000000000000000000000000000000000..d2ed34ec7ac330a1b0784481280e979cd7ee1649 --- /dev/null +++ b/documentation/creators.md @@ -0,0 +1,3 @@ +- [Raúl Garcia-Castro](http://www.garcia-castro.com/foaf.rdf#me) ([Universidad Politécnica de Madrid](http://www.oeg-upm.net/)) +- [Sergio-Mario Carulli-Pérez](https://www.linkedin.com/in/sergio-mario-carulli-p%C3%A9rez-7632b5217/) ([Universidad Politécnica de Madrid](http://www.oeg-upm.net/)) +- [Maria Poveda-Villalon](https://w3id.org/people/mpoveda/) ([Universidad Politécnica de Madrid](http://www.oeg-upm.net/)) diff --git a/documentation/description.md b/documentation/description.md new file mode 100644 index 0000000000000000000000000000000000000000..96b8a3cf431c6f7b964bf5d4504bd28e29bc3795 --- /dev/null +++ b/documentation/description.md @@ -0,0 +1,247 @@ +
NOTE: The text in this section is extracted from ETSI TS 103 410-12 (V2.1.1) [0], and therefore falls inside the ETSI IPR Policy
+ + +### General Overview + +An overview of the SAREF4GRID ontology is provided in Figures 1, 2, 3 and 4. For all the entities described in [the technical specification ETSI TS 103 410-12](#[0]), it is indicated whether they are defined in the SAREF4GRID extension or elsewhere by the prefix included before their identifier, i.e. if the element is defined in SAREF4GRID, the prefix is s4grid, while if the element is reused from another ontology it is indicated by a prefix according to [the Namespace Declarations section](#namespacedeclarations). + +Arrows are used to represent properties between classes and to represent some RDF, RDF-S and OWL constructs, more precisely: + +* Plain arrows with white triangles represent the [rdfs:subClassOf](http://www.w3.org/2000/01/rdf-schema#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. +* Dashed arrows between two classes indicate a local restriction in the origin class, i.e. that the object property can be instantiated between the classes in the origin and the destination of the arrow. The identifier of the object property is indicated within the arrow. +* Dashed arrows with no identifier are used to represent the [rdf:type](http://www.w3.org/1999/02/22-rdf-syntax-ns#type) relation, indicating that the element in the origin of the arrow is an instance of the class in the destination of the arrow. + +Datatype properties are denoted by rectangles attached to the classes, in an UML-oriented way. Dashed boxes represent local restrictions in the class, i.e. datatype properties that can be applied to the class they are attached to. + +Individuals are denoted by rectangles in which the identifier is underlined. + +Note that Figures 1, 2, 3 and 4 aim at showing a global overview of the main classes of SAREF4GRID and their mutual relations. More details on the different parts of the figures are provided from clause 4.2.2 to clause 4.2.14. + + +
+ SAREF4GRID overview: Meter information +
Figure 1: SAREF4GRID overview: Meter information
+
+ + +
+ SAREF4GRID overview: Observations and profiles +
Figure 2: SAREF4GRID overview: Observations and profiles
+
+ + +
+ SAREF4GRID overview: Activity calendar and scripts +
Figure 3: SAREF4GRID overview: Activity calendar and scripts
+
+ + +
+ SAREF4GRID overview: Services +
Figure 4: SAREF4GRID overview: Services
+
+ + +### Meter + +[Figure 5](#Figure_5) provides an overview of how to represent an electric grid meter using the [s4grid:GridMeter](#s4grid:GridMeter) class. The representation of electric grid meters and their properties has been extracted from the DLMS/COSEM standard (IEC 62056-1-0:2014 [[i.2]](#[i.2])). + +Unlike in other SAREF extensions, meter-specific information is not defined using properties from SAREF. This is because the DLMS/COSEM standard defines the data structures to model meters from simple up to very complex functionality (IEC 62056-6-2:2017 [[i.4]](#[i.4])). Moreover, each piece of information within the metering equipment has a unique identifier called OBIS (OBject Identification System) which identifies the instance of a COSEM object (IEC 62056-6-1:2017 [[i.3]](#[i.3])). This data includes not only observation values, but also abstract values used for configuration or for obtaining information about the behaviour of the metering equipment. + +For this reason, the characteristics of the meter are represented as properties that are not observable by the meter ([s4grid:MeterProperty](#s4grid:MeterProperty), fully represented in [Figure 6](#Figure_6)), i.e. they are not observations ([saref:Observation](https://saref.etsi.org/core/Observation)). The properties of a meter are defined by a value ([saref:PropertyValue](https://saref.etsi.org/core/PropertyValue)) and some are complemented with a unit of measurement ([saref:UnitOfMeasure](https://saref.etsi.org/core/UnitOfMeasure)). + + +
+ Meter model +
Figure 5: Meter model
+
+ +Meters store internal configuration parameters. The DLMS/COSEM standard (IEC 62056-1-0:2014 [[i.2]](#[i.2])) defines properties related to the configuration of a meter that are necessary to ensure its correct operation. SAREF4GRID categorizes the main properties related to the configuration of a meter ([s4grid:MeterProperty](#s4grid:MeterProperty)): screen display configuration ([s4grid:ScreenDisplay](#s4grid:ScreenDisplay)), electric threshold values ([s4grid:Threshold](#s4grid:Threshold)), time from which a measure has to be outside the threshold before to be considered a quality issue ([s4grid:TimeThreshold](#s4grid:TimeThreshold)), number of voltage sags ([s4grid:VoltageSagNumber](#s4grid:VoltageSagNumber)), number of voltage swells ([s4grid:VoltageSwellNumber](#s4grid:VoltageSwellNumber)), number of long power failures ([s4grid:LongPowerFailuresNumber](#s4grid:LongPowerFailuresNumber)), information provided by the manufacturer ([s4grid:Manufacturer](#s4grid:Manufacturer)), turn ratio of the transformer ([s4grid:TransformerRatio](#s4grid:TransformerRatio)), communication configuration ([s4grid:Network](#s4grid:Network)), status of meter profiles ([s4grid:ProfileStatus](#s4grid:ProfileStatus)), client power limits ([s4grid:PowerLimit](#s4grid:PowerLimit)), reference values for power quality ([s4grid:PowerQuality](#s4grid:PowerQuality)), client billing periods ([s4grid:BillingPeriod](#s4grid:BillingPeriod)), information about the electric grid phase ([s4grid:Phase](#s4grid:Phase)), information about the electric grid phase angle ([s4grid:PhaseAngle](#s4grid:PhaseAngle)), and electric quadrant ([s4grid:Quadrant](#s4grid:Quadrant)). It should be noted that in SAREF4GRID only the general properties are being defined. In order to use a more specific property it is advisable to indicate the general property it comes from (if it exists). The properties which are defined in SAREF4GRID are depicted in [Figure 6](#Figure_6). + + +
+ Meter property model +
Figure 6: Meter property model
+
+ + +### Firmware + +SAREF4GRID allows describing the identification information related to administration and maintenance of meters by means of the [s4grid:Firmware](#s4grid:Firmware) class, as presented in [Figure 7](#Figure_7). They are not communication parameters but support device management. The representation of the firmware of a meter has been extracted from IEC 6205662:2017 [[i.4]](#[i.4]). + +A meter firmware may be described by its: version ([s4grid:hasFirmwareVersion](#s4grid:hasFirmwareVersion)), unique vendor identifier ([s4grid:hasVendorId](#s4grid:hasVendorId)), and unique product identifier as assigned by the vendor ([s4grid:hasProductId](#s4grid:hasProductId)). Besides, a firmware can be related to an electric grid meter by means of the [s4grid:hasFirmware](#s4grid:hasFirmware) property. + + +
+ Firmware model +
Figure 7: Firmware model
+
+ + +### Network interface + +SAREF4GRID allows describing the MAC address of the physical device (or, more generally, of a device or software) by means of the [s4grid:NetworkInterface](#s4grid:NetworkInterface) class, as presented in [Figure 8](#Figure_8). There shall be an instance of this class for each network interface of a meter. The representation of the network interface of a meter has been extracted from IEC 62056-6-2:2017 [[i.4]](#[i.4]). + + +
+ Network interface model +
Figure 8: Network interface model
+
+ + +### Clock + +SAREF4GRID allows describing the clock of a meter by means of the [s4grid:Clock](#s4grid:Clock) class, as presented in [Figure 9](#Figure_9). This clock manages all information related to date and time including deviations of the local time to a generalized time reference (UTC) due to time zones and daylight-saving time schemes. The representation of the meter clock has been extracted from IEC 62056-6-2:2017 [[i.4]](#[i.4]). + +A meter clock may be described by its: time ([s4grid:hasTime](#s4grid:hasTime)), time zone where the meter is located ([s4grid:hasTimeZone](#s4grid:hasTimeZone)), clock status maintained by the meter ([s4grid:hasStatus](#s4grid:hasStatus)), date at which the local time starts to deviate from the normal time ([s4grid:hasDaylightSavingsBegin](#s4grid:hasDaylightSavingsBegin)), date at which the local time ends to deviate from the normal time ([s4grid:hasDaylightSavingsEnd](#s4grid:hasDaylightSavingsEnd)), deviation in generalized time ([s4grid:hasDaylightSavingsDeviation](#s4grid:hasDaylightSavingsDeviation)), if the daylight savings time feature is enabled ([s4grid:hasDaylightSavingsEnabled](#s4grid:hasDaylightSavingsEnabled)), and where the basic timing information comes from ([s4grid:hasClockBase](#s4grid:hasClockBase)). Besides, a clock can be related to a meter by means of the [s4grid:hasClock](#s4grid:hasClock) property. + + +
+ Clock model +
Figure 9: Clock model
+
+ + +### Breaker state + +As it can be observed in [Figure 10](#Figure_10), the modelling of states in the SAREF4GRID ontology mostly relies on the state model proposed in SAREF. In order to reduce duplication with SAREF documentation, the reader is referred to the SAREF specification ETSI TS 103 264 [[1]](#[1]) for details about state modelling including here details only for the new concepts. + +SAREF allows to define the state in which a device can be found. However, the SAREF4GRID extension also requires to be able to define the possible transitions between states and complex states. Therefore, the [s4grid:BreakerState](#s4grid:BreakerState) class has been defined according to IEC 62056-6-2:2017 [[i.4]](#[i.4]). + +A meter breaker represents the internal or external disconnect unit of the meter (e.g. electricity breaker, gas valve) in order to connect or disconnect the premises of the consumer to/from the supply. A meter breaker state may be described by its: physical state ([s4grid:hasOutputState](#s4grid:hasOutputState)), internal state ([s4grid:hasControlState](#s4grid:hasControlState)) and the possible transitions between states ([s4grid:hasControlMode](#s4grid:hasControlMode)). For more information between the possible transitions see IEC 6205662:2017 [[i.4]](#[i.4]). + + +
+ Breaker state model +
Figure 10: Breaker state model
+
+ + +### Script table + +As it can be observed in [Figure 11](#Figure_11), the modelling of scripts in the SAREF4GRID ontology mostly relies on the service model proposed in SAREF. In order to reduce duplication with SAREF documentation, the reader is referred to the SAREF specification [[1]](#[1]) for details about service modelling including here details only for the new concepts. + +SAREF allows to define the functions which accomplish the task for which a device is designed. However, the SAREF4GRID extension also requires to be able to define the triggering of a series of actions by executing scripts, and where those scripts are stored. Therefore, the [s4grid:ScriptTable](#s4grid:ScriptTable) class has been defined according to IEC 6205662:2017 [[i.4]](#[i.4]). + +A script table represents a table of script entries. Moreover, the [s4grid:Script](#s4grid:Script) class defines a series of action specifications. An action specification activates a method or modifies an attribute of a COSEM object within the logical device. Besides, a script table can be related to an electric grid meter by means of the [s4grid:hasScriptTable](#s4grid:hasScriptTable) property. + + +
+ Script table model +
Figure 11: Script table model
+
+ + +### Scheduled action + +SAREF4GRID allows the execution of periodic actions within a meter by means of the [s4grid:SingleScheduledAction](#s4grid:SingleScheduledAction) class, as presented in [Figure 12](#Figure_12); such actions are not necessarily linked to tariffication. A scheduled action describes the script, which is stored in a script table, that is going to be executed at a determined date. The representation of the meter scheduled action has been extracted from IEC 62056-6-2:2017 [[i.4]](#[i.4]). + +A meter single scheduled action may be described by its: execution time ([s4grid:hasExecutionTime](#s4grid:hasExecutionTime)) and what script is going to be executed ([s4grid:executesScript](#s4grid:executesScript)). Besides, a single schedule action can be related to a meter by means of the [s4grid:hasSingleScheduledAction](#s4grid:hasSingleScheduledAction) property. + + +
+ Scheduled action model +
Figure 12: Scheduled action model
+
+ + +### Activity calendar + +SAREF4GRID allows modelling the handling of various tariff structures in the meter by means of the [s4grid:ActivityCalendar](#s4grid:ActivityCalendar) class, as presented in [Figure 13](#Figure_13). An activity calendar provides a list of scheduled actions, following the classical way of calendar-based schedules by defining seasons, weeks, etc. The representation of the meter activity calendar has been extracted from IEC 62056-6-2:2017 [[i.4]](#[i.4]). + +An activity calendar is active ([s4grid:hasCalendarNameActive](#s4grid:hasCalendarNameActive)) if it is currently used for billing. Each active calendar has an associated passive calendar ([s4grid:hasCalendarNamePassive](#s4grid:hasCalendarNamePassive)) and its function is to allow to modify the parameters of the active calendar on a date prior to its activation date ([s4grid:hasActivatePassiveCalendarTime](#s4grid:hasActivatePassiveCalendarTime)). Activation date is the date from which the meter will use the passive calendar parameters and, therefore, they become active calendar parameters. An active calendar is compound by active seasons ([s4grid:hasActiveSeasonProfile](#s4grid:hasActiveSeasonProfile)) and a passive calendar is compound by passive seasons ([s4grid:hasPassiveSeasonProfile](#s4grid:hasPassiveSeasonProfile)). Notice that there is no distinction between an active calendar and a passive calendar because together they represent an activity calendar and they share the same OBIS code. + +A season profile ([s4grid:SeasonProfile](#s4grid:SeasonProfile)) represents periods of time during the year when billing conditions are always the same. A season profile is characterized by a start date ([s4grid:hasSeasonStart](#s4grid:hasSeasonStart)) and seven day profiles ([s4grid:hasDayProfile](#s4grid:hasDayProfile)) to apply, which together represent a week (there is one day profile for each day of the week). A season profile finishes when the next season profile begins. + +A day profile ([s4grid:DayProfile](#s4grid:DayProfile)) represents the discrimination of time along the day. Moreover, the seven day profiles together represent a period during the week when billing conditions are always the same. There are two day profiles: regular days ([s4grid:RegularDayProfile](#s4grid:RegularDayProfile)), which represent not festive days, and special days ([s4grid:SpecialDayProfile](#s4grid:SpecialDayProfile)), which represent at which date there is a festivity, i.e. normal day behaves as a special day ([s4grid:hasScpecialDayDate](#s4grid:hasScpecialDayDate)). A day profile is characterized by a day schedule ([s4grid:hasDaySchedule](#s4grid:hasDaySchedule)). + +A day schedule ([s4grid:DaySchedule](#s4grid:DaySchedule)) defines the activation of certain scripts during the day, which can perform different activities inside the meter. For each day schedule, a list of scheduled actions is defined by a script to be executed ([s4grid:executesScript](#s4grid:executesScript)) with the corresponding activation time ([s4grid:hasStartTime](#s4grid:hasStartTime)). + + +
+ Activity calendar model +
Figure 13: Activity calendar model
+
+ + +### Power line properties + +As it can be observed in [Figure 14](#Figure_14) and [Figure 15](#Figure_15), the modelling of observations in the SAREF4GRID ontology mostly relies on the observation model proposed in SAREF. In order to reduce duplication with SAREF documentation, the reader is referred to the SAREF specification [[1]](#[1]) for details about observation modelling including here details only for the new concepts. + +The DLMS/COSEM standard (IEC 62056-1-0 [[i.2]](#[i.2])) defines the observations that a meter shall take from a power line. It should be noted that in SAREF4GRID only the general properties are being defined. In order to use a more specific property it is necessary to indicate the general property from which it comes from. The properties that are defined in SAREF4GRID, which are measured from a power line ([s4grid:PowerLine](#s4grid:PowerLine)), are depicted in [Figure 14](#Figure_14) and [Figure 15](#Figure_15). + +SAREF4GRID categorizes the main properties related to the energy and power observations of a power line ([s4grid:EnergyPowerProperty](#s4grid:EnergyPowerProperty)): active energy observations ([s4grid:ActiveEnergy](#s4grid:ActiveEnergy)), reactive energy measurements observations ([s4grid:ReactiveEnergy](#s4grid:ReactiveEnergy)), apparent power observations ([s4grid:ApparentPower](#s4grid:ApparentPower)), demand register observations ([s4grid:DemandRegister](#s4grid:DemandRegister)), active power observations ([s4grid:ActivePower](#s4grid:ActivePower)), reactive power observations ([s4grid:ReactivePower](#s4grid:ReactivePower)), current observations ([s4grid:Current](#s4grid:Current)), voltage observations ([s4grid:Voltage](#s4grid:Voltage)), and power factor related observations ([s4grid:PowerFactor](#s4grid:PowerFactor)). + + +
+ Energy and power property model +
Figure 14: Energy and power property model
+
+ + +SAREF4GRID also categorises the main properties related to the quality observations of a power line ([s4grid:QualityProperty](#s4grid:QualityProperty)): duration of voltage sags ([s4grid:DurationVoltageSag](#s4grid:DurationVoltageSag)), duration of voltage swells ([s4grid:DurationVoltageSwell](#s4grid:DurationVoltageSwell)), and duration of long power failures ([s4grid:DurationLongPowerFailure](#s4grid:DurationLongPowerFailure)). + +
+ Quality property model +
Figure 15: Quality property model
+
+ + +### Profile generic + +SAREF4GRID allows modelling the storing, sorting and accessing of data groups or data series (i.e. capture objects in COSEM) in the meter by means of the [s4grid:ProfileGeneric](#s4grid:ProfileGeneric) class, as presented in [Figure 16](#Figure_16). Capture objects are specific attributes or elements of (an) attribute(s) of COSEM objects. The capture objects are collected periodically or occasionally. The representation of the profile generic of a meter has been extracted from IEC 62056-62:2017 [[i.4]](#[i.4]). + +A profile generic is represented by the objects that it captures ([s4grid:Clock](#s4grid:Clock), [saref:PropertyValues](https://saref.etsi.org/core/PropertyValues) and [saref:Observations](https://saref.etsi.org/core/Observations)). These objects are collected in each period defined in the [s4grid:hasCapturePeriod](#s4grid:hasCapturePeriod) property. + + +
+ Profile generic model +
Figure 16: Profile generic model
+
+ + +### Get service + +[Figure 17](#Figure_17) provides an overview of the modelling of get services ([s4grid:GetService](#s4grid:GetService)). A get service is performed through get operations ([s4grid:GetOperation](#s4grid:GetOperation)). The get operation modelling involves two main concepts, namely [s4grid:CosemOperationInput](#s4grid:CosemOperationInput) and [s4grid:GetOperationOutput](#s4grid:GetOperationOutput). As can be seen in the figure, the modelling of get services totally relies on the service model proposed in ETSI TS 118 112 [[2]](#[2]). In order to reduce duplication with the oneM2M documentation, the reader is referred to the oneM2M specification for details about service modelling. The representation of the inputs and outputs of a get service has been extracted from IEC 6205662:2017 [[i.4]](#[i.4]). + +A get operation needs one input which represents what is going to be retrieved (the whole instance or just a property of the instance). Therefore, the input of a get operation can be either a class, the range of a datatype property, or the range of an object property. The [s4grid:CosemOperationInput](#s4grid:CosemOperationInput) class specifies the instance from which data is going to be retrieved by indicating the OBIS code ([s4grid:obtainInputFromObis](#s4grid:obtainInputFromObis)). If only the OBIS code is specified, it is understood that the whole instance is going to be retrieved. Moreover, the [s4grid:GetOperationPropertyInput](#s4grid:GetOperationPropertyInput) class specifies the object/datatype property of an instance from which data is going to be retrieved by indicating the OBIS code and the name of the object/datatype property ([s4grid:obtaintInputForProperty](#s4grid:obtaintInputForProperty)). If the OBIS code and the property name are specified, it is understood that just the range of a property of the instance is going to be retrieved. + +A get operation is going to generate one output which represents the type of what is going to be retrieved. The output of a get operation ([s4grid:GetOperationOutput](#s4grid:GetOperationOutput)) can be either a class or a datatype. The [s4grid:GetOperationDataOutput](#s4grid:GetOperationDataOutput) class specifies that the output is going to be a datatype. In this case the type of the output is defined using the [s4grid:hasOutputDataType](#s4grid:hasOutputDataType) property, indicating the type of the datatype. The [s4grid:GetOperationObjectOutput](#s4grid:GetOperationObjectOutput) class specifies that the output is going to be a class. In this case the type of the output is defined using the [s4grid:hasOutputObjectType](#s4grid:hasOutputObjectType) property, indicating the name of the class. + +Additionally, in the case of a get service of a [s4grid:ProfileGeneric](#s4grid:ProfileGeneric) class, a selective access ([s4grid:SelectiveAccess](#s4grid:SelectiveAccess)) can be specified. This indicates the range of entries to be retrieved ([s4grid:EntryDescriptor](#s4grid:EntryDescriptor)) or the range of values ([s4grid:RangeDescriptor](#s4grid:RangeDescriptor)) to be retrieved from a [s4grid:ProfileGeneric](#s4grid:ProfileGeneric) class. + + +
+ Get service model +
Figure 17: Get service model
+
+ + +### Set service + +[Figure 18](#Figure_18) provides an overview of the modelling of set services ([s4grid:SetService](#s4grid:SetService)). A set service is performed through set operations ([s4grid:SetOperation](#s4grid:SetOperation)). The set operation modelling involves one main concept, namely [s4grid:CosemOperationInput](#s4grid:CosemOperationInput). As can be seen in the figure, the modelling of set services totally relies on the service model proposed in ETSI TS 118 112 [[2]](#[2]). In order to reduce duplication with the oneM2M documentation, the reader is referred to the oneM2M specification for details about service modelling. The representation of the inputs and outputs of a set service has been extracted from IEC 62056-6-2:2017 [[i.4]](#[i.4]). + +A set operation needs two inputs: the element that is going to be modified and the new data that is going to replace the old data. The element that is going to be modified is represented by a class meanwhile the new data is represented either by a class, the range of a datatype property, or the range of an object property (depending on if the whole instance is going to be modified or just a property). Therefore, the [s4grid:CosemOperationInput](#s4grid:CosemOperationInput) class specifies the instance from which data is going to be modified by indicating the OBIS code ([s4grid:obtaintInputFromObis](#s4grid:obtaintInputFromObis)) and the new data is represented either by the [s4grid:SetOperationObisInput](#s4grid:SetOperationObisInput), [s4grid:SetOperationObjectInput](#s4grid:SetOperationObjectInput), or [s4grid:SetOperationDataInput](#s4grid:SetOperationDataInput) classes. + +The [s4grid:SetOperationObisInput](#s4grid:SetOperationObisInput) class indicates that the whole instance is going to be modified. In this case the type of the input is defined using the [s4grid:hasInputObjectType](#s4grid:hasInputObjectType) property, indicating the name of the class expected to modify the instance. The [s4grid:SetOperationObjectInput](#s4grid:SetOperationObjectInput) class indicates that just the range of an object property of the instance is going to be modified. In this case the type of the input is defined using the [s4grid:obtainInputForProperty](#s4grid:obtainInputForProperty), which indicates the name of the object property whose range is going to be modified, and the [s4grid:hasInputObjectType](#s4grid:hasInputObjectType) property, indicating the name of the class expected to modify the range of the object property. The [s4grid:SetOperationDataInput](#s4grid:SetOperationDataInput) class indicates that just the range of a datatype property of the instance is going to be modified. In this case the type of the input is defined using the [s4grid:obtainInputForProperty](#s4grid:obtainInputForProperty), which indicates the name of the datatype property whose range is going to be modified, and the [s4grid:hasInputDataType](#s4grid:hasInputDataType) property, which indicates the type of the datatype expected to modify the range of the datatype property. + + +
+ Set service model +
Figure 18: Set service model
+
+ + +### Action service + +[Figure 19](#Figure_19) provides an overview of the modelling of action services ([s4grid:ActionService](#s4grid:ActionService)). An action service is performed through action operations ([s4grid:ActionOperation](#s4grid:ActionOperation)). The action operation modelling involves one main concept, namely [s4grid:CosemOperationInput](#s4grid:CosemOperationInput). As can be seen in the figure, the modelling of action services totally relies on the service model proposed in ETSI TS 118 112 [[2]](#[2]). In order to reduce duplication with the oneM2M documentation, the reader is referred to the oneM2M specification for details about service modelling. The representation of the inputs and outputs of an action service has been extracted from IEC 62056-6-2:2017 [[i.4]](#[i.4]). + +An action operation needs two inputs: the element that is going to be affected by an action and the parameters necessary for the action to be executed. The element that is going to be affected by an action is represented by a class and the parameters are either represented by a class or a value. Therefore, the [s4grid:CosemOperationInput](#s4grid:CosemOperationInput) class specifies the instance from which data is going to be modified by indicating the OBIS code ([s4grid:obtainInputFromObis](#s4grid:obtainInputFromObis)) and the parameters are represented either by the [s4grid:SimpleActionOperationInput](#s4grid:SimpleActionOperationInput) or the [s4grid:ComplexActionOperationInput](#s4grid:ComplexActionOperationInput) classes. The [s4grid:CosemOperationInput](#s4grid:CosemOperationInput) class specifies the instance that is going to be affected by the action by indicating the OBIS code ([s4grid:obtainInputFromObis](#s4grid:obtainInputFromObis)). The [s4grid:SimpleActionOperationInput](#s4grid:SimpleActionOperationInput) class indicates that the parameter needed by the action to operate is simple (i.e. integer, string, etc.). In this case the value of the parameter is defined using the [s4grid:hasActionValue](#s4grid:hasActionValue) property. The [s4grid:ComplexActionOperationInput](#s4grid:ComplexActionOperationInput) class indicates that the parameter needed by the action to operate is complex (i.e. structure). There are two cases of complex parameters: [s4grid:PresetAdjustingTime](#s4grid:PresetAdjustingTime) class, which is needed by a [s4grid:Clock](#s4grid:Clock) to modify the time, and [s4grid:SpecialDayEntry](#s4grid:SpecialDayEntry) class, which is needed by an [s4grid:ActivityCalendar](#s4grid:ActivityCalendar) to adding a new special day. + + +
+ Action service model +
Figure 19: Action service model
+
+ + diff --git a/documentation/examples.md b/documentation/examples.md new file mode 100644 index 0000000000000000000000000000000000000000..5597ed164137c007a1bd97ddf11da81c54d5c147 --- /dev/null +++ b/documentation/examples.md @@ -0,0 +1,186 @@ +
NOTE: The text in this section is extracted from ETSI TS 103 410-12 (V2.1.1) [0], and therefore falls inside the ETSI IPR Policy
+ +This clause shows different examples of how to instantiate the SAREF4GRID extension of SAREF. + +The example presented in [Figure 20](#Figure_20) depicts an electric grid meter (ex:Meter1234). It can be described by a set of meter properties (such as the one shown in the figure, ex:ScrollDisplayMode) that are identified by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). Notice that some meter properties do not specify a unit of measure. + +SAREF4GRID does not aim to provide an exhaustive definition of all the properties defined in IEC 6205662 [[i.4]](#[i.4]). Instead, it defines a set of general properties (those shown in [Figure 6](#Figure_6), e.g. [s4grid:ScreenDisplay](#s4grid:ScreenDisplay) in the figure) and specific properties can be related to these general properties using the SKOS ontology [[i.5]](#[i.5]). Using SKOS more specific properties can be defined specifying from which general property they are derived (skos:narrower), and which properties belong to a general property (skos:broader). + + +
+ Example of electric grid meter information I +
Figure 20: Example of electric grid meter information I
+
+ +The example presented in [Figure 21](#Figure_21) depicts an electric grid meter (ex:Meter1234). It can be described by a set of meter properties (e.g. ex:ActivePowerLimitContract1TariffPeriod1) which are identified by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). The meter properties used to describe a meter are broader than the properties shown in [Figure 6](#Figure_6) (e.g. [s4grid:PowerLimit](#s4grid:PowerLimit)). Notice that some meter properties specify a unit of measure (e.g. [om:watt](http://www.wurvoc.org/vocabularies/om-1.8/watt)). + + +
+ Example of electric grid meter information II +
Figure 21: Example of electric grid meter information II
+
+ +Unlike other SAREF extensions, a meter firmware is not defined by a datatype property. The example presented in [Figure 22](#Figure_22) depicts a meter firmware (e.g. ex:ActivePLCFirmware) which is represented by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). + + +
+ Example of electric grid meter firmware +
Figure 22: Example of electric grid meter firmware
+
+ +[Figure 23](#Figure_23) contains an example of a network interface (ex:MacAddress1234) defined for a meter. Moreover, the network interface is represented by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). + + +
+ Example of electric grid meter network interface +
Figure 23: Example of electric grid meter network interface
+
+ +[Figure 24](#Figure_24) contains an example of a meter clock (ex:Clock1234). Moreover, the clock is represented by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). Notice that the clock is not only represented by a time ([s4grid:hasTime](#s4grid:hasTime)) but is also represented by the time zone in which it is located and how the time is changed. + + +
+ Example of electric grid meter clock +
Figure 24: Example of electric grid meter clock
+
+ +[Figure 25](#Figure_25) contains an example of a meter breaker state (ex:CurrentBreakerState). In this example, it is represented that the meter is physically connected ([s4grid:hasOutputState](#s4grid:hasOutputState)), internally connected ([s4grid:hasControlState](#s4grid:hasControlState)), and it can be remotely, manually and locally disconnected ([s4grid:hasControlMode](#s4grid:hasControlMode)). Moreover, the breaker state is represented by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). + + + +
+ Example of electric grid meter breaker state +
Figure 25: Example of electric grid meter breaker state
+
+ +[Figure 26](#Figure_26) contains an example of how scripts (ex:ConnectionScript and ex:DisconnectionScript) are stored in the meter. A script table (ex:DisconnectScriptTable) is needed in order to represent where the scripts are located. Moreover, a single scheduled action (ex:DisconnectControlScheduler) is used to represent that a script is going to be executed in a determined date. Moreover, the script table and single scheduled action are represented by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). + + +
+ Example of electric grid meter script table and scheduled action +
Figure 26: Example of electric grid meter script table and scheduled action
+
+ +[Figure 27](#Figure_27) contains an example of how an activity calendar (ex:ActivityCalendarContract1-1234) is represented in a meter. This activity calendar is represented by an active season profile (ex:SeasonActive1) that is described by the date at which it starts and two regular day profiles: one that describes working days (ex:WeekDay) and other that describes weekend days (ex:WeekendDay). Each day profile is represented by when a billing period starts each day (ex:WeekDayTariffPeriod1 and ex:WeekendDayTariffPeriod1) and what scripts need to be executed to make the billing (ex:ResetBillingPeriod1 and ex:ResetBillingPeriod2). Additionally, a special day profile (ex:SpecialFriday1) defines which days are special (e.g. festive) and, therefore, another tariffication is going to be applied. Moreover, the activity calendar is represented by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). Notice that just the active calendar is represented (e.g. the passive calendar associated to the active calendar is not represented) in order to simplify the example. + + +
+ Example of electric grid meter activity calendar +
Figure 27: Example of electric grid meter activity calendar
+
+ +One of the main functions of electric grid meters is to take measures from a power line in order to control what is happening in the electric grid. [Figure 28](#Figure_28) presents an example of a power line observation (ex:TotalIncrementalActiveEnergyImportObservation123) for a power line property (ex:TotalIncrementalActiveEnergyImport) that is identified by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). + +As with meter properties, SAREF4GRID does not aim to provide an exhaustive definition of all the properties defined in IEC 62056-6-2 [[i.4]](#[i.4]). Instead, it defines a set of general properties (those shown in [Figure 14](#Figure_14) and [Figure 15](#Figure_15), e.g. [s4grid:ActiveEnergy](#s4grid:ActiveEnergy) in the figure) and specific properties can be related to these general properties using the SKOS ontology [[i.5]](#[i.5]). Using SKOS more specific properties can be defined specifying from which general property they are derived (skos:narrower), and which properties belong to a general property (skos:broader). + + +
+ Example of electric grid meter observations I +
Figure 28: Example of electric grid meter observations I
+
+ +[Figure 29](#Figure_29) presents another example of a power line observation (ex:MaximumDemandRegisterImportC1TP1Observation136) for a power line property (ex:MaximumDemandRegisterImportC1TP1) that is identified by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). The power line properties are broader than the properties shown in [Figure 14](#Figure_14) and [Figure 15](#Figure_15) (e.g. [s4grid:DemandRegister](#s4grid:DemandRegister)). + + +
+ Example of electric grid meter observations II +
Figure 29: Example of electric grid meter observations II
+
+ +Different profile generics can be generated in order to access data groups that are stored in an electric grid meter. [Figure 30](#Figure_30) presents an example of a profile generic (ex:IncrementalLoadProfile1234) whose objective is to store the incremental energy values that a meter measures (ex:Observation1 to ex:Observation6) each hour. Additionally, the profile generic stores the clock (ex:Clock1234) to indicate the time at which the profile generic captures elements, and the AMR status (ex:PropertyValue1) that the meter stores. Moreover, the profile generic is represented by an OBIS code ([s4grid:hasObis](#s4grid:hasObis)). + + +
+ Example of electric grid meter profile generic +
Figure 30: Example of electric grid meter profile generic
+
+ +Each element that a meter stores can be obtained through a get service. [Figure 31](#Figure_31) presents an example of how it is specified that a COSEM element is going to be obtained. A get service (ex:GetServiceIncrementalLoadProfile) is executed through a get operation (ex:GetOperationIncrementalLoadProfile). This operation indicates the desired input (ex:OperationInputIncrementalLoadProfile), which in this case specifies the element from which data is going to be retrieved, and the desired output (ex:OutputIncrementalLoadProfile), which in this case specifies the data structure that is going to be given. + + +
+ Example of electric grid meter get service I +
Figure 31: Example of electric grid meter get service I
+
+ +[Figure 32](#Figure_32) presents an example of how it is specified that an attribute of a COSEM element is going to be obtained. Notice that in this example, the attribute corresponds to a datatype property of the SAREF4GRID ontology. A get service (ex:GetServiceCapturePeriodIncrementalLoadProfile) is executed through a get operation (ex:GetOperationCapturePeriodIncrementalLoadProfile). This operation indicates the desired input (ex:OperationInputCapturePeriodIncrementalLoadProfile), which in this case specifies the datatype property of the element from which data is going to be retrieved, and the desired output (ex:OutputCapturePeriodIncrementalLoadProfile), which in this case specifies the datatype that is going to be given. + + +
+ Example of electric grid meter get service II +
Figure 32: Example of electric grid meter get service II
+
+ +[Figure 33](#Figure_33) presents an example of how it is specified that an attribute of a COSEM element is going to be obtained. Notice that in this example, the attribute corresponds to an object property of the SAREF4GRID ontology. A get service (ex:GetServiceDisconnectionScript) is executed through a get operation (ex:GetOperationDisconnectionScript). This operation indicates the desired input (ex:OperationInputDisconnectionScript), which in this case specifies the object property of the element from which data is going to be retrieved, and the desired output (ex:OutputDisconnectionScript), which in this case specifies the data structure that is going to be given. + + +
+ Example of electric grid meter get service III +
Figure 33: Example of electric grid meter get service III
+
+ +Property-related services in get operations usually refer to the entire property. However, in the case of certain properties, selective access to only part of the property may be provided. [Figure 34](#Figure_34) presents an example of how it is specified that a range of values are going to be retrieved from a profile generic. A selective range get service (ex:GetServiceIncrementalLoadProfileRange) is executed through a get operation (ex:GetOperationIncrementalLoadProfileRange). + +This operation indicates the desired input (ex:OperationInputIncrementalLoadProfileRange), which in this case specifies the element from which data is going to be retrieved, and the desired output (ex:OutputIncrementalLoadProfileRange), which in this case specifies the data structure that is going to be given. Additionally, a selective access with a range descriptor (ex:RangeDescriptor1) indicates that just the entries whose value is between 1 and 10 are going to be retrieved. + + +
+ Example of electric grid meter get service IV +
Figure 34: Example of electric grid meter get service IV
+
+ +[Figure 35](#Figure_35) presents an example of how it is specified that a range of entries are going to be retrieved from a profile generic. A selective entry get service (ex:GetServiceIncrementalLoadProfileEntry) is executed through a get operation (ex: GetOperationIncrementalLoadProfileEntry). This operation indicates the desired input (ex:OperationInputIncrementalLoadProfileEntry), which in this case specifies the element from which data is going to be retrieved, and the desired output (ex:OutputIncrementalLoadProfileEntry), which in this case specifies the data structure that is going to be given. Additionally, a selective access with an entry descriptor (ex:EntryDescriptor1) indicates that just the top 10 entries are going to be retrieved. + + +
+ Example of electric grid meter get service V +
Figure 35: Example of electric grid meter get service V
+
+ +Each element that a meter stores can be modified through a set service. [Figure 36](#Figure_36) presents an example of how it is specified that a COSEM element is going to be modified. A set service (ex:SetMulticastCommunicationIdentifier) is executed through a set operation (ex:SetOperationMulticastCommunicationIdentifier). This operation indicates the desired input (ex:InputMulticastCommunicationIdentifier), which in this case specifies the element from which data is going to be modified and the data structure that is going to replace the previous data. + + +
+ Example of electric grid meter set service I +
Figure 36: Example of electric grid meter set service I
+
+ +[Figure 37](#Figure_37) presents an example of how it is specified that an attribute of a COSEM element is going to be modified. Notice that in this example, the attribute corresponds to a datatype property of the SAREF4GRID ontology. A set service (ex:SetServiceCapturePeriodIncrementalLoadProfile) is executed through a set operation (ex:SetOperationCapturePeriodIncrementalLoadProfile). This operation indicates the desired input (ex:InputICapturePeriodIncrementalLoadProfile), which in this case specifies the datatype property of the element from which data is going to be modified and the data type that is going to replace the previous data. + + +
+ Example of electric grid meter set service II +
Figure 37: Example of electric grid meter set service II
+
+ +[Figure 38](#Figure_38) presents an example of how it is specified that an attribute of a COSEM element is going to be modified. Notice that in this example, the attribute corresponds to an object property of the SAREF4GRID ontology. A set service (ex:SetServiceDisconnectionScript) is executed through a set operation (ex:SetOperationDisconnectionScript). This operation indicates the desired input (ex:InputIDisconnectionScript), which in this case specifies the object property of the element from which data is going to be modified and the data structure that is going to replace the previous data. + + +
+ Example of electric grid meter set service III +
Figure 38: Example of electric grid meter set service III
+
+ +Each element that a meter stores can be affected through an action service. [Figure 39](#Figure_39) presents an example of how it is specified that a COSEM element is going to be affected by an action. Notice that in this example the input parameter needed to execute the action is simple (e.g. integer, string, etc.). An action service (ex:ResetServiceRegister) is executed through an action operation (ex:ResetServiceOperation). This operation indicates the desired input (ex:ResetServiceOperationInput), which in this case specifies the element that is going to be affected by the action and the value of the parameter needed by the action. + + +
+ Example of electric grid meter action service I +
Figure 39: Example of electric grid meter action service I
+
+ +[Figure 40](#Figure_40) presents an example of how it is specified that a COSEM element is going to be affected by an action. Notice that in this example the input parameter needed to execute the action is a structure. An action service (ex:PresetAdjustingTimeServiceClock) is executed through an action operation (ex:PresetAdjustingTimeOperation). This operation indicates the desired input (ex:PresetAdjustingTime1), which in this case specifies the element that is going to be affected by the action and the values of the parameter structure needed by the action. + + +
+ Example of electric grid meter action service II +
Figure 40: Example of electric grid meter action service II
+
+ +[Figure 41](#Figure_41) presents an example of how it is specified that a COSEM element is going to be affected by an action. Notice that in this example the input parameter needed to execute the action is a structure. An action service (ex:SpecialDayEntryServiceActivityCalendar) is executed through an action operation (ex:SpecialDayEntryOperation). This operation indicates the desired input (ex:SpecialDayEntry1), which in this case specifies the element that is going to be affected by the action and the values of the parameter structure needed by the action. + + +
+ Example of electric grid meter action service III +
Figure 41: Example of electric grid meter action service III
+
diff --git a/documentation/references.md b/documentation/references.md new file mode 100644 index 0000000000000000000000000000000000000000..50b2c127b2fb9df1ff87cd3a04d28670878fcc24 --- /dev/null +++ b/documentation/references.md @@ -0,0 +1,14 @@ +### Normative references + +* [0] [ETSI TS 103 410-12 (V2.1.1)](https://www.etsi.org/deliver/etsi_ts/103400_103499/10341012): "SmartM2M; Extension to SAREF; Part 12: Smart Grid Domain". +* [1] [ETSI TS 103 264](https://www.etsi.org/deliver/etsi_ts/103200_103299/103264/): "SmartM2M; Smart Applications; Reference Ontology and oneM2M Mapping". +* [2] [ETSI TS 118 112 (V3.7.3)](https://www.etsi.org/deliver/etsi_ts/118100_118199/118112/03.07.03_60/ts_118112v030703p.pdf): "oneM2M; Base Ontology; (oneM2M TS-0012 version 3.7.3 Release 3)". + + +### Informative references + +* [i.1] ETSI TR 103 904 (V1.1.1): "SmartM2M; SAREF extension investigation; Requirements for the Smart Grid domain". +* [i.2] IEC 62056-1-0:2014: "Electricity metering data exchange - The DLMS/COSEM suite - Part 1-0: Smart metering standardisation framework". +* [i.3] IEC 62056-6-1:2017: "Electricity metering data exchange - The DLMS/COSEM suite - Part 6-1: Object Identification System (OBIS)". +* [i.4] IEC 62056-6-2:2017: "Electricity metering data exchange - The DLMS/COSEM suite - Part 6-2: COSEM interface classes". +* [i.5] W3C® Recommendation 18 August 2009: "SKOS Simple Knowledge Organization System - Reference", A. Miles and S. Bechhofer.