Controller

A OpenEMS Edge Controller holds the actual business logic or the actual algorithm that controls hardware. The logic of each active Controller is executed regularly on every Cycle, i.e. once per second.

1. Api Backend

Connects to OpenEMS Backend and sends all Channel data regularly. It is implemented as a Controller, as Channels can be written from OpenEMS Backend.

2. Api Modbus

Provides a Modbus-Slave implementation for OpenEMS Edge. It provides access to Channels from an external device via Modbus/TCP.

3. REST-Api Controller

A REST-Api for external access to OpenEMS Edge. This Controller provides access to Channels and JSON-RPC Requests from an external device via JSON/REST.

The default port for the server is 8084; so the default base address for REST calls is http://x:<PASSWORD>@<IP>:8084/rest, where

  • http is the protocol

  • x is the user. Authentication in OpenEMS is via password only, so the username can be omitted.

  • <PASSWORD> is the user password. If no specific settings have been made, try 'user' or 'admin' here.

  • 8084 is the configured port

A good way to test REST-Api calls is via the Chrome extension Restlet

For more information find the implementation Source Code .

Those are the available REST-Api endpoints:

3.1. Endpoint /rest/channel/<Component-ID>/<Channel-ID>

  • Component-ID is the ID of the Component, e.g. "_sum", "ess0", "meter0",…​

  • Channel-ID is the ID of the Channel, e.g. "ActivePowerL1", "Soc",…​

3.1.1. GET

Use a HTTP request with method GET to read the current value of a Channel.

Example: To read the current state of charge of the battery, send a GET request to http://x:user@localhost:8084/rest/_sum/EssSoC. It returns a response like:

{
  "value": 50
}

3.1.2. POST

Use a HTTP request with method POST to write a Channel.

Example: To switch a Digital-Output or Relay on, send a POST request to http://x:user@localhost:8084/rest/io0/Relay1 with the following body:

{
  "value": true
}

3.2. Endpoint '/jsonrpc'

This allows remote procedure calls (RPC) using JSON-RPC. The JSON-RPC commands need to be sent as POST requests with the specified body.

JSON-RPC usually requires the properties 'id' and 'jsonrpc'. Those can be omitted here, as they are not required for HTTP POST calls.

Following JSON-RPC commands are available:

3.2.1. getEdgeConfig

Gets the current configuration of the OpenEMS Edge.

{
  "method": "getEdgeConfig",
  "params": {}
}

3.2.2. componentJsonApi

Forwards a JSON-RPC payload to a given Component, identified by its Component-ID.

3.2.2.1. getModbusProtocol

Gets the currently active Modbus-TCP protocol definition from the Modbus-TCP-Api Controller with the ID "ctrlModbusTcp0".

{
  "method":"componentJsonApi",
  "params":{
    "componentId":"ctrlApiModbusTcp0",
    "payload":{
      "method":"getModbusProtocol",
      "params":{

      }
    }
  }
}

3.2.3. updateComponentConfig

Updates a Component configuration.

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

4. Api Websocket

Provides a JSON/REST implementation via HTTP Websocket for OpenEMS Edge. It provides access to Channels and JSON-RPC Requests from an external device via Websocket. This Controller is used for local connection of OpenEMS UI.

5. Asymmetric Balancing Cos-Phi

Controls an asymmetric energy storage system in self-consumption optimization mode while keeping the grid meter on a defined cos-phi.

6. Asymmetric Fix Active Power

Sets a fixed active power for charging/discharging of an asymmetric energy storage system.

7. Asymmetric Fix Reactive Power

Sets a fixed reactive power for an asymmetric energy storage system.

8. Asymmetric Phase Rectification

Balances the three phases at the grid using an asymmetric energy storage system.

9. Channel-Threshold

Generic Controller that sets a digital output according to the value of given Channel - e.g. turn a Relay on, when battery state of charge is above a given threshold.

10. CHP control via State-of-Charge (SoC)

Controls a CHP device. Signals the CHP to turn 'ON' when battery SoC is low; signal it to turn 'OFF' when SoC is high. This controller needs four parameters,

  • State of Charge(Soc) of the ESS.

  • Low Threshold(LT) Soc

  • High Threshold(HT) Soc

  • Output channel to signal.

The Soc of the Ess is compared with the LT and HT, and The following operations or state change is performed.

  • If the Soc is less-than("<") LT, signal is sent to the Output channel which eventually turns the CHP device 'ON'.

  • If the Soc is greater-than(">") HT, signal is sent to the Output channel which turns the CHP device 'OFF'.

  • Any other conditions the there is no change in the State of the CHP device.

10.1. Configuration

  • Component-ID Unique ID of this Component (id), e.g. "ctrlIoAlarm0", "ctrlIoAlarm1"

  • Alias Human-readable name of this Component; defaults to Component-ID (alias)

  • Input Channels Addresses of the input State-Channels (inputChannelAddress), This is a array of input state channels.

  • Output Channel Channel address of the Digital Output that should be switched (outputChannelAddress)

  • Low Threshold Low boundary of the threshold

  • High Threshold High boundary of the threshold

