APIs Device to Cloud Send and receive IoT data

The ability to send and receive data from an IoT device always depends on the protocol supported by your device. In this chapter, we will assume that you have an IoT device that supports LwM2M.

Before you continue, please consult the operating instructions/ user manual of your LwM2M-device.

Please get familiar with:

• Which LwM2M-Objects does your LwM2M-Device support?
• Which LwM2M-Resources are could you READ, which LwM2M-Resources could you WRITE?
• What’s the main use-case of the device?
  • Do you have a battery powered device? What’s the battery lifetime of your device? What’s your expected battery life time? What does your hardware vendor recommend?
  • What’s triggering your main use-case? Do you need some values only in a special case? Do you need the data of your main-use case in some fixed time intervall or if something happens on the device (condition)?

We suggest to execute a READ on all Objects that you find in the operating instructions/ user manual of your device.

Overview Copied!

LwM2M assumes that the device communication is triggered by the customer (except LwM2M SEND not supported yet).

LwM2M specification describes following interfaces:

• Device Management Interface
• Reporting Interface

The device is the single point of truth for an LwM2M object.

To find out the value of an object or resource, send an LwM2M READ request to your LwM2M client. (Device Management Interface capability). To be informed when an object or resource has changed on your device, send an LwM2M OBSERVE to your LwM2M client. (Reporting Interface). Your LwM2M client will notify you if any changes are made to your object or resource. Please refer to the operating instructions/user manual of your LwM2M device to find out which objects or resources are supported.

This chapter describes:

• which LwM2M operations are supported
• how to send a message to an IoT device
• how to check that a message was sent successfully to your device

LwM2M operation mappings Copied!

To interact with LwM2M devices, the content (con) of the outgoing-msg is similar to LwM2M protocol:

READ /<obj>/<inst>/<res> 

WRITE /<obj>/<inst>/<res>
<type>: <value>

EXECUTE /<obj>/<inst>/<res>

EXECUTE /<obj>/<inst>/<res>?
<type>: <value>

OBSERVE /<obj>/<inst>/<res>

OBSERVE /<obj>/<inst>/<res> 
<type>=<value>&<type>=<value>

UNOBSERVE /<obj>/<inst>/<res>

A customer is allowed to make only 1 OBSERVE to one resource, even if the second OBSERVE is supposed to have parameters and the first one is without.
The parameters are could be used for OBSERVE/UNOBSERVE:

• pmin: minimum period, indicates the minimum time in seconds the LwM2M Client MUST wait between two notifications
• pmax: maximum period, indicates the maximum time in seconds the LwM2M Client MAY wait between two notifications
• gt: greater than, defines a threshold high value
• lt: less than, defines a threshold low value
• steps: steps, defines a threshold low value. When this Attribute is present, the LwM2M Client MUST notify the Server each time the Observed Resource value crosses this threshold with respect to pmin parameter

Send message to IoT device Copied!

Messages sent to the outgoing-msg container will be forwarded to the device. The con field contains the information sent to the device.

We are supporting 2 types of content format mode - Protocol specific mode and REST Api mode. User can send single command and multiple command as well.

These are the method supported - READ or RD, WRITE or WR, EXECUTE or EXE, OBSERVE or OBS, UNOBSERVE or UOBS (Supported in other 2 modes)

Below are the example of each mode.

Protocol specific mode (Single command): Copied!

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

{
    "m2m:cin": {
        "con": "READ /6"
    }
}

Protocol specific mode (Multiple command): Copied!

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

{
    "m2m:cin": {
        "con": "READ /6; RD /3/0/0"
    }
}

REST API mode (Single command): Copied!

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

{
  "m2m:cin": {
    "con": {
      "method": "GET",
      "path": "/3442/0/160"
    },
    "cnf": "application/json:0"
  }
}

REST API mode (Multiple command): Copied!

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

{
    "m2m:cin": {
        "con": [
            {
                "method": "read",
                "path": "/6"
            },
            {
                "method": "READ",
                "path": "/3/0/0"
            }
        ],
        "cnf": "application/json:0"
    }
},

Flow / Process is described below Copied!

This example requests LwM2M-Object 3 (Device):

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

{
  "m2m:cin": {
    "con": "READ /3"
  }
}

