Mistake on this page? Email us

Edge Local Management API

Note: This document describes the API version 1.

This API is experimental and no backwards compatibility is guaranteed.

You can use the Device Management Edge Local Management API to query and set LwM2M endpoint and Resource data of Edge Core.

See the document about the Edge JSON-RPC API for protocol translators for more information about LwM2M endpoint and Object structure.

  • The connection between Edge Core and Local Management API client is a websocket connection over a Unix domain socket.
  • The API request payload are JSONRPC 2.0 messages.
  • The default domain socket path is /tmp/edge.sock.
  • The URI for the API version 1 is /1/mgmt.

Edge Core does not support persistent data storages. Therefore, when Edge Core shuts down, the state and all the data related to protocol translators and LwM2M Object structures are lost.

Local Management API methods

Devices (method: `devices`)

You can use the Local Management API method to list the endpoints and all their Object structures. This method does not take any parameters.

Result

On success, the result is returned in the following format:

{
  "id": "1234567890",
  "jsonrpc": "2.0",
  "result": {
    "data": [
      {
        "endpointName": "thermometer-0",
        "resources": [
          {
            "operation": 1,
            "type": "float",
            "uri": "/3303/0/5700"
          },
          ...
          ]
        ...
      ...
      }
    ]
  }
}

The keys and their values in the JSON response:

Key Value description Example/possible values
data Array of endpoints.
endpointName Name of an endpoint. "ble-temperature-sensor-1"
resources Array of resources.
operation The bit-field of allowed operations on the resource. The allowed operations for the resource or any combination of them:
read0x01
write0x02
execute0x04
delete0x08
type The type of the resource. Allowed types are "string", "integer", "float", "boolean", "opaque", "time" and "objlink".
uri Resource URI containing object, object instance and resource. For example: "/3303/0/5700".

Errors

In case there is an error, the devices method may return the following error response.

Method-specific error objects:

Code Message Description
-32603 Internal error Device list request failed.

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "devices",
  "params":{}
}

Example success response (no endpoints)

{
  "id": "1234567890",
  "jsonrpc": "2.0",
  "result": {
    "data":[]
  }
}

Example success response (1 endpoint)

{
  "id": "1234567890",
  "jsonrpc": "2.0",
  "result": {
    "data": [
      {
        "endpointName": "cpu-temperature-0",
        "resources": [
          {
            "operation": 1,
            "type": "float",
            "uri": "/3303/0/5700"
          },
          {
            "operation": 1,
            "type": "string",
            "uri": "/3303/0/5701"
          }
        ]
      }
    ]
  }
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32603,
    "data": "Device list request failed.",
    "message": "Internal error"
  }
}

Read Resource (method: `read_resource`)

After discovering the endpoints and their Object and Resource structure, you can use the read_resource method to read the values of the Resources. This method needs the endpointName and Resource uri as parameters.

Parameter endpointName (required)

Type: string
Description: The `endpointName` object containing the endpoint LwM2M objects and resources.

Parameter uri (required)

Type: string
Description: URI to the resource containing LwM2M object, object instance and resource.

Result

On success, read_resource returns the result in the following format:

{ "id":"1234567890",
  "jsonrpc":"2.0",
  "result": {
    "type":<resource type>
    "base64Value":<Binary value in Base64 Network Endian format>,
    "stringValue":<Value in string. Note this key-value pair may be missing. See below description about key `stringValue` for details.>
  }
}

The keys and their values in the JSON response:

Key Value description Example / possible values
type The type of the resource. "string", "integer", "float", "boolean", "opaque", "time" and "objlink"
base64Value The binary value in Base64 Network Byte Order. "QEdK5X//nTc="
stringValue The string value. There may be loss in precision for values of type "float" or "double". Note: stringValue key is missing for values of type "opaque", "time", and "objlink". "46.585128784"

Errors

On failure, an error response is returned.

Method-specific error objects:

Code Message Description
-32602 Invalid params Key 'endpointName' missing.
-32602 Invalid params Value for key 'endpointName' missing or empty.
-32602 Invalid params Key 'uri' missing.
-32602 Invalid params Value for key 'uri' missing or empty.
-32602 Invalid params Value for key 'uri' malformed.
-30102 Resource not found. Cannot read resource value.
-30104 Resource not readable. Cannot read resource value.

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "read_resource",
  "params": {
    "endpointName": "ble-temperature-device",
    "uri" : "/3303/0/5700"
  }
}

Example successful response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": {
    "type": "float",
    "base64Value": "QEcHSP//kFU=",
    "stringValue": "46.056915283"
  }
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Value for key 'endpointName' missing or empty",
    "message": "Invalid params"
  }
}

Write Resource (method: `write_resource`)

You can update the endpoint device Resources using the write_resource method.

The value regardless of the LwM2M type MUST be Base64 encoded. This is required to support binary content.

To be able write a value the Resource needs to exist already. The client needs to specify endpointName, Resource uri and base64Value.

The client cannot change the resource type. The value has to be Base64 encoded correctly based on the resource type as below:

string: UTF-8.
integer:  A binary signed integer in network byte-order (8, 16, 32 or 64 bits).
float: IEEE 754-2008 floating point value in network byte-order (32 or 64 bits).
boolean: An 8-bit unsigned integer with value 0 or 1.
opaque: A sequence of binary data.
time: Same representation as integer.
objlnk: Two 16 bit unsigned integers one beside the other. The first one is
the Object ID and the second is the Object Instance ID.

Refer to OMA Lightweight Machine to Machine Technical Specification for data type specifications.

If Edge Core replies ok, the value is recorded and available for querying from Device Management and available for notifications. If a failure response is received the value writing failed.

Parameter endpointName (required)

Type: string
Description: The `endpointName` object containing the endpoint LwM2M objects and resources.

Parameter uri (required)

Type: string
Description: URI to the resource containing LwM2M object, object instance and resource.

Parameter base64Value (required)

Type: string
Description: Base64 encoded value in network byte-order.

Result

On a successful write operation, an ok response is returned.

Errors

On a failed write operation, an error response is returned.

Method-specific error objects:

Code Message Description
-32602 Invalid params Missing or invalid 'endpointName' field.
-32602 Invalid params Value for key 'endpointName' missing or empty.
-32602 Invalid params Missing or invalid 'uri' field.
-32602 Invalid params Value for key 'uri' missing or empty.
-32602 Invalid params Value for key 'uri' malformed.
-32602 Invalid params Key 'base64Value' missing.
-32602 Invalid params Value for key 'base64Value' missing.
-32603 Internal error Cannot write resource value.
-30101 Illegal value. Cannot write resource value.
-30102 Resource not found. Cannot write resource value.
-30105 Resource not writable. Cannot write resource value.
-30106 Write request to protocol translator failed. Cannot write resource value.

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "write_resource",
  "params": {
    "endpointName": "ble-temperature-device",
    "uri" : "/3303/0/5700",
    "base64Value": "QEcHSP//kFU="
  }
}

Example successful response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": "ok"
}

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -30101,
    "data": "Write value failed. Failed to update device values from json.",
    "message": "Illegal value."
  }
}