Introduction

LwM2M Action API allows to trigger read, write, observe-start, observe-end and execute operations on LwM2M devices. When action API is being called, then the LwM2M server tries to trigger the particular operation on the device:

• If the device is available (the device is currently registered on a LwM2M server) and the operation is valid, then a particular operation will be triggered on the device.
• If the device is available but the operation is not valid, then an incident will be created under the incidents tab. Not valid operation examples:
  • Object, object instance, resource, or resource instance does not exist on the device.
  • Unsupported action is being requested on a particular object, object instance, resource, or resource instance. E.g. trigger write operation on a read-only resource.
• If the device is not available then action API will return 409 (Conflict) status code with an error.

{
   "statusCode":409,
   "statusText":"Conflict",
   "errors":[
      {
         "message":"Device with ID abcdefghijABCDEFGHIJK and customer ID 1234567890 is not registered to any LwM2M server"
      }
   ]
}

The Objects and Resources page explains how LwM2M standard defines information sources called resources. To recap the naming convention an example is added below:
/3441/1/1110/0
<Object id>/<Object Instance id>/<Resource id>/<Resource Instance id>

Action Types

Read

Read Operation allows reading values from:

• Object Level
• Object Instance Level
• Resource Level
• Resource Instance Level

Trigger read operation from /6/0/1 resource:

curl --request POST \
     --url https://api.1nce.com/management-api/v1/devices/abcdefghijABCDEFGHIJK/actions \
     --header 'Content-Type: application/json' \
     --data '
{
     "action": "read",
     "resourceAddress": "/6/0/1"
}
'

Trigger read operation from all /6 object resources:

curl --request POST \
     --url https://api.1nce.com/management-api/v1/devices/abcdefghijABCDEFGHIJK/actions \
     --header 'Content-Type: application/json' \
     --data '
{
     "action": "read",
     "resourceAddress": "/6"
}
'

Write

Currently, write operation is only supported on the resource level.
All write operations should contain data as a string. Although different LwM2M resources have different data types - all writable data should be provided as a string value.

• String "abcASAD+$-_^("
• Integer "50"
• Float "55.55"
• Bool "true"
• Opaque "RXhhbXBsZSBtZXNzYWdlIDEyMw=="
• Time "2022-04-25T13:47:53.022Z"
• Object Link "/6/0"

Trigger write operation on /3441/0/110 resource:

curl --request POST \
     --url https://api.1nce.com/management-api/v1/devices/abcdefghijABCDEFGHIJK/actions \
     --header 'Content-Type: application/json' \
     --data '
{
     "action": "write",
     "resourceAddress": "/3441/0/110",
     "data": "abcASAD+$-_^("
}
'

Observe

Observe-Start

It is possible to start observation by triggering observe-start operation on:

• Object Level
• Object Instance Level
• Resource Level

If an observation is started on a specific resource /6/0/1, then data will be sent to the server whenever the value on this resource will be changed.

curl --request POST \
     --url https://api.1nce.com/management-api/v1/devices/abcdefghijABCDEFGHIJK/actions \
     --header 'Content-Type: application/json' \
     --data '
{
     "action": "observe-start",
     "resourceAddress": "/6/0/1"
}
'

{
  "/6/0/1": -3
}

If an observation is started on a specific object /6, then all the object data will be sent to the server whenever a value on a resource on this object will be changed.

curl --request POST \
     --url https://api.1nce.com/management-api/v1/devices/abcdefghijABCDEFGHIJK/actions \
     --header 'Content-Type: application/json' \
     --data '
{
     "action": "observe-start",
     "resourceAddress": "/6"
}
'

{
  "/6/0/1": -3,
  "/6/0/0": 4,
  "/6/0/5": 1652098161000
}

Observe-End

To end an observation observe-end operation should be triggered:

curl --request POST \
     --url https://api.1nce.com/management-api/v1/devices/abcdefghijABCDEFGHIJK/actions \
     --header 'Content-Type: application/json' \
     --data '
{
     "action": "observe-end",
     "resourceAddress": "/6"
}
'

Execute

Execute operation is used to perform some non-idempotent operation such as a reboot or a firmware upgrade.
Trigger execute operation on /3/0/4 resource (reboot device):

curl --request POST \
     --url https://api.1nce.com/management-api/v1/devices/abcdefghijABCDEFGHIJK/actions \
     --header 'Content-Type: application/json' \
     --data '
{
     "action": "execute",
     "resourceAddress": "/3/0/4"
}
'