ETSI TR 118 525 V1.0.0 (2016-03)

oneM2M; Application Developer Guide (oneM2M version 1.0.0 Release 1)

DTR/oneM2M-000025

General Information

• Status: Published
• Publication Date: 17-Mar-2016
• Technical Committee: oneM2M - oneM2M
• Current Stage: 12 - Completion
• Due Date: 28-Mar-2016
• Completion Date: 18-Mar-2016

Standards Content (Sample)

ETSI TR 118 525 V1.0.0 (2016-03)






TECHNICAL REPORT
oneM2M;
Application Developer Guide
(oneM2M TR-0025 version 1.0.0 Release 1)

---------------------- Page: 1 ----------------------
oneM2M TR-0025 version 1.0.0 Release 1 2 ETSI TR 118 525 V1.0.0 (2016-03)



Reference
DTR/oneM2M-000025
Keywords
application, interoperability, M2M, testing

ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE

Tel.: [phone]  Fax: [phone]

Siret N° 348 623 562 00017 - NAF 742 C
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° 7803/88

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 only prevailing document is the
print of the Portable Document Format (PDF) version kept on a specific network drive within ETSI Secretariat.
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
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.

© European Telecommunications Standards Institute 2016.
All rights reserved.

TM TM TM
DECT , PLUGTESTS , UMTS and the ETSI logo are Trade Marks of ETSI registered for the benefit of its Members.
TM
3GPP and LTE™ are Trade Marks of ETSI registered for the benefit of its Members and
of the 3GPP Organizational Partners.
GSM® and the GSM logo are Trade Marks registered and owned by the GSM Association.
ETSI

---------------------- Page: 2 ----------------------
oneM2M TR-0025 version 1.0.0 Release 1 3 ETSI TR 118 525 V1.0.0 (2016-03)
Contents
Intellectual Property Rights . 5
Foreword . 5
1 Scope . 6
2 References . 6
2.1 Normative references . 6
2.2 Informative references . 6
3 Definitions and abbreviations . 7
3.1 Definitions . 7
3.2 Abbreviations . 7
4 Conventions . 7
5 Use case . 7
6 Architecture . 8
7 Procedures . 9
7.1 Introduction . 9
7.2 Call Flows . 10
7.2.1 Application registration and Access control policy creation . 10
7.2.2 Initial resource creation . 11
7.2.3 Discovery of group resources . 12
7.2.4 Discovery and retrieval of contentInstance resources . 13
7.3 Remote control scenarios . 15
7.3.1 Introduction. 15
7.3.2 Single light lamp control . 15
7.3.3 Multiple light lamps control. 15
8 Implementation . 16
8.1 Introduction . 16
8.2 Assumptions . 16
8.3 Addressing for Entities . 17
8.4 Modelling for Light State Data . 17
8.5 Resource Structure . 17
8.5.1 Resource Structure of IN-CSE . 17
8.5.2 Resource Structure of MN-CSE . 17
8.6 Role of Entities . 19
8.6.1 oneM2M service platform (IN-CSE) . 19
8.6.2 Home gateway application (MN-AE) . 19
8.6.3 Light applications (ADN-AE1 and ADN-AE2) . 19
8.6.4 Smartphone application (IN-AE) . 19
8.7 Implementation Procedures . 20
8.7.1 Introduction. 20
8.7.2 MN-CSE registration . 20
8.7.3 Access control policy creation . 20
8.7.4 Application entities registration . 21
8.7.4.1 Light application ADN-AE1 . 21
8.7.4.2 Light application ADN-AE2 . 21
8.7.4.3 Home gateway application MN-AE . 22
8.7.4.4 Smartphone application IN-AE . 22
8.7.5 Containers creation . 23
8.7.5.1 Create a container of ADN-AE1 . 23
8.7.5.2 Create a container of ADN-AE2 . 23
8.7.6 ContentInstances creation . 23
8.7.6.1 Create a content instance of ADN-AE1 . 23
8.7.6.2 Create a content instance of ADN-AE2 . 24
8.7.7 Groups creation . 24
8.7.7.1 Create a group for updating all light states . 24
ETSI

