ETSI TS 103 780 V1.1.1 (2022-08)

SmartM2M; SAREF: oneM2M usage guidelines

DTS/SmartM2M-103780

General Information

• Status: Not Published
• Technical Committee: SmartM2M - Smart M2M
• Current Stage: 12 - Completion
• Due Date: 15-Aug-2022
• Completion Date: 08-Aug-2022

Standards Content (Sample)

TECHNICAL SPECIFICATION
SmartM2M;
SAREF: oneM2M usage guidelines

2 ETSI TS 103 780 V1.1.1 (2022-08)

Reference
DTS/SmartM2M-103780
Keywords
interoperability, IoT, IoT platforms, oneM2M,
SAREF, semantic, smart lift
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE

Tel.: [phone]  Fax: [phone]

Siret N° 348 623 562 00017 - APE 7112B
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° w061004871

Important notice
The present document can be downloaded from:
http://www.etsi.org/standards-search
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI
deliverable is the one made publicly available in PDF format at www.etsi.org/deliver.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
https://portal.etsi.org/TB/ETSIDeliverableStatus.aspx
If you find errors in the present document, please send your comment to one of the following services:
https://portal.etsi.org/People/CommiteeSupportStaff.aspx
If you find a security vulnerability in the present document, please report it through our
Coordinated Vulnerability Disclosure Program:
https://www.etsi.org/standards/coordinated-vulnerability-disclosure
Notice of disclaimer & limitation of liability
The information provided in the present deliverable is directed solely to professionals who have the appropriate degree of
experience to understand and interpret its content in accordance with generally accepted engineering or
other professional standard and applicable regulations.
No recommendation as to products and services or vendors is made or should be implied.
No representation or warranty is made that this deliverable is technically accurate or sufficient or conforms to any law
and/or governmental rule and/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.
In no event shall ETSI be held liable for loss of profits or any other incidental or consequential damages.

Any software contained in this deliverable is provided "AS IS" with no warranties, express or implied, including but not
limited to, the warranties of merchantability, fitness for a particular purpose and non-infringement of intellectual property
rights and ETSI shall not be held liable in any event for any damages whatsoever (including, without limitation, damages
for loss of profits, business interruption, loss of information, or any other pecuniary loss) arising out of or related to the use
of or inability to use the software.
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and
microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.

© ETSI 2022.
All rights reserved.
ETSI
3 ETSI TS 103 780 V1.1.1 (2022-08)
Contents
Intellectual Property Rights . 4
Foreword . 4
Modal verbs terminology . 4
1 Scope . 5
2 References . 5
2.1 Normative references . 5
2.2 Informative references . 5
3 Definition of terms, symbols and abbreviations . 6
3.1 Terms . 6
3.2 Symbols . 6
3.3 Abbreviations . 6
4 Motivation . 6
5 System Description . 8
5.1 Use case . 8
5.2 Custom Model . 10
5.3 Semantic Modelling . 12
5.4 Smart Device Modelling . 15
6 Semantic Annotation in oneM2M . 18
6.1 Semantic description of services using SAREF Ontology . 18
6.2 Describing oneM2M APIs with the oneM2M Base Ontology . 19
6.2.1 Clothes Washing Machine APIs using oneM2M . 19
6.2.2 Custom Model API semantic description . 20
6.2.3 Semantic Model annotation . 20
6.2.4 SDT model annotation . 21
7 Semantic Queries . 22
7.1 Foreword . 22
7.2 Discovery Queries . 22
7.3 Interoperability Queries . 23
8 Procedures . 25
8.1 Introduction . 25
8.2 Implementation . 25
8.2.1 Semantics Description Utilitie s . 25
8.2.2 Semantic Query Utilities . 25
8.3 Semantics representations and primitives . 25
8.3.1 Introduction. 25
8.3.2 Create . 26
8.3.3 Semantic Query . 29
9 Conclusion . 31
Annex A (informative): Bibliography . 33
History . 34

ETSI
4 ETSI TS 103 780 V1.1.1 (2022-08)
Intellectual Property Rights
Essential patents
IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The declarations
pertaining to these essential IPRs, if any, are publicly available for ETSI members and non-members, and can be
found in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to
ETSI in respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the
ETSI Web server (https://ipr.etsi.org/).
Pursuant to the ETSI Directives including the ETSI IPR Policy, no investigation regarding the essentiality of IPRs,
including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not
referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become,
essential to the present document.
Trademarks
The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners.
ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no
right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does
not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks.
DECT™, PLUGTESTS™, UMTS™ and the ETSI logo are trademarks of ETSI registered for the benefit of its

Members. 3GPP™ and LTE™ are trademarks of ETSI registered for the benefit of its Members and of the 3GPP
Organizational Partners. oneM2M™ logo is a trademark of ETSI registered for the benefit of its Members and of the ®
oneM2M Partners. GSM and the GSM logo are trademarks registered and owned by the GSM Association.
Foreword
This Technical Specification (TS) has been produced by ETSI Technical Committee Smart Machine-to-Machine
communications (SmartM2M).
Modal verbs terminology
In the present document "shall", "shall not", "should", "should not", "may", "need not", "will", "will not", "can" and
"cannot" are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of
provisions).
"must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation.

