Backend-to-Backend communication

OpenEMS Backend provides two "Backend-to-Backend-Api" implementations, that provide a way to communicate with one or more OpenEMS Edge devices via backend connection. They are designed using the JSON-RPC communication protocol via REST/JSON (io.openems.backend.b2brest) or via Websocket (io.openems.backend.b2bwebsocket) connection.

1. Authentication

BasicAuth on opening of the connection.

2. Error Handling

Example:

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "error": {
    "code": 3000,
    "message": "Edge [edge0] is not connected",
    "data: ["edge0"]
  }
}
Properties id and jsonrpc can be omitted for JSON/REST, as they are not required for HTTP POST calls.

3. Requests

3.1. GetEdgesStatus

Lists the current status of Edges.

3.1.1. Request

{
  "jsonrpc":"2.0",
  "id":"UUID",
  "method":"getEdgesStatus",
  "params":{
    "edgeIds: ["edge0", "edge1"]
  }
}

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. To 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":{}
}