oneM2M™ is a standard for IoT platform, which is standardized by oneM2M partnership project. oneM2M defines set of functionalities that are commonly used in IoT applications, which is called Common Services Function (CSF). The implementation of the CSF is provided by Communication Service Entity (CSE). oneM2M also defines the interface to use the CSF with REST oriented API that consist of limited types of operation (CREATE, RETRIEVE, UPDATE, DELETE, NOTIFY) on many types of resources. Applications of oneM2M use the interface to communicate with CSEs. In a system managed by a single service provider, multiple CSEs can exist and they form tree structure. The root CSE is called Infrastructure Node CSE (IN-CSE). Each application connects to one of CSEs in the system. CSEs have routing capability and application can send request to any CSEs in the system through the directly-connected CSE.
One of characteristic aspects of oneM2M is to allow multiple protocols and serialization formats for messages. Currently specified protocols are HTTP, CoAP, MQTT and WebSocket, and specified serialization are XML, JSON and CBOR (Concise Binary Object Representation). To make specification coherent, oneM2M specifications are separated into abstract level and concrete level. As abstract level, TS-0001 defines the oneM2M architecuture and resource types and TS-0004 defines data procedures and data structures. As concrete level, TS-0008 , TS-0009 , TS-0010 , and TS-0020 define concrete protocol which are mappoed to model of the abstract level. Here, the interface defined in abstract level, which independent on concrete protocols, is regarded as oneM2M Service Layer.
oneM2M Partners Type 1 (ARIB, ATIS, CCSA, ETSI, TIA, TSDSI, TTA, TTC) register oneM2M trademarks and logos in their respective jurisdictions.
One of potential problems is application portability. oneM2M specifies protocol based interfaces, but doesn’t specify a programming level API. Without a standardized API, application program tends to be built tightly coupled with the libraries handling the communication method (combination of protocol and serialization) that is initially intend to use. In that case it would be hard to operate the application in another environment where different communication method is used; basically it is required to modify the application drastically. oneM2M could introduce segmentation of ecosystem within oneM2M compliant applications due to the lack of application portability.
This chapter provides interface to oneM2M applications for communicating communicate CSE at Service Layer of oneM2M. The providing API is protocol and serialization agnostic for preventing the problem above. Once application developer write code, it can be run in other environment where different communication method is used.
Another benefit of the service is reduction of computational resources, typically latency of execution in a certain cases, where both application and CSE is implemented on OSGi framework. In that case, it is possible to reduce executiontime for serialization/deserialization of data, context-switch of applications, compared to the case where they communicates with a certain communication protocol.
-
Protocol Agnostic - API is independent on protocol that are used in communications. oneM2M specifies multiple protocols, which are HTTP, CoAP, MQTT and WebSocket. conversion operations.
-
Serialization Agnostic - API is independent on serialization that are actually used in communications. oneM2M specifies multiple serializations, which are XML, JSON and CBOR .
-
Support of synchoronous and asynchronous method call - API allows both of calling manners.
-
Use of Data Transfer Object (DTO) - DTO is used as parameters passing on API. Since oneM2M defines many types, concrete DTOs are specified for the higher level structure, and for lower structures generic DTO is used.
-
Low level and high level operations - API allows for applications to use both low level operation and high level operation, where low level operation allows all possible oneM2M operations and high level operation allows resource level operations, which are create, retrieve, update, and delete.
The following entities are used in this specification:
-
Application Bundle - Application, which use oneM2M CSE's capability. This specification assumes that an application bundle consists an oneM2M application.
-
ServiceLayer - This is the API used by oneM2M applications.
-
NotificationListener - Listener Interface, which is necessary to implement by oneM2M applications, when then need to received notifications.
-
ServiceLayer Implementation Bundle - Bundle providing implementation of ServiceLayer and its ServiceFactory.
-
oneM2M CSE - oneM2M's Server. It may exist remotely or locally.
oneM2M ServiceLayer is the interface used by an application for sending request and get response as return method. It contains low level API and high level API.
request() method allows very raw data type access and it enables all possible message exchanges among oneM2M entities. This is called the low level API. The method takes requestPrimitive as an argument and returns responseRequest. It allows all possible operation of oneM2M. For the return type, OSGi Promise ( Promises Specification ) is used for allowing synchronous and asynchronous calling manner.
The low level API may be redundant to application developers, because they need to write composition of requestPrimitive and decomposition of responsePrimitive. Following methods allow application developers to develop application with less lines of code. They provides higher level of abstraction; operation level of resource such as create, retrieve, update, delete, notify and discovery. They cover typical oneM2M operations but do not cover all of possible messages of oneM2M.
Implementation of these high level API automatically inserts ‘requestID’ and ‘from’ parameter to RequestDTO.
Following example shows temperature measurement application using container resource and contentInstance resource.
ServiceReference<ServiceLayer> sr = bc
.getServiceReference(ServiceLayer.class);
ServiceLayer sl = bc.getService(sr);
ResourceDTO container = new ResourceDTO();
container.resourceType = Constants.RT_contentInstance;
container.resourceName = "temperatureStore";
sl.create("/CSE1/csebase", container).getValue();
ScheduledExecutorService service = Executors
.newSingleThreadScheduledExecutor();
AtomicInteger count = new AtomicInteger(0);
service.scheduleAtFixedRate(() -> {
ResourceDTO instance = new ResourceDTO();
instance.resourceType = Constants.RT_contentInstance;
instance.resourceName = "instance" + count.getAndIncrement();
instance.attribute = new HashMap<String,Object>();
instance.attribute.put("content", measureTemperature());
sl.create("/CSE1/csebase/temperatureStore", instance);
}, 0, 60, TimeUnit.SECONDS);
Following example shows visualizing application of temperature data.
ServiceReference<ServiceLayer> sr = (ServiceReference<ServiceLayer>) bc
.getServiceReference("org.osgi.service.onem2m.ServiceLayer");
ServiceLayer sl = bc.getService(sr);
FilterCriteriaDTO fc = new FilterCriteriaDTO();
fc.createdAfter = "20200101T120000";
fc.createdBefore = "20200101T130000";
List<Integer> resourceTypes = new ArrayList<Integer>();
resourceTypes.add(Constants.RT_contentInstance);
fc.resourceType = resourceTypes;
fc.filterOperation = FilterOperation.AND;
List<String> l = sl.discovery("/CSE1/csebase/temperatureStore", fc)
.getValue();
List<Pair<String,Double>> renderData = new ArrayList<Pair<String,Double>>();
for (String uri : l) {
ResourceDTO resource = sl.retrieve(uri).getValue();
renderData.add(new Pair<String,Double>(resource.creationTime,
(Double) resource.attribute.get("content")));
}
renderService(renderData);
NotificationListener is an interface for receiving oneM2M notification. An application that needs to receive oneM2M notifications must implement the interface and register it to the OSGi registry.
A ServiceLayer Implementation Bundle must call the notify() method of the NotificationListener, when it receives notification from CSE. In notification, target address is designated by AE-ID. The ServiceLayer Implementation Bundle finds the coresponding instance of the NotificationListener by checking its registerer bundle and checking internal mapping table of AE-ID and application bundle.
public class MyListener implements NotificationListener {
public void notified(RequestPrimitiveDTO request){
NotificationDTO notification = request.content.notification;
NotificationEventDTO event = notification.notificationEvent;
Object updatedResource = event.representation;
NotificationEventType type = event.notificationEventType;
if( type == NotificationEventType.update_of_resource ){
// check updated resource, execute some actions.
}
}
}
@Activate
public void activate(BundleContext bc) {
NotificationListener l = new MyListener();
bc.registerService(NotificationListener.class, l, null);
}
}
OSGi DTOs are used for representing data structured passed on the API. Some of the data structures, which are directly referred from API or in small number of hops, are specified with concrete field names. The following figure shows DTOs with concrete field names, and reference relationship of class. Following DTO's rule, instances must not have loop reference relationship.
ResourceDTO represents oneM2M resource. ResourceDTO has both fields with concrete names and a field (named as attribute) for having sub-elements in generic manner. All of fields of the ResourceDTO represent attributes. Most of attributes have a primitive type and part of attributes have structured value. For structured value, if it possible defined concrete DTOs must be used, otherwise GenericDTO must be used.
oneM2M specifies two types of key names for representing name of resources, attributes, and elements of data structure, which are long name and short name. Long name is human readable representation, for example "resourceID", meanwhile short name is compact representation for minimizing network transfer, consist with typically 2-4 alphabetical characters, for example "ri". All field names in concrete DTOs are based on long name. Long name should be used for key names of GenericDTO and attribute names of ResourceDTO.
Implementation of ServiceLayer may use credentials on behalf of application bundles on the communication with oneM2M CSE. So ServiceLayer Implementation should pass the service reference of ServiceLayer to only the proper application bundle. Use of ServiceFactory is to realize this. Application Bundles should not pass the service reference to other application bundles.
How to configure those credentials is left to developer of ServiceLayer Implementation, and it is out of scope the specification.
Service Layer API for oneM2M Specification Package Version 1.0.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.
Example import for consumers using the API in this package:
Import-Package: org.osgi.service.onem2m; version="[1.0,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.service.onem2m; version="[1.0,1.1)"
-
NotificationListener- Interface to receive notification from other oneM2M entities. -
OneM2MException- General Exception for oneM2M. -
ServiceLayer- Primary Interface for an oneM2M application entity to send request and get response to/from other oneM2M entity.
Interface to receive notification from other oneM2M entities.
Application that receives notification must implement this interface and register to OSGi service registry. No service property is required.
General Exception for oneM2M.
The exception message.
The exception error code.
Construct a OneM2MException with a message and an error code.
Primary Interface for an oneM2M application entity to send request and get response to/from other oneM2M entity.
It contains low level API and high level API. The only low level method is request() and other methods are categorized as high level API.
Consumers of this API must not implement this type
URI for parent resource of the resource being created.
resource data
create resource
The create() method is a method to create new resource under specified uri. The second argument resource is expression of resource to be generated. The resourceType field of the resourceDTO must be assigned. For other fields depends on resource type. Section 7.4 of TS-00004 specifies the optionalities of the fields.
Promise of created resource
target URI for deleting resource
delete resource
delete resource on the URI specified by uri argument.
promise of execution status
URI for resource tree to start the search
filter criteria selecting resources
find resources with filter condition specified in fc argument.
Discovery Result Type is kept as blank and default value of target CSE is used for the parameter.
list of URIs matching the condition specified in fc
URI for resource tree to start the search
filter criteria
Discovery Result Type (structured/unstructured)
find resources with filter condition specified in fc argument.
With this method application can specify desired identifier in result
list of URIs matching the condition specified in fc
uri of destination
content of notification
send notification
Promise of notification execution status
request primitive
send a request and receive response.
This method allows very raw data type access and it enables all possible message exchanges among oneM2M entities. This is called the low level API. This method allows all possible operation of oneM2M. For the return type, OSGi Promise is used for allowing synchronous and asynchronous calling manner.
promise of ResponseDTO.
URI for retrieving resource
retrieve resource
retrieve resource on URI specified by uri argument. This method retrieve all attributes of the resource.
retrieved resource data
URI for retrieving resource
names of the target attribute
retrieve resource with selected attributes.
retrieve resource on URI specified by uri argument. This method retrieve selected attributes by targetAttributes argument. The retrieve() methods are methods to retrieve resource on URI specified by uri argument.
retrieved resource data
URI for updating resource
data resource
update resource
The update() method is a method to update resource on the URI specified by uri argument. The resource argument holds attributes to be updated. Attributes not to be updated shall not included in the argument.
updated resource
Service Layer Data Transfer Objects for oneM2M Specification Package Version 1.0.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.
Example import for consumers using the API in this package:
Import-Package: org.osgi.service.onem2m.dto; version="[1.0,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.service.onem2m.dto; version="[1.0,1.1)"
-
AttributeDTO- DTO expresses Attribute. -
ChildResourceRefDTO- DTO expresses ChildResourceRef. -
Constants- This class defines constants for resource types. -
DasInfoDTO- DTO expresses DasInfo. -
FilterCriteriaDTO- DTO expresses FilterCriteria. -
FilterCriteriaDTO.FilterOperation- Enum FilterOperation -
FilterCriteriaDTO.FilterUsage- Enum FilterUsage -
GenericDTO- GenericDTO expresses miscellaneous data structures of oneM2M. -
IPEDiscoveryRequestDTO- IPEDiscoveryRequestDTO is an element of NotificationEventDTO -
LocalTokenIdAssignmentDTO- DTO expresses LocalTokenIdAssignment. -
NotificationDTO- DTO expresses Notification. -
NotificationEventDTO- DTO expresses NotificationEventDTO -
NotificationEventDTO.NotificationEventType- NotificationEventType -
PrimitiveContentDTO- DTO expresses Primitive Content. -
ReleaseVersion- enum expresses oneM2M specification version. -
RequestPrimitiveDTO- DTO expresses Request Primitive. -
RequestPrimitiveDTO.DesiredIdentifierResultType- Enum for DesiredIdentifierResultType -
RequestPrimitiveDTO.Operation- enum type for Operation -
RequestPrimitiveDTO.ResultContent- enum type for Result Content -
ResourceDTO- DTO expresses Resource. -
ResourceWrapperDTO- DTO expresses ResourceWrapper. -
ResponsePrimitiveDTO- DTO expresses Response Primitive. -
ResponsePrimitiveDTO.ContentStatus- Enum ContentStatus -
ResponseTypeInfoDTO- DTO expresses ResponseTypeInfo -
ResponseTypeInfoDTO.ResponseType- enum ResponseType -
SecurityInfoDTO- DTO expresses Security Info. -
SecurityInfoDTO.SecurityInfoType- Enum SecurityInfoType
DTO expresses Attribute.
This class is typically used in FilterCriteriaDTO for expressing matching condition.
Not Thread-safe
DTO expresses ChildResourceRef.
oneM2M TS-0004 6.3.5.29, oneM2M XSD childResourceRef
Not Thread-safe
resource type specialization of the child resource pointed to by the URI in case type represents a flexContainer. This is an optional field.
This class defines constants for resource types.
resource type for accessControlPolicyAnnc
resource type for AEContactListPerCSE
resource type for authorizationDecision
resource type for authorizationInformation
resource type for authorizationPolicy
resource type for backgroundDataTransfer
resource type for contentInstanceAnnc
resource type for crossResourceSubscription
resource type for dynamicAuthorizationConsultation
resource type for dynamicAuthorizationConsultationAnnc
resource type for flexContainerAnnc
resource type for localMulticastGroup
resource type for locationPolicyAnnc
resource type for m2mServiceSubscriptionProfile
resource type for multimediaSessionAnnc
resource type for notificationTargetMgmtPolicyRef
resource type for notificationTargetPolicy
resource type for ontologyRepositoryAnnc
resource type for policyDeletionRules
resource type for semanticDescriptorAnnc
resource type for semanticMashupInstance
resource type for semanticMashupInstanceAnnc
resource type for semanticMashupJobProfile
resource type for semanticMashupJobProfileAnnc
resource type for semanticMashupResult
resource type for semanticMashupResultAnnc
resource type for serviceSubscribedAppRule
resource type for serviceSubscribedNode
resource type for timeSeriesInstanceAnnc
DTO expresses DasInfo. DAS is short for Dynamic Authorization Server.
oneM2M TS-0004 6.3.5.45, oneM2M XSD dynAuthTokenReqInfo and dasInfo
Not Thread-safe
Information to send to the Dynamic Authorization Server
Secured Information to send to the Dynamic Authorization Server. JWS or JWE is assigned to this field.
DTO expresses FilterCriteria. This data structure is used for searching resources.
oneM2M TS-0004 6.3.5.8, oenM2M TS-0004 7.3.3.17.17
Not Thread-safe
Enum FilterOperation
Enum FilterUsage
GenericDTO expresses miscellaneous data structures of oneM2M.
Not Thread-safe
Substructure of DTO. Type of the value part should be one of types allowed as OSGi DTO.
IPEDiscoveryRequestDTO is an element of NotificationEventDTO
Not Thread-safe
DTO expresses LocalTokenIdAssignment.
oneM2M XSD dynAuthLocalTokenIdAssignments and localTokenIdAssignment
Not Thread-safe
DTO expresses Notification.
Not Thread-safe
aeReferenceIDChange element
AE Registration Point Change
Flag showing subscription deletion This field is optional.
tracking ID 1
tracking ID 1
Flag showing verification request. This field is optional.
DTO expresses NotificationEventDTO
This data structure is held in NotificationDTO.
Not Thread-safe
notificationEventType
NotificationEventType
retrieve_of_container_resource_with_no_child_resource
DTO expresses Primitive Content.
This Data structure is used as union. Only one field MUST have a value, the others MUST be null.
oneM2M TS-0004 6.3.5.5, oneM2M TS-0004 7.2.1, oneM2M XSD primitiveContent
Not Thread-safe
enum expresses oneM2M specification version.
This information is introduced after Release 2.0 and oneM2M uses only R2A, R3_0 (as 2a and 3).
DTO expresses Request Primitive.
oneM2M TS-0004 6.4.1, oneM2M XSD requestPrimitive
Not Thread-safe
Authorization Signatures
In oneM2M this parameter is expressed in m2m:signatureList.
Primitive Content
Delivery Aggregation
This parameter is related to CMDH(Communication Management and Delivery Handling) policy.
Desired Identifier Result Type
This parameter specifies identifier type in response, such as structured or unstructured. This parameter used to be Discovery Result Type in previous oneM2M release.
Event Category
allowed values are 2(Immediate), 3(BestEffort), 4(Latest), and 100-999 as user defined range.
oneM2M TS-0004 6.3.3, oneM2M XSD eventCat, oneM2M XSD stdEventCats
From Parameter.
Originator of the request is stored.
Local Token Identifiers
In oneM2M this parameter is expressed as list of xs:NCName.
Operation This field is mandatory.
Request Expiration Timestamp
* This parameter is related to CMDH(Communication Management and Delivery Handling) policy.
Result Content
Result Expiration Timestamp
This parameter is related to CMDH(Communication Management and Delivery Handling) policy.
Result Persistence
This parameter is related to CMDH(Communication Management and Delivery Handling) policy.
Token Identifiers
In oneM2M this parameter is expressed as list of m2m:tokenID.
Tokens
Each token is in m2m:dynAuthJWT
Vendor Information
Used for vendor specific information. No procedure is defined for the parameter.
Enum for DesiredIdentifierResultType
enum type for Operation
enum type for Result Content
DTO expresses Resource.
Universal attributes are expressed in field of the class. Common attributes and other attributes are stored in attribute field.
Not Thread-safe
Non Universal Attribute. Value Part must be the types that are allowed for OSGi DTO. In case of value part can be expressed DTO in this package, the DTO must be used. In case of value part have sub-elements, GenericDTO must be used.
Parent ID Resource ID of parent resource.
Resource Type
DTO expresses ResourceWrapper.
Not Thread-safe
DTO expresses Response Primitive.
oneM2M TS-0004 6.4.2, oneM2M XSD responsePrimitive
Not Thread-safe
Assigned Token Identifiers
Primitive Content
Content Status
Event Category
allowed values are 2(Immediate), 3(BestEffort), 4(Latest), and 100-999 as user defined range.
oneM2M TS-0004 6.3.3, oneM2M XSD eventCat, oneM2M XSD stdEventCats
Originating Timestamp To Parameter
ResultExpiration Timestamp
Vendor Information
Used for vendor specific information. No procedure is defined for the parameter.
Enum ContentStatus
DTO expresses ResponseTypeInfo
Not Thread-safe
Notification URI
Response Type Value
enum ResponseType
DTO expresses Security Info.
This class is used as union. SecurityInfoType field indicates which type of content is stored.
Not Thread-safe
Security Info Type
Enum SecurityInfoType
DynamicAuthorizationRelationshipMappingRequest
DynamicAuthorizationRelationshipMappingResponse
[1]oneM2M: TS-0001 Functional Architecture V3.15.1 https://www.onem2m.org/images/files/deliverables/Release3/TS-0001-Functional_Architecture-V3_15_1.pdf
[2]oneM2M: TS-0004 Service Layer Core Protocol V3.11.2 https://www.onem2m.org/images/files/deliverables/Release3/TS-0004_Service_Layer_Core_Protocol_V3_11_2.pdf
[3]oneM2M: TS-0008 CoAP Protocol Binding V3.3.1 https://www.onem2m.org/images/files/deliverables/Release3/TS-0008-CoAP_Protocol_Binding-V3_3_1cl.pdf
[4]oneM2M: TS-0009 HTTP Protocol Binding V3.2.1 https://www.onem2m.org/images/files/deliverables/Release3/TS-0009-HTTP_Protocol_Binding-V3_2_1cl.pdf
[5]oneM2M: TS-0010 MQTT Protocol Binding V3.0.1 https://www.onem2m.org/images/files/deliverables/Release3/TS-0010-MQTT_protocol_binding-V3_0_1.pdf
[6]oneM2M: TS-0020 WebSocket Protocol Binding V3.0.1 https://www.onem2m.org/images/files/deliverables/Release3/TS-0020-WebSocket_Protocol_Binding-V3_0_1.pdf
[7]oneM2M-schemas https://git.onem2m.org/PRO/XSD