ETSI
5 ETSI TS 103 780 V1.1.1 (2022-08)
1 Scope
The present document has the objective to provide guidelines for the usage of SAREF over oneM2M (also including the
SDT interoperability) for vertical industry sectors.
The present document also 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:
• 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
2.1 Normative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
Referenced documents which are not found to be publicly available in the expected location might be found at
https://docbox.etsi.org/Reference.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long-term validity.
The following referenced documents are necessary for the application of the present document.
Not Applicable.
2.2 Informative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
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.
[i.1] ETSI TS 118 112: "oneM2M; Base Ontology (oneM2M TS-0012)".
[i.2] ETSI TS 118 130: "oneM2M; Ontology based Interworking (oneM2M TS-0030)".
[i.3] ETSI TS 118 104: "oneM2M; Service Layer Core Protocol (oneM2M TS-0004)".
[i.4] onem2m-jupyter-notebooks.
NOTE: Available at https://github.com/ankraft/onem2m-jupyter-notebooks.
[i.5] ETSI TS 118 123: "oneM2M; Home Appliances Information Model and Mapping (oneM2M
TS-0023)".
ETSI
6 ETSI TS 103 780 V1.1.1 (2022-08)
3 Definition of terms, symbols and abbreviations
3.1 Terms
Void.
3.2 Symbols
Void.
3.3 Abbreviations
For the purposes of the present document, the following abbreviations apply:
AE Application Entity
API Application Programming Interface
CSE Common Service Entity
HTTP Hypertext Transfer Protocol
IoT Internet Of Things
IPE Interworking Proxy Element
JSON JavaScript Object Notation
M2M Machine to Machine
NoDN Non-oneM2M Device Node
RDF Resource Description Framework
SAREF Smart Applications REFerence ontology
SDT Smart Device Template
SPARQL SPARQL Protocol and RDF Query Language
URI Uniform Resource Identifier
X-M2M-CTS oneM2M HTTP protocol custom header for "Content Status"
X-M2M-RI oneM2M HTTP protocol custom header for "Request Identifier"
X-M2M-RSC oneM2M HTTP protocol custom header for "Response Status Code"
X-M2M-RVI oneM2M HTTP protocol custom header for "Release Version Indicator"
XML eXtensible Markup Language
4 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.
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.
ETSI
7 ETSI TS 103 780 V1.1.1 (2022-08)

Figure 1: Semantic understanding of device and data in IoT deployments
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.

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 ETSI
TS 118 130 [i.2]). A third approach to modelling devices in oneM2M is the use of Smart Device Templates (see ETSI
TS 118 123 [i.5]).
ETSI
8 ETSI TS 103 780 V1.1.1 (2022-08)
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.
5 System Description
5.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
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 flows 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.
ETSI
9 ETSI TS 103 780 V1.1.1 (2022-08)

Figure 4: Generic oneM2M Call Flows
The messages shown in Figure 4 are further described here:
1. Register the AE/IPE: In oneM2M an IPE is a type of AE that is intended to communicate with NoDNs. 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.
ETSI
10 ETSI TS 103 780 V1.1.1 (2022-08)
2. Create Polling Channel: A 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.)
3. 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.
4. Register Client application AE: Client applications are also modelled as resources and register in the
oneM2M CSE.
5. 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 it has been shown how using the semantics capabilities of oneM2M and the
SAREF ontology the same application can discover and control clothes washing machines from any
manufacturer.
6. 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.
7. 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.
8. Update the model resources: When the state of the clothes washing machine changes, the change in state will
be reflected in the oneM2M CSE.
9. 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.
10. 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.
11. 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.
12. Poll for notifications. Because the IPE cannot receive notifications directly, it shall 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.
5.2 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.
ETSI
11 ETSI TS 103 780 V1.1.1 (2022-08)

Figure 5: Custom washing machine model

Figure 6: Custom Model oneM2M Call Flows
ETSI
12 ETSI TS 103 780 V1.1.1 (2022-08)
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 5.1.
Create Information Model (Figure 6): 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 resource is created for the Status information of the clothes washing machine. The IPE creates
resources that have the following content when there are any changes in the status of the
clothes washing machine:
{
"WashingMachineStatus ": "WASHING", // Or "STOPPED", "ERROR"
}
A 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
resource:
{
"state": "ON", // Or "OFF", "Toggle"
}
A resource is created as a child of the command resource by the IPE. This will
cause a notification to be sent to the IPE when a new command is made by an application.
5.3 Semantic Modelling
A SAREF description of the washing machine is mapped to the resource structure shown in Figure 7 using the rules
described in ETSI TS 118 130 [i.2] and ETSI TS 118 112 [i.1]. A complete derivation of this example is shown in ETSI
TS 118 112 [i.1], clause 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 it is shown that the description here has triples that are intended to help define the resource tree structure
according to the rules described in ETSI TS 118 130 [i.2] and ETSI TS 118 112 [i.1]. However, when the description of
the clothes-washing machine is put into a some are removed because they do not offer
information useful for SPARQL queries.
ETSI
13 ETSI TS 103 780 V1.1.1 (2022-08)
@prefix rdf:  .
@prefix rdfs:  .
@prefix oneM2M: .
@prefix saref: .
@prefix s4bldg: .
@prefix sn:   .