{
  "contentInstance": {
    "content": "READ /3",
    "resourceType": 4,
    "contentSize": 7,
    "stateTag": 10,
    "creator": "CTestApp",
    "resourceName": "f4587503-9545-4430-adb4-3055076633de",
    "resourceID": "6879032d3c8c87cdb4009999",
    "parentID": "68767201272211da007e5999",
    "creationTime": "20250717T140533,829000",
    "lastModifiedTime": "20250717T140533,829000"
  }
}

After processing the request, the message is transferred to the /device-communication/<deviceID>/sent-msg container.

You can read the last message (/la) sent to device using:

GET {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/device-communication/<deviceID>/sent-msg/la
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
  "contentInstance": {
    "content": "READ /3",
    "resourceType": 4,
    "contentSize": 7,
    "stateTag": 7,
    "creator": "CTestApp",
    "resourceName": "efd62c6f-050f-436f-aef4-55499ec4d01d",
    "resourceID": "6879032e50fa7af1af3e4999",
    "parentID": "68767201272211da007e5999",
    "creationTime": "20250717T140534,016000",
    "lastModifiedTime": "20250717T140534,016000"
  }
}

Get last received device messages via API Copied!

The following query gets the last message sent to the received msg container:

GET {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/device-communication/<deviceID>/received-msg/la
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
  "contentInstance": {
    "content": {
      "nodeResourceName": "device001",
      "time": 1752761134124,
      "messageType": "response",
      "path": "3",
      "method": "read",
      "status": {
        "code": 406,
        "message": "not acceptable",
        "detail": "Command was successfully send to the device. Device rejects command, not acceptable."
      },
      "data": {
        "3/0/0": "My Demo Device",
        "3/0/1": "Model 500",
        "3/0/2": "LT-500-000-0001",
        "3/0/3": "1.0.0",
        "3/0/9": 72,
        "3/0/10": 75108,
        "3/0/11/0":0,
        "3/0/13": 1752761133000,
        "3/0/14": "+02",
        "3/0/15": "Europe/Berlin",
        "3/0/16": "U",
        "3/0/17": "Demo",
        "3/0/18": "1.0.1",
        "3/0/19": "1.0.2",
        "3/0/20": 3,
        "3/0/21": 129024
      }
    },
    "contentInfo": "application/json:0",
    "resourceType": 4,
    "contentSize": 464,
    "stateTag": 12,
    "creator": "CDevice-Provisioning",
    "resourceName": "aabefd77-2166-4710-8e22-cce1c8d76312",
    "resourceID": "6879032f50fa7af1af3e4999",
    "parentID": "68767201272211da007e5999",
    "creationTime": "20250717T140535,167000",
    "lastModifiedTime": "20250717T140535,167000"
  }
}

Device to Cloud supports following received messages:

• Protocol specific status messages:
  • LwM2M-Device connect: LwM2M-REGISTER
  • LwM2M-Device updates LwM2M-Session: LwM2M-UPDATE
  • LwM2M-Device disconnect: LwM2M-DEREGISTER
  • LwM2M-Session expires

