The Device Controller can be accessed via an API to allow customers to send data to the devices in an automated way without going through the portal.
The Device Controller API description is available in the API Explorer.

Examples

Create Action Request

An action request can include different fields per protocol. Therefore, an example request body is given for every protocol.

UDP

Creating UDP action request for a device with deviceId 123456789012345678:

curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/UDP"

The request body looks like this:

{
  "payload": "Data to send to the device",
  "payloadType": "STRING",
  "port": 3000,
  "requestMode": "SEND_NOW"
}

CoAP

Creating CoAP action request for a device with deviceId 123456789012345678:

curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/COAP"

The request body looks like this:

{
  "payload": "Data to send to the device",
  "payloadType": "STRING",
  "port": 3000,
  "path": "/example?param1=query_param_example",
  "requestType": "POST",
  "requestMode": "SEND_NOW"
}

LwM2M

Creating LwM2M action request for a device with deviceId 123456789012345678:

curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/LWM2M"

The request body looks like this:

{
  "action": "write",
  "resourceAddress": "/3311/0/5850",
  "data": "Data to send to the device",
  "requestMode": "SEND_WHEN_ACTIVE"
}

Bulk request

Creating LwM2M action request for multiple devices:

curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/actions/LWM2M"

The request body looks like this:

{
  "action": "write",
  "resourceAddress": "/3311/0/5850",
  "data": "Data to send to the device",
  "requestMode": "SEND_WHEN_ACTIVE",
  "deviceIds": ["123456789012345678", "123456789012345679", "123456789012345680"]
}

Retry Mechanism

When submitting an action request with SEND_WHEN_ACTIVE mode, the user can specify the parameter sendAttempts in
the request body to restrict how many times the device controller can attempt to send the data to the device.

If all attempts fail, then the action request will be permanently marked with the status FAILED.

The sendAttempts parameter is optional and, if unspecified, defaults to 1.

The maximum number of allowed retries is 5.

⚠️ Please note that this functionality is NOT supported by the UDP protocol.

Request Body Properties

These are the properties of a request body. It specifies when and which message will be sent to the device.

