Nature

Physical hardware is abstracted in OpenEMS Edge using Natures. A Nature defines a set of characteristics and attributes which need to be provided by each OpenEMS component that implements it. These characteristics are defined by Channels. For example an implementation of an Ess (Energy Storage System), needs to provide an Soc-Channel (State of charge of the battery).

Technically Natures are implemented as OSGi API Bundles.

Each .api bundle contains the nature interfaces that device implementations must implement. For example, io.openems.edge.ess.api defines interfaces like SymmetricEss, AsymmetricEss, ManagedSymmetricEss, etc. These are sub-natures of the Ess nature.

OpenEMS Edge provides the following types of Natures:

1. Device Natures

e.g.: - io.openems.edge.battery.api - Battery interfaces - io.openems.edge.batteryinverter.api - Battery inverter interfaces - io.openems.edge.ess.api - Energy Storage System interfaces - io.openems.edge.evcs.api - EV Charging Station interfaces - io.openems.edge.evse.api - EV Supply Equipment interfaces - io.openems.edge.meter.api - Power meter interfaces - io.openems.edge.pvinverter.api - PV inverter interfaces - io.openems.edge.io.api - IO device interfaces - io.openems.edge.heat.api - Heat pump interfaces - io.openems.edge.thermometer.api - Thermometer interfaces

2. Service/Support Natures

e.g.: - io.openems.edge.controller.api - Controller interfaces - io.openems.edge.scheduler.api - Scheduler interfaces - io.openems.edge.timedata.api - Time-series data interfaces - io.openems.edge.timeofusetariff.api - Dynamic pricing interfaces - io.openems.edge.predictor.api - Forecasting interfaces - io.openems.edge.weather.api - Weather service interfaces - io.openems.edge.energy.api - Energy management interfaces

Following you find all natures currently defined in OpenEMS Edge:

3. Battery

A battery that is connected to a battery inverter.

4. Battery-Inverter

Together with a battery, a battery-inverter builds an Energy Storage System.

Source Code

5. Controller

A Controller; see the Controller chapter for details.

6. OpenEMS Energy API

The API for OpenEMS Energy Schedules.

Source Code

7. ESS (Energy Storage System)

An Energy Storage System is an integrated system with battery and battery inverter. This API bundle defines the core natures (interfaces) that ESS components implement.

7.1. Core ESS Natures

SymmetricEss

A symmetric Energy Storage System that provides balanced power across all phases. This is the base nature for most ESS implementations.

Key Channels:

  • SOC - State of Charge (%)

  • CAPACITY - Battery capacity (Wh)

  • GRID_MODE - Current grid mode (On-Grid/Off-Grid)

  • ACTIVE_POWER - Active power (W, negative=charge, positive=discharge)

  • REACTIVE_POWER - Reactive power (var)

ManagedSymmetricEss

A controllable symmetric Energy Storage System that extends SymmetricEss. Supports active and reactive power control commands. This is the most commonly used nature for controllable ESS implementations.

Key Channels:

  • ALLOWED_CHARGE_POWER - Maximum allowed charge power (W, negative value)

  • ALLOWED_DISCHARGE_POWER - Maximum allowed discharge power (W, positive value)

  • SET_ACTIVE_POWER_EQUALS - Write command to set active power

  • SET_ACTIVE_POWER_LESS_OR_EQUALS - Write command to limit maximum discharge power

  • SET_ACTIVE_POWER_GREATER_OR_EQUALS - Write command to limit maximum charge power

  • SET_REACTIVE_POWER_EQUALS - Write command to set reactive power

AsymmetricEss

A three-phase Asymmetric Energy Storage System that extends SymmetricEss. Provides separate power measurements for each phase (L1, L2, L3).

Key Channels:

  • ACTIVE_POWER_L1, ACTIVE_POWER_L2, ACTIVE_POWER_L3 - Active power per phase (W)

  • REACTIVE_POWER_L1, REACTIVE_POWER_L2, REACTIVE_POWER_L3 - Reactive power per phase (var)

ManagedAsymmetricEss

A controllable asymmetric Energy Storage System that extends both ManagedSymmetricEss and AsymmetricEss. Allows independent control of each phase.

Key Channels:

  • SET_ACTIVE_POWER_L1_EQUALS, SET_ACTIVE_POWER_L2_EQUALS, SET_ACTIVE_POWER_L3_EQUALS - Write commands for active power per phase

  • SET_REACTIVE_POWER_L1_EQUALS, SET_REACTIVE_POWER_L2_EQUALS, SET_REACTIVE_POWER_L3_EQUALS - Write commands for reactive power per phase

SinglePhaseEss

A single-phase Energy Storage System that extends AsymmetricEss. Connected to only one phase (L1, L2, or L3).

Key Methods:

  • getPhase() - Returns which phase (L1/L2/L3) the ESS is connected to

ManagedSinglePhaseEss

A controllable single-phase Energy Storage System that extends both ManagedSymmetricEss and SinglePhaseEss.

7.2. Specialized ESS Natures

HybridEss

An ESS with one or more DC-coupled PV chargers. Extends SymmetricEss.