GET {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/device-communication/<deviceID>/received-msg/la
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

• Protocol specific messages with a response code:
  • LwM2M-Device responds to a LwM2M-EXECUTE request
  • LwM2M-Device responds to a LwM2M-WRITE request
• Protocol specific messages with a response code and usage data:
  • LwM2M-Device responds to a LwM2M-READ request
  • LwM2M-Device reports a new value, started with a LwM2M-OBSERVE request

{
  "contentInstance": {
    "content": {
      "nodeResourceName": "device001",
      "time": 1752761134124,
      "messageType": "registration"
    },
    "contentInfo": "application/json:0",
    "resourceType": 4,
    "contentSize": 98,
    "stateTag": 679,
    "creator": "CDevice-Provisioning",
    "resourceName": "aabefd77-2166-4710-8e22-cce1c8d76312",
    "resourceID": "6879032f50fa7af1af3e4999",
    "parentID": "68767201272211da007e5999",
    "creationTime": "20250717T140535,167000",
    "lastModifiedTime": "20250717T140535,167000"
  }
}

{
  "contentInstance": {
    "content": {
      "nodeResourceName": "device001",
      "time": 1752761134124,
      "messageType": "update"
    },
    "contentInfo": "application/json:0",
    "resourceType": 4,
    "contentSize": 98,
    "stateTag": 492,
    "creator": "CDevice-Provisioning",
    "resourceName": "aabefd77-2166-4710-8e22-cce1c8d76312",
    "resourceID": "6879032f50fa7af1af3e4999",
    "parentID": "68767201272211da007e5999",
    "creationTime": "20250717T140535,167000",
    "lastModifiedTime": "20250717T140535,167000"
  }
}

{
  "contentInstance": {
    "content": {
      "nodeResourceName": "device001",
      "time": 1752761134124,
      "messageType": "registration-expire"
    },
    "contentInfo": "application/json:0",
    "resourceType": 4,
    "contentSize": 98,
    "stateTag": 679,
    "creator": "CDevice-Provisioning",
    "resourceName": "aabefd77-2166-4710-8e22-cce1c8d76312",
    "resourceID": "6879032f50fa7af1af3e4999",
    "parentID": "68767201272211da007e5999",
    "creationTime": "20250717T140535,167000",
    "lastModifiedTime": "20250717T140535,167000"
  }
}

{
  "contentInstance": {
    "content": {
      "nodeResourceName": "device001",
      "time": 1760369534197,
      "messageType": "deregistration"
    },
    "contentInfo": "application/json:0",
    "resourceType": 4,
    "contentSize": 103,
    "stateTag": 2,
    "creator": "CNI-IPE",
    "resourceName": "885a4a3d-8d6a-42b5-8494-2f4e9244e9f4",
    "resourceID": "68ed1b7f2f1e20a332acfbd3",
    "parentID": "68ed1a932f1e20a332acfbad",
    "creationTime": "20251013T153215,279000",
    "lastModifiedTime": "20251013T153215,279000"
  }
}

{
  "contentInstance": {
    "content": {
      "nodeResourceName": "device001",
      "time": 1760366796844,
      "messageType": "response",
      "method": "exec",
      "status": {
        "code": 200,
        "message": "success",
        "detail": null
      },
      "resourcePath": "3442/0/2",
      "data": null
    },
    "labels": [
      "Room:room123",
      "Floor:2"
    ],
    "contentInfo": "application/json:0",
    "resourceType": 4,
    "contentSize": 204,
    "stateTag": 46244,
    "creator": "CNI-IPE",
    "resourceName": "6433d02a-ac4b-4659-a643-8be8fd793ba7",
    "resourceID": "68ed10cd2f1e20a332acfa97",
    "parentID": "689dd12bb41e8b5c4d36ac02",
    "creationTime": "20251013T144637,898000",
    "lastModifiedTime": "20251013T144637,898000"
  }
}

{
  "contentInstance": {
    "content": {
      "nodeResourceName": "device001",
      "time": 1760365370037,
      "messageType": "response",
      "method": "write",
      "status": {
        "code": 200,
        "message": "success",
        "detail": null
      },
      "resourcePath": "3442/0/110",
      "data": null
    },
    "labels": [
      "Room:room123",
      "Floor:2"
    ],
    "contentInfo": "application/json:0",
    "resourceType": 4,
    "contentSize": 207,
    "stateTag": 46215,
    "creator": "CNI-IPE",
    "resourceName": "2c043b96-50e0-47c1-aba7-e68118537770",
    "resourceID": "68ed0b3bdb835ff84403f541",
    "parentID": "689dd12bb41e8b5c4d36ac02",
    "creationTime": "20251013T142251,114000",
    "lastModifiedTime": "20251013T142251,114000"
  }
}

{
  "contentInstance": {
    "content": {
      "nodeResourceName": "device001",
      "time": 1760365796442,
      "messageType": "response",
      "method": "read",
      "status": {
        "code": 200,
        "message": "success",
        "detail": null
      },
      "resourcePath": "6",
      "data": {
        "6/0/0": -20,
        "6/0/1": -40,
        "6/0/5": 1760110380000
      }
    },
    "labels": [
      "Room:room123",
      "Floor:2"
    ],
    "contentInfo": "application/json:0",
    "resourceType": 4,
    "contentSize": 240,
    "stateTag": 46224,
    "creator": "CNI-IPE",
    "resourceName": "dff66e4f-ea1f-491d-90e1-afe54427d678",
    "resourceID": "68ed0ce5db835ff84403f57b",
    "parentID": "689dd12bb41e8b5c4d36ac02",
    "creationTime": "20251013T142957,540000",
    "lastModifiedTime": "20251013T142957,540000"
  }
}

{
      "contentInstance": {
        "content": {
          "nodeResourceName": "device001",
          "time": 1755871998246,
          "messageType": "notify",
          "resourcePath": "/3303/0/5602",
          "dataValue": 25.5,
          "attributes": {}
        },
        "contentInfo": "application/json:0",
        "resourceType": 4,
        "contentSize": 155,
        "stateTag": 18,
        "creator": "CDevice-Provisioning",
        "resourceName": "9ba8fc8d-d3c8-4a74-8643-2bf3cf3eaa6d",
        "resourceID": "68a87affb41e8b5c4d371c07",
        "parentID": "689dd12bb41e8b5c4d36ac02",
        "creationTime": "20250822T141319,281000",
        "lastModifiedTime": "20250822T141319,281000"
      }
}

Message types Copied!

Following methods, messageTypes are defined for LwM2M

Received message error table Copied!

*) Please check user manual of your device or contact hardware manufacturer for further assistance.

