Gateway resource manager JSON-RPC API

Note: This document describes the API version 1.

This document defines the JSON-RPC APIs that Edge Core supports and APIs the Edge gateway resource managers expect. The Edge gateway resource manager implementations must adhere to this specification:

• The connection between Edge Core and a gateway resource manager is a WebSocket connection over a Unix domain socket.
• The API request payload is JSONRPC 2.0 messages.
• The default domain socket path is /tmp/edge.sock.
• The URI for the API version 1 is /1/grm.

Edge Core does not support persistent data storage. Therefore, when Edge Core shuts down, the state and all the data related to gateway resource managers and LwM2M object structures are lost.

Websocket connection

The gateway resource managers and Edge Core use a WebSocket connection to exchange messages:

• Edge Core provides only a Unix domain socket where the gateway resource manager implementations connect.
• Edge Core uses a WebSocket server and libwebsockets library.

You can find more information in the WebSocket RFC and specification.

Connection handling

Closing the WebSocket disconnects the resource manager from Edge Core and the other way around.

When the gateway resource manager closes the WebSocket connection, Edge Core cleans all associated data from its internal structures.

When Edge Core shuts down, it closes the WebSocket connections to the gateway resource manager and cleans all the associated data from its internal structures. When Edge Core turns on again, the gateway resource manager can reconnect.

Note: When reconnecting, the resource manager must register itself and the resources again.

JSON-RPC 2.0 use

For JSON-RPC 2.0 use:

• All requests must contain the id member.
• The id member can be a number or string. The id value is used to match a request to its response, so it must be unique within the scope of a gateway resource manager connection.
• The Edge Core gateway resource manager JSON-RPC API assumes that all parameters to JSON-RPC 2.0 methods are given in the params member of the object.
• The method member must contain the function name. The value is restricted to ASCII characters.
• The jsonrpc member must contain the value 2.0.

For more details, please see the JSON-RPC 2.0 specification.

JSON-RPC methods

Available methods in Edge Core:

• Gateway Resource Manager Register.
• Add Resource.
• Write Resource Value.

Implement the Write method in the resource manager.

Object definitions

Object resource-structure

• Type: object.
• Description: An Object describing the structure for the gateway resources to be operated. The Object describes the LwM2M Object structure containing Objects, Object instances and Resources.

Member objects (required)

• Type: array.
• Description: The Object list for the LwM2M Objects.

Object `lwm2m-object`

• Type: object.
• Description: An Object describing an LwM2M Object. The LwM2M Object structure contains an Object ID and LwM2M Object Instances.

Member objectId (required)

• Type: integer.
• Description: The Object ID. The LwM2M or IPSO Object ID describes LwM2M Object characteristics.

Note: Object 1, 3, 14, 10252, 10255, 26241 and 35011 are reserved in edge-core.

Member objectInstances (required)

• Type: array.
• Description: The Object Instance list for LwM2M Object Instances.

Object `lwm2m-object-instance`

• Type: object.
• Description: An Object Instance describing an LwM2M Object Instance, the instance ID and list of Resources.

Member objectInstanceId (required)

• Type: integer.
• Description: The Object Instance ID.

Member resources (required)

• Type: array.
• Description: The Resource list for the LwM2M Object Instance.

Object `lwm2m-resource`

• Type: object.
• Description: A Resource Object describing the Resource characteristics. This Object describes the LwM2M or IPSO Resource.

Member resourceId (required)

• Type: integer.
• Description: The LwM2M resource or IPSO resource ID.

Member resourceName

• Type: string.
• Description: An optional resource name.

Member operations (required)

Type: integer. Description: The bit-field for allowed operations. The allowed Resource operations, or any combination of them, are:

read   : 0x01
write  : 0x02
execute: 0x04
delete : 0x08

The bit-field is used to contain the operation or combinations of operations. For example, to allow read and execute operations when registering a Resource, the field value is 0x05.

The value can be constructed with a logical OR operation: 0x01 | 0x04 = 0x05.

The set operations in the bit-field can be checked with logical AND operations:

• 0x05 & 0x01 = 0x01 equals the read operation.
• 0x05 & 0x02 = 0x00 indicates that the write operation is not set.

Member type (required)

• Type: string.
• Description: The LwM2M Resource value type. Please refer to LwM2M specification for the value types.
• Allowed values:
  • string.
  • int.
  • float.
  • bool.
  • opaque.
  • time.

Member value (required)

• Type: string
• Description: The value as a Base64-encoded string. All values must be passed as Base64-encoded values. This is required for binary content support. Refer to the LwM2M specification for encoding of the value types.

Object `write`

• Type: object
• Description: The write operation data container. This object describes which resource is the target of the operation defined in the uri member. The operation member defines the initiated operation, and the value member contains the value for the write operation or arguments for the execute operation.

Member operation (required)

• Type: integer.

• Description: The operation to execute:

  read   : 0x01
  write  : 0x02
  execute: 0x04
  delete : 0x08
  

The bit-field is used to contain the operation or combinations of the operations.

When the write function is targeted to a Resource, it must contain only one operation.

The set operations in the bit-field can be checked with logical AND operations. For example, to check operation 0x02 -

• 0x02 & 0x02 = 0x02 equals the write operation.
• 0x02 & 0x04 = 0x00 indicates that the execute operation is not set.

Member uri (required)

• Type: object.
• Description: The URI to LwM2M Resource. The URI LwM2M Resource contains the Object ID, Object Instance ID and the Resource ID.

Member value

