APIs Device to Cloud Onboard devices

Device provisioning request

Devices are represented as node instances in oneM2M. You can request to onboard a list of nodes by adding a “/device-provisioning/request”:

  • Request
  • Response
POST {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/device-provisioning/request HTTP/2
Accept: application/json
Content-Type: application/json;ty=28
X-M2M-Origin: CTestApp
fullName: true
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
    "dtiot:noPRt": {
        "cnd": "com.telekom.iot.orchestrator.nodeProvisioningRequest",
        "rn": "myProvisioningRequest01",
        "operation": 1,
        "requestList": [
            {
                "nodeID" : "urn:gsma:imei:3519...88011",
                "nodeResourceName" : "sensor001",
                "ICCID" : "898...20111",
                "profile" : "SCS-LwM2M",
                "labels": [
                  "d2c:1.0"
                ],
                "nodeCredentials": [
                  "psk-id:testId",
                  "psk:dGVzdDEyMw=="
                ],
                "ndvi": {
                    "rn": "device-info",
                    "mgd": 1007,
                    "man": "ACME",
                    "dty": "Some sensor",
                    "mod": "12345",
                    "dlb": ["d2c:1.0","some:label"],
                    "dc": "measured something"
                  }
            }
        ]
    }
}

HTTP/1.1 201 Created
Date: Thu, 21 Nov 2024 09:17:48 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 533
Connection: close
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "dtiot:noPRt": {
    "cnd": "com.telekom.iot.orchestrator.nodeProvisioningRequest",
    "rn": "myProvisioningRequest01",
    "opern": 1,
    "reqLt": [
      {
        "ni": "urn:gsma:imei:3519...88011",
        "noRNe": "sensor001",
        "ICCID": "898...20111",
        "profe": "SCS-LwM2M",
        "labels": [
          "d2c:1.0"
        ],
        "nodeDeviceInfo": {
          "resourceName": "device-info",
          "mgmtDefinition": 1007,
          "manufacturer": "ACME",
          "deviceType": "Some sensor",
          "model": "12345",
          "deviceLabel": ["d2c:1.0","some:label"],
          "description": "measured something" 
        },
        "nodeCredentials": [
          "psk-id:testId",
          "psk:dGVzdDEyMw=="
        ]
      }
    ],
    "ty": 28,
    "cr": "CD2C-Customer-App",
    "st": 0,
    "ri": "67...2a",
    "pi": "671...3f",
    "ct": "20241121T091747,984000",
    "lt": "20241121T091747,984000"
  }
}

Parameters:

  • In Content-Type header: ty=28 means “flexContainer”
  • cnd - containerDefinition
    • Contains an identifier reference (URI) to the “flexContainer” schema definition which shall be used by the CSE to validate the syntax of the FlexContainer resource
  • operation: 1=provision
  • requestList: Array of “node” instances with
    • nodeID: The value shall be a valid nodeID string in one of the following formats: urn:gsma:imei:<imei> or urn:x-dtiot:dev:sn:<string with the serial number from device>
    • nodeResourceName: This is the “Device ID” which e.g. is used in Device Groups to identify the device.
    • ICCID (optional): ICCID of the SIM Card that will be used by the device.
    • profile: Defines the IoT platform where the device is onboarded: Here: “SCS-LwM2M”.
    • labels: An array of strings. The label "d2c:1.0" is mandatory for “Device to Cloud” IoT devices. Example: ["color:red","manufacturer:ACME","d2c:1.0"]
    • nodeCredentials (optional): An array of strings, e.g. ["psk-id:xyz","psk:secret-as-base64"]. The psk-id must be unique (e.g. UUID) and please never reuse a psk-secret between devices.
    • nodeDeviceInfo (optional): device-related information
  • X-M2M-RI: Represents a unique request ID. Please don’t use 123!! If you have a support request you can help us by providing us the related request ID.

Device provisioning response

The system will process your device provisioning request and the result is available in the “/device-provisioning/response”:

  • Request
  • Response
GET {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/device-provisioning/response/{{resourceName}} HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
Date: Thu, 05 Dec 2024 09:19:49 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 653
Connection: close
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "dtiot:prRRe": {
    "containerDefinition": "com.telekom.iot.orchestrator.provisioningRequestResponse",
    "resourceName": "responseToRequest-67...56",
    "requestResourceID": "67...56",
    "responseStatus": 2,
    "generalErrorMessage": "Total to be provisioned: 1; Successfully processed: 0; Errors: 1",
    "individualErrorMessages": [
      {
        "nodeID": "ur...116",
        "errorMessage": "device profile not supported"
      }
    ],
    "resourceType": 28,
    "creator": "CD2C-Customer-App",
    "stateTag": 0,
    "resourceID": "67...ba7",
    "parentID": "67...f32",
    "creationTime": "20241205T074006,516000",
    "lastModifiedTime": "20241205T074006,516000"
  }
}

Parameter:

  • resourceName: the prefix “responseToRequest-” must be used alongside with resource id of the device-provisioing request (for example, “responseToRequest-67…56”)

Check the device node

Each time your LwM2M device makes an LwM2M register request to Device to Cloud, D2C requests LwM2M objects 3 (Device) and 6 (Location) from your LwM2M device.

