API REST

Provides RESTful HTTP/JSON access to OpenEMS Edge channels and JSON-RPC methods. Enables external systems to monitor and control OpenEMS via standard HTTP protocol.

Source Code

Overview

The REST API Controller exposes OpenEMS channels and configuration as REST endpoints. External clients (web applications, mobile apps, scripts) can:

  • Read Channels: Query current values of any channel via GET requests

  • Write Channels: Set channel values via POST requests (write-enabled mode only)

  • Regex Queries: Use regular expressions to query multiple channels in one request

  • JSON-RPC Methods: Execute remote procedure calls for complex operations

  • Configuration Management: Query and update component configuration

  • Component Discovery: Get full Edge configuration with components and channels

Key Capabilities

  • HTTP/JSON REST endpoints

  • Regular expression channel queries

  • Basic authentication (password-based)

  • Read-only or read-write access modes

  • Configurable port (default 8084)

  • Connection rate limiting

  • Write timeout protection

  • Debug logging mode

Components

Controller.Api.Rest.ReadWrite

Description

HTTP REST server with read-write access to channels and JSON-RPC methods. External clients can read all channels and write to channels via POST requests.

Factory-PID

Controller.Api.Rest.ReadWrite

Service Binding

Implements:

  • io.openems.edge.controller.api.rest.readwrite.ControllerApiRestReadWrite

  • io.openems.edge.controller.api.rest.RestApi

  • io.openems.edge.controller.api.Controller

  • io.openems.edge.common.component.OpenemsComponent

Table 1. Configuration Parameters
Parameter Description Type Default

id

Unique component identifier

String

ctrlApiRest0

alias

Human-readable component name

String

(component-id)

enabled

Enable/disable the controller

Boolean

true

port

HTTP server port

Integer

8084

connectionlimit

Maximum concurrent HTTP connections

Integer

5

apiTimeout

Timeout for channel writes (seconds)

Integer

60

debugMode

Enable verbose debug logging

Boolean

false

Controller.Api.Rest.ReadOnly

Description

HTTP REST server with read-only access to channels. External clients can only read channels; write requests are rejected.

Factory-PID

Controller.Api.Rest.ReadOnly

Configuration Parameters

Same as ReadWrite.

Base URL

All REST requests use this base URL pattern:

http://[username:password@]<IP>:<PORT>/rest
URL Components

  • username: Always optional; if omitted, can be replaced with x

  • password: User password (required for authentication)

  • <IP>: Edge machine IP address or hostname

  • <PORT>: Configured port (default 8084)

  • /rest: REST API path prefix

Examples

REST Endpoints

GET /rest/channel/<Component-ID>/<Channel-ID>

Read the current value of a single channel.

Parameters

  • <Component-ID>: Component identifier (e.g., _sum, ess0, meter0)

  • <Channel-ID>: Channel identifier (e.g., ActivePowerL1, Soc)

Response

{
  "type": "INTEGER",
  "accessMode": "RO",
  "text": "",
  "unit": "%",
  "value": 50
}
Response Fields

  • type: Data type (INTEGER, LONG, FLOAT, STRING, STATE, BOOLEAN)

  • accessMode: Read/Write permissions (RO, RW)

  • text: Human-readable description

  • unit: Measurement unit (W, V, %, A, Hz, etc.)

  • value: Current channel value

Example Requests

Read ESS state of charge
GET http://x:user@localhost:8084/rest/channel/_sum/EssSoc
Read meter active power
GET http://x:user@localhost:8084/rest/channel/meter0/ActivePower

GET /rest/channel/<Regex-Component>/<Regex-Channel>

Query multiple channels using regular expressions.

Parameters

  • <Regex-Component>: Regular expression pattern for component IDs (e.g., .* for all)

  • <Regex-Channel>: Regular expression pattern for channel IDs (e.g., Active.*Power for active power channels)

Response

Returns array of matching channels:

[
  {
    "address": "pvInverter0/ActivePower",
    "type": "INTEGER",
    "accessMode": "RO",
    "text": "",
    "unit": "W",
    "value": 90
  },
  {
    "address": "meter0/ActivePower",
    "type": "INTEGER",
    "accessMode": "RO",
    "text": "",
    "unit": "W",
    "value": 465
  },
  {
    "address": "ess0/ActivePower",
    "type": "INTEGER",
    "accessMode": "RW",
    "text": "",
    "unit": "W",
    "value": -250
  }
]

Example Requests

Query all active power channels
GET http://x:user@localhost:8084/rest/channel/.*/Active.*Power
Query all ESS-related channels
GET http://x:user@localhost:8084/rest/channel/ess.*/.*
Query all reactive power channels
GET http://x:user@localhost:8084/rest/channel/.*/Reactive.*Power

POST /rest/channel/<Component-ID>/<Channel-ID>

Write a value to a writable channel (read-write mode only).

Parameters

  • <Component-ID>: Component identifier

  • <Channel-ID>: Writable channel identifier

