Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • specifications/tr/tr-0073
1 result
Show changes
Commits on Source (3)
Hide whitespace changes
Inline Side-by-side
Showing
with 886 additions and 112 deletions
TR-0073-Developer_Guide_Deploying_Semantics.md
View file @ 2dfa5880
<p align="center">
<img src="media/image1.png" alt="__CAPTION__">
</p>
![oneM2M logo](media/logo.png)
|oneM2M<br />Technical Report |oneM2M<br />Technical Report |
|-|-|
|Document Number |TR-00xx-V-x.y.z |
|Document Name: |The name of the document<br /> |
|Date: |&lt;20yy-mm-dd> |
|Abstract: |&lt; An abstract of the document and information that may be used in subsequent electronic searches> |
|Template Version: January 2020 (do not modify) | |
|Document Number |TR-0073-Developer_Guide_Deploying_Semantics-V0_0_1 |
|Document Name: |Developer Guide: Deploying Semantics |
|Date: |2022-03-09 |
|Abstract: |This developer guide is to describe how developer can quickly implement semantic functionality of the release 3. The intended work is about a basic scenario describing the semantic annotation using SAREF and oneM2M Base ontologies using the oneM2M semantic descriptor resources and semantic discovery and semantic queries |
|Template Version: January 2017 |Template Version: January 2017 (Do not modify) |
The present document is provided for future development work within oneM2M only. The Partners accept no liability for any use of this report.
The present document has not been subject to any approval process by the oneM2M Partners Type 1. Published oneM2M specifications and reports for implementation should be obtained via the oneM2M Partners' Publications Offices.
The present document has not been subject to any approval process by the oneM2M Partners Type 1. Published oneM2M specifications and reports for implementation should be obtained via the oneM2M Partners' Publications Offices.
About oneM2M
The purpose and goal of oneM2M is to develop technical specifications which address the need for a common M2M Service Layer that can be readily embedded within various hardware and software, and relied upon to connect the myriad of devices in the field with M2M application servers worldwide.
More information about oneM2M may be found at: http//www.oneM2M.org
More information about oneM2M may be found at: http//www.oneM2M.org
Copyright Notification
(c) 2020, oneM2M Partners Type 1 (ARIB, ATIS, CCSA, ETSI, TIA, TSDSI, TTA, TTC).
(c) 2022, oneM2M Partners Type 1 (ARIB, ATIS, CCSA, ETSI, TIA, TSDSI, TTA, TTC).
All rights reserved.
......@@ -36,188 +35,962 @@ The copyright and the foregoing restriction extend to reproduction in all media.
Notice of Disclaimer & Limitation of Liability
**Notice of Disclaimer & Limitation of Liability**
The information provided in this document is directed solely to professionals who have the appropriate degree of experience to understand and interpret its contents in accordance with generally accepted engineering or other professional standards and applicable regulations. No recommendation as to products or vendors is made or should be implied.
NO REPRESENTATION OR WARRANTY IS MADE THAT THE INFORMATION IS TECHNICALLY ACCURATE OR SUFFICIENT OR CONFORMS TO ANY STATUTE, GOVERNMENTAL RULE OR REGULATION, AND FURTHER, NO REPRESENTATION OR WARRANTY IS MADE OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR AGAINST INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS. NO oneM2M PARTNER TYPE 1 SHALL BE LIABLE, BEYOND THE AMOUNT OF ANY SUM RECEIVED IN PAYMENT BY THAT PARTNER FOR THIS DOCUMENT, WITH RESPECT TO ANY CLAIM, AND IN NO EVENT SHALL oneM2M BE LIABLE FOR LOST PROFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES. oneM2M EXPRESSLY ADVISES ANY AND ALL USE OF OR RELIANCE UPON THIS INFORMATION PROVIDED IN THIS DOCUMENT IS AT THE RISK OF THE USER.
# Contents
[Contents](#contents)
[1 Scope](#1-scope)
[2 References](#2-references)
&nbsp;&nbsp;&nbsp;&nbsp;[2.1 Normative references](#21-normative-references)
&nbsp;&nbsp;&nbsp;&nbsp;[2.2 Informative references](#22-informative-references)
[3 Definition of terms, symbols and abbreviations](#3-definition-of-terms,-symbols-and-abbreviations)
&nbsp;&nbsp;&nbsp;&nbsp;[3.1 Terms](#31-terms)
&nbsp;&nbsp;&nbsp;&nbsp;[3.2 Symbols](#32-symbols)
&nbsp;&nbsp;&nbsp;&nbsp;[3.3 Abbreviations](#33-abbreviations)
[4 Conventions](#4-conventions)
[5 User defined clause(s) from here onwards](#5-user-defined-clause%28s%29-from-here-onwards)
&nbsp;&nbsp;&nbsp;&nbsp;[5.1 User defined subdivisions of clause(s) from here onwards](#51-user-defined-subdivisions-of-clause%28s%29-from-here-onwards)
[Proforma copyright release text block](#proforma-copyright-release-text-block)
&nbsp;&nbsp;&nbsp;&nbsp;[Annexes](#annexes)
[Annex &lt;A>:Title of annex](#annex-%26lta%3E%3Atitle-of-annex)
[Annex &lt;B>:Title of annex](#annex-%26ltb%3E%3Atitle-of-annex)
&nbsp;&nbsp;&nbsp;&nbsp;[ First clause of the annex](#----first-clause-of-the-annex)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[B.1.1 First subdivided clause of the annex](#b11----first-subdivided-clause-of-the-annex)
[Annex &lt;y>:Bibliography](#annex-%26lty%3E%3Abibliography)
[History](#history)
# 1 Scope
The present document ...
`EXAMPLE: The present document provides the necessary adaptions to the endorsed document.`
# 1 Scope
The present document provides a simple use case for guiding application developers to model physical devices in oneM2M and adding semantic annotations that will enable interoperability of devices that are modelled in oneM2M:
<mark>The Scope shall not contain requirements.</mark>
- Describe the motivation for the use of semantics in oneM2M
- Description of a physical device that is to be modelled in oneM2M,
- Description of methods that can be used to model the device using oneM2M resources and procedures,
- The semantic annotation of the devices using the oneM2M base ontology,
- The semantic queries that can be used to discover device capabilities and enable interoperability,
- The call flows for implementation of the use case with a focus on the semantic aspects.
# 2 References
<mark>The following text block applies.</mark>
References are either specific (identified by date of publication and/or edition number or version number) or nonspecific. For specific references,only the cited version applies. For non-specific references, the latest version of the referenced document (including any amendments) applies.
## 2.1 Normative references
<mark>As a Technical Report (TR) is entirely informative it shall not list normative references.</mark>
The following referenced documents are necessary for the application of the present document.
Not applicable.
Normative references are not applicable in the present document.
## 2.2 Informative references
<mark>Clause 2.2 shall only contain informative references which are cited in the document itself.</mark>
References are either specific (identified by date of publication and/or edition number or version number) or nonspecific. For specific references, only the cited version applies. For non-specific references, the latest version of the referenced document (including any amendments) applies.
The following referenced documents are not necessary for the application of the present document but they assist the user with regard to a particular subject area.
- <a name="_ref_i.1">[i.1]</a> oneM2M Drafting Rules [https://member.onem2m.org/static_Pages/others/Rules_Pages/oneM2M-Drafting-Rules-V1%202%202.doc](https://member.onem2m.org/static_Pages/others/Rules_Pages/oneM2M-Drafting-Rules-V1%202%202.doc)
- <a name="_ref_i.1">[i.1]</a> oneM2M Drafting Rules.
> NOTE: Available at: [http://www.onem2m.org/images/files/oneM2M-Drafting-Rules.pdf](http://www.onem2m.org/images/files/oneM2M-Drafting-Rules.pdf).
# 3 Definition of terms, symbols and abbreviations
<mark>Delete from the above heading the word(s) which is/are not applicable.</mark>
- <a name="_ref_i.2">[i.2]</a> oneM2M TS-0011: "Common Terminology".
- <a name="_ref_i.3">[i.3]</a> oneM2M TS-0012: "Base Ontology".
- <a name="_ref_i.4">[i.4]</a> oneM2M TS-0030: "Generic Interworking".
- <a name="_ref_i.5">[i.5]</a> oneM2M TS-0001: "Functional Architecture".
- <a name="_ref_i.6">[i.6]</a> oneM2M TS-0004: "Service Layer Core Protocol".
- <a name="_ref_i.7">[i.7]</a> oneM2M TS-0009: "HTTP Protocol Binding".
- <a name="_ref_i.8">[i.8]</a> ETSI TS(R) 103 783: SAREF: SDT interoperability and oneM2M base ontology alignment
# 3 Definitions
## 3.1 Terms
<mark>Clause numbering depends on applicability.</mark>
For the purposes of the present document, the terms and definitions given in oneM2M TS-0011 <a href="#_ref_i.2">[i.2]</a> apply.
AE Application Entity
- <mark>A definition shall not take the form of, or contain, a requirement.</mark>
- <mark>The form of a definition shall be such that it can replace the term in context. Additional information shall be given only in the form of examples or notes (see below).</mark>
- <mark>The terms and definitions shall be presented in alphabetical order.</mark>
CSE Common Service Entity
For the purposes of the present document, the [following] terms and definitions [given in ... and the following] apply:
IPE Interworking Proxy Element
<mark>Definition format</mark>
nodn non-oneM2M device node
<mark>&lt;defined term>: &lt;definition></mark>
SAREF Smart Applications REFerence ontology
<mark>If a definition is taken from an external source, use the format below where [N] identifies the external document which must be listed in Section 2 References.</mark>
<mark>&lt;defined term>[N]: &lt;definition></mark>
# 4 Conventions
The key words "Shall", "Shall not", "May", "Need not", "Should", "Should not" in the present document are to be interpreted as described in the oneM2M Drafting Rules <a href="#_ref_i.1">[i.1]</a>.
<mark>example 1: text used to clarify abstract rules by applying them literally</mark>
> NOTE: This may contain additional information.
# 5 Motivation
The assumption of many existing oneM2M applications is that they interact with other oneM2M applications through known resource structures. They either create the resources themselves or are configured to use specific resources. Information is typically stored in containers, sometimes as base64-encoded content instances, with the implicit assumption that applications have a-priori knowledge of the syntax and semantics of this information.
## 3.2 Symbols
Depending on a-priori knowledge of the structures and data works well for small-scale vertical deployments of IoT devices. When the deployment evolves to include new devices, the existing applications change to reflect the new additions. However, in larger systems of IoT devices where the IoT devices may be a part of a legacy deployment or more than a single vertical solution, changes to all existing applications may become impractical. To enable growth and diversity of IoT devices in large heterogenous settings, applications need to be able to discover the structure and meaning of data from devices and how to use the services of the devices. In oneM2M Release 1 support for discovery of resources based on specific attribute values and the use of labels was defined. The agreement of a fixed set of labels (using a-priori knowledge) can be a viable solution for small deployments.
<mark>Clause numbering depends on applicability.</mark>
For the purposes of the present document, the [following] symbols [given in ... and the following] apply:
<mark>Symbol format</mark>
<mark>`&lt;symbol> &lt;Explanation>`</mark>
<mark>`&lt;2nd symbol> &lt;2nd Explanation>`</mark>
<mark>`&lt;3rd symbol> &lt;3rd Explanation>`</mark>
![Figure 1: Semantic understanding of device and data in IoT deployments](media/image2.png)
## 3.3 Abbreviations
**Figure 1: Semantic understanding of device and data in IoT deployments**
<mark>Abbreviations should be ordered alphabetically.</mark>
<mark>Clause numbering depends on applicability.</mark>
For medium or large deployments of heterogeneous IoT devices a more expressive approach for describing and discovering IoT devices is provided by oneM2M. Each type of device in a heterogeneous deployment can model services and data in the oneM2M Service Layer using different structures and syntax of data. For example, temperature sensors may report measurements using different units such as Celsius, Fahrenheit and Kelvin. Additionally, those IoT devices may measure different aspects, such as indoor temperature, outdoor temperature, refrigerator temperature, etc., and the representation of the measurement may differ as well.<br />
For the purposes of the present document, the [following] abbreviations [given in ... and the following] apply:
<mark>Abbreviation format</mark>
![Figure 2: Meaningfulness of data from IoT devices](media/image3.png)
<mark>`&lt;ABBREVIATION1> &lt;Explanation>`</mark>
<mark>`&lt;ABBREVIATION2> &lt;Explanation>`</mark>
<mark>`&lt;ABBREVIATION3> &lt;Explanation>`</mark>
**Figure 2: Meaningfulness of data from IoT devices**
With semantic annotations in oneM2M, all the different aspects of IoT devices can be described using RDF triples, which is a standard semantic format. The vocabulary used for a semantic description can be defined according to an ontology such as SAREF. With semantic discovery, applications can describe precisely what information they need or can deal with. This is powered by specifying a semantic filter using the SPARQL query language. The SPARQL filter is matched against the respective semantic annotations of each resource within the discovery scope. This feature in oneM2M helps applications to properly handle the data from the IoT devices.
Besides differences in the data from an IoT device in oneM2M the information model of devices can be modelled in a variety of ways. As with most IoT platforms, oneM2M supports custom information models that are defined for a specific use case and work well in small scale or single vertical scenarios. Another method that oneM2M defines to model devices is based on the semantic description of a device that is mapped to a resource structure (see TS-0030). A third approach to modelling devices in oneM2M is the use of Smart Device Templates (see TS-0023).
With all these options available to model a device the ability to have a-priori knowledge of a device model becomes less likely as IoT deployments scale beyond small vertical use cases. The oneM2M Base Ontology addresses this and enables developers of these different models to make them interoperable if the appropriate semantic annotations are made and semantic filtering is used to discover the appropriate API for a model. The focus of the remainder of this developer guide is to demonstrate this process.
# 6 System Description
## 6.1 Use case
The example scenario describes a clothes-washing machine and an application to monitor and control the IoT enabled product. This clause will show three different oneM2M resource tree models of the clothes washing machine and the call flows to create those models. The logic and call flows necessary for a client application to control and monitor the status of the clothes-washing machine is also described. In the next clause the washing machine capabilities are described using the SAREF ontology so that the client application can discover the washing machines. Additionally, the oneM2M Base Ontology describes how to use the device and commands that these clothes washing machines offer so that the client application can control any of them without regard to which resource tree model represents them.
This simplified clothes-washing machine has enough features to demonstrate the difference between the different modelling approaches supported in oneM2M. The concepts shown here can be applied to a full featured clothes-washing machine or any other IoT enabled device for that matter. The features and capabilities that are modelled are:
- The washing machine has been produced by manufacturer XYZ.
- XYZ describes this type of washing machine as "Very cool Washing Machine".
- The model of the type of washing machine is XYZ_Cool.
- The state of the washing machine can take the values "WASHING" or "STOPPED" or "ERROR".
- The washing machine supports three commands: ON, OFF, Toggle
- The washing machine is in My_Bathroom.
![Figure 3: Functional Architecture for Smart Clothes Washing Machine](media/image4.png)
**Figure 3: Functional Architecture for Smart Clothes Washing Machine**
The clothes-washing machine is modelled as a non-oneM2M device (nodn) for all three models. However, everything in this guide applies equally if these were modelled as native oneM2M devices. There is no difference in the model or the call flows for everything to the right of the Interworking Proxy Element (IPE) shown in the figure below. Figure 4 shows a generic set of oneM2M call flow for the clothes washing machine (and the IPE) and the client application communicating through the oneM2M CSE. The level of detail provided here applies to all the different modelling approaches for the clothes washing machine. Differences in the call flows that are dependent on the model used, shown in blue shading, are further detailed where the specific models are described.
![Figure 4: Generic oneM2M Call Flows](media/image5.png)
**Figure 4: Generic oneM2M Call Flows**
The messages shown in Figure 4 are further described here:
- **Register the AE/IPE**. In oneM2M an IPE is a type of AE that is intended to communicate with nodn's. The IPE is responsible for registering itself and creating the appropriate resources in a oneM2M CSE to model the nodn as if it were a oneM2M device. The result is that a washing machine that is native oneM2M and a washing machine that is non-oneM2M can be modelled the same way and the client applications cannot tell the difference.
- **Create Polling Channel**. A &lt;pollingChannel> resource is used by applications or devices that are not reachable from the CSE that need to receive notification requests. This happens when, for example, the device is in a home with a firewall that prevents direct requests to the device from outside the local network in the home. [It is also appropriate for IoT devices that communicate using cellular networks].
- **Create Information Model**. The IPE creates all the resources needed to provide the status and enable control of the clothes washing machines. These messages (in almost all cases multiple resources are used) will be described with the details relevant to the specific model in later sub-clauses. This includes creating subscriptions to the resources that are used to enable the application to control the clothes washing machines.
- **Register Client application AE**. Client applications are also modelled as &lt;AE> resources and register in the oneM2M CSE.
- **Discover Washing Machine**. An application designed to control the clothes washing machines produced by manufacturer XYZ will be able to discover them using a-priori knowledge of labels that are used to identify those washing machines. Later we will see how using the semantics capabilities of oneM2M and the SAREF ontology the same application can discover and control clothes washing machines from any manufacturer.
- **Retrieve clothes washing machine resources**. The client application generally has a user interface to show the status and allow control of the clothes washing machine. The client application will retrieve the specific resources that it needs to provide that capability. The application may have more features than a given washing machine model supports or, similarly the clothes washing machine model may expose more features than the client application needs. This step will use SPARQL queries to dynamically determine what resources are needed by the client application.
- **Subscribe to resources**. The client application is made aware of changes in the state of a clothes washing machine by receiving notifications of the changes. The client application first subscribes to the resources that contain information that it needs.
- **Update the model resources**. When the state of the clothes washing machine changes, the change in state will be reflected in the oneM2M CSE.
- **Notification of state changes**. When resources in the oneM2M CSE are created or updated the CSE will send notifications to applications that are subscribed to the resources. A client application that receives a notification can present this information to users or take some other actions.
- **Send commands to clothes washing machine**. The client application exposes to a user features or capabilities of the clothes washing machine. The client application sends the appropriate oneM2M primitives, based on the model, to use those features or capabilities.
- **Generate notification** for clothes washing machine. When the client application sends a oneM2M primitive to a resource that controls the clothes washing machine, a notification is generated (assuming notifications were created). In our scenario, since the clothes washing machine and the IPE are behind a firewall and therefore not reachable, the notification for the IPE are stored in the CSE and made available to the IPE via the long polling process.
- **Poll for notifications**. Because the IPE cannot receive notifications directly, it must use the long polling procedure to retrieve its notifications from the CSE. The IPE processes notifications by sending commands to the clothes washing machine using the API of the clothes washing machine.
## 6.2 Device models using a Custom Model
Using oneM2M to represent devices allows for unlimited flexibility. A device model can be customized to support the needs of the manufacturer or system architecture. The resource tree structure shown here represents a custom model that has a single container for reading the status of the washing machine and a separate container to set or command the washing machine.
![Figure 5: Custom washing machine model](media/image6.png)
**Figure 5: Custom washing machine model**
![Figure 6: Custom Model oneM2M Call Flows](media/image7.png)
**Figure 6: Custom Model oneM2M Call Flows**
Only the messages highlighted in light blue are described here as the rest of the messages are the same as in the general call flow described in clause 6.1.
# 4 Conventions
The key words "Shall", "Shall not", "May", "Need not", "Should", "Should not" in this document are to be interpreted as described in the oneM2M Drafting Rules <a href="#_ref_i.1">[i.1]</a>
# 5 User defined clause(s) from here onwards
&lt;Text>
- Create Information Model. The IPE creates all the resources needed to for the clothes washing machine that it knows how to model a priori. This IPE is developed with awareness of the clothes washing machine interface and the model that it is creating in the oneM2M CSE.
- A &lt;container> resource is created for the Status information of the clothes washing machine. The IPE creates &lt;contentInstance> resources that have the following content when there are any changes in the status of the clothes washing machine:
```
{
"WashingMachineStatus ": "WASHING", // Or "STOPPED", "ERROR"
}
```
## 5.1 User defined subdivisions of clause(s) from here onwards
&lt;Text>
- A &lt;container> resource is created for the command and control of the clothes washing machine. When the client application is setting the state of the device the following payload can be provided in a &lt;contentInstance> resource:
<mark>The following text is to be used when appropriate:</mark>
```
{
"state": "ON", // Or "OFF", "Toggle"
}
```
- A &lt;subscription> resource is created as a child of the command &lt;container> resource by the IPE. This will cause a notification to be sent to the IPE when a new command is made by an application.
# <mark>Proforma copyright release text block</mark>
<mark>This text box shall immediately follow after the heading of an element (i.e. clause or annex) containing a proforma or template which is intended to be copied by the user. Such an element shall always start on a new page.</mark>
<mark>Notwithstanding the provisions of the copyright clause related to the text of the present document, oneM2M grants that users of the present document may freely reproduce the &lt;proformatype> proforma in this {clause|annex} so that it can be used for its intended purposes and may further publish the completed &lt;proformatype>.</mark>
<mark>&lt;PAGE BREAK></mark>
## 6.3 Device models using Semantic Modelling
A SAREF description of the washing machine is mapped to the resource structure shown in Figure 6 using the rules described in TS-0030 and TS-0012. A complete derivation of this example is shown in [ref to TS-0012] Annex B.1.3.3.
The description of our (simplified) washing machine using SAREF ontology is expanded upon here:
- The state of the washing machine is given by SAREF:state: WashingMachineStatus that can take the values "WASHING" or "STOPPED" or "ERROR".
- The washing machine has an actuating function: StartStopFunction which has three commands:
- ON_Command
- OFF_Command
- Toggle_Command
- The washing machine has also a metering function: MonitoringFunction that sets the WashingMachineStatus.
- The washing machine is located at My_Bathroom.
Later we will see that the description here has triples that are intended to help define the resosurce tree structure according to the rules described in TS-0030 and TS-0012. However, when the description of the clothes-washing machine is put into a &lt;semanticdescriptor> some are removed because they do not offer information useful for SPARQL queries.
>
```
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix oneM2M: <http://www.onem2m.org/ontology/Base_Ontology/> .
@prefix saref: <https://saref.etsi.org/core/> .
@prefix s4bldg: <https://saref.etsi.org/saref4bldg/> .
@prefix sn: <http://www.XYZ.com/WashingMachines/SerialNumbers/> .
sn:WASH_XYZ
a <http://www.XYZ.com/WashingMachines#XYZ_Cool> ;
rdfs:comment "Very cool Washing Machine" ;
saref:hasFunction sn:WASH_XYZ-MonitoringFunction , sn:WASH_XYZ-StartStopFunction ;
saref:hasManufacturer "XYZ" ;
saref:hasService sn:WASH_XYZ-MonitorService , sn:WASH_XYZ-SwitchOnService ;
saref:hasState sn:WASH_XYZ-WashingMachineStatus ;
s4bldg:isContainedIn sn:My_Bathroom .
sn:WASH_XYZ-StartStopFunction-OFF_Command a saref:OffCommand .
sn:WASH_XYZ-StartStopFunction-Toggle_Command a saref:ToggleCommand .
sn:WASH_XYZ-StartStopFunction-ON_Command a saref:OnCommand .
sn:WASH_XYZ-MonitoringFunction a saref:SensingFunction ;
saref:hasCommand sn:WASH_XYZ-MonitoringFunction-WashingMachineStatus .
sn:WASH_XYZ-StartStopFunction a saref:ActuatingFunction ;
saref:hasCommand sn:WASH_XYZ-StartStopFunction-Toggle_Command ,
sn:WASH_XYZ-StartStopFunction-OFF_Command ,
sn:WASH_XYZ-StartStopFunction-ON_Command .
```
![Figure 7: SAREF Washing Machine Model](media/image8.png)
**Figure 7: SAREF Washing Machine Model**
- The procedure defined in TS-0012 require the IPE to parse the semantic description to generate a total of three custom &lt;flexContainer> definitions to support the structure shown in Figure 7. The schemas generated are added as the content of a &lt;contentInstance> resource under a container for these custom definitions. The locations of these schemas are referenced in the container definition attribute of the respective &lt;flexContainer>.
- two &lt;flexContainer> child-resources for Services and their &lt;semanticDescriptor>s are used for modelling the services SwitchOnService and MonitorService;
- the SwitchOnService in turn has a child resource of type &lt;flexContainer> for Operations which exposes the Toggle_Command;
- one customAttribute of the SwitchOnService &lt;flexContainer> is used for holding the values for InputDataPoint: BinaryInput;
- one customAttribute of the MonitorService &lt;flexContainer> is used for holding the values for OutputDataPoint: WashingMachineStatus.
![Figure 8: SAREF Model oneM2M Call Flows](media/image9.png)
**Figure 8: SAREF Model oneM2M Call Flows**
Only the messages highlighted in light blue are described here as the rest of the messages are the same as in the general call flow described in clause 6.1.
- Create Information Model. The IPE creates all the resources needed to for the clothes washing machine that it generates from parsing the semantic description. This IPE is developed with awareness of the clothes washing machine interface but without awareness of the model that it is creating in the oneM2M CSE. This requires extra logic to parse the RDF triples to generate custom container definitions, which is not included in this example as only the output of the parsing process is shown.
- A &lt;flexContainer> resource is created for the MonitorService with a single custom attribute washingMachineStatus. The IPE updates this resource with the following content when there are any changes in the status of the clothes washing machine:
```
{
"WashingMachineStatus": "WASHING", // Or "STOPPED", "ERROR"
}
```
- A &lt;flexcontainer> resource is created for the SwitchOnService that allows command and control of the clothes washing machine. The client application sets the state of the device by updating the resource with the following payload:
```
{
"BinaryInput": false
}
```
- A &lt;flexcontainer> resource is created for the Toggle command as a child of the SwitchOnService. This action is used to change the current state of the clothes washing machine. The client application toggles the state of the device by sending an update request to the resource with an empty payload.
- A &lt;subscription> resource is created as a child of the Toggle command &lt;flexContainer> resource by the IPE. This will cause a notification to be sent to the IPE when a new command is made by an application.
- A &lt;subscription> resource is created as a child of the SwitchOnService &lt;flexContainer> resource by the IPE. This will cause a notification to be sent to the IPE when a new command is made by an application
## 6.4 Device models using Smart Device Template
TS-0023 defines a framework for developing common standardized models of devices. There are multiple device specific domains defined and new models and domains are added in each release of oneM2M. The Home Domain contains a deviceClothesWasher model that aligns with the device that we are trying to model. The resource tree structure of the deviceClothesWasher is shown in Figure 5. There are many more potential services exposed in this model than our example simplified washing machine provides. The elements in bold are required for a compliant SDT model. Services in the model that are not supported by our simple clothes-washing machine are not implemented unless they are required. It should be noted that using an SDT model is the only model that can be certified by a certification authority.
![Figure 9: SDT washing machine model](media/image10.png)
**Figure 9: SDT washing machine model**
When using a SDT model from TS-0023 to represent a physical device it is necessary to map the functionality of the device to be modelled with the existing modules defined for the SDT device.
|Meta-Data |Device Value |SDT modelling |
|-|-|-|
|Manufacturer |XYZ |The SDT model captures this information in a dmDeviceInfo ModuleClass |
|Manufacturer description |"Very cool Washing Machine" |The SDT model captures this information in a dmDeviceInfo ModuleClass |
|Model Type |XYZ_Cool |The SDT model captures this information in a dmDeviceInfo ModuleClass |
|Supported Commands |ON<br />OFF<br />Toggle<br /> |The SDT model enables the ON and OFF commands using the state attribute of the binarySwitch ModuleClass. The Toggle command is supported by the toggle ActionModule. |
|State |"WASHING"<br />"STOPPED"<br />"ERROR" |The SDT model offers runState ModuleClass which supports more enumerations that indicated by our product. |
|Location |My_Bathroom |The SDT model does not have an attribute specifically for Location. |
## <mark>Annexes</mark>
<mark>Each annex shall start on a new page (insert a page break between annexes A and B, annexes B and C, etc.).<mark>
![Figure 10: SDT model oneM2M Call Flows](media/image11.png)
# Annex &lt;A>:<br />Title of annex
**Figure 10: SDT model oneM2M Call Flows**
&lt;Text>
<mark>&lt;PAGE BREAK></mark>
Only the messages highlighted in light blue are described here as the rest of the messages are the same as in the general call flow described in clause 6.1.
# Annex &lt;B>:<br />Title of annex
&lt;Text>
- Create Information Model. The IPE creates all the resources needed to for the clothes washing machine that it knows how to model a priori using SDT. This IPE is developed with awareness of the clothes washing machine interface and the model that it is creating in the oneM2M CSE.
- A &lt;flexContainer> resource is created for the runState with the custom attribute currentMachineState and MachineStates. The IPE updates this resource with the following content when there are any changes in the status of the clothes washing machine:
## <!--B.1--> First clause of the annex
```
{
"CurrentMachineState ": 3, // Or [1,3,5,6]
}
```
&lt;Text>
- A &lt;flexcontainer> resource is created for the binarySwitch module that allows command and control of the clothes washing machine. The client application sets the state of the device by updating the resource with the following payload:
### B.1.1 First subdivided clause of the annex
```
{
"state": False, // Or True
}
```
&lt;Text>
- A &lt;flexcontainer> resource is created for the Toggle command as a child of the binarySwitch. This action is used to change the current state of the clothes washing machine. The client application toggles the state of the device by sending an update request to the resource with an empty payload.
- A &lt;flexcontainer> resource is created for the clothesWasherJobMode with custom attributes currentJobMode and jobModes. This resource is mandatory for the deviceClothesWasher SDT model, but the IPE will set the states and never modify them.
- A &lt;subscription> resource is created as a child of the toggle &lt;flexContainer> resource by the IPE. This will cause a notification to be sent to the IPE when a new command is made by an application.
- A &lt;subscription> resource is created as a child of the binarySwitch command &lt;flexContainer> resource by the IPE. This will cause a notification to be sent to the IPE when a new command is made by an application.
<mark>&lt;PAGE BREAK></mark>
# Annex &lt;y>:<br />Bibliography
<mark>The annex entitled "Bibliography" is optional.</mark>
<mark>It shall contain a list of standards, books, articles, or other sources on a particular subject which are not mentioned in the document itself.</mark>
<mark>It shall not include references mentioned in the document.</mark>
# 7 Semantic Annotation in oneM2M
## 7.1 Semantic description of services using SAREF Ontology
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 explicitly specifies the recurring core concepts in the Smart Applications domain, the main relationships between these concepts, and axioms to constrain the usage of these concepts and relationships. SAREF is based on the fundamental principles of reuse and alignment of concepts and relationships that are defined in existing assets, modularity to allow separation and recombination of different parts of the ontology depending on specific needs, extensibility to allow further growth of the ontology, and maintainability to facilitate the process of identifying and correcting defects, accommodate new requirements, and cope with changes in (parts of) SAREF.
We can use the SAREF ontology to describe the services of the washing machine and the oneM2M Base Ontology to describe the oneM2M interface for the services.
- <mark>&lt;Publication>: "&lt;Title>".</mark>
The services of any clothes washing machine are fundamentally the same regardless of which model is used. Especially in this case where we are describing the same clothes washing machine. The following RDF triples describe the services and functions of our clothes washing machine.
<mark>OR</mark>
```
@prefix saref: <https://saref.etsi.org/core/> .
@prefix s4bldg: <> .
@prefix xsd: <> .
@prefix rdfs: <> .
@prefix sn: <> .
@prefix m2m: <> .
<mark>&lt;Publication>: "&lt;Title>".</mark>
sn:WASH_XYZ_RESOURCE_ID a <http://www.XYZ.com/WashingMachines#XYZ_Cool> ;
rdfs:comment "Very cool Washing Machine" ;
saref:hasFunction sn:WASH_XYZ-MonitoringFunction, sn:WASH_XYZ-StartStopFunction ;
saref:hasManufacturer "XYZ" ;
saref:hasService sn:WASH_XYZ-MonitorService , sn:WASH_XYZ-SwitchOnService ;
saref:hasState sn:WASH_XYZ-WashingMachineStatus ;
s4bldg:isContainedIn sn:My_Bathroom ;
m2m:oneM2MTargetURI "RESOURCE_ID" ;
m2m:hasOperation sn:WASH_XYZ-SwitchOnService_RESOURCE_ID,
sn:WASH_XYZ-StartStopFunction-ON_Command_RESOURCE_ID,
sn:WASH_XYZ-StartStopFunction-OFF_Command_RESOURCE_ID,
sn:WASH_XYZ-StartStopFunction-TOGGLE_Command_RESOURCE_ID,
sn:WASH_XYZ-MonitoringFunction-WashingMachineStatus_RESOURCE_ID .
<mark>&lt;PAGE BREAK></mark>
```
These triples will be placed into a &lt;semanticDescription> resource in each of the models. Notice that these triples have a token "RESOURCE_ID" in several places that will be replaced at execution time with a resource identifier or resource address related to the parent of this particular &lt;semanticDescriptor>.
# History
<mark>This clause shall be the last one in the document and list the main phases (all additional information will be removed at the publication stage).</mark>
## 7.2 Describing oneM2M APIs with the oneM2M Base Ontology
## 7.2.1 Clothes Washing Machine APIs using oneM2M
Because the resource tree structure for each of the models is different the oneM2M primitives needed to access the services of the clothes washing machine will also be different. However, the goal for interworking device models is to allow a user to issue the same command to perform an operation regardless of which model is used. This can be approximated in a dynamic manner using the oneM2M base ontology to describe each of the services offered by the device and the resources that provide access to those services. For example, the washing machine that we have described offers the following operations:
- TURN ON WASHING MACHINE
- TURN OFF WASHING MACHINE
- TOGGLE THE WASHING MACHINE STATUS
- GET STATUS OF WASHING MACHINE
The oneM2M primitives to execute these operations are dependent on the resource tree structure used to model the washing machine. For example, to determine the status of the washing machine for each model the following oneM2M requests and responses are used:
|Model |Request |Response |
|-|-|-|
|SDT |RETRIEVE /cseBaseName/IPE_ROOT/deviceclothesWasher/runState |{ " currentMachineState ": 3<br /> "machineStates": [1,3,5,6]<br /> "currentJobState": 6<br /> "jobStates":[2,3,4,5,6]<br /> "progressPercentage":95.0<br />} |
|SAREF |RETRIEVE /cseBaseName/IPE_ROOT/My-WashingMachine/sarefWashingMachine/MonitorService |{ "WashingMachineStatus":WASHING<br />} |
|Custom |RETRIEVE /cseBaseName/IPE_ROOT/myWashingMachine/Status/la |{ "WashingMachineStatus":WASHING<br />} |
Similarly, to command the washing machine to STOP the following oneM2M primitives are sent:
|Model |Request |
|-|-|
|SDT |UPDATE /cseBaseName/IPE_ROOT/deviceClothesWasher/binarySwitch <br />{"state": False } |
|SAREF |UPDATE /cseBaseName/IPE_ROOT/My-WashingMachine/SwitchOnService<br />{"BinaryInput": False} |
|Custom |CREATE /cseBaseName/IPE_ROOT/myWashingMachine/Command <br />{"OFF"} |
## 7.2.2 Custom Model API semantic description
The specific primitive requests described in clause 7.2.1 are described in RDF triples using the oneM2M base ontology. The classes of interest in the oneM2M base ontology are: m2m:oneM2MTargetURI, m2m:hasDataRestriction, m2m:oneM2MMethod.
```
@prefix saref: <https://saref.etsi.org/core/> .
@prefix s4bldg: <> .
@prefix xsd: <> .
@prefix rdfs: <> .
@prefix sn: <> .
@prefix m2m: <> .
sn:WASH_XYZ-StartStopFunction-ON_Command_RESOURCE_ID a m2m:Operation, <https://saref.etsi.org/core/OnCommand> ;
m2m:oneM2MTargetURI "/myWashingMachine/command";
m2m:hasDataRestriction "ON";
m2m:oneM2MMethod "CREATE" .
sn:WASH_XYZ-StartStopFunction-OFF_Command_RESOURCE_ID a m2m:Operation, <https://saref.etsi.org/core/OffCommand> ;
m2m:oneM2MTargetURI "/myWashingMachine/command";
m2m:hasDataRestriction "OFF";
m2m:oneM2MMethod "CREATE" .
sn:WASH_XYZ-StartStopFunction-TOGGLE_Command_RESOURCE_ID a m2m:Operation, <https://saref.etsi.org/core/ToggleCommand> ;
m2m:oneM2MTargetURI "/myWashingMachine/command";
m2m:hasDataRestriction "TOGGLE";
m2m:oneM2MMethod "CREATE" .
sn:WASH_XYZ-MonitoringFunction-WashingMachineStatus_RESOURCE_ID a m2m:Operation, <https://saref.etsi.org/core/GetCommand> ;
m2m:oneM2MTargetURI "/myWashingMachine/status";
m2m:oneM2MMethod "RETRIEVE" .
```
## 7.2.3 Semantic Model annotation
The specific primitive requests described in clause 7.2.1 are described in RDF triples using the oneM2M base ontology. The classes of interest in the oneM2M base ontology are: m2m:oneM2MTargetURI, m2m:hasDataRestriction, m2m:oneM2MMethod and m2m:oneM2Mattribute.
```
@prefix saref: <https://saref.etsi.org/core/> .
@prefix s4bldg: <> .
@prefix xsd: <> .
@prefix rdfs: <> .
@prefix sn: <> .
@prefix m2m: <> .
sn:WASH_XYZ-StartStopFunction-ON_Command_RESOURCE_ID a m2m:Operation, <https://saref.etsi.org/core/OnCommand> ;
m2m:oneM2MTargetURI "/My-WashingMachine/SwitchOnService";
m2m:oneM2Mattribute "BinaryInput" ;
m2m:oneM2MMethod "UPDATE" ;
m2m:hasDataRestriction "True".
sn:WASH_XYZ-StartStopFunction-OFF_Command_RESOURCE_ID a m2m:Operation, <https://saref.etsi.org/core/OffCommand> ;
m2m:oneM2MTargetURI "/My-WashingMachine/SwitchOnService";
m2m:oneM2Mattribute "BinaryInput" ;
m2m:oneM2MMethod "UPDATE" ;
m2m:hasDataRestriction "False".
sn:WASH_XYZ-MonitoringFunction-WashingMachineStatus_RESOURCE_ID a m2m:Operation, <https://saref.etsi.org/core/GetCommand> ;
m2m:oneM2MTargetURI "/My-WashingMachine/sarefWashingMachine";
m2m:oneM2MMethod "RETRIEVE" ;
m2m:oneM2Mattribute "WashingMachineStatus" .
```
## 7.2.4 SDT model annotation
The specific primitive requests described in clause 7.2.1 are described in RDF triples using the oneM2M base ontology. The classes of interest in the oneM2M base ontology are: m2m:oneM2MTargetURI, m2m:hasDataRestriction, m2m:oneM2MMethod and m2m:oneM2Mattribute.
```
@prefix saref: <https://saref.etsi.org/core/> .
@prefix s4bldg: <> .
@prefix xsd: <> .
@prefix rdfs: <> .
@prefix sn: <> .
@prefix m2m: <> .
sn:WASH_XYZ-StartStopFunction-ON_Command a m2m:Operation, <https://saref.etsi.org/core/OnCommand> ;
m2m:oneM2MTargetURI "/deviceClothesWasher/binarySwitch";
m2m:oneM2Mattribute "powerState" ;
m2m:hasDataRestriction "True";
m2m:oneM2MMethod "UPDATE" .
sn:WASH_XYZ-StartStopFunction-OFF_Command a m2m:Operation, <https://saref.etsi.org/core/OffCommand> ;
m2m:oneM2MTargetURI "/deviceClothesWasher/binarySwitch";
m2m:oneM2Mattribute "powerState" ;
m2m:hasDataRestriction "False";
m2m:oneM2MMethod "UPDATE" .
sn:WASH_XYZ-StartStopFunction-TOGGLE_Command a m2m:Operation, <https://saref.etsi.org/core/ToggleCommand> ;
m2m:oneM2MTargetURI "/deviceClothesWasher/binarySwitch/toggle";
m2m:oneM2MMethod "UPDATE" .
sn:WASH_XYZ-MonitoringFunction-WashingMachineStatus a m2m:Operation ;
m2m:oneM2MTargetURI "/deviceClothesWasher/runState";
m2m:oneM2Mattribute "currentMachineState" ;
m2m:oneM2MMethod "RETRIEVE" .
```
# 8 Semantic Queries
This section describes the semantic queries and how the responses can be used to achieve interoperability. Generally, these queries are executed by an application that is designed to use the IoT devices.
## 8.1 Discovery Queries
By using the oneM2M Base Ontology in the &lt;semanticDescriptor> resources we can send queries to the oneM2M CSE to find the services offered by a device and further query those services to discover the oneM2M primitives to access those services.
Here is a list of queries that we will support for all three of the models:
**Query 1: Find all washing machines of manufacturer XYZ.**
```
PREFIX sn: <http://www.XYZ.com/WashingMachines#XYZ_Cool>
PREFIX m2m: <https://git.onem2m.org/MAS/BaseOntology/raw/master/base_ontology.owl#>
PREFIX saref: <https://saref.etsi.org/core/>
SELECT ?res ?wm
WHERE {
?wm a sn:XYZ_Cool .
?wm m2m:oneM2MTargetURI ?res .
}
```
This lists 3 washing machines
|res |wm |
|-|-|
|"myWashingMachine" |http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_myWashingMachine |
|"My-WashingMachine" |http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_My-WashingMachine |
|"deviceClothesWasher" |http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_deviceClothesWasher |
**Query 2: List all the commands offered by a specific washing machine**
```
PREFIX sn:<http://www.XYZ.com/WashingMachines#>
PREFIX m2m: <https://git.onem2m.org/MAS/BaseOntology/raw/master/base_ontology.owl#>
PREFIX saref: <https://saref.etsi.org/core/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
SELECT ?wm ?operation ?command
WHERE {
?wm m2m:hasOperation ?operation .
?operation a ?command .
VALUES ?wm {<http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_myWashingMachine>} .
?command rdfs:subClassOf saref:Command
}
```
This lists the operations and commands and functions associated with the commands
|wm |operation |command |
|-|-|-|
|http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_myWashingMachine |http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ-StartStopFunction-ON_Command_myWashingMachine |saref:OnCommand |
|http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_myWashingMachine |http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ-StartStopFunction-OFF_Command_myWashingMachine |saref:OffCommand |
|http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_myWashingMachine |http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ-StartStopFunction-TOGGLE_Command_myWashingMachine |saref:ToggleCommand |
|http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_myWashingMachine |http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ-MonitoringFunction-WashingMachineStatus_myWashingMachine |saref:GetCommand |
## 8.2 Interoperability Queries
The following queries demonstrate how interoperability is achieved using semantics in oneM2M. Using the results of the queries above we can issue the following types of queries to determine exactly how to use the services of the washing machines, without regard the way it was modeled. This query shows how to use the saref:GetCommand for the SDT model of the washing machine
**Query 3: How do I use saref:GetCommand of the SDT washing machine**
```
PREFIX m2m: <https://git.onem2m.org/MAS/BaseOntology/raw/master/base_ontology.owl#>
PREFIX saref: <https://saref.etsi.org/core/>
SELECT ?sarefCommand ?method ?targetURI ?attr ?res
WHERE {
?wm m2m:hasOperation ?operation .
?operation a m2m:Operation .
?operation m2m:oneM2MMethod ?method .
optional {?operation m2m:hasDataRestriction ?res} .
optional {?operation m2m:oneM2Mattribute ?attr} .
?operation a ?sarefCommand .
?operation m2m:oneM2MTargetURI ?targetURI .
VALUES ?wm {<http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_deviceClothesWasher>} .
VALUES ?sarefCommand {saref:GetCommand}
}
```
The result of executing query 3 is:
|sarefCommand |Method |targetURI |Attr |res |
|-|-|-|-|-|
| |"RETRIEVE" |"/deviceClothesWasher/runState" |"currentMachineState" | |
Query 3 can be modified for demonstration purposes to show the response for all three washing machines by removing the line beginning with "VALUES ?wm". The result of this query can be compared with the expected responses described in clause 7.2.1.
|sarefCommand |method |targetURI |attr |res |
|-|-|-|-|-|
| |"RETRIEVE" |"/deviceClothesWasher/runState" |"currentMachineState" | |
| |"RETRIEVE" |"/My-WashingMachine/sarefWashingMachine/ MonitorService" |"WashingMachineStatus" | |
| |"RETRIEVE" |"/myWashingMachine/status/la" | | |
**Query 4: How do I use all commands of the washing machine modeled with SDT**
```
SELECT ?sarefCommand ?method ?targetURI ?attr ?res
WHERE {
?wm m2m:hasOperation ?operation .
?operation a m2m:Operation .
?operation m2m:oneM2MMethod ?method .
optional {?operation m2m:hasDataRestriction ?res} .
optional {?operation m2m:oneM2Mattribute ?attr} .
?operation a ?sarefCommand .
?operation m2m:oneM2MTargetURI ?targetURI .
VALUES ?wm {&lt;http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_deviceClothesWasher>} .
VALUES ?sarefCommand {saref:GetCommand saref:OnCommand saref:OffCommand saref:ToggleCommand}
}
ORDER BY ?sarefCommand
```
This query can be issued after discovering the appropriate device to dynamically build the commands needed to perform operations on the device.
|sarefCommand |method |targetURI |attr |res |
|-|-|-|-|-|
|saref:GetCommand |"RETRIEVE" |"/deviceClothesWasher/runState" |"currentMachineState" | |
|saref:OffCommand |"UPDATE" |"/deviceClothesWasher/binarySwitch" |"powerState" |"False" |
|saref:OnCommand |"UPDATE" |"/deviceClothesWasher/binarySwitch" |"powerState" |"True" |
|saref:ToggleCommand|"UPDATE" |"/deviceClothesWasher/binarySwitch/toggle" | | |
The SPARQL query that is used is a critical component of the ability to dynamically determine the API of the model. The tokens following the SELECT statement are variables that will be included in the response. For this use case we need to know what oneM2M primitive to send to a CSE to perform the desired command. The method implies the type of resource that is at the targetURI. An UPDATE method implies that the targetURI is a &lt;flexContainer> whereas if the method is CREATE then the resource type being created will be a &lt;contentInstance>. In the case of a &lt;flexContainer> "attr" specifies the custom attribute that needs to be updated and the "res" specifies the value to use in that attribute.
If we were designing a smartphone application to control the washing machine it might look like the wireframe shown below.
![Figure 11: Sample application wireframe](media/image12.png)
**Figure 11: Sample application wireframe**
# 9 Procedures
## 9.1 Introduction
Previous clauses describe the use case, the call flows, the semantic description of our device and the SPARQL queries that we can use based on the semantic description that we created. As you will see in this section, the values returned from a query are fully dependent on the query issued. The oneM2M CSE will pass the query results back in the format defined by SPARQL query results. This example receives a JSON response (the query is sent using XML just to highlight that this can be done).
This clause will show the actual oneM2M primitives that implement the use case described above. This guide will focus on the semantic description resources and the semantic queries. The specific primitives needs to create the &lt;AE>, &lt;container>, and &lt;flexcontainer> resources have been covered in other documents in oneM2M.
## 9.2 Implementation
## 9.2.1 Semantics Description Utilities
The requirements for the creation of a &lt;semanticDescription> resource include base64 encoding the 'dsp' attribute. There are many libraries that do this operation and for this example python was used.
```
import base64
def smdEncode(description):
msgAscii = description.encode('ascii')
b64 = base64.b64encode(msgAscii)
descriptionb64 = b64.decode('ascii')
return descriptionb64
def smdDecode(message):
b64d = message.encode('ascii')
msgdAscii = base64.b64decode(b64d)
return msgdAscii.decode('ascii')
```
## 9.2.2 Semantic Query Utilities
When sending a SPARQL query as a request parameter for a oneM2M primitive, the query must be "url" encoded. There are many libraries that do this operation and for this example python was used.
```
import urllib.parse
def encodedSparqlQuery(query):
return urllib.parse.quote(query, safe='')
```
## 9.2.3 Semantics representations and primitives
In oneM2M the &lt;semanticDescriptor> resource is used to provide semantic annotations, such as the ones in clause 7. Semantic annotations can use the oneM2M base ontology as well as external ontologies, such as SAREF. The oneM2M base ontology is primarily used to discover how to use the APIs for devices that are modelled in oneM2M. External Ontologies are used to describe the capabilities of the device being models or other features of data that is available in oneM2M, i.e., ontologies could describe the content of data or metadata. A &lt;semanticDescriptor> resource can be a child of &lt;AE>, &lt;container>, &lt;contentInstance>, &lt;group>, &lt;node>, &lt;flexContainer>, &lt;timeSeries>, &lt;mgmtObj> resources.
The semantic annotations in a &lt;semanticDescription> can apply to the parent resource or other resources. There are two types of semantic searches that can be performed; 1) semantic discovery and 2) semantic query. A semantic discovery will find matching &lt;semanticDescriptor> resources and provide the URI of the parent resource of the &lt;semanticDescriptor> resources that match the query. A semantic query request will return the response to the SPARQL query in the format defined in the query. These differences may impact the decision regarding what parent resource to target for a &lt;semanticDescriptor> resource.
The representation of a &lt;semanticDescriptor> resource must be in one of the supported semantic formats supported in oneM2M. The supported formats from TS-0004 are:
![Figure 12: <semanticDescriptor> Resource](media/image13.png)
**Figure 12: &lt;semanticDescriptor> Resource**
In this use case we use RDF/XML in the primitives as that is supported by the test implementation. The semantic annotations shown in clause 7 are written in RDF/Turtle. A convenient utility to convert the RDF/Turtle is available at [https://www.easyrdf.org/converter]() or the python rdflib library.
Another requirement for the &lt;semanticDescriptor> resource is that the descriptor attribute is set to the value of the semantic triples encoded as xs:base64Binary.
And finally, when issuing a Semantic request, whether it is a discovery or query, the semanticFilter parameter of the request requires "percent-encoding" when using the HTTP protocol binding, as used in this guide.
Since the &lt;semanticDescriptor> resource is separate from the resources that it describes there is considerable flexibility available to application developers. For example, if a product such as an IPE for a clothes washing machine does not provide &lt;semanticDescriptor> resources, it is possible for another application to provide the &lt;semanticDescriptor> resources. This can support application development that continually expands its supported devices. In this clothes washing machine use case the client application can deploy with any of the three models described above, but as the application developer becomes aware of other clothes washing machines, they can create the &lt;semanticDescriptor> resources for those devices and then applications that have been developed to use the original deployed devices will be interoperable with these new devices, without change to the application. This concept is one of the ways that oneM2M breaks down the silos of vertical deployments.
## 9.2.4 Create &lt;semanticDescriptor>
The &lt;semanticDescriptor> resource can be created by the entity that is creating the model or by a separate client entity, depending on the &lt;accessControlPolicies> of the parent resource. This example shows the create &lt;semanticDescriptor> for the Custom Model. The RDF triples that we used to semantically describe the washing machine were first converted to RDF/XML and then base64 encoded. The result of that encoding is used for the "dsp" attribute of the &lt;semanticDescriptor>.
The following code is written using python and use the utilities available here [reference to ACME tutorial].
```
prefixes_io = '''@prefix saref: <https://saref.etsi.org/core/> .
@prefix s4bldg: <https://saref.etsi.org/saref4bldg/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix sn: <http://www.XYZ.com/WashingMachines#XYZ_Cool> .
@prefix m2m: <https://git.onem2m.org/MAS/BaseOntology/raw/master/base_ontology.owl#> .
'''
smdBase = '''sn:WASH_XYZ_RESOURCE_ID a <http://www.XYZ.com/WashingMachines#XYZ_Cool> ;
rdfs:comment "Very cool Washing Machine" ;
saref:hasFunction sn:WASH_XYZ-MonitoringFunction, sn:WASH_XYZ-StartStopFunction ;
saref:hasManufacturer "XYZ" ;
saref:hasService sn:WASH_XYZ-MonitorService , sn:WASH_XYZ-SwitchOnService ;
saref:hasState sn:WASH_XYZ-WashingMachineStatus ;
s4bldg:isContainedIn sn:My_Bathroom ;
m2m:oneM2MTargetURI "RESOURCE_ID" ;
m2m:hasOperation sn:WASH_XYZ-SwitchOnService_RESOURCE_ID, sn:WASH_XYZ-StartStopFunction-ON_Command_RESOURCE_ID, sn:WASH_XYZ-StartStopFunction-OFF_Command_RESOURCE_ID, sn:WASH_XYZ-StartStopFunction-TOGGLE_Command_RESOURCE_ID,
sn:WASH_XYZ-MonitoringFunction-WashingMachineStatus_RESOURCE_ID .
'''
smdfull = prefixes_io + smdBase
g = Graph().parse(data=smdfull, format='n3')
smdxml = g.serialize(format='xml', indent=4)
targetURI = 'myWashingMachine'
payload = smdxml.replace("RESOURCE_ID", targetURI)
smd2b64 = smdEncode(payload)
CREATE(
'http://localhost:50000/oneM2M-semantics/' + targetURI,
# This is the Custom Washing Machine AE
# Request Headers
{
'X-M2M-Origin': originator1, # Set the originator
'X-M2M-RI': '123', # Request identifier
'X-M2M-RVI': '3', # Release verson indicator
'Accept': 'application/json', # Response shall be JSON
'Content-Type': 'application/json;ty=24' # Content is JSON, and represents an <semanticDescriptor> resource
},
# Request Body
{
'm2m:smd': {
'rn': 'smdCustomWasher',
'dcrp': 'application/rdf+xml:1', # the RDF triples use RDF/XML format;
'dsp': smd2b64 # the base64 encode triples
}
}
)
```
The resulting oneM2M primitive request and response using the HTTP protocol binding and JSON payload binding is shown below.
```
Sending request to http://localhost:50000/oneM2M-semantics/myWashingMachine
Headers
X-M2M-Origin: Cipe1
X-M2M-RI: 123
X-M2M-RVI: 3
Accept: application/json
Content-Type: application/json;ty=24
Body
{
"m2m:smd": {
"rn": "smdCustomWasher",
"dcrp": "application/rdf+xml:1",
"dsp": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPHJkZjpSREYKICAgeG1sbnM6bTJtPSJodHRwczovL2dpdC5vbmVtMm0ub3JnL01BUy9CYXNlT250b2xvZ3kvcmF3L21hc3Rlci9iYXNlX29udG9sb2d5Lm93bCMiCiAgIHhtbG5zOnJkZj0iaHR0cDovL3d3dy53My5vcmcvMTk5OS8wMi8yMi1yZGYtc3ludGF4LW5zIyIKICAgeG1sbnM6cmRmcz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC8wMS9yZGYtc2NoZW1hIyIKICAgeG1sbnM6czRibGRnPSJodHRwczovL3NhcmVmLmV0c2kub3JnL3NhcmVmNGJsZGcvIgogICB4bWxuczpzYXJlZj0iaHR0cHM6Ly9zYXJlZi5ldHNpLm9yZy9jb3JlLyIKPgogIDxyZGY6RGVzY3JpcHRpb24gcmRmOmFib3V0PSJodHRwOi8vd3d3LlhZWi5jb20vV2FzaGluZ01hY2hpbmVzI1hZWl9Db29sV0FTSF9YWVpfbXlXYXNoaW5nTWFjaGluZSI+CiAgICA8cmRmOnR5cGUgcmRmOnJlc291cmNlPSJodHRwOi8vd3d3LlhZWi5jb20vV2FzaGluZ01hY2hpbmVzI1hZWl9Db29sIi8+CiAgICA8cmRmczpjb21tZW50PlZlcnkgY29vbCBXYXNoaW5nIE1hY2hpbmU8L3JkZnM6Y29tbWVudD4KICAgIDxzYXJlZjpoYXNGdW5jdGlvbiByZGY6cmVzb3VyY2U9Imh0dHA6Ly93d3cuWFlaLmNvbS9XYXNoaW5nTWFjaGluZXMjWFlaX0Nvb2xXQVNIX1hZWi1Nb25pdG9yaW5nRnVuY3Rpb24iLz4KICAgIDxzYXJlZjpoYXNGdW5jdGlvbiByZGY6cmVzb3VyY2U9Imh0dHA6Ly93d3cuWFlaLmNvbS9XYXNoaW5nTWFjaGluZXMjWFlaX0Nvb2xXQVNIX1hZWi1TdGFydFN0b3BGdW5jdGlvbiIvPgogICAgPHNhcmVmOmhhc01hbnVmYWN0dXJlcj5YWVo8L3NhcmVmOmhhc01hbnVmYWN0dXJlcj4KICAgIDxzYXJlZjpoYXNTZXJ2aWNlIHJkZjpyZXNvdXJjZT0iaHR0cDovL3d3dy5YWVouY29tL1dhc2hpbmdNYWNoaW5lcyNYWVpfQ29vbFdBU0hfWFlaLU1vbml0b3JTZXJ2aWNlIi8+CiAgICA8c2FyZWY6aGFzU2VydmljZSByZGY6cmVzb3VyY2U9Imh0dHA6Ly93d3cuWFlaLmNvbS9XYXNoaW5nTWFjaGluZXMjWFlaX0Nvb2xXQVNIX1hZWi1Td2l0Y2hPblNlcnZpY2UiLz4KICAgIDxzYXJlZjpoYXNTdGF0ZSByZGY6cmVzb3VyY2U9Imh0dHA6Ly93d3cuWFlaLmNvbS9XYXNoaW5nTWFjaGluZXMjWFlaX0Nvb2xXQVNIX1hZWi1XYXNoaW5nTWFjaGluZVN0YXR1cyIvPgogICAgPHM0YmxkZzppc0NvbnRhaW5lZEluIHJkZjpyZXNvdXJjZT0iaHR0cDovL3d3dy5YWVouY29tL1dhc2hpbmdNYWNoaW5lcyNYWVpfQ29vbE15X0JhdGhyb29tIi8+CiAgICA8bTJtOm9uZU0yTVRhcmdldFVSST5teVdhc2hpbmdNYWNoaW5lPC9tMm06b25lTTJNVGFyZ2V0VVJJPgogICAgPG0ybTpoYXNPcGVyYXRpb24gcmRmOnJlc291cmNlPSJodHRwOi8vd3d3LlhZWi5jb20vV2FzaGluZ01hY2hpbmVzI1hZWl9Db29sV0FTSF9YWVotU3dpdGNoT25TZXJ2aWNlX215V2FzaGluZ01hY2hpbmUiLz4KICAgIDxtMm06aGFzT3BlcmF0aW9uIHJkZjpyZXNvdXJjZT0iaHR0cDovL3d3dy5YWVouY29tL1dhc2hpbmdNYWNoaW5lcyNYWVpfQ29vbFdBU0hfWFlaLVN0YXJ0U3RvcEZ1bmN0aW9uLU9OX0NvbW1hbmRfbXlXYXNoaW5nTWFjaGluZSIvPgogICAgPG0ybTpoYXNPcGVyYXRpb24gcmRmOnJlc291cmNlPSJodHRwOi8vd3d3LlhZWi5jb20vV2FzaGluZ01hY2hpbmVzI1hZWl9Db29sV0FTSF9YWVotU3RhcnRTdG9wRnVuY3Rpb24tT0ZGX0NvbW1hbmRfbXlXYXNoaW5nTWFjaGluZSIvPgogICAgPG0ybTpoYXNPcGVyYXRpb24gcmRmOnJlc291cmNlPSJodHRwOi8vd3d3LlhZWi5jb20vV2FzaGluZ01hY2hpbmVzI1hZWl9Db29sV0FTSF9YWVotU3RhcnRTdG9wRnVuY3Rpb24tVE9HR0xFX0NvbW1hbmRfbXlXYXNoaW5nTWFjaGluZSIvPgogICAgPG0ybTpoYXNPcGVyYXRpb24gcmRmOnJlc291cmNlPSJodHRwOi8vd3d3LlhZWi5jb20vV2FzaGluZ01hY2hpbmVzI1hZWl9Db29sV0FTSF9YWVotTW9uaXRvcmluZ0Z1bmN0aW9uLVdhc2hpbmdNYWNoaW5lU3RhdHVzX215V2FzaGluZ01hY2hpbmUiLz4KICA8L3JkZjpEZXNjcmlwdGlvbj4KPC9yZGY6UkRGPgo="
}
}
Response
MISSING TEXT
Body
{
"m2m:smd": {
"ct": "20220714T112657",
"et": "99991231T235959",
"lt": "20220714T112657",
"pi": "Cipe1",
"ri": "smd165779801715710114cse01"
}
}
```
The code above is repeated for each &lt;semanticDescriptor> resource that is created. For this use case, there are six &lt;semanticdescriptor> resources created. Three &lt;semanticDescriptor> resources that describe the capabilities of the washing machine are identical except for the "RESOURCE_ID" token that is replaced with the appropriate value. The other three &lt;semanticDescriptor> resources describe the API of the model and therefore have different values for the oneM2M baseOntology classes.
## 9.2.5 Semantic Query
When a SPARQL query is created, it can be passed in the "semanticFilter" request parameter, shown below with the shortname form of the request parameter of "smf". The query must first be ascii encoded. Using python, the following code will execute query 4 from above to dynamically determine all four primitives needed to use the SDT model of the washing machine. Additionally, the "Semantic Query Indicator", "sqi", is set to "1" to distinguish this query request from a semantic discovery request. A semantic discovery request will return a list of URIs that match the query rather than a query response.
```
query = '''PREFIX sn:&lt;http://www.XYZ.com/WashingMachines#>
PREFIX m2m: &lt;https://git.onem2m.org/MAS/BaseOntology/raw/master/base_ontology.owl#>
PREFIX saref: &lt;https://saref.etsi.org/core/>
SELECT ?sarefCommand ?method ?targetURI ?attr ?res
WHERE {
?wm m2m:hasOperation ?operation .
?operation a m2m:Operation .
?operation m2m:oneM2MMethod ?method .
optional {?operation m2m:hasDataRestriction ?res} .
optional {?operation m2m:oneM2Mattribute ?attr} .
?operation a ?sarefCommand .
?operation m2m:oneM2MTargetURI ?targetURI .
VALUES ?wm {&lt;http://www.XYZ.com/WashingMachines#XYZ_CoolWASH_XYZ_deviceClothesWasher>} .
VALUES ?sarefCommand {saref:GetCommand saref:OnCommand saref:OffCommand saref:ToggleCommand}
}
ORDER BY ?sarefCommand
'''
encSMQ = encodedSparqlQuery(query)
RETRIEVE (
'http://localhost:50000/oneM2M-semantics?fu=1&sqi=1&smf='+ encSMQ,
# Request Headers
{
'X-M2M-Origin' : originator2, # Set the originator
'X-M2M-RI' : 'semQ1', # Unique request identifier
'X-M2M-RVI' : '3', # Release verson indicator
'Accept' : 'application/json' # Response shall be JSON
}
)
```
The resulting oneM2M primitive request and response using the HTTP protocol binding and JSON payload binding is shown below. It is important to note the JSON response to the query. An application will have to parse the response from the query to get the desired information.
```
Sending request to
http://localhost:50000/oneM2M-semantics?fu=1&sqi=1&smf=PREFIX sn%3A&lt;http%3A%2F%2Fwww.XYZ.com%2FWashingMachines%23> PREFIX m2m%3A &lt;https%3A%2F%2Fgit.onem2m.org%2FMAS%2FBaseOntology%2Fraw%2Fmaster%2Fbase_ontology.owl%23> PREFIX saref%3A &lt;https%3A%2F%2Fsaref.etsi.org%2Fcore%2F> SELECT %3FsarefCommand %3Fmethod %3FtargetURI %3Fattr %3Fres WHERE { %3Fwm m2m%3AhasOperation %3Foperation . %3Foperation a m2m%3AOperation . %3Foperation m2m%3AoneM2MMethod %3Fmethod . optional {%3Foperation m2m%3AhasDataRestriction %3Fres} . optional {%3Foperation m2m%3AoneM2Mattribute %3Fattr} . %3Foperation a %3FsarefCommand . %3Foperation m2m%3AoneM2MTargetURI %3FtargetURI . VALUES %3Fwm {&lt;http%3A%2F%2Fwww.XYZ.com%2FWashingMachines%23XYZ_CoolWASH_XYZ_deviceClothesWasher>} . VALUES %3FsarefCommand {saref%3AGetCommand saref%3AOnCommand saref%3AOffCommand saref%3AToggleCommand} } ORDER BY %3FsarefCommand
CHECK WHITESPACE
Headers missing text
Response missing text
Body
[
{
"attr": {
"type": "literal",
"value": "currentMachineState"
},
"method": {
"type": "literal",
"value": "RETRIEVE"
},
"sarefCommand": {
"type": "uri",
"value": "https://saref.etsi.org/core/GetCommand"
},
"targetURI": {
"type": "literal",
"value": "/deviceClothesWasher/runState"
}
},
{
"attr": {
"type": "literal",
"value": "powerState"
},
"method": {
"type": "literal",
"value": "UPDATE"
},
"res": {
"type": "literal",
"value": "False"
},
"sarefCommand": {
"type": "uri",
"value": ""
},
"targetURI": {
"type": "literal",
"value": "/deviceClothesWasher/binarySwitch"
}
},
{
"attr": {
"type": "literal",
"value": "powerState"
},
"method": {
"type": "literal",
"value": "UPDATE"
},
"res": {
"type": "literal",
"value": "True"
},
"sarefCommand": {
"type": "uri",
"value": ""
},
"targetURI": {
"type": "literal",
"value": "/deviceClothesWasher/binarySwitch"
}
},
{
"method": {
"type": "literal",
"value": "UPDATE"
},
"sarefCommand": {
"type": "uri",
"value": ""
},
"targetURI": {
"type": "literal",
"value": "/deviceClothesWasher/binarySwitch/toggle"
}
}
]
```
```
code here
```
# 10 History
|Publication history |Publication history |Publication history |
|-|-|-|
|V1.1.1 |&lt;yyyy-mm-dd> |&lt;Milestone> |
| | | |
| | | |
| | | |
| | | |
......@@ -230,7 +1003,8 @@ The key words "Shall", "Shall not", "May", "Need not", "Should", "Should not" in
|Draft history (to be removed on publication) |Draft history (to be removed on publication) |Draft history (to be removed on publication) |
|-|-|-|
|V1.1.1 |&lt;yyyy-mm-dd> |&lt;CR ID> applied - &lt;Summary of changes> |
|V0.0.0 |2022-03-09 |SKELETON |
| | | |
| | | |
| | | |
| | | |
......
media/.gitkeep 0 → 100644
View file @ 2dfa5880
media/image1.png 0 → 100644
View file @ 2dfa5880
media/image1.png

4.71 KiB

media/image10.png 0 → 100644
View file @ 2dfa5880
media/image10.png

90.2 KiB

media/image11.png 0 → 100644
View file @ 2dfa5880
media/image11.png

74.8 KiB

media/image12.png 0 → 100644
View file @ 2dfa5880
media/image12.png

230 KiB

media/image13.png 0 → 100644
View file @ 2dfa5880
media/image13.png

186 KiB

media/image2.png 0 → 100644
View file @ 2dfa5880
media/image2.png

231 KiB

media/image3.png 0 → 100644
View file @ 2dfa5880
media/image3.png

183 KiB

media/image4.png 0 → 100644
View file @ 2dfa5880
media/image4.png

146 KiB

media/image5.png 0 → 100644
View file @ 2dfa5880
media/image5.png

65.2 KiB

media/image6.png 0 → 100644
View file @ 2dfa5880
media/image6.png

20.1 KiB

media/image7.png 0 → 100644
View file @ 2dfa5880
media/image7.png

95.3 KiB

media/image8.png 0 → 100644
View file @ 2dfa5880
media/image8.png

48.5 KiB

media/image9.png 0 → 100644
View file @ 2dfa5880
media/image9.png

72.6 KiB