Battery-Inverter API

Defines interfaces for battery inverter implementations in OpenEMS.

Overview

This API bundle defines the core interfaces and contracts for battery inverter components. A battery inverter is a critical component that converts between DC power from a battery and AC power for the grid or loads. Together with a battery component, a battery inverter builds an Energy Storage System (ESS).

The bundle provides interfaces for:

  • Symmetric battery inverters for three-phase systems

  • Managed battery inverters that can be controlled

  • Hybrid battery inverters that can also handle PV input

  • Off-grid battery inverters

  • Inverter constraints and error handling

Core Interfaces

SymmetricBatteryInverter

Base interface for symmetric battery inverters.

Purpose: Read-only interface providing monitoring channels for inverter state and power values.

Key Channels

  • GRID_MODE (Enum): 0=Undefined, 1=On-Grid, 2=Off-Grid

  • ACTIVE_POWER (Integer, W): Positive=Discharge, Negative=Charge

  • REACTIVE_POWER (Integer, var): Reactive power output

  • APPARENT_POWER (Integer, VA): Total apparent power

  • DC_CHARGE_ENERGY (Long, Wh): Cumulative charging energy

  • DC_DISCHARGE_ENERGY (Long, Wh): Cumulative discharging energy

  • Various voltage, current, and temperature monitoring channels

ManagedSymmetricBatteryInverter

Controllable battery inverter interface extending SymmetricBatteryInverter.

Purpose: Control and manage battery inverter charging/discharging operations.

Key Methods:

  • run(Battery battery, int setActivePower, int setReactivePower) - Apply power setpoints

  • getStaticConstraints() - Get power constraints for the inverter

  • getPowerPrecision() - Get minimum power step resolution

  • Inherits StartStoppable for start/stop lifecycle management

Typical Usage: Controllers use this interface to command the inverter to charge or discharge at specified power levels.

HybridManagedSymmetricBatteryInverter

Extended interface for hybrid inverters that manage both battery and PV.

Purpose: Control inverters that can simultaneously handle battery and photovoltaic inputs.

Additional Capabilities:

  • Manages DC side with battery input and PV input

  • Coordinates charging from both sources

  • Handles PV feed-to-grid scenarios

OffGridBatteryInverter

Interface for off-grid battery inverter systems.

Purpose: Support for island/microgrid mode where battery inverter operates independently from the main grid.

Use Cases:

  • Backup power systems

  • Island installations

  • Microgrids

BatteryInverterConstraint

Data structure for power constraints.

Purpose: Defines minimum and maximum charge/discharge power limits based on current conditions.

Usage: Allows inverters to dynamically report operational limits to controllers (e.g., thermal derating, battery SOC limits).

BatteryInverterErrorAcknowledge

Interface for error acknowledgment handling.

Purpose: Allows external acknowledgment of inverter fault states and errors.

Related Implementations

Device-specific battery inverter implementations:

Implemented In

  • io.openems.edge.batteryinverter.kaco.blueplanetgridsave - KACO blueplanet gridsave 50/80

  • io.openems.edge.batteryinverter.refu - REFU battery inverter (SunSpec)

  • io.openems.edge.batteryinverter.sinexcel - Sinexcel inverter

Test implementations:

Test Doubles

  • DummyManagedSymmetricBatteryInverter - Test double for managed symmetric

  • DummyOffGridBatteryInverter - Test double for off-grid

  • Located in io.openems.edge.batteryinverter.test subpackage

Use Cases

ESS (Energy Storage System)

Battery Inverter + Battery component together provide ESS functionality:

  • Charge/discharge coordination

  • Reactive power support

  • Grid support services

  • Off-grid capability

Source Code