sn:WASH_XYZ
a            ;
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
The procedure defined in ETSI TS 118 112 [i.1] requires the IPE to parse the semantic description to generate a total of
three custom definitions to support the structure shown in Figure 7. The schemas generated are added
as the content of a resource under a container for these custom definitions. The locations of these
schemas are referenced in the container definition attribute of the respective :
• two child-resources for Services and their s are used for modelling the
services SwitchOnService and MonitorService;
ETSI
14 ETSI TS 103 780 V1.1.1 (2022-08)
• the SwitchOnService in turn has a child resource of type for Operations which exposes the
Toggle_Command;
• one customAttribute of the SwitchOnService is used for holding the values for
InputDataPoint: BinaryInput;
• one customAttribute of the MonitorService is used for holding the values for
OutputDataPoint: WashingMachineStatus.

Figure 8: SAREF Model oneM2M Call Flows
ETSI
15 ETSI TS 103 780 V1.1.1 (2022-08)
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 5.1.
Create Information Model (Figure 8): 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 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 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, // Or True
}
A 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 resource is created as a child of the Toggle command 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 resource is created as a child of the SwitchOnService resource by the IPE. This will
cause a notification to be sent to the IPE when a new command is made by an application
5.4 Smart Device Modelling
ETSI TS 118 123 [i.5] 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 has been modeled. The resource tree
structure of the deviceClothesWasher is shown in Figure 9. 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.
ETSI
16 ETSI TS 103 780 V1.1.1 (2022-08)

Figure 9: SDT washing machine model
When using a SDT model from ETSI TS 118 123 [i.5] 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.
Table 1
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
ETSI
17 ETSI TS 103 780 V1.1.1 (2022-08)
Meta-Data Device Value SDT modelling
Supported Commands ON The SDT model enables the ON and OFF commands
OFF using the state attribute of the binarySwitch
Toggle ModuleClass. The Toggle command is supported by the
toggle ActionModule
State "WASHING" The SDT model offers runState ModuleClass which
"STOPPED" supports more enumerations than indicated by our
"ERROR" product
Location My_Bathroom The SDT model does not have an attribute specifically
for Location
Figure 10: SDT model oneM2M Call Flows
ETSI
18 ETSI TS 103 780 V1.1.1 (2022-08)
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 5.1.
Create Information Model (Figure 10): 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 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:
{
"CurrentMachineState ": 3, // Or [1,3,5,6]
}
A 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:
{
"state": false, // Or true
}
A 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 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 resource is created as a child of the toggle 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 resource is created as a child of the binarySwitch command 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 Semantic Annotation in oneM2M
6.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.
SAREF ontology has been used to describe the services of the washing machine and the oneM2M Base Ontology to
describe the oneM2M interface for the services.
The services of any clothes washing machine are fundamentally the same regardless of which model is used. Especially
in this case where the same clothes washing machine is described. The following RDF triples describe the services and
functions of our clothes washing machine.
ETSI
19 ETSI TS 103 780 V1.1.1 (2022-08)
@prefix saref: .
@prefix s4bldg: .
@prefix xsd: .
@prefix rdfs: .
@prefix sn: .
@prefix m2m: .

sn:WASH_XYZ_RESOURCE_ID a ;
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.

These triples will be placed into a resource in each of the models.
NOTE: 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 .
6.2 Describing oneM2M APIs with the oneM2M Base Ontology
6.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 has been
described offers the following operations:
1) TURN ON WASHING MACHINE
2) TURN OFF WASHING MACHINE
3) TOGGLE THE WASHING MACHINE STATUS
4) 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.
Table 2
Model Request Response
SDT RETRIEVE { " currentMachineState ": 3
/cseBaseName/IPE_ROOT/deviceclothesWashe  "machineStates": [1,3,5,6]
r/runState   "currentJobState": 6
"jobStates":[2,3,4,5,6]
"progressPercentage":95.0
}
SAREF RETRIEVE /cseBaseName/IPE_ROOT/My-
{ "WashingMachineStatus":"WASHING"
WashingMachine/sarefWashingMachine/Monitor }
Service
Custom RETRIEVE { "WashingMachineStatus":"WASHING"
/cseBaseName/IPE_ROOT/myWashingMachine/ }
Status/la
ETSI
20 ETSI TS 103 780 V1.1.1 (2022-08)
Similarly, to command the washing machine to STOP the following oneM2M primitives are sent.
Table 3
Model Request
SDT UPDATE /cseBaseName/IPE_ROOT/deviceClothesWasher/binarySwitch
{"state": false }
SAREF UPDATE /cseBaseName/IPE_ROOT/My-WashingMachine/SwitchOnService
{"BinaryInput": false}
Custom CREATE /cseBaseName/IPE_ROOT/myWashingMachine/Command
{"OFF"}
6.2.2 Custom Model API semantic description
The specific primiti
...