Internal Component Communication

This page describes the internal communication protocol between OpenEMS Edge, OpenEMS Backend and OpenEMS UI. The components keep an open Websocket connection which is used for bi-directional communication.

1. JSON-RPC introduction

The protocol is based on JSON-RPC. For details about JSON-RPC please refer to the specification. As a rough summary, the protocol is divided into

1.1. JSON-RPC Request

Identified by a unique ID and method name with specific params. Expects a Response.

{
  "jsonrpc": "2.0",
  "id": UUID,
  "method": "method",
  "params": {}
}

1.2. JSON-RPC Success Response

Referring to the ID of the Request, providing a result which can be empty or hold specific data.

{
  "jsonrpc": "2.0",
  "id": UUID,
  "result": {}
}

1.3. JSON-RPC Error Response

Referring to the ID of the Request, providing error code, message and optionally data.

{
  "jsonrpc": "2.0",
  "id": UUID,
  "result": {
    "code": number,
    "message": string,
    "data"?: {}
  }
}

1.4. JSON-RPC Notification

Identified by a unique method name with specific params. Does not expect a Response.

{
  "jsonrpc": "2.0",
  "method": "method",
  "params": {}
}

2. Example communication messages

The information on this page is useful to understand the internal communication structure and can help if your plan is to replace one component by a custom implementation, e.g. implementing your own frontend application, or if you plan to extend the provided feature-set.

2.1. Subscribe Channels

Real-time channel data may change at a high rate. Instead of requiring the consumer to constantly pull the data, the OpenEMS API provides a publish-subscribe schema that notifies the consumer about updated values. It is initiated via a JSON-RPC request:

{
  "jsonrpc": "2.0",
  "id": UUID,
  "method": "subscribeChannels",
  "params": {
    "count": number,
    "channels": string[]
  }
}

The parameters for subscribing to channel data are:

count: a request count value that needs to be increased on each request to avoid concurrency problems
channels: a list of channel addresses as strings, e.g. "ess0/Soc", "ess0/ActivePower"

From then on, the API constantly keeps sending currentData JSON-RPC notifications, containing the data for all subscribed channels:

{
  "jsonrpc": "2.0",
  "method": "currentData",
  "params": {
    [channelAddress]: string | number
  }
}

To unsubscribe from channels, a new subscribeChannels request has to be sent with an empty list of channels.

2.2. Edge-RPC

When using the API via OpenEMS Backend, it is possible to transparently target a specific OpenEMS Edge, that is connected to the Backend by wrapping the JSON-RPC request into an Edge-RPC request:

{
  "jsonrpc": "2.0",
  "id": UUID,
  "method": "edgeRpc",
  "params": {
    "edgeId": string,
    "payload": JSON-RPC-Request
  }
}

The parameters for an “edgeRpc” request are:

edgeId: the unique ID of the Edge at the Backend
payload: the JSON-RPC Request that should be forwarded to the Edge, e.g. getEdgeConfig or updateComponentConfig.

The JSON-RPC response then also wraps the original result as a payload:

{
  "jsonrpc": "2.0",
  "id": UUID,
  "result": {
    "payload": JSON-RPC-Response
  }
}

2.3. JsonApi Component

To directly send a JSON-RPC request to one specific OpenEMS Component, that component has to implement the JsonApi interface. Then the componentJsonApi request can be used to wrap a JSON-RPC request as payload:

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "method": "componentJsonApi",
  "params": {
    "componentId": string,
    "payload": JSON-RPC-Request
  }
}

2.4. Edge-Config

The EdgeConfig may be retrieved using the following JSON-RPC method:

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "method": "getEdgeConfig",
  "params": {}
}

See Edge → Configuration

3. Communication schema

3.1. Authenticate UI to Edge/Backend using token

On opening of the websocket connection to Edge/Backend, the UI is authenticated using an existing token.

3.2. Authenticate UI to Edge using password

3.3. Subscribe to Channels

Allows a Component to subscribe on certain Channel values. The latest Channel values are then periodically sent.

subscribeChannels+currentData

3.4. Subscribe to System-Log

Sends the log output of Edge to UI via Backend.

subscribeSystemLog