Traceability of messages Copied!

The main idea of messages traceability is to give the ability to track the relationship between messages: which sent-msg was sent and which received-msg was received as a result of the outgoing-msg being created.
For this purpose 2 labels are used:

• “requestId:<requestId>” - ID of the Operation
• “outgoing-msgRN:” - Resource Name of the outgoing message

All messages in one message-chain have the same pair of labels.

In case of Responses the message-chain has 3 messages: outgoing-msg (deleted after sending), sent-msg and received-msg
In case of Reports (OBSERVE operation) the message chain has 1 outgoing-msg (deleted after sending), 1 sent-msg and any number of received-ms, but the labels are the same for all messages in the chain.

Example of outgoing message

{
  "contentInstance": {
    "content": {
      "method": "READ",
      "path": "/3442/0/160"
    },
    "contentInfo": "application/json:0",
    "resourceType": 4,
    "contentSize": 36,
    "stateTag": 51,
    "creator": "CDevice-Provisioning",
    "resourceName": "9395fa27-aa51-4507-a1ba-dacb8dc19d87",
    "resourceID": "68f6541daa507dce1aaf212d",
    "parentID": "68d17c07e95403e717f85b97",
    "creationTime": "20251020T152413,162000",
    "lastModifiedTime": "20251020T152413,162000"
  }
}

Example of corresponding sent message

{
  "contentInstance": {
    "content": {
      "method": "READ",
      "path": "/3442/0/160"
    },
    "labels": [
      "outgoing_msgRN:9395fa27-aa51-4507-a1ba-dacb8dc19d87",
      "requestId:7ccd7dfe-95a1-4c14-8afb-d0814bbbf5c1"
    ],
    "contentInfo": "application/json:0",
    "resourceType": 4,
    "contentSize": 35,
    "stateTag": 49,
    "creator": "CNI-IPE",
    "resourceName": "fda6a1b4-db83-4611-8a53-44a82d60fb1e",
    "resourceID": "68f6542a681d63b473637265",
    "parentID": "68d17c07e95403e717f85b99",
    "creationTime": "20251020T152426,504000",
    "lastModifiedTime": "20251020T152426,504000"
  }
}

Example of corresponding received message

{
  "content": {
    "nodeResourceName": "d2c-lwm2m-java-client-tst002",
    "time": 1760973853388,
    "messageType": "response",
    "method": "read",
    "status": {
      "code": 200,
      "message": "success",
      "detail": null
    },
    "resourcePath": "3442/0/160",
    "data": {
      "3442/0/160": 946684800
    }
  },
  "labels": [
    "outgoing_msgRN:9395fa27-aa51-4507-a1ba-dacb8dc19d87",
    "requestId:7ccd7dfe-95a1-4c14-8afb-d0814bbbf5c1"
  ],
  "contentInfo": "application/json:0",
  "resourceType": 4,
  "contentSize": 229,
  "stateTag": 54940,
  "creator": "CNI-IPE",
  "resourceName": "60a08f83-71dd-4eb2-986f-7f096c25d422",
  "resourceID": "68f65421aa507dce1aaf2131",
  "parentID": "68d17c07e95403e717f85b9b",
  "creationTime": "20251020T152417,136000",
  "lastModifiedTime": "20251020T152417,136000"
}