---------------------- Page: 3 ----------------------
oneM2M TR-0025 version 1.0.0 Release 1 4 ETSI TR 118 525 V1.0.0 (2016-03)
8.7.7.2 Create a group for retrieval of all latest light states . 25
8.7.8 Subscriptions creation . 25
8.7.8.1 Subscription to the content instance of ADN-AE1 . 25
8.7.8.2 Subscription to the content instance of ADN-AE2 . 26
8.7.9 Discovery . 26
8.7.9.1 Introduction . 26
8.7.9.2 Discovery of single light registered with MN-CSE . 26
8.7.9.3 Discovery of groups located in MN-CSE . 27
8.7.10 Latest content instances retrieval . 27
8.7.10.1 Introduction . 27
8.7.10.2 Retrieve the latest content instance of ADN-AE1 . 27
8.7.10.3 Retrieve the latest content instance of ADN-AE2 . 28
8.7.10.4 Retrieve a group of latest content instances for all light states. 28
8.7.11 Light state modification . 29
8.7.11.1 Introduction . 29
8.7.11.2 Create a content instance under container of ADN-AE1 . 30
8.7.11.3 Create a content instance under container of ADN-AE2 . 30
8.7.11.4 Update the state of all lights using group fanout . 30
8.7.12 Notifications . 31
8.7.12.1 Introduction . 31
8.7.12.2 Post a notification to ADN-AE1 . 31
8.7.12.3 Post a notification to ADN-AE2 . 32
9 Conclusion . 32
Annex A: Reading Resources . 33
Annex A.1 Introduction . 33
Annex A.2 CSE resources . 33
Annex A.2.1 IN-CSE . 33
Annext A.2.2 MN-CSE . 33
Annex A.3 Gateway device application MN-AE . 34
Annex A.4. Light device applications . 34
Annex A.4.1 ADN-AE1 . 34
Annex A.4.2 ADN-AE2 . 35
Annex A.5 Smartphone application IN-AE . 35
Annex A.6 Access control policy . 36
Annex A.7 Containers . 36
Annex A.7.1 Container under ADN-AE1 . 36
Annex A.7.2 Container under ADN-AE2 . 37
Annex A.8 ContentInstances . 37
Annex A.8.1 Latest contentInstance in ADN-AE1 . 37
Annex A.8.2 Latest contentInstance in ADN-AE2 . 38
Annex A.9 Subscriptions . 38
Annex A.9.1 Subscription to container in ADN-AE1 . 38
Annex A.9.2 Subscription to container in ADN-AE2 . 39
Annex A.10 Groups. 39
Annex A.10.1 Group1 . 39
Annex A.10.2 Group2 . 40
History . 41

ETSI

---------------------- Page: 4 ----------------------
oneM2M TR-0025 version 1.0.0 Release 1 5 ETSI TR 118 525 V1.0.0 (2016-03)
Intellectual Property Rights
IPRs essential or potentially essential to the present document may have been declared to ETSI. The information
pertaining to these essential IPRs, if any, is 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 IPR Policy, no investigation, 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.
Foreword
This Technical Report (TR) has been produced by ETSI Partnership Project oneM2M (oneM2M).
ETSI

---------------------- Page: 5 ----------------------
oneM2M TR-0025 version 1.0.0 Release 1 6 ETSI TR 118 525 V1.0.0 (2016-03)
1 Scope
The present document provides a guide for application developers to develop applications using functionalities provided
by any oneM2M compliant service platform with thescope of as follows:
• Objective of the use case,
• The architecture of the use case mapped into an oneM2M service platform,
• The execution procedures for implementation of the use case, and
•  Implementation details of the use case.
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/.
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] oneM2M Drafting Rules
NOTE: Available at http://www.onem2m.org/images/files/oneM2M-Drafting-Rules.pdf
[i.2] ETSI TS 118 101 (V1.1.0): "oneM2M; Functional Architecture (oneM2M TS-0001)".
[i.3] ETSI TS 118 104 (V1.1.0): "oneM2M; Service Layer Core protocol Specification (oneM2M TS-0004)".
[i.4] ETSI TS 118 109 (V1.1.0): "oneM2M; HTTP Protocol Binding (oneM2M TS-0009)".
[i.5] ETSI TS 118 111: "oneM2M; Common Terminology (oneM2M TS-0011)".

ETSI

---------------------- Page: 6 ----------------------
oneM2M TR-0025 version 1.0.0 Release 1 7 ETSI TR 118 525 V1.0.0 (2016-03)
3 Definitions and abbreviations
3.1 Definitions
For the purposes of the present document, the terms and definitions given in ETSI TS 118 111 [i.5] and the following
apply.
NOTE: A term defined in the present document takes precedence over the definition of the same term, if any, in ETSI TS 118 111 [i.5].

M2M service provider domain: part of the M2M System that is associated with a specific M2M Service Provider
registrar CSE: CSE where an Application or another CSE has registered
resource: uniquely addressable entity in oneM2M architecture
3.2 Abbreviations
For the purposes of the present document, the following abbreviations apply:
ACP Access Control Policy
ADN Application Dedicated Node
ADN-AE AE which resides in the Application Dedicated Node
AE Application Entity
CoAP Constrained Application Protocol
CSE Common Services Entity
CSE-ID Common Service Entity Identifier
DNS Domain Name System
FQDN Fully Qualified Domain Name
HTTP HyperText Transfer Protocol
IN Infrastructure Node
IN-AE Application Entity that is registered with the CSE in the Infrastructure Node
IN-CSE CSE which resides in the Infrastructure Node
IP Internet Protocol
JSON JavaScript Object Notation
M2M Machine to Machine
Mca Reference Point for M2M Communication with AE
Mcc Reference Point for M2M Communication with CSE
MN Middle Node
MN-AE Application Entity that is registered with the CSE in Middle Node
MN-CSE CSE which resides in the Middle Node
PoA Point of Access
SP Service Provider
URI Uniform Resource Identifier
XML eXtensible Markup Language


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 [i.1].
5 Use case
This clause briefly describes the use case from perspective of service being provided by the oneM2M platform. The
physical device components are introduced in the current section.
ETSI