Property	Data Type	Description	Available for protocol. *Optional
payload	STRING	Data to send to the device.	UDP, *CoAP
payloadType	ENUM	Type of the payload. Values: `STRING`, `BASE64`.	UDP, *CoAP
port	INTEGER	Communication port number of a device.	UDP, CoAP
requestMode	ENUM	Values: `SEND_NOW`, `SEND_WHEN_ACTIVE` (when a device sends a message). Default: `SEND_NOW`.	UDP, CoAP, *LwM2M
path	STRING	Absolute path to the resource.	CoAP
requestType	ENUM	Method used to send message. Values: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`.	CoAP
action	ENUM	LwM2M action name. Values: `read`, `write`, `execute`, `observe-start`, `observe-end`.	LwM2M
resourceAddress	STRING	LwM2M OMA object resource address.	LwM2M
data	STRING	Data to send to the device.	*LwM2M
sendAttempts	INTEGER	The maximum number of attempts to send data to the device. Default: 1	CoAP, LWM2M

Note that for LwM2M there's no possibility to provide a data type for the data property. For LwM2M we support 8 data types: TIME, STRING, BOOLEAN, INTEGER, FLOAT, UNSIGNED_INTEGER, OBJLINK and OPAQUE. The data type depends on the addressed resource. Users should provide the data in a stringified format (base64 encoded string for OPAQUE). In case an invalid data type for a resource is used, an Admin Log will be created.

Response

The API will accept the request with a 202 Accepted response code and a response body containing two properties: id (string) and message (string). The id can be used to track the status of the request or cancel the request (see examples below). The message property contains a confirmation message about the request created. Example:

{
  "id": "trxHeBL0d234fsfds",
  "message": "Action read for resource /3/45/22 successfuly scheduled for device 123456789012345678."
}

Get action request(s)

Get action request(s) endpoints are available to track the status of the request and potentially see the response from a device using CoAP/LwM2M. The requestData property return protocol-specific request data provided when the request was created. For LwM2M the responseData can contain the following properties if available: code (response code), payload (data from the device), for Coap there is also additional field - payloadType (payload type). The payloadType is either TEXT when the response content format is printable, or BASE64 if the content format is not printable or not present at all. In case an error occurs, the field errorMessage is present in the responseData.

By specific requestId

Getting request with id trxHeBL0d234fsfds:

curl -X GET "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/trxHeBL0d234fsfds"

The response could be 200 OK with body:

{
  "id": "trxHeBL0d234fsfds",
  "status": "SUCCEEDED",
  "deviceId": "123456789012345678",
  "ip": "127.0.0.1",
  "protocol": "LWM2M",
  "created": "2024-08-22T11:14:28.157Z",
  "updated": "2024-08-22T11:14:28.157Z",
  "mode": "SEND_WHEN_ACTIVE",
  "resultData": {
    "code": "205",
    "payload": "Data from the device",
    "payloadType": "TEXT"
  },
  "requestData": {
    "action": "write",
    "resourceAddress": "/3311/0/5850",
    "data": "Data to send to the device",
    "iccid": "123456789012345678",
    "imsi1": "456789012345678",
    "traceId": "1-66c71d94-f8f46a5cb7ae4ac4def607f1",
    "deviceId": "123456789012345678",
    "requestId": "trxHeBL0d234fsfds",
    "customerId": "1234567890",
    "requestMode": "SEND_WHEN_ACTIVE",
    "deviceIpAddress": "127.0.0.1"
  },
  "sendAttemptsLeft": 0,
  "sendAttempts": 3
}

For LwM2M resultData could be

{
  "resultData": {
    "code": "205",
    "payload": "Data from the device"
  }
}

For CoAP resultData printable text:

{
  "resultData": {
    "code": "205",
    "payload": "Data from the device",
    "payloadType": "TEXT"
  }
}

For CoAP resultData binary text:

{
  "resultData": {
    "code": "205",
    "payload": "RGF0YSBmcm9tIHRoZSBkZXZpY2U=",
    "payloadType": "BASE64"
  }
}

By using the optional filter query parameters

There are 2 endpoints available that support query parameters and are meant to query action requests by different statuses:

Active action requests are those which have statuses IN_PROGRESS and SCHEDULED

Archived action requests are those which have statuses CANCELLED,FAILED and SUCCEEDED

Getting multiple archived requests with optional filters (query parameters) specified. For example, to get all LwM2M action requests that succeeded for a device with id 123456789012345678::

curl -X GET "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/archived?protocol=LWM2M&deviceId=123456789012345678&status=SUCCEEDED"

The response could be 200 OK response code with body:

{
  "items": [
    {
      "id": "2l0mG3WulN1SUvlIcHjvKXBeZk0",
      "status": "SUCCEEDED",
      "deviceId": "123456789012345678",
      "ip": "127.0.0.1",
      "protocol": "LWM2M",
      "created": "2024-08-22T11:14:28.157Z",
      "updated": "2024-08-22T11:14:28.157Z",
      "mode": "SEND_WHEN_ACTIVE",
      "resultData": {
        "code": "205",
        "payload": "Data from the device"
      },
      "requestData": {
        "data": "Data to send to the device",
        "iccid": "123456789012345678",
        "imsi1": "456789012345678",
        "action": "write",
        "traceId": "1-66c71d94-f8f46a5cb7ae4ac4def607f1",
        "deviceId": "123456789012345678",
        "requestId": "2l0mG3WulN1SUvlIcHjvKXBeZk0",
        "customerId": "1234567890",
        "requestMode": "SEND_WHEN_ACTIVE",
        "deviceIpAddress": "127.0.0.1",
        "resourceAddress": "/3311/0/5850"
      },
      "sendAttemptsLeft": 0,
      "sendAttempts": 3
    }
  ],
  "page": 1,
  "pageAmount": 1
}

Getting multiple active requests with optional filters (query parameters) specified. For example, to get all UDP action requests that are scheduled for a device with id 123456789012345678::

curl -X GET "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/active?protocol=UDP&deviceId=123456789012345678&requestMode=SEND_WHEN_ACTIVE"

The response could be 200 OK response code with body:

{
  "items": [
    {
      "id": "2l0kyyq0zGSuc1C78NKe5Pc3Auk",
      "status": "SCHEDULED",
      "deviceId": "123456789012345678",
      "ip": "127.0.0.1",
      "protocol": "UDP",
      "created": "2024-08-22T11:03:59.267Z",
      "updated": "2024-08-22T11:03:59.267Z",
      "mode": "SEND_WHEN_ACTIVE",
      "requestData": {
        "port": 4343,
        "iccid": "123456789012345678",
        "imsi1": "456789012345678",
        "payload": "Hello world",
        "traceId": "1-66c71b1f-64f6213bb0ea04d2f5784494",
        "deviceId": "123456789012345678",
        "requestId": "2l0kyyq0zGSuc1C78NKe5Pc3Auk",
        "customerId": "1234567890",
        "payloadType": "STRING",
        "requestMode": "SEND_WHEN_ACTIVE",
        "deviceIpAddress": "127.0.0.1"
      },
      "sendAttemptsLeft": 1,
      "sendAttempts": 1
    }
  ],
  "page": 1,
  "pageAmount": 1
}

Delete action request(s)

The delete endpoint is used the cancel requests. This means SCHEDULED requests will be updated to the status CANCELLED. The messages will not be sent to the device.

By specific requestId

Delete request with id trxHeBL0d234fsfds:

curl -X DELETE "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/trxHeBL0d234fsfds"

The response could be 200 OK response code with body:

{
  "id": "trxHeBL0d234fsfds",
  "status": "CANCELLED"
}

By deviceId

Delete all requests for device with id 123456789012345678:

curl -X DELETE "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/requests"

The response could be 200 OK response code with body:

[{
  "id": "trxHeBL0d234fsfds",
  "status": "CANCELLED"
}]