= 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

[[_symmetric_battery_inverter]]
=== 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

[[_managed_symmetric_battery_inverter]]
=== 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.

[[_hybrid_managed_symmetric_battery_inverter]]
=== 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

[[_off_grid_battery_inverter]]
=== 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

https://github.com/OpenEMS/openems/tree/develop/io.openems.edge.batteryinverter.api[Source Code icon:github[]]