Backend-to-Backend communication

OpenEMS Backend provides a "Backend-to-Backend-Api", that provides a way to communicate with one or more OpenEMS Edge devices via backend connection. It is designed as a JSON-RPC communication protocol via Websocket connection.

1. Authentication

BasicAuth on opening of the Websocket connection.

2. Error Handling

Example:

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "error": {
    "code": 3000,
    "message": "Edge [edge0] is not connected",
    "data: ["edge0"]
  }
}

3. Requests

3.1. GetEdgesStatus

Lists the current status of all accessible Edges.

3.1.1. Request

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

3.1.2. Response

{
  "jsonrpc":"2.0",
  "id":"UUID",
  "result":{
    "edge0":{
      "online":true
    },
    "edge1":{
      "online":false
    }
  }
}

3.2. GetEdgesChannelsValues

Queries the latest value of certain channels for a number of Edge-Devices. Channels that are not available or do not have a current value are returned as null.

3.2.1. Request

{
  "jsonrpc":"2.0",
  "id":"UUID",
  "method":"getEdgesChannelsValues",
  "params":{
    "ids":[
      "edge0",
      "edge1"
    ],
    "channels":[
      "_sum/EssSoc",
      "_sum/ProductionActivePower"
    ]
  }
}

3.2.2. Response

{
  "jsonrpc":"2.0",
  "id":"UUID",
  "result":{
    "edge0":{
      "_sum/EssSoc":50,
      "_sum/ProductionActivePower":0
    },
    "edge1":{
      "_sum/EssSoc":99,
      "_sum/ProductionActivePower":null
    }
  }
}

3.3. SubscribeToChannels

Registers a subscription for regular updates of channel values. Request is acknowledged by an empty success Response and followed by regular JSON-RPC Notifications. Du stop the subscription, an empty 'subscribeEdgesChannels' Request needs to be sent.

The parameter "count" must be increased with each new Request. Only the Request with the highest "count" value is active.

3.3.1. Request

{
  "jsonrpc":"2.0",
  "id":"UUID",
  "method":"subscribeEdgesChannels",
  "params":{
    "count": 0
    "ids":[
      "edge0",
      "edge1"
    ],
    "channels":[
      "_sum/EssSoc",
      "_sum/ProductionActivePower"
    ]
  }
}

3.3.2. Response

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

3.3.3. Notifications

{
  "jsonrpc":"2.0",
  "method":"edgesCurrentData",
  "params":{
    "edge0":{
      "_sum/EssSoc":50,
      "_sum/ProductionActivePower":1502
    },
    "edge1":{
      "_sum/EssSoc":20,
      "_sum/ProductionActivePower":null
    }
  }
}

3.3.4. Unsubscribe-Request

{
  "jsonrpc":"2.0",
  "id":"UUID",
  "method":"subscribeEdgesChannels",
  "params":{
    "ids":[],
    "channels":[]
  }
}

3.4. SetGridConnSchedule

Each battery storage system in an Edge-Device can be controlled to balance on a specific value at the grid connection point. This Request allows sending such a Schedule to an Edge-Device.

3.4.1. Request

{
  "jsonrpc":"2.0",
  "id":"UUID",
  "method":"setGridConnSchedule",
  "params":{
    "id":"edgeId",
    "schedule":[
      {
        "startTimestamp":1542464697,
        "duration":900,
        "activePowerSetPoint":0
      }
    ]
  }
}

3.4.2. Response

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