---------------------- Page: 7 ----------------------
oneM2M TR-0025 version 1.0.0 Release 1 8 ETSI TR 118 525 V1.0.0 (2016-03)
The described use case enables the remote control of lights via a smartphone or smart tab which embeds an application
that gains access to a oneM2M service platform. The overview of the use case of remote lights control is shown in
figure 5.1. The main components are introduced as follows:
 Light lamps shown in the current use case are deployed at a house and attached to a home gateway. The light
lamps are able to interact with a oneM2M platform through a wireless access interface.
 The home gateway is configured to be able to search and connect light lamps into itself and to communicate
with a oneM2M service platform in terms of exchanging and storing light lamps states between the light lamps
and the oneM2M service platform.
 oneM2M service platform provides vertical application services targeted at different field domains, for
instance, home, vehicle, and industry. The oneM2M service platform supports a group of common service
functionalities such as registration, discovery, data management, group management, subscription/notification
etc.
 The smartphone application is embedded into a smartphone and acts as a remote light controller with
capabilities as the follows:
Discovery of light lamps deployed into the home gateway.
Sending commands to change light states i.e. ON and OFF.
Retrieval of light states.

oneM2M Service
Platform
Light#1
Light#2
Home Gateway
Smartphone
embedding with
applications as a
remote light
controller

Figure 5.1: Overview of remote lights control use case


6 Architecture
This clause describes the architecture of the implemented use case with components represented by the oneM2M entity
roles. For instance, a physical device can be modelled as an ADN-AE and the oneM2M service system can be modelled
as an IN-CSE, etc.
The remote lights control use case shown in figure 5.1 can be mapped into the oneM2M functional architecture depicted
in figure 6.1.
ETSI

---------------------- Page: 8 ----------------------
oneM2M TR-0025 version 1.0.0 Release 1 9 ETSI TR 118 525 V1.0.0 (2016-03)
mcc
IN-CSE
mca
mca
AD N-AE - 1 IN-AE
MN-AE
Light#1
oneM2M Service
Smartphone
Platform
AD N-AE - 2
MN-CSE
embedding with
mca
applications as a
Light#2 Home Gateway
remote light
controller
Home Domain

Figure 6.1: oneM2M functional architecture of remote lights control use case

In oneM2M functional architecture two entity roles are defined, one is AE and the other is CSE. Application dedicated
devices e.g. light lamps are usually acted as an ADN-AE. Smartphone applications that are embedded into smartphone
devices and able to communicate directly with oneM2M service platform can also be acted as an ADN-AE. oneM2M
service system is acted as an IN-CSE and the home gateway plays a role of MN-CSE.
Two reference points, mca and mcc which are defined in the oneM2M functional architecture are used between AE and
CSE and between two CSEs in the current use case, respectively. As figure 6.1 shows, the reference point used between
any light application (ADN-AE-1 or ADN-AE-2) and home gateway MN-CSE is mca while that of between home
gateway and oneM2M service platform is mcc.
In summary, applications used in the current use case are classified as follows:
 ADN-AE1: an application embedded in the light lamp Light#1 with capabilities to control light lamp Light#1
and interact with the home gateway MN-CSE through mca reference point;
 ADN-AE2: an application embedded in the light lamp Light#2 with capabilities to control light lamp Light#2
and interact with the home gateway MN-CSE through mca reference point;
 IN-AE: a smartphone application embedded in the smartphone device with capabilities to interact directly with
the oneM2M service platform IN-CSE through mcc reference point and thereby remotely control light lamps
Light#1 and Light#2;
 MN-AE: a gateway application embedded into the home gateway MN-CSE and interact with MN-CSE through
mca reference point.

7 Procedures
7.1 Introduction
The deployment of oneM2M standard of present use case requires procedures that are classified as follows:
Registration: The current procedure contains light lamps registration, gateway application registration, and
accessControlPolicy resource creation for a selective access to data storage resources.
ETSI

---------------------- Page: 9 ----------------------
oneM2M TR-0025 version 1.0.0 Release 1 10 ETSI TR 118 525 V1.0.0 (2016-03)
Initial resource creation: The current procedure contains group resources creation, container resources
creation with specific access control policies, content instance resources creation with initial light states,
subscription resources creation for notifications.
Discovery of container resource: all containers with a specific filter criteria can be discovered by the
gateway application and provided as members of group resources.
Discovery and retrieval lights states: all containers with a specific filter criteria could be discovered and
retrieved using resource identities through a smartphone application which gains access to oneM2M service
platform and content information could also be retrieved.
Single light switch on/off: Any light that is discovered by and connected to the smartphone application is
able to be switched on and off via a smartphone application.
Multiple lights switch on/off: More than one lights that are discovered by and connected to the smartphone
application are able to be switched on and off together via a smartphone application.

7.2 Call Flows
7.2.1 Application registration and Access control policy creation
Call flows regar
...