D2C then stores some values from objects 3 and 6 in a device info resource with the name device-info in your device node, e.g:

  • manufacturer
  • device model
  • hardware version
  • firmware version
  • GPS location

You can retrieve this device-info :

  • Request
  • Response
GET  {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/sensor001?ty=14&rcn=4 HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
Date: Thu, 05 Dec 2024 07:57:10 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1462
Connection: close
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "node": {
    "nodeID": "urn:g...18",
    "labels": [
      "0:profile:SCS-LwM2M",
      "1:ICCID:898...118"
    ],
    "resourceName": "sensor001",
    "resourceType": 14,
    "resourceID": "67...6d",
    "parentID": "eos",
    "creationTime": "20241204T085316,145000",
    "lastModifiedTime": "20241204T085316,145000",
    "deviceInfo": [
      {
        "location": "geo:-49.0,109.0",
        "deviceLabel": "",
        "model": "Model 500",
        "deviceName": "",
        "manufacturerDetailsLink": "",
        "subModel": "",
        "fwVersion": "1.0.0",
        "swVersion": "1.0.2",
        "osVersion": "",
        "systemTime": "f�9",
        "supportURL": "",
        "presentationURL": "",
        "protocol": [
          "LWM2M"
        ],
        "manufacturer": "Leshan Demo Device",
        "hwVersion": "1.0.1",
        "country": "",
        "deviceType": "Demo",
        "mgmtDefinition": 1007,
        "resourceType": 13,
        "resourceName": "device-info",
        "resourceID": "67...71",
        "parentID": "67...6d",
        "creationTime": "20241204T085316,367000",
        "lastModifiedTime": "20241204T085316,367000"
      }
    ]
  }
}

Modify the device node

You can update the device-info of the device by providing device resource name in path, e.g. the latitude and longitude of the geographic location:

  • Request
  • Response
PUT {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/sensor001/device-info HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
  "m2m:dvi": {
          "loc": "geo:48.861045,2.335765"
        }
}

HTTP/1.1 200 OK
Date: Thu, 21 Nov 2024 09:07:04 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 445
Connection: close
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "m2m:dvi": {
    "loc": "geo:48.861045,2.335765",
    "mod": "Sensor",
    "man": "ACME",
    "dlb": "|label:value anotherLabel:value",
    "mgd": 1007,
    "ty": "SIM",
    "ty": 13,
    "rn": "9cbe6936-e619-4e70-89f3-6f2ddce0fca8",
    "ri": "673e...2b",
    "pi": "673e...29",
    "ct": "20241121T090606,785000",
    "lt": "20241121T090704,392000",
    "typeShortName": null
  }
}

Parameters:

  • loc: geographic location

Working with device properties

Use the ‘Device Properties’ option to add additional information to a device and for filtering.

There are two types of device properties:

  1. general properties
  2. uplink properties

General properties are key/value pairs where you can add additional data to your device, e.g.

  • asset id
  • building address, floor, room number
  • additional type info
  • last battery change date

Uplink properties are key/value pairs which are added to each device message. This simplifies the integration into your systems, since you can avoid complex lookups when processing the data. Uplink properties are identified by key names starting with prefix “UplinkProperty_”.

Example request to add device properties as labels in lbl:

  • Request
  • Response
PUT {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/sensor001 HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
  "m2m:nod": {
    "lbl": [
      "Location:13509 Berlin, Holzhauser Str 4-8, Building A",
      "LastMaintanance:12.03.2024 12:34",
      "UplinkProperty_AssetId:1234546",
      "UplinkProperty_BuildingId:BER-76545",
      "UplinkProperty_Status:PendingInstallation",
      "d2c:1.0",
      "profile:SCS-LwM2M"
    ]
  }
}

HTTP/1.1 200 OK
Date: Wed, 26 Feb 2025 18:37:54 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 384
Connection: keep-alive
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "node": {
    "nodeID": "urn:gsma:imei:351934546755710",
    "labels": [
      "Location:13509 Berlin, Holzhauser Str 4-8, Building A",
      "LastMaintanance:12.03.2024 12:34",
      "UplinkProperty_AssetId:1234546",
      "UplinkProperty_BuildingId:BER-76545",
      "UplinkProperty_Status:PendingInstallation",
      "d2c:1.0",
      "profile:SCS-LwM2M"
    ],
    "resourceName": "sensor001",
    "resourceType": 14,
    "resourceID": "67bd837591fd7e5aef539891",
    "parentID": "d2c-dev-1",
    "creationTime": "20250225T084645,956000",
    "lastModifiedTime": "20250226T183754,087000",
    "typeShortName": null
  }
}

Important: The label "d2c:1.0" and "profile:SCS-LwM2M" are mandatory for “Device to Cloud” LwM2M devices in DMO. Please ensure that it is always retained in update operations.

Delete the device node

A device can be deleted by deleting its node . The system will clean up all related objects (sent/received messages, groups, …).

  • Request
  • Response
DELETE {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/sensor001 HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
Date: Thu, 21 Nov 2024 09:44:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 0
Connection: close
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

Next step

Start sending commands to your LwM2M device and receive data back from the device.