improved documentation

The Smart Applications REFerence ontology (SAREF) is intended to enable interoperability between solutions from different providers and among various activity sectors in the Internet of Things (IoT), thus contributing to the development of the global digital market.

SAREF shall use the SAREF Communication framework as defined in [[5]](#[5]) (ETSI TS 103 267: "SmartM2M; Smart Appliances; Communication Framework”).

 No newline at end of file

The editors would like to thank the ETSI SmartM2M technical committee for providing guidance and expertise.

Also, many thanks to the ETSI staff and all other current and former active Participants of the ETSI SmartM2M group for their support, technical input and suggestions that led to improvements to this ontology.

Also, special thanks goes to the ETSI SmartM2M Technical Officer Guillemin Patrick for his help.

- [Laura Daniele](https://www.linkedin.com/in/lauradaniele) ([TNO](https://tno.nl/))

- [Raúl Garcia-Castro](http://www.garcia-castro.com/foaf.rdf#me) ([Universidad Politécnica de Madrid](http://www.oeg-upm.net/))

- [Maxime Lefrançois](http://maxime-lefrancois.info/me#) ([MINES Saint-Étienne](https://www.mines-stetienne.fr/))

- [Maria Poveda-Villalon](https://w3id.org/people/mpoveda/) ([Universidad Politécnica de Madrid](http://www.oeg-upm.net/))

<h3>General Overview</h3>

<p><a href="#Figure_1">Figure 1</a> shows an overview of the main classes of SAREF and their relationships.<p>

<figure>

  <img src="diagrams/Overview.png" alt="SAREF Overview"/>

  <figcaption id="Figure_1">Figure 1: Overview of the SAREF ontology</figcaption>

</figure>

<h3>Device</h3>

<p>SAREF focuses on the concept of device, which is defined as <q>a tangible object designed to accomplish a particular task in households, common public buildings or offices. In order to accomplish this task, the device performs one or more functions</q>. Examples of devices are a light switch, a temperature sensor, an energy meter and a washing machine. A washing machine is designed to wash (task) and to accomplish this task it performs a start and stop function. The <a href="#saref:Device">saref:Device</a> class and its properties are shown in <a href="#Figure_2">Figure 2</a>.</p>

<figure>

  <img src="diagrams/Device.png" alt="Device class"/>

  <figcaption id="Figure_2">Figure 2: Device class</figcaption>

</figure>

<p>A <a href="#saref:Device">saref:Device</a> can have some properties that uniquely characterize it, namely its model and manufacturer (<a href="#saref:hasModel">saref:hasModel</a> and <a href="#saref:hasManufacturer">saref:hasManufacturer</a> properties, respectively). </p>

<p>SAREF is conceived in a modular way in order to allow the definition of any device from pre-defined building blocks, based on the function(s) that the device performs. Therefore, a <a href="#saref:Device">saref:Device</a> has at least one function (<a href="#saref:hasFunction">saref:hasFunction</a> min 1 <a href="#saref:Function">saref:Function</a>). Moreover, a <a href="#saref:Device">saref:Device</a> can be used for (<a href="#saref:isUsedFor">saref:isUsedFor</a> property) the purpose of offering a commodity, such as <a href="#saref:Water">saref:Water</a> or <a href="#saref:Gas">saref:Gas</a>. It can also measure a property, such as <a href="#saref:Temperature">saref:Temperature</a>, <a href="#saref:Energy">saref:Energy</a> and <a href="#saref:Smoke">saref:Smoke</a>. Moreover, a device may consist of other devices (<a href="#saref:consistsOf">saref:consistsOf</a> property).</p>

<figure>

  <img src="diagrams/Device.png" alt="Types of devices"/>

  <figcaption id="Figure_3">Figure 3: Types of devices</figcaption>

</figure>

As shown in <a href="#Figure_3">Figure 3</a>, types of devices that can be represented are actuators (e.g. a <a href="#saref:Switch">saref:Switch</a> that can be further specialized in <a href="#saref:LightSwitch">saref:LightSwitch</a> and <a href="#saref:DoorSwitch">saref:DoorSwitch</a>), sensors (e.g. a <a href="#saref:SmokeSensor">saref:SmokeSensor</a> and <a href="#saref:TemperatureSensor">saref:TemperatureSensor</a>), meters, and appliances. Note that more types of devices, sensors and actuators exist which can be defined to extend SAREF (the device types in <a href="#Figure_4">Figure 4</a> represent only some examples that aim at explaining the rationale behind SAREF). A description of these types of devices is presented in the next clause, in combination with the function that they perform. Examples of devices for specific domains are defined in the SAREF extensions (<a href="#[i.2]">[i.2]</a> to <a href="#[i.7]">[i.7]</a>).

<h3>Function</h3>

<p>A function is represented in SAREF with the <a href="#saref:Function">saref:Function</a> class and is defined as <q>the functionality necessary to accomplish the task for which a device is designed</q>. Examples of functions are <a href="#saref:ActuatingFunction">saref:ActuatingFunction</a>, <a href="#saref:SensingFunction">saref:SensingFunction</a>, <a href="#saref:MeteringFunction">saref:MeteringFunction</a> and <a href="#saref:EventFunction">saref:EventFunction</a>. The <a href="#saref:Function">saref:Function</a> class and its properties are shown in <a href="#Figure_4">Figure 4</a>. </p>

<p>In particular:</p>

<ul>

  <li>The <a href="#saref:ActuatingFunction">saref:ActuatingFunction</a> allows to <q>transmit data to actuators, such as level settings (e.g. temperature) or binary switching (e.g. open/close, on/off)</q> and can be divided into different types, such as for example:</li>

  <ul>

    <li>The actuating function of type <a href="#saref:OnOffFunction">saref:OnOffFunction</a> allows to <q>switch on and off an actuator</q>. This function allows the commands <a href="#saref:OnCommand">saref:OnCommand</a>, <a href="#saref:OffCommand">saref:OffCommand</a> and <a href="#saref:ToggleCommand">saref:ToggleCommand</a>.</li>

    <li>The actuating function of type <a href="#saref:LevelControlFunction">saref:LevelControlFunction</a> allows to <q>do level adjustments of an actuator in a certain range (e.g. 0%-100%), such as dimming a light or set the speed of an electric motor</q>. This function allows the commands <a href="#saref:SetLevelCommand">saref:SetLevelCommand</a> (which can be of type <a href="#saref:SetAbsoluteLevel">saref:SetAbsoluteLevel</a> or <a href="#saref:SetRelativeLevel">saref:SetRelativeLevel</a>), <a href="#saref:StepUpCommand">saref:StepUpCommand</a> and <a href="#saref:StepDownCommand">saref:StepDownCommand</a>.</li>

  </ul>

  <li>The <a href="#saref:SensingFunction">saref:SensingFunction</a> allows to <q>transmit data from sensors, such as measurement values (e.g. temperature) or sensing data (e.g. occupancy)</q>. This function allows the command <a href="#saref:GetCommand">saref:GetCommand</a>.</li>

  <li>The <a href="#saref:MeteringFunction">saref:MeteringFunction</a> allows to <q>get data from a meter, such as current meter reading or instantaneous demand</q>. This function allows the commands <a href="#saref:GetCurrentMeterValueCommand">saref:GetCurrentMeterValueCommand</a>, <a href="#saref:GetMeterDataCommand">saref:GetMeterDataCommand</a>, and <a href="#saref:GetMeterHistoryCommand">saref:GetMeterHistoryCommand</a>. </li>

  <li>The <a href="#saref:EventFunction">saref:EventFunction</a> allows to <q>notify another device that a certain threshold value has been exceeded</q>. This function allows the command <a href="#saref:NotifyCommand">saref:NotifyCommand</a>.</li>

</ul>

<figure>

  <img src="diagrams/Function.png" alt="Function class "/>

  <figcaption id="Figure_4">Figure 4: Function class </figcaption>

</figure>

<p>In order to show how these functions shall be used, some examples of devices and their functions are defined as follows:</p>

<ul>

  <li>a washing machine is a device of type <a href="#saref:Appliance">saref:Appliance</a>, accomplishes the task <a href="#saref:Washing">saref:Washing</a> and performs an actuating function of type <a href="#saref:StartStopFunction">saref:StartStopFunction</a>;</li>

  <li>a sensor is a device of type <a href="#saref:Sensor">saref:Sensor</a> and performs a <a href="#saref:SensingFunction">saref:SensingFunction</a>;</li>

  <li>a temperature sensor is a device that consists of a sensor, is of type <a href="#saref:Sensor">saref:Sensor</a>, performs the <a href="#saref:SensingFunction">saref:SensingFunction</a> and measures a property of type <a href="#saref:Temperature">saref:Temperature</a>;</li>

  <li>a smoke sensor is a device that consists of a sensor, is of type <a href="#saref:Sensor">saref:Sensor</a>, performs the <a href="#saref:SensingFunction">saref:SensingFunction</a> (to measure a property of type <a href="#saref:Smoke">saref:Smoke</a>) and <a href="#saref:EventFunction">saref:EventFunction</a> (to notify that a certain threshold has been exceeded); </li>

  <li>a switch is a device that is of type <a href="#saref:Actuator">saref:Actuator</a> and performs an actuating function of type <a href="#saref:OnOffFunction">saref:OnOffFunction</a> or <a href="#saref:OpenCloseFunction">saref:OpenCloseFunction</a>;</li>

  <li>a door switch is a device that consists of a switch, is of type of <a href="#saref:Actuator">saref:Actuator</a>, performs the <a href="#saref:OpenCloseFunction">saref:OpenCloseFunction</a> and is used for the purpose of controlling a building object such as a door;</li>

  <li>a dimmer lamp is a device that is of type <a href="#saref:Actuator">saref:Actuator</a>, performs an actuating function of type <a href="#saref:LevelControlFunction">saref:LevelControlFunction</a> and measures a property of type <a href="#saref:Light">saref:Light</a>;</li>

  <li>a meter is a device that is of type <a href="#saref:Meter">saref:Meter</a> and performs a <a href="#saref:MeteringFunction">saref:MeteringFunction</a>;</li>

  <li>an energy meter is a device that consists of a meter, is of type <a href="#saref:Meter">saref:Meter</a>, performs the <a href="#saref:MeteringFunction">saref:MeteringFunction</a> and measures the <a href="#saref:Energy">saref:Energy</a> property.</li>

</ul>

<h3>Command</h3>

<p>A <a href="#saref:Function">saref:Function</a> shall have at least one command associated to it (<a href="#saref:hasCommand">saref:hasCommand</a> min 1 <a href="#saref:Command">saref:Command</a>). <a href="#Figure_5">Figure 5</a> shows the list of commands currently available in SAREF. This list is used here for illustration purposes and can be extended with new commands.</p>

<figure>

  <img src="diagrams/Command.png" alt="Command class"/>

  <figcaption id="Figure_5">Figure 5: Command class</figcaption>

</figure>

<p>For example:</p>

<ul>

  <li>The commands <a href="#saref:OnCommand">saref:OnCommand</a>, <a href="#saref:OffCommand">saref:OffCommand</a> and <a href="#saref:ToggleCommand">saref:ToggleCommand</a> are associated to the function <a href="#saref:OnOffFunction">saref:OnOffFunction</a>.</li>

  <li>The commands <a href="#saref:SetLevelCommand">saref:SetLevelCommand</a> (which can be of type <a href="#saref:SetAbsoluteLevel">saref:SetAbsoluteLevel</a> or <a href="#saref:SetRelativeLevel">saref:SetRelativeLevel</a>), <a href="#saref:StepUpCommand">saref:StepUpCommand</a> and <a href="#saref:StepDownCommand">saref:StepDownCommand</a> are associated to the function <a href="#saref:LevelControlFunction">saref:LevelControlFunction</a>.</li>

  <li>The command <a href="#saref:GetCommand">saref:GetCommand</a> is associated to the function <a href="#saref:SensingFunction">saref:SensingFunction</a>.</li>

  <li>The commands <a href="#saref:GetCurrentMeterValueCommand">saref:GetCurrentMeterValueCommand</a>, <a href="#saref:GetMeterDataCommand">saref:GetMeterDataCommand</a>, <a href="#saref:GetMeterHistoryCommand">saref:GetMeterHistoryCommand</a> are associated to the function <a href="#saref:MeteringFunction">saref:MeteringFunction</a>.</li>

  <li>The command <a href="#saref:NotifyCommand">saref:NotifyCommand</a> is associated to the function <a href="#saref:EventFunction">saref:EventFunction</a>.</li>

</ul>

<p>Figure 5 further shows that a command can act upon a state (<a href="#saref:actsUpon">saref:actsUpon</a> relation) to represent that the consequence of a command can be a change of state of a device. Note that a command may act upon a state, but does not necessarily act upon a state. For example, the <a href="#saref:OnCommand">saref:OnCommand</a> acts upon the <a href="#saref:OnOffState">saref:OnOffState</a>, but the <a href="#saref:GetCommand">saref:GetCommand</a> does not act upon any state, since it only gives a directive to retrieve a certain value.</p>

<h3>State</h3>

<p>Depending on the function(s) it performs, a device can be found in a corresponding <a href="#saref:State">saref:State</a>, as shown in <a href="#Figure_6">Figure 6</a>. For example, a switch can be found in the <a href="#saref:OnOffState">saref:OnOffState</a>, which is further specialized in <a href="#saref:OnState">saref:OnState</a> and <a href="#saref:OffState">saref:OffState</a>. A light switch can be found in the <a href="#saref:OnOffState">saref:OnOffState</a> upon which the <a href="#saref:OnCommand">saref:OnCommand</a> and <a href="#saref:OffCommand">saref:OffCommand</a> shall act. Note that SAREF is not restricted to binary states such as the <a href="#saref:OnOffState">saref:OnOffState</a>, but allows to define also n-ary states (see, for example, the <a href="#saref:MultiLevelState">saref:MultiLevelState</a> class). </p> 

<figure>

  <img src="diagrams/State.png" alt="State class"/>

  <figcaption id="Figure_6">Figure 6: State class</figcaption>

</figure>

<h3>Service</h3>

<p>Figure 7 shows that a device offers a service (the <a href="#saref:Service">saref:Service</a> class), which is a representation of a function to a network that makes this function discoverable, registerable and remotely controllable by other devices in the network. A service shall represent at least one function (<a href="#saref:represents">saref:represents</a> min 1 <a href="#saref:Function">saref:Function</a>) and is offered by at least one device that wants (a certain set of) its function(s) to be discoverable, registerable and remotely controllable by other devices in the network (<a href="#saref:isOfferedBy">saref:isOfferedBy</a> min 1 <a href="#saref:Device">saref:Device</a>). Multiple devices can offer the same service. A service shall specify the device that is offering the service and the function(s) to be represented.</p>

<p>For example, a light switch can offer the service of remotely switching the lights in a home through mobile phone devices that are connected to the local network (<a href="#saref:SwitchOnService">saref:SwitchOnService</a> class). This "remote switching" service represents the <a href="#saref:OnOffFunction">saref:OnOffFunction</a> previously described.</p>

<p>Note that the concept of service is further elaborated in the oneM2M Base Ontology <a href="#[4]">[4]</a>, to which the reader is referred in order to model the details of a service that are out of the scope of SAREF. </p>

<figure>

  <img src="diagrams/Service.png" alt="Service class"/>

  <figcaption id="Figure_7">Figure 7: Service class</figcaption>

</figure>

<h3>Profile</h3>

<p>A device in SAREF can be further characterized by a profile. <a href="#Figure_8">Figure 8</a> shows the <a href="#saref:Profile">saref:Profile</a> class and its properties. A profile is a specification associated to a device to collect information about a certain property or commodity (e.g. energy or water) for optimizing its usage in the home/building in which the device is located. Therefore, a profile is linked to a certain property or commodity (using the <a href="#saref:isAbout">saref:isAbout</a> property), can be calculated over a time span (using the <a href="#saref:hasTime">saref:hasTime</a> property) and can be associated to some costs (using the <a href="#saref:hasPrice">saref:hasPrice</a> property). A specialization of a profile is the Power Profile defined in the SAREF4ENER extension in ETSI TS 103 410-1 <a href="#[i.2]">[i.2]</a> (this power profile can be associated to a device for optimizing the energy efficiency in the home/building in which the device is located).</p>

<figure>

  <img src="diagrams/Profile.png" alt="Profile class"/>

  <figcaption id="Figure_8">Figure 8: Profile class</figcaption>

</figure>

<h3>Measurement, Property, and Unit of Measure</h3>

<p>The classes <a href="#saref:Measurement">saref:Measurement</a>, <a href="#saref:Property">saref:Property</a> and <a href="#saref:UnitOfMeasure">saref:UnitOfMeasure</a> allow to relate different measurements from a given device for different properties measured in different units, i.e. the <a href="#saref:Measurement">saref:Measurement</a> class describes a measurement of a physical quantity (using the <a href="#saref:hasValue">saref:hasValue</a> property) for a given <a href="#saref:Property">saref:Property</a> and according to a given <a href="#saref:UnitOfMeasure">saref:UnitOfMeasure</a>. In this way, it is possible to differentiate between properties and the measurements made for such properties, and to store measurements for a concrete property in different units of measurement. Furthermore, a timestamp can be added (using the <a href="#saref:hasTimestamp">saref:hasTimestamp</a> property) to identify when the measurement applies to the property, which can be used either for single measurements or for series of measurements (e.g. measurement streams). <a href="#Figure_9">Figure 9</a> shows that a <a href="#saref:Device">saref:Device</a> can measure or control a <a href="#saref:Property">saref:Property</a> (which may be from a <a href="#saref:FeatureOfInterest">saref:FeatureOfInterest</a>), which in turn relates to a <a href="#saref:Measurement">saref:Measurement</a>, which in turn is measured in a given <a href="#saref:UnitOfMeasure">saref:UnitOfMeasure</a>. Note that it is possible to follow also the inverse direction in which a <a href="#saref:Device">saref:Device</a> makes a measurement in a certain unit of measure (using the <a href="#saref:makesMeasurement">saref:makesMeasurement</a> property), and this measurement can be related to a <a href="#saref:Property">saref:Property</a> (using the <a href="#saref:relatesToProperty">saref:relatesToProperty</a> property). A <a href="#saref:FeatureOfInterest">saref:FeatureOfInterest</a> represents any real world entity from which a <a href="#saref:Property">saref:Property</a> is measured.</p>

<p>As an example, the <a href="#saref:Power">saref:Power</a> and <a href="#saref:Energy">saref:Energy</a> classes can be related to a certain measurement value (using the <a href="#saref:hasValue">saref:hasValue</a> property), which is measured in a certain unit of measure i.e. Kilowatt for power (<a href="#saref:PowerUnit">saref:PowerUnit</a>) and Kilowatt_Hour for energy (<a href="#saref:EnergyUnit">saref:EnergyUnit</a>). Analogously, the <a href="#saref:Price">saref:Price</a> class can be related to a certain measurement value that is measured using a certain <a href="#saref:Currency">saref:Currency</a>, which is a subclass of the <a href="#saref:UnitOfMeasure">saref:UnitOfMeasure</a> class. Further examples on how to define units of measure can be found in the different SAREF extensions (<a href="#[i.2]">[i.2]</a> to <a href="#[i.7]">[i.7]</a>).</p>

<p>The <a href="#saref:Time">saref:Time</a> class allows to specify the "time" concept in terms of temporal entities (i.e. instants or intervals) according to the existing W3C® Time ontology to avoid defining this concept from scratch. </p>

<figure>

  <img src="diagrams/Measurement.png" alt="Measurement class"/>

  <figcaption id="Figure_9">Figure 9: Measurement class</figcaption>

</figure>