APIs Device to Cloud Key concepts

Device to Cloud is based on the oneM2M standard.

The oneM2M API can be used as a generic interoperability layer to integrate different devices, applications and platforms.

This page explains how to work with the oneM2M API and how to understand the oneM2M resource types.

External Links to the OneM2M Web Site

TL;DR

Follow our the step-by-step guide with ready-to-use API requests. This will help you to onboard your first device and to send its IoT data to your application.

oneM2M resources types explained

oneM2M is a powerful framework to manage IoT assets, applications, configuration and IoT data. It uses the concept of resources to describe those entities. These oneM2M resources are organized in a tree structure. The root of this tree is the CSEBase (CSE = Common Services Entity). On T IoT Hub, the CSEBase is representing your tenant.

Hint:
If you need to assign the management of specific IoT devices to separate groups for security or billing purposes, you should order multiple tenants.

In the context of T IoT Hub, a oneM2m node resource represents specific information about a device or gateway. It may have specializations of the mgmtObj resource as children, which represent further hardware and software aspects of managing a node .

In addition to management capabilities, a node resource may host AE (Application Entity) resources, such as those used for edge processing applications.

An AE resource represents any kind of application or functionality in a oneM2M system that implements functional, management, or business logic. This could be:

  • An application or abstracted functionality on a device node . There may be multiple AEs per node.
  • An application running in the proximity of a CSE, e.g. a connector to other cloud platforms.
  • An application running remotely, e.g your business application in the cloud

An AE (Application Entity) is an entity that accesses resources on the CSE, apart from the CSE itself. It might seem like an obvious distinction, but it’s key to how the system works.

The container resource represents a container for data instances. It enables data sharing with other entities and supports tracking. A container resource has no associated content, it has only attributes and child resources. The child resource type contentInstance is used to store data. A container may have also one or more other container resources as children, in order to model complex data structures. In a contentInstance , the data is stored in the con (content) field.

A flexContainer represents a customizable container for data instances, which can be extended with custom attributes. It serves as a template, and is never instantiated directly, only by derived objects. This concept is similar to that of the mgmtObj resource, which isn’t instantiated directly, either. For example, the flexContainer is used in “Device Provisioning Requests” and “Device Groups”.

oneM2M resource types

Resource Type NameTypeDescription
AE2An AE (application entity) resource represents any kind of application or functionality in a oneM2M system that implements any kind of functional, management, or business logic.
container3The container resource represents a container for data instances. It is used to share information with other entities and potentially to track the data. A container resource has no associated content.
contentInstance4The contentInstance resource represents a data instance within the container resource.
CSEBase5A CSEBase may have most of the other resource types as children. Some of them, however, shall only be located directly under the CSEBase, for example, the AE or the remoteCSE resource.
mgmtObj13The mgmtObj resource contains management data which represents individual M2M management functions. It functions mostly as a base class for defining specializations for management aspects, such as for “battery”, “memory”, etc.
node14A node represents specific pieces of information about a (oneM2M) node / device. It may have specializations of the mgmtObj resource as children, which then represent further hardware and software aspects that can be used to manage a node.
flexContainer28A flexContainer represents a customizable container for data instances that can be extended with so-called custom attributes.
FlexContainerInstance52The flexContainerInstance resource represents a data instance in the flexContainer resource.
subscription23The subscription resource contains information about the resource it subscribes to (usually the parent resource of the subscription). A subscription allows an entity in the oneM2M architecture to receive notifications about changes to the subscribed resource.

Resource hierarchy for Device to Cloud

We provide the following structure for each Device to Cloud tenant (CSEBase):

oneM2M Hierarchy

To request the onboarding of a device, you add a device-provisioning/request (a special flexContainer with a list of devices).

Our provisioning process will onboard your device automatically in an oneM2M IPE (Interworking Proxy Entity) that supports your device protocol (e.g. LwM2M). The process will also create the following structure in the CSEBase:

  • A node with the device name containing management objects, which contain information about the device, such as manufacturer, firmware version, and so on. In LwM2M, this information comes from the device. You can also add information as required, e.g. device location and digital twin data.
  • The containers to send and receive messages.

To integrate your applications, you need to create an own AE resource in CSEBase with the WebHook endpoint URL configured as poa (point of access). Your own AE resource represent your client application that you want to integate with Device to Cloud.

When you create device groups (aka flex containers under the device-group AE), the AE subscriptions are automatically created when you add your application(s) and devices to the group. This subscription will route device traffic to your application.

Using the REST API

Here you learn to understand the REST requests we use in our step-by-step tutorial.

You can request resources by simply addressing them via the resourceId or resourceName, e.g.

GET {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/sensor001

GET {{API_URL}}/device-management-orchestrator/v3/~/{{TENANT}}/678f6fb89d2884f06af2a293

To list all nodes (aka devices) you need to specify the type get-parameter ty=14, e.g.:

GET {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}?ty=14

To list all resources, add the rcn (= result content) URL parameter:

  • rcn=4 to retrieve all nodes and their management objects (full resources)
  • rcn=6 to retrieve the ids (and only the ids) of all resources directly under the specified path
  • rcn=8 to retrieve all details of all resources in the subtree under the specified path
  • rcn=9 (in update calls only) to return a resource representation of the assigned and modified attributes only

For example:

You can retrieve all details of all resources in the subtree under the specified path.

GET {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}?rcn=8

You can also request all resources with type of node ty=14 (reperesents your device), filter by a lbl and retrieve the ids (and only the ids) of all resources directly under the specified path rcn=6. All parameters that you specify in the path are filter conditions concatinated with “AND”.

GET {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}?ty=14&lbl=ICCID:123456789012345&rcn=6

You can also request all resources by a node id ni. Example:

GET {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}?ty=14&ni=urn:gsma:imei:90420156-025763-0&rcn=8

To create devices, the type must be specified in the the Content-Type HTTP header.

Example request to create an AE (ty=2):

POST {{API_URL}}/device-management-orchestrator/v3/{{TENANT}} HTTP/2
Accept: application/json
Content-Type: application/json;ty=2
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
    "m2m:ae": {
        "api": "NMyApp",
        "rn": "MyApp",
        "poa": [ "https://my-awesome-app.com/iot-data-webhook" ]
	}
}
  • X-M2M-Origin: The Application ID you create during client application registration is the ID you must use in all subsequent requests to the API. Select an Origin that starts with character C e.h. CTestApp.
  • X-M2M-RI: Represents a unique request ID. It is highly recommended to generate a UUID per request. Please don’t use 123!! If you have a support request you can help us by providing us the related request ID.

For a full specification on resource addressing, resource operations and request/response patterns, please consult the oneM2M API specification.