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.refu88k - REFU 88K hybrid inverter

  • 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