LwM2M resource mappings Copied!

Device to Cloud automatically reads LwM2M Objects 3 and 6 (LwM2M-READ) when an LwM2M-Device connects with an LwM2M-Register.

• Object 3 (Device) (xml definition , LwM2M Editor )
• Object 6 (Location) (xml definition , LwM2M Editor )

Device to Cloud reads the following LwM2M resources when a LwM2M Client makes a LwM2M Register request.

All resources in the table below are stored in oneM2M data model in an oneM2M device info management object. The management object “device-info” is as well updated, if a customer requests the information with a READ or OBSERVE.

(1) Reliability of Information depends on Device Firmware, see also Object 5 “Firmware Update” , Object 9 Software Management , and chapter “E.6 LwM2M Object: Firmware Update” in LwM2M Specification .

(2) format: geo:<latitude>,<longitude> (see RFC5870 )

To get this data from a node, use a http request like this:

GET {{API_URL}}/device-management-orchestrator/v3/{{tenant_name}}/device001?ty=13&rcn=8 HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CAdmin
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
  "node": {
    "credentials": [
      {
        "description": "cred",
        "mgmtDefinition": 1029,
        "resourceName": "credentials",
        "resourceType": 13,
        "resourceID": "680b85bb8482fd7b93dc2999",
        "parentID": "680b85bb8482fd7b93dc2999",
        "creationTime": "20250425T125315,719000",
        "lastModifiedTime": "20250425T125315,719000",
        "credentialID": "test@test.com",
        "credentialSecret": "test123"
      }
    ],
    "deviceInfo": [
      {
        "resourceName": "device-info",
        "mgmtDefinition": 1007,
        "deviceLabel": "device001",
        "resourceType": 13,
        "resourceID": "680b85bb8482fd7b93dc2999",
        "parentID": "680b85bb8482fd7b93dc2999",
        "creationTime": "20250425T125315,860000",
        "lastModifiedTime": "20250428T090849,562000",
        "deviceName": "My Demo Device",
        "fwVersion": "1.0.0",
        "systemTime": "1752761133000"
      }
    ]
  }
}

Parameters:

• ty=13 to receive the oneM2M management object of the node
• rcn=8 to retrieve all details of all resources directly under the specified path

LwM2M defines following interfaces in the LwM2M Client Registration Interface (see chapter 6.2. Client Registration Interface on page 38):

• LwM2M-Register
• LwM2M-Update
• LwM2M-De-Register

When a device makes an LwM2M-Register, LwM2M-Update or LwM2M-De-Register, Device to Cloud stores the server time in a oneM2M label in oneM2M device node. In addition to that, Device to Cloud stores the server time, when an LwM2M Client exceeds the LwM2M Lifetime as expiration timestamp.

To see these labels call:

GET  {{API_URL}}/device-management-orchestrator/v3/{{tenant_name}}/device001 HTTP/2
Accept: application/json
Content-Type: application/json
fullName: {{fullname}}
X-M2M-Origin: CDevice-Provisioning
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
  "node": {
    "nodeID": "urn:gsma:imei:3519345467882060",
    "labels": [
      "d2c-uplink-property_Address:Kuckhoff street",
      "d2c-uplink-property_Room:2035",
      "profile:SCS-lwM2M",
      "ICCID:89882280000004492060",
      "updates_timestamp: 1738537906296",
      "registrations_timestamp: 1733389745807"
    ],
    "resourceName": "device001",
    "resourceType": 14,
    "resourceID": "680b85bb8482fd7b93dc2999",
    "parentID": "d2c-dev-1",
    "creationTime": "20250425T125315,410000",
    "lastModifiedTime": "20250428T084509,703000"
  }
}

Next: Forward messages to applications Copied!

In the next step, you learn how to integrate your application and use device groups to configure the data routing to your application endpoint.