EOS/docs/akkudoktoreos/adapter/adapterhomeassistant.md

% SPDX-License-Identifier: Apache-2.0 (adapter-homeassistant-page)=

Home Assistant Adapter

The Home Assistant adapter provides a bidirectional interface between Home Assistant (HA) and the Akkudoktor-EOS (EOS) energy optimisation system.

It allows EOS to:

• Read entity states and attributes from Home Assistant
• Write optimisation results and control instructions back to Home Assistant

This enables EOS to integrate seamlessly with Home Assistant–managed devices, sensors, and energy meters, while keeping EOS device simulations and optimisation logic decoupled from HA-specific implementations.

Configuration entity IDs

EOS can synchronise parts of its configuration from Home Assistant entity states. This is particularly useful for device (resource) parameters that are already provided by Home Assistant integrations, such as:

• Battery capacity
• Maximum charge or discharge power
• Nominal device ratings

These configuration values are typically consumed by EOS device simulations during optimisation.

Entity state conversion rules

When reading configuration values from entity states, the adapter applies the following heuristics to convert the HA state into a suitable EOS value:

• Boolean True: ["y", "yes", "on", "true", "home", "open"]
• Boolean False: ["n", "no", "off", "false", "closed"]
• None: ["unavailable", "none"]
• float: if the value can be converted to a floating-point number
• str: if none of the above apply

Device instruction entity IDs

After each energy optimisation run, EOS produces device instructions for the controlled resources. These instructions are written back to Home Assistant via dedicated entities.

• The entity state represents the selected operation mode of the device.

• Entity attributes provide additional parameters for the operation mode, such as:

  • operation_mode_factor
  • Power or rate limits
  • Mode-specific control parameters

Home Assistant automations or device integrations can then react to these entity updates to perform the actual control actions.

Device measurement entity IDs

Before starting an energy optimisation run, EOS retrieves measurement values from Home Assistant that describe the current state of devices.

Typical examples include:

• Battery state of charge (SoC)
• Current power or energy levels
• Device availability or readiness indicators

These measurements are used as input for EOS device simulations and strongly influence optimisation results.

Load EMR entity IDs

Load Energy Meter Readings (EMR) are used to adapt and refine the load prediction.

EOS retrieves these readings from Home Assistant before each energy management run to align forecasts with actual consumption.

PV production EMR entity IDs

PV production Energy Meter Readings (EMR) are used to adapt and refine the photovoltaic generation forecast.

EOS retrieves these readings from Home Assistant before each optimisation run to improve forecast accuracy based on real production data.

Solution entity IDs

Each energy management run produces an optimisation solution.

In addition to device-level instructions, EOS can publish solution-level details to dedicated Home Assistant entities. These entities are useful for:

• Debugging and validation
• Visualisation and dashboards
• Gaining deeper insight into optimisation decisions

EOS updates these entities after each energy management run.

Entity state and value conversion

To adapt, scale, or transform Home Assistant entity values to match EOS expectations, it is recommended to use template sensors.

This allows value conversion to remain fully within Home Assistant, keeping the EOS configuration clean and consistent.

Example: Battery SoC conversion

Convert a battery state of charge from percentage [0..100] to a normalised factor [0.0..1.0]:

template:
  - sensor:
      - name: "Battery1 SoC Factor"
        unique_id: "battery1_soc_factor"
        state: >
          {% set bat_charge_soc = states('sensor.battery1_soc_percent') | float(100) -%}
          {{ bat_charge_soc / 100.0 }}
        state_class: measurement