10.2. Example Configuration

  • Component-ID : ctrlChpSoc0

  • Alias : myChpCtrl

  • Input Channels : _sum/EssSoc

  • Output Channel : io0/Relay1

  • Low Threshold 25

  • High Threshold 75

_sum/EssSoc - represents the Soc channel of the ESS0, io0/relay1 - represents the relay 1 of the relay board.

11. Detailed Debug Log

Constantly shows the values of all Channels of a Component on the console. Primarily used for developing and debugging.

12. Debug Log

Constantly shows the most important values of all Components on the console. This is often activated by default to be able to track the running system easily.

13. ESS AC-Island

Switches an AC PV inverter to the emergency power on grid outage.

14. ESS Delay Charge

This Controller delays full charing of an energy storage system (ESS) to a certain hour of the day. If for example configured to delay till 4 pm, the allowed charge power is limited in a way, that 100 % State-of-Charge is reached only at 4 pm. The Controller therefor constantly watches the remaining time and remaining capacity of the ESS.

15. ESS Limit Discharge Cell Voltage

Limits the discharge power of an energy storage system according to minimal cell voltage, e.g. to keep energy for emergency power or to avoid deep discharge.

16. ESS Limit Total Discharge

Limits the discharge power of an energy storage system according to its State-of-Charge, e.g. to keep energy for emergency power or to avoid deep discharge.

17. ESS One Full Cycle

Executes a full charge/discharge cycle with an energy storage system. This can be used to let the Battery Management System (BMS) reset its reference points for State-of-Charge calculattion.

18. EVCS

Controls an Electric Vehicle Charging Station (EVCS) in different modes, like "Force-Charge" and "Surplus Energy Charging".

19. EVCS Fix Active Power

Sets a fixed maximum charge power to an Electric Vehicle Charging Station (EVCS).

20. High-Load Timeslot

Controls an energy storage system for a High-Load timeslot application (German "Hochlastzeitfenster").

21. IO Alarm

Switches a digital output, when one or more State-Channels are set. This controller can be used to signal alarms. This controller is used to check for the State-Channels which are boolean type, which typically represents the error channels. A specific configured digital output channel can be signaled based on the configured input State-Channels(one more channels).

21.1. Configuration

  • Component-ID Unique ID of this Component (id), e.g. "ctrlIoAlarm0", "ctrlIoAlarm1"

  • Alias Human-readable name of this Component; defaults to Component-ID (alias)

  • Input Channels Addresses of the input State-Channels (inputChannelAddress), This is a array of input state channels.

  • Output Channel Channel address of the Digital Output that should be switched (outputChannelAddress)

Multiple instances can be created in "Apache felix" during the configuration for each Output channel signal.

21.2. Example Configuration

  • Component-ID : ctrlIoAlarm0

  • Alias : myIoAlarm

  • Input Channels : [ess0/State15, ess0/State33, ess0/State43]

  • Output Channel : io0/Relay1

ess0/State15 - represents the State15 channels of the ESS0, io0/relay1 = represents the relay 1 of the KM tronic relay board.

The above example configuration describes, if any of the configured three input channels is set to "True" then a signal "True" is sent to output channel, else the "False" signal is sent to outout channel.

22. IO Fix Digital Output

Sets a digital output statically ON or OFF.

23. PV-Inverter Fix Power Limit

Sets a fixed power limit for PV-Inverter production.

24. Sell-To-Grid limit

Dynamically limits the Sell-To-Grid power to a defined maximum power.

25. Symmetric Balancing

Controls a symmetric energy storage system in self-consumption optimization mode.

26. Symmetric Balancing Schedule

Controls a symmetric energy storage system in self-consumption optimization mode. Allows the definition of a Schedule to set the target power on the grid meter. This Controller can be controlled using the OpenEMS Backend-to-Backend interface.

27. Symmetric Fix Active Power

Sets a fixed active power for charging/discharging of a symmetric energy storage system.

28. Symmetric Fix Reactive Power

Sets a fixed reactive power for a symmetric energy storage system.

29. Symmetric Limit Active Power

Limits the allowed active power for charging and discharging of a symmetric energy storage system.

30. Symmetric Linear Power Band

Executes a test cycle for a symmetric energy storage system by increasing and decreasing the charging/discharging power in given limits.

31. Symmetric Peak-Shaving

Applies peak-shaving at the grid using a symmetric energy storage system.

32. Symmetric Random-Power

Applies random charging/discharging of a symmetric energy storage system for performance tests.

33. Symmetric Reactive-Power Voltage-Characteristics

Controls a symmetric energy storage system using a Q-by-U reference function.