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.

1. Exchanging data between EOS and Home Assistant

Basic concept

EOS reads configuration data and measurements from Home Assistant entity states before each energy management run.

EOS publishes results by writing states and attributes to Home Assistant entities. After each optimisation run, these values are available as standard Home Assistant entities and can be used like any other sensor or state.

Typical use cases in Home Assistant:

• Dashboards and visualisation
• Automations and scripts
• Device or manufacturer integrations
• Debugging and validation

Configuration steps in EOS

1. Enable and configure the Home Assistant adapter

EOS must be configured with access to the Home Assistant API. It must be run as a Home Assistant add-on.

2. Define source entity IDs

Configure EOS to read configuration and measurement entities from Home Assistant. Typical sources include:

• Configuration entities
• Measurement entities

3. Define target entity IDs

Configure EOS to write the results back to Home Assistant. Typical targets include:

• Device instruction entities
• Solution / optimisation result entities

4. Run energy optimisation

• EOS reads the source entities before optimisation.
• After the run, EOS writes the device instruction and solution entities back to Home Assistant.

Configuration steps in Home Assistant

1. Accept entities created by EOS

Entities written by EOS automatically appear in Home Assistant’s state machine.

2. Make entities usable in the UI

• Entities created by EOS have no unique ID.
• To use them properly in dashboards, history, or automations, wrap them in template sensors.

3. Use EOS data

EOS entities can be referenced in:

• Automations
• Scripts
• Dashboards
• Device control logic

:::{admonition} Warning :class: warning Entities created by EOS have no unique ID. The unique ID cannot be set by an add-on. To use the entity information in the Home Assistant UI, a template sensor should be used. :::

Example: UI-usable template sensor for an EOS entity

template:
  - sensor:
      - name: "Battery1 Operation Mode"
        unique_id: "battery1_op_mode"
        state: >
          {% set battery1_op_mode = states('sensor.eos_battery1') -%}
          {{ battery1_op_mode }}
        state_class: measurement

2. Data obtained from EOS

2.1 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 device's selected operation mode.

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

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

Note: Home Assistant automations or device integrations can react to these updates to execute control actions.

2.2 Solution entity IDs

Each energy management run produces an optimisation solution.

EOS can publish solution-level details to dedicated Home Assistant entities for:

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

EOS updates these entities after each energy management run.

3. Data read by EOS from Home Assistant

Before starting an energy optimisation run, EOS retrieves several categories of data from Home Assistant, including:

3.1 Configuration entity IDs

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

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

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

The configuration key is the /-separated path of the setting. Devices are addressed by their device_id, e.g. devices/batteries/battery1/profile_adjustment/nominal_capacity_wh. Only existing settings are updated: a path that names no setting, e.g. a device that is not configured, is reported as an error in the EOS log. An entity that is unavailable or unknown leaves the configured value unchanged.

3.2 Device measurement entity IDs

EOS retrieves measurement values that describe the current state of devices, such as:

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

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

3.3 Energy meter entity IDs

Energy Meter Readings (EMR) are used to adapt and refine predictions.

• Load energy meter readings
• Grid export energy meter readings
• Grid import energy meter readings
• PV production energy meter readings

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

4. Entity state and value conversion

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

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

Recommendation: value conversion in Home Assistant

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

This keeps value conversion fully within Home Assistant, ensuring a clean and consistent EOS configuration.

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

5. Further processing of EOS data in Home Assistant

Once published, EOS data behaves like any other Home Assistant entity and can be:

• Used as triggers or conditions in automations
• Mapped to device-specific services or integrations
• Visualised in dashboards
• Compared with measured values for monitoring and validation

EOS does not directly control devices. It provides structured optimisation results, while Home Assistant remains responsible for executing the actual control actions.

6. Data sent to EOS and how

All data sent to EOS is provided via Home Assistant entity states and attributes.

Data type	HA entity type	Purpose in EOS
Configuration values	Sensor / Number	Device modelling
Measurements	Sensor	Initial device state
Energy meter readings	Sensor	Forecast correction
Availability flags	Binary sensor	Device availability

EOS always reads this data; Home Assistant remains the authoritative source for measurements and configuration.

Summary

• EOS focuses on forecasting, simulation, and optimisation
• Home Assistant focuses on measurement, integration, and execution

The Home Assistant adapter provides a clear, structured interface between both systems, allowing flexible integration without coupling EOS to Home Assistant device specifics.