Request Body

{
  "value": <NEW_VALUE>
}

Response

Returns 200 OK if successful. No body returned.

Example Requests

Enable a digital output relay
POST http://x:user@localhost:8084/rest/channel/io0/Relay1
Content-Type: application/json

{
  "value": true
}
Set ESS charging power
POST http://x:user@localhost:8084/rest/channel/ess0/SetActivePowerEquals
Content-Type: application/json

{
  "value": 5000
}
Set boolean input
POST http://x:user@localhost:8084/rest/channel/heatpump0/Start
Content-Type: application/json

{
  "value": false
}

JSON-RPC Endpoints

POST /rest/jsonrpc

Execute JSON-RPC method calls.

All JSON-RPC requests are sent as POST requests with JSON body. Standard JSON-RPC fields id and jsonrpc are optional.

getEdgeConfig

Get complete Edge configuration including components, channels, and their metadata.

Request
{
  "method": "getEdgeConfig",
  "params": {}
}
Response
{
  "components": [
    {
      "id": "_sum",
      "alias": "Summary",
      "type": "io.openems.edge.common.sum.Sum",
      "channels": [
        {
          "id": "GridActivePower",
          "type": "INTEGER",
          "unit": "W",
          "accessMode": "RO"
        }
      ]
    },
    {
      "id": "ess0",
      "alias": "Battery System",
      "type": "io.openems.edge.ess.api.ManagedSymmetricEss",
      "channels": [...]
    }
  ]
}

componentJsonApi

Forward a JSON-RPC payload to a specific component.

Request
{
  "method": "componentJsonApi",
  "params": {
    "componentId": "ctrlApiModbusTcp0",
    "payload": {
      "method": "getModbusProtocol",
      "params": {}
    }
  }
}
Response

Returns component-specific response (varies by component).

Example: Get Modbus Protocol
{
  "method": "componentJsonApi",
  "params": {
    "componentId": "ctrlApiModbusTcp0",
    "payload": {
      "method": "getModbusProtocol",
      "params": {}
    }
  }
}

updateComponentConfig

Modify component configuration parameters.

Request
{
  "method": "updateComponentConfig",
  "params": {
    "componentId": "ctrlDebugLog0",
    "properties": [
      {
        "name": "enabled",
        "value": true
      },
      {
        "name": "logLevel",
        "value": "DEBUG"
      }
    ]
  }
}
Response

Returns 200 OK if successful.

Configuration Examples

Standard Read-Write Setup
{
  "id": "ctrlApiRest0",
  "alias": "REST API Server",
  "enabled": true,
  "port": 8084,
  "connectionlimit": 10,
  "apiTimeout": 60,
  "debugMode": false
}
High-Concurrency Read-Only Setup
{
  "id": "ctrlApiRest0",
  "alias": "REST API (Read-Only)",
  "enabled": true,
  "port": 8080,
  "connectionlimit": 50,
  "apiTimeout": 30,
  "debugMode": false
}

Authentication

Basic HTTP authentication is used. Format:

Authorization: Basic base64(username:password)

Usernames are typically: * user (default unprivileged) * admin (admin privileges) * x (if username is omitted)

Password must match configured user password in OpenEMS.

Error Responses

Status Meaning

200 OK

Request successful

400 Bad Request

Invalid JSON format or missing required parameters

401 Unauthorized

Authentication failed (invalid credentials)

403 Forbidden

Access denied (insufficient permissions or read-only mode)

404 Not Found

Component or channel not found

408 Request Timeout

Channel write operation timed out

500 Internal Server Error

Server error
Error Response Format
{
  "error": "Channel not found: component/channel"
}

Client Examples

cURL

Read channel
curl -u x:user http://localhost:8084/rest/channel/_sum/EssSoc
Write channel
curl -X POST -u x:user \
  -H "Content-Type: application/json" \
  -d '{"value": 5000}' \
  http://localhost:8084/rest/channel/ess0/SetActivePowerEquals
Regex query
curl -u x:user http://localhost:8084/rest/channel/.*/Active.*Power
JSON-RPC call
curl -X POST -u x:user \
  -H "Content-Type: application/json" \
  -d '{"method":"getEdgeConfig","params":{}}' \
  http://localhost:8084/rest/jsonrpc

JavaScript/Fetch

Read channel
fetch('http://localhost:8084/rest/channel/_sum/EssSoc', {
  headers: { 'Authorization': 'Basic ' + btoa('x:user') }
}).then(r => r.json()).then(data => console.log(data.value));
Write channel
fetch('http://localhost:8084/rest/channel/ess0/SetActivePowerEquals', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('x:user'),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ value: 5000 })
});

Testing Tools

Popular tools for testing REST APIs:

  • Postman - Desktop client for REST testing

  • Restlet Client - Chrome extension

  • Insomnia - REST client alternative to Postman

  • curl - Command-line HTTP client