• Type: string.
• Description: The value as a Base64-encoded string. The encoded value can contain a string, an integer, float, boolean, opaque, time or object link value.
• Required for operation write 0x02.
• Optional for operation execute 0x04.

Refer to the OMA Lightweight Machine to Machine Technical Specification for data type specifications of value types.

Generic error codes

You can receive the following error responses if any of the callable methods fail:

Available methods from Edge Core

Gateway resource manager register (method: `gw_resource_manager_register`)

All gateway resource managers must register before sending any other JSON-RPC messages.

The registration resides locally in Edge Core. Multiple gateway resource managers can connect to Edge Core. Each such resource manager has a unique connection id that acts as identifier for Edge Core to communicate with that particular ws client.

Parameter name (required)

• Type: string.
• Description: Gateway resource manager name. The name must be unique across connected gateway resource managers to a given Edge Core instance.

Result

A successful registration of the gateway resource manager returns an ok response.

Errors

A failed registration of the gateway resource manager returns an error response.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "gw_resource_manager_register",
  "params": {
    "name": "grm-example"
  }
}

Example success response

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

Example error response

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

Add Resources (method: `add_resource`)

You may register multiple LWM2M resources with this method to Edge Core. Edge Core handles resource registration to Device Management.

Edge Core records the passed LwM2M Object structure and sends it to Device Management. The resource manager receives an ok response when the resource addition to Edge Core is successful.

If Edge Core receives an incorrect resource registration message, the LwM2M Object structure is not registered to Edge Core and Device Management.

Note: The gateway resource manager must be registered to Edge Core before registering devices.

Parameter resource-structure (required)

• Type: object.
• Description: The Object containing the gateway LwM2M Object and Resources to be added.

Result

A successful resource registration returns an ok response.

Errors

A failed resource registration returns an error response.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "add_resource",
  "params": {
    "objects": [{
      "objectId": 33001,
      "objectInstances": [{
        "objectInstanceId": 0,
        "resources": [{
          "resourceId": 1,
          "resourceName": "Example Resource",
          "operations": 3,
          "type": "float",
          "value":"P4AAAA=="
        }]
      }]
    }]
  }
}

Tip: The operations key is bit-coded, and the value 0x01 | 0x02 = 0x03 indicates that the read and write operations are allowed.

Example success response

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

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "data": "Missing or invalid 'objectId' field.",
    "message": "Error"
  }
}

Write Resource Values (method: `write_resource_value`)

You can update the Resources by using the write_resource_value method.

If Edge Core replies ok, it records the value. The value is then available for querying in Device Management and notifications. If Edge Core responds with an error, it does not record the value. Edge Core must forward the value to Device Management.

Note: The value, regardless of the LwM2M type, must be Base64-encoded. This is required to support binary content.

The value formats allowed for write operations are defined as:

• 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.

Note: You must register the gateway resource manager to Edge Core before adding resources to it and initiating the write_resource_value operation.

Parameter Resources (required)

• Type: object.
• Description: The Object containing the gateway LwM2M Object and Resources to be updated.

Result

A successful write operation returns an ok response.

Errors

A failed write operation returns an error response.

Method-specific error objects:

Example request

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "write",
  "params": {
    "objects": [{
      "objectId": 33001,
      "objectInstances": [{
        "objectInstanceId": 0,
        "resources": [{
          "resourceId": 1,
          "resourceName": "Example Resource",
          "operations":3,
          "type":"float",
          "value":"QAAAAA=="
        }]
      }]
    }]
  }
}

Tip: The operations key is bit-coded, and the value 0x01 | 0x02 = 0x03 indicates that the read and write operations are allowed.

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

Expected methods from the gateway resource manager

The resource manager can react to messages sent by Edge Core. The gateway resource manager reacts to write requests with execute or write operation.

Method `write`

You need to implement this method for write operations initiated towards added resources.

A put or execute operation to gateway resources is performed with the write method that the resource manager implements.

Note: The value, regardless of the LwM2M type, must be Base64-encoded. This is required to support binary content.

Note: You must register the gateway resource manager and the resource to Edge Core to receive write calls.

Receiving a write operation on a Resource

The operation member has value 0x02. This indicates the write operation.

The value member contains the new value for the Resource.

Edge Core writes the values in the widest possible format for precision. Edge Core does not know the data type size that the resource use. The following data size and format must be supported:

• string: UTF-8.
• integer: a binary signed integer in network byte-order (64 bits).
• float: IEEE 754-2008 floating point value in network byte-order (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 the OMA Lightweight Machine to Machine Technical Specification for data type specifications.

Receiving an execute operation on the resource

The operation member has value 0x04. This indicates the execute operation.

The execute operation may contain arguments in the value member. The OMA Lightweight Machine to Machine Technical Specification defines the argument syntax. For the gateway resource manager and Edge Core, the syntax and formatting of the execute arguments is not enforced. Implementations can define their own format, but we recommend that you use the syntax in the OMA Lightweight Machine to Machine Technical Specification.

Parameter write (required)

• Type: object.
• Description: The write operation data.

Result

A successful write operation returns an ok response.

Errors

A failed write operation returns an error response.

Example request received

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "write",
  "params": {
    "operation":2,
    "uri":{
      "objectId":33001,
      "objectInstanceId":0,
      "resourceId":1
    },
    "value":"v/gAAAAAAAA="
  }
}

Tip: The operation key is bit-coded, and the value 0x02 indicates that the write operation is allowed.

Example success response

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

Example error response

{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}