Key Channels:

  • DC_DISCHARGE_POWER - Actual battery discharge power (W), i.e., ACTIVE_POWER minus DC charger production

  • DC_CHARGE_ENERGY - Cumulative battery charge energy (Wh)

  • DC_DISCHARGE_ENERGY - Cumulative battery discharge energy (Wh)

    Note: For hybrid inverters, ACTIVE_POWER includes excess DC-PV production, while DC_DISCHARGE_POWER represents the actual battery power flow.

MetaEss

A virtual ESS that wraps one or more physical energy storage systems. Extends SymmetricEss. Used for ESS clusters or combined systems.

Key Methods:

  • getEssIds() - Returns array of Component-IDs of the physical ESS components

    Usage: Implements aggregation logic to combine multiple ESS into a single logical unit.

OffGridEss

An ESS with off-grid (island mode) capabilities. Extends ManagedSymmetricEss.

Key Methods:

  • isOffGridPossible() - Returns true if the ESS can build a micro-grid in off-grid mode

    Usage: Typically used with systems that can form and maintain an AC grid when disconnected from the utility grid.

EssErrorAcknowledge

Defines error acknowledgement capabilities for ESS components. Extends OpenemsComponent.

Key Channels:

  • TIMEOUT_START_BATTERY - Fault state when battery start timeout is exceeded

  • TIMEOUT_START_BATTERY_INVERTER - Fault state when battery inverter start timeout is exceeded

  • TIMEOUT_STOP_BATTERY - Fault state when battery stop timeout is exceeded

  • TIMEOUT_STOP_BATTERY_INVERTER - Fault state when battery inverter stop timeout is exceeded

    Key Methods:

  • executeErrorAcknowledge() - Attempts to clear error channels

    Usage: Implemented by ESS components that require explicit error acknowledgement and timeout handling.

7.3. Auxiliary Components

7.3.1. DC Charger

EssDcCharger

A DC-coupled solar charger connected to the DC side of an energy storage system. Extends OpenemsComponent.

Key Channels:

  • ACTUAL_POWER - Current DC power production (W, positive value)

  • ACTUAL_ENERGY - Cumulative energy production (Wh)

  • MAX_ACTUAL_POWER - Maximum ever recorded power (W)

  • VOLTAGE - DC voltage (V)

    Usage: Used in hybrid ESS systems where PV production feeds directly into the battery DC bus.

7.3.2. Off-Grid Switch

OffGridSwitch

A device that determines grid status and actively switches between on-grid and off-grid modes. Extends OpenemsComponent.

Key Channels:

  • MAIN_CONTACTOR - Main contactor state connecting inverter to public grid (Boolean)

  • GROUNDING_CONTACTOR - Grounding contactor state for off-grid neutral connection (Boolean)

  • GRID_MODE - Current grid mode (On-Grid/Off-Grid)

    Usage: Used in systems with active grid separation capabilities.

7.4. Nature Hierarchy

The following diagram shows the inheritance relationships:

OpenemsComponent (base interface)
├── SymmetricEss
│   ├── ManagedSymmetricEss
│   │   ├── ManagedAsymmetricEss (also extends AsymmetricEss)
│   │   ├── ManagedSinglePhaseEss (also extends SinglePhaseEss)
│   │   └── OffGridEss
│   ├── AsymmetricEss
│   │   ├── ManagedAsymmetricEss (also extends ManagedSymmetricEss)
│   │   └── SinglePhaseEss
│   │       └── ManagedSinglePhaseEss (also extends ManagedSymmetricEss)
│   ├── MetaEss
│   └── HybridEss
├── EssDcCharger
├── OffGridSwitch
└── EssErrorAcknowledge

7.5. Implementation Guidelines

When implementing an ESS component, choose the appropriate nature(s):

  • Read-only ESS: Implement SymmetricEss only

  • Controllable ESS: Implement ManagedSymmetricEss

  • Three-phase with independent control: Implement ManagedAsymmetricEss

  • Single-phase system: Implement ManagedSinglePhaseEss

  • Hybrid inverter with DC-PV: Implement HybridEss and provide EssDcCharger component(s)

  • Off-grid capable: Implement OffGridEss and optionally OffGridSwitch

  • ESS cluster/aggregation: Implement MetaEss

Multiple natures can be combined. For example, a hybrid off-grid ESS would implement both HybridEss and OffGridEss.

8. EVCS (Electric Vehicle Charging Station)

Evcs

A charging station for electric vehicles like e-cars and e-buses.

9. Electric Vehicle Supply Equipment (EVSE) Api

APIs for

  • Electric Vehicle

  • Charge Point

Source Code

10. OpenEMS Edge Heat Api

Source Code

11. I/O (Digital or Analog Input/Output)

DigitalOutput

One or more digital outputs or relays.

DigitalInput

One or more digital inputs.

AnalogVoltageOutput

One or more Analog Voltage outputs.

AnalogInput

One or more analog inputs.

12. Meter

ElectricityMeter

An electricity meter.

13. Predictor

A Predictor provides abstract access to prediction of production and consumption.

14. Scheduler

A Scheduler; see the Scheduler chapter for details.

15. Thermometer

A Thermometer measures temperature.

16. Timedata

A provider for time-series data, like historic recordings of Channels.

17. Time-Of-Use Tariff API.

Provides abstract access for getting prices from every "Time-Of-Use" tariff providers like: - aWATTar - Stromdao with Corrently

Source Code

18. Weather API

Provides a clean and unified interface for accessing historical and forecast weather data from various API providers.

Source Code