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
• Read Resource
• Write Resource

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:

Errors

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

Method-specific error objects:

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:

Errors

On failure, an error response is returned.

Method-specific error objects:

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:

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."
  }
}