EOS Connect is an open-source tool for intelligent energy management and optimization.
It connects to various smart home platforms (like Home Assistant and OpenHAB) to monitor, forecast, and control your energy flows.
EOS Connect fetches real-time and forecast data (PV, load, prices), processes it via the EOS (Energy Optimization System), and automatically controls devices (such as Fronius inverters or batteries supported by evcc) to optimize your energy usage and costs.
Key Features:
- Automated Energy Optimization:
Uses real-time and forecast data to maximize self-consumption and minimize grid costs. - Battery and Inverter Management:
Supports charge/discharge control, grid/PV modes, and dynamic charging curves. - Integration with Smart Home Platforms:
Works with Home Assistant, OpenHAB, EVCC, and MQTT for seamless data exchange and automation. - Dynamic Web Dashboard:
Provides live monitoring, manual control, and visualization of your energy system. - Cost Optimization:
Aligns energy usage with dynamic electricity prices (e.g., Tibber, smartenergy.at). - Flexible Configuration:
Easy to set up and extend for a wide range of energy systems and user needs.
EOS Connect helps you get the most out of your solar and storage systems—whether you want to save money, increase self-sufficiency, or simply monitor your energy flows in real time.
- EOS Connect
- Dynamic Energy Flow Control:
- Automatically optimizes energy usage based on system states and external data.
- Supports manual override modes for precise control.
- Battery Management:
- Monitors battery state of charge (SOC) and remaining energy.
- Configures charging and discharging modes, including:
- Charge from grid.
- Avoid discharge.
- Discharge allowed.
- EVCC-specific modes (e.g., fast charge, PV mode).
- Dynamic Charging Curve:
- If enabled, EOS Connect automatically adjusts the maximum battery charging power based on the current state of charge (SOC). This helps to optimize battery health and efficiency by reducing charge power as the battery approaches full capacity.
- Cost and Solar Optimization:
- Aligns energy usage with real-time electricity prices (e.g., from Tibber or smartenergy.at) to minimize costs.
- Incorporates PV forecasts to prioritize charging during periods of high solar output.
- Reduces grid dependency and maximizes self-consumption by combining cost and solar production data.
- Energy Optimization Scheduling:
- Displays timestamps for the last and next optimization runs.
- Tracks system performance and optimization results.
- Real-Time Monitoring:
- View current system states, including battery SOC, grid charge power, and EVCC modes.
- Dynamic icons and color-coded indicators for easy visualization.
- User Controls:
- Set grid charge power and override system modes directly from the interface.
- Configure EVCC charging behavior with intuitive controls.
- Home Assistant:
- Full MQTT integration with Home Assistant Auto Discovery.
- Automatically detects and configures energy system entities.
- OpenHAB:
- Integrates with OpenHAB for monitoring and controlling energy systems.
- Publishes system states and subscribes to commands via MQTT.
- EVCC (Electric Vehicle Charging Controller):
- Monitors and controls EVCC charging modes and states.
- Supports fast charge, PV charging, and combined modes.
- Inverter Interfaces:
- OPTION 1: Communicates directly with a Fronius GEN24 to monitor and control energy flows.
fronius_gen24: Enhanced interface with firmware-based authentication for all firmware versionsfronius_gen24_legacy: Legacy interface for corner cases or troubleshooting
- OPTION 2: Use the evcc external battery control to interact with all inverter/ battery systems that are supported by evcc (hint: the dynamic max charge power is currently not supported by evcc external battery control)
- OPTION 3: using without a direct control interface to get the resulting commands by EOS connect MQTT or web API to control within your own environment (e.g. Integrate inverter e.g. sungrow SH10RT #35 )
- Retrieves real-time data such as grid charge power, discharge power, and battery SOC.
- OPTION 1: Communicates directly with a Fronius GEN24 to monitor and control energy flows.
- MQTT Broker:
- Acts as the central hub for real-time data exchange.
- Publishes system states and subscribes to control commands.
This project is in its early stages and is actively being developed and enhanced.
2025-04-10
- EOS made a breaking change - see here Akkudoktor-EOS/EOS#513
- there were also changes in the API at '<your_ip>:8503' - unfortunately the API is not versioned (ping ;-) )
- to fullfil both versions there is small hack to identify the connected EOS
- finally the current version can run with both EOS versions
2025-09-06
- Added Enhanced Fronius GEN24 Interface (
fronius_gen24) with intelligent authentication support:- ✅ Automatic Firmware Detection: Detects firmware version and selects optimal authentication method
- ✅ Universal Compatibility: Works with all firmware versions (< 1.36.5-1, 1.36.5-1 to 1.38.5-x, ≥ 1.38.6-1)
- ✅ Smart Authentication: MD5 for older firmware, SHA256 with MD5 fallback for newest firmware
- ✅ Optimized Performance: Reduces authentication overhead by using firmware-appropriate methods
- ✅ Better Error Handling: Clear troubleshooting guidance for authentication issues
- ✅ 100% Backward Compatibility: Drop-in replacement for previous interface
- Recommended: Default interface for all Fronius GEN24 installations
- Legacy Fallback: Use
fronius_gen24_legacyfor corner cases if needed
Get up and running with EOS Connect in just a few steps!
- Home Assistant (recommended for most users)
(Or see Installation and Running for Docker and local options) - An already running instance of EOS (Energy Optimization System)
EOS Connect acts as a client and requires a reachable EOS server for optimization and control. - Properly configured EOS for prediction (see EOS Configuration Requirements below)
- Add the ohAnd/ha_addons repository to your Home Assistant add-on store.
- Install both the EOS Add-on and the EOS Connect Add-on.
- Configure both add-ons via the Home Assistant UI.
- Start both add-ons.
The EOS Connect web dashboard will be available at http://homeassistant.local:8081 (or your HA IP).
- On first start, a default
config.yamlwill be created in the add-on’s config folder. - Edit this file via the Home Assistant add-on UI to set your EOS server address and other options.
- See the CONFIG_README for full configuration details.
- Open the web dashboard at http://homeassistant.local:8081 (or your HA IP).
- Check live data, forecasts, and system status.
- Integrate with your automation tools using the Web API or MQTT.
Important: EOS Connect requires specific prediction settings in your EOS instance. The default EOS configuration should work out-of-the-box, but verify these settings if you experience issues with forecasting.
In your EOS config.yml, ensure these prediction parameters are configured:
# EOS config.yml - Prediction and Optimization settings
prediction:
# Prediction horizon (default: 48 hours)
# EOS Connect requires at least 48 hours for proper optimization
hours_ahead: 48
optimization:
# Optimization horizon (default: 48 hours)
# Should match or be <= prediction hours_ahead
hours_ahead: 48- Optimization Requests: EOS Connect sends optimization requests to EOS on a configurable interval (e.g., every 3 minutes)
- No EOS Internal Scheduling: EOS Connect manages all timing - no internal EOS optimization intervals are used
- 48-Hour Forecasting: EOS Connect provides 48-hour load and PV forecasts to EOS for optimal decision making
- Short/No predictions: Verify
prediction.hours_ahead: 48in EOS config - Optimization errors: Ensure
optimization.hours_aheadis set to 48 or less than prediction horizon - EOS Connect timing: All optimization scheduling is handled by EOS Connect, not EOS internal timers
The default EOS configuration typically includes these 48-hour settings. If you've customized your EOS config, ensure these values are properly set.
For detailed EOS configuration, refer to the EOS documentation.
If you're new to Home Assistant add-ons, see the official documentation for help.
Not using Home Assistant?
See Installation and Running for Docker and local installation instructions.
EOS Connect is a self-running system that periodically collects:
- Local energy consumption data.
- PV solar forecasts for the next 48 hours.
- Upcoming energy prices.
Using this data, a request is sent to EOS, which creates a model predicting the energy needs based on different energy sources and loads (grid, battery, PV).
EOS Connect waits for the response from EOS (e.g., ~2 min 15 sec for a full 48-hour prediction on a Raspberry Pi 5). After receiving the response, it is analyzed to extract the necessary values.
Finally, the system sets up the inverter based on the following states:
MODE_CHARGE_FROM_GRIDwith a specific target charging power (based on your configuration).MODE_AVOID_DISCHARGE.MODE_DISCHARGE_ALLOWEDwith a specific target maximum discharging power (based on your configuration).
The system repeats this process periodically, e.g., every 3 minutes, as defined in the configuration.
Figure: EOS Connect process flow
Note: Due to my limited drawing skills ;-) , the principle diagram above was generated with the help of an AI image engine.
Data collection for load forecasting is based on your existing load data provided by an OpenHAB or Home Assistant instance (using the persistence of each system). EOS requires a load forecast for today and tomorrow.
Load data is retrieved from:
- Today one week ago, averaged with today two weeks ago.
- Tomorrow one week ago, averaged with tomorrow two weeks ago.
- Car Load Adjustment: If an electric vehicle (EV) is/ was connected, its load is subtracted from the household load to ensure accurate forecasting of non-EV energy consumption.
Load Sensor Requirements:
- Data Quality: The sensor must provide numeric values and in unit 'watts'.
- Value Handling: EOS Connect accepts both positive and negative values from your sensor. For the internal processing: all values are converted to absolute positive values for load calculations.
- Sensor Types: Use sensors representing the overall net household consumption. Expected that all additonal loads as ev charge or an optional load are included here.
(See Home Assistant Persistance for more details.)
Load data is retrieved from the last two days:
- From two days ago (00:00) to yesterday midnight.
- Car Load Adjustment: Similar to Home Assistant, the EV load is subtracted from the household load to isolate non-EV energy consumption.
EOS Connect supports multiple sources for solar (PV) production forecasts. You can choose the provider that best fits your location and needs. The following PV forecast sources are available and configurable:
-
Akkudoktor (default)
Direct integration with the Akkudoktor API for reliable PV forecasts. -
Open-Meteo
Uses the Open-Meteo API and open-meteo-solar-forecast Python library for library-based calculation -
Open-Meteo Local
Gathers radiation and cloud cover data from Open-Meteo and calculates PV output locally using an own model (experimental). -
Forecast.Solar
Connects to the Forecast.Solar API for detailed PV production forecasts. -
EVCC
Retrieves PV forecasts directly from an existing EVCC installation via its API. This option leverages EVCC's built-in solar forecast capabilities, including its automatic scaling feature that adjusts forecasts based on your actual historical PV production data for improved accuracy.
Energy price forecasts are retrieved from the chosen source (TIBBER or AKKUDOKTOR API). Note: Prices for tomorrow are available earliest at 1 PM. Until then, today's prices are used to feed the model.
The dashbaord of EOS connect is available at http://localhost:8081.
EOS Connect can be integrated with your smart home or automation tools using MQTT or its built-in web API. See below for details.
EOS Connect provides a RESTful web API for real-time data access and remote control.
All endpoints return JSON and can be accessed via HTTP requests.
Details
Base URL:
http://<host>:<port>/
(Default port is set in your config, e.g., 8081)
| Endpoint | Method | Returns / Accepts | Description |
|---|---|---|---|
/json/current_controls.json |
GET | JSON | Current system control states (AC/DC charge, mode, etc.) |
/json/optimize_request.json |
GET | JSON | Last optimization request sent to EOS |
/json/optimize_response.json |
GET | JSON | Last optimization response from EOS |
/controls/mode_override |
POST | JSON (see below) | Override system mode, duration, and grid charge power |
Show Example: /json/current_controls.json (GET)
{
"current_states": {
"current_ac_charge_demand": 2000,
"current_dc_charge_demand": 0,
"current_discharge_allowed": true,
"inverter_mode": "Discharge Allowed",
"inverter_mode_num": 2,
"override_active": false,
"override_end_time": null
},
"battery": {
"soc": 85.5,
"usable_capacity": 9000,
"max_charge_power_dyn": 5000
},
"evcc": {
"charging_mode": "pv",
"charging_state": true,
"current_sessions": [ ... ]
},
"state": {
"last_response_timestamp": "2024-06-01T12:00:00+02:00",
"next_run": "2024-06-01T12:03:00+02:00"
},
"timestamp": "2024-06-01T12:00:00+02:00",
"api_version": "0.0.1"
}Show Example: /controls/mode_override (POST)
Override the system mode, duration, and grid charge power.
Payload:
{
"mode": 1, // Integer, see mode table below
"duration": "02:00", // String, format "HH:MM"
"grid_charge_power": 2.0 // Float, kW (e.g., 2.0 for 2000 W)
}Response:
- On success:
{ "status": "success", "message": "Mode override applied" } - On error:
{ "error": "Invalid mode value" }
System Modes (mode field):
| Mode Name | Mode Number | Description |
|---|---|---|
Auto |
0 | Fully automatic optimization (default mode) |
ChargeFromGrid |
1 | Force battery charging from the grid |
Discharge |
2 | Force battery discharge |
Idle |
3 | No charging or discharging |
PVOnly |
4 | Charge battery only from PV (solar) |
How to Use:
- Get current system state:
GET http://localhost:8081/json/current_controls.json - Override mode and charge power:
POST http://localhost:8081/controls/mode_override
with JSON body as shown above.
You can use curl, Postman, or any HTTP client to interact with these endpoints.
Notes:
- The web API is always available on the configured port.
- All responses are in JSON format.
- The override will be active for the specified duration, after which the system returns to automatic mode.
- Invalid values will result in an error response.
EOS Connect publishes a wide range of real-time system data and control states to MQTT topics. You can use these topics to monitor system status, battery and inverter data, optimization results, and more from any MQTT-compatible tool (e.g., Home Assistant, Node-RED, Grafana, etc.).
MQTT Data Published
Base topic:
<mqtt_configured_prefix>/eos_connect/
(Set <mqtt_configured_prefix> in your config.yaml, e.g., myhome)
| Topic Suffix | Full Topic Example | Payload Type / Example | Description |
|---|---|---|---|
optimization/state |
myhome/eos_connect/optimization/state |
String ("ok", "error") |
Current optimization request state |
optimization/last_run |
myhome/eos_connect/optimization/last_run |
ISO timestamp | Timestamp of the last optimization run |
optimization/next_run |
myhome/eos_connect/optimization/next_run |
ISO timestamp | Timestamp of the next scheduled optimization run |
control/override_charge_power |
myhome/eos_connect/control/override_charge_power |
Integer (W) | Override charge power |
control/override_active |
myhome/eos_connect/control/override_active |
Boolean (true/false) |
Whether override is active |
control/override_end_time |
myhome/eos_connect/control/override_end_time |
ISO timestamp | When override ends |
control/overall_state |
myhome/eos_connect/control/overall_state |
Integer (see mode table) | Current overall system mode |
control/eos_homeappliance_released |
myhome/eos_connect/control/eos_homeappliance_released |
Boolean | Home appliance released flag |
control/eos_homeappliance_start_hour |
myhome/eos_connect/control/eos_homeappliance_start_hour |
Integer (hour) | Home appliance start hour |
battery/soc |
myhome/eos_connect/battery/soc |
Float (%) | Battery state of charge |
battery/remaining_energy |
myhome/eos_connect/battery/remaining_energy |
Integer (Wh) | Usable battery capacity |
battery/dyn_max_charge_power |
myhome/eos_connect/battery/dyn_max_charge_power |
Integer (W) | Dynamic max charge power |
inverter/special/temperature_inverter |
myhome/eos_connect/inverter/special/temperature_inverter |
Float (°C) | Inverter temperature (if Fronius V1/V2) |
inverter/special/temperature_ac_module |
myhome/eos_connect/inverter/special/temperature_ac_module |
Float (°C) | AC module temperature (if Fronius V1/V2) |
inverter/special/temperature_dc_module |
myhome/eos_connect/inverter/special/temperature_dc_module |
Float (°C) | DC module temperature (if Fronius V1/V2) |
inverter/special/temperature_battery_module |
myhome/eos_connect/inverter/special/temperature_battery_module |
Float (°C) | Battery module temperature (if Fronius V1/V2) |
inverter/special/fan_control_01 |
myhome/eos_connect/inverter/special/fan_control_01 |
Integer | Fan control 1 (if Fronius V1/V2) |
inverter/special/fan_control_02 |
myhome/eos_connect/inverter/special/fan_control_02 |
Integer | Fan control 2 (if Fronius V1/V2) |
evcc |
myhome/eos_connect/evcc |
JSON object | Charging state, mode, and session info (if enabled) |
status |
myhome/eos_connect/status |
String ("online") |
Always set to "online" |
control/eos_ac_charge_demand |
myhome/eos_connect/control/eos_ac_charge_demand |
Integer (W) | AC charge demand |
control/eos_dc_charge_demand |
myhome/eos_connect/control/eos_dc_charge_demand |
Integer (W) | DC charge demand |
control/eos_discharge_allowed |
myhome/eos_connect/control/eos_discharge_allowed |
Boolean | Discharge allowed |
- Monitor battery SOC in Home Assistant:
- Subscribe to
myhome/eos_connect/battery/socto get real-time battery state of charge.
- Subscribe to
- Track optimization runs:
- Subscribe to
myhome/eos_connect/optimization/last_runandmyhome/eos_connect/optimization/next_runfor scheduling info.
- Subscribe to
- Visualize inverter temperatures:
- Subscribe to
myhome/eos_connect/inverter/special/temperature_inverter(if Fronius V1/V2 inverter is connected).
- Subscribe to
- Check if override is active:
- Subscribe to
myhome/eos_connect/control/override_active.
- Subscribe to
You can use any MQTT client, automation platform, or dashboard tool to subscribe to these topics and visualize or process the data as needed.
Notes:
- The
<mqtt_configured_prefix>is set in your configuration file (seeconfig.yaml). - Some topics (e.g., inverter special values, EVCC) are only published if the corresponding hardware is present and enabled.
- All topics are published with real-time updates as soon as new data is available.
EOS Connect can be remotely controlled via MQTT by publishing messages to specific topics. This allows you to change system modes, set override durations, and adjust grid charge power from external tools such as Home Assistant, Node-RED, or any MQTT client.
MQTT Data Subscribed
Base topic:
<mqtt_configured_prefix>/eos_connect/
(Set <mqtt_configured_prefix> in your config.yaml, e.g., myhome)
| Topic Suffix | Full Topic Example | Expected Payload | Description / Effect |
|---|---|---|---|
control/overall_state/set |
myhome/eos_connect/control/overall_state/set |
Integer or string (mode) | Changes the system mode (see table below) |
control/override_remain_time/set |
myhome/eos_connect/control/override_remain_time/set |
String "HH:MM" |
Sets the override duration (e.g., "02:00") |
control/override_charge_power/set |
myhome/eos_connect/control/override_charge_power/set |
Integer (watts) | Sets the override grid charge power (e.g., 2000) |
You can set the system mode by publishing either the mode name (string) or the mode number (integer).
Only the following values are accepted:
| Mode Name | Mode Number | Description |
|---|---|---|
Auto |
0 | Fully automatic optimization (default mode) |
ChargeFromGrid |
1 | Force battery charging from the grid |
Discharge |
2 | Force battery discharge |
Idle |
3 | No charging or discharging |
PVOnly |
4 | Charge battery only from PV (solar) |
- Publish a message to the desired topic with the correct payload.
- The system will immediately process the command and update its state.
- You can use any MQTT client, automation platform, or script.
-
Set system mode to "Auto":
mosquitto_pub -t "myhome/eos_connect/control/overall_state/set" -m "Auto"
or
mosquitto_pub -t "myhome/eos_connect/control/overall_state/set" -m "0"
-
Force battery charging from grid:
mosquitto_pub -t "myhome/eos_connect/control/overall_state/set" -m "ChargeFromGrid"
or
mosquitto_pub -t "myhome/eos_connect/control/overall_state/set" -m "1"
-
Set override duration to 1 hour 30 minutes:
mosquitto_pub -t "myhome/eos_connect/control/override_remain_time/set" -m "01:30"
-
Set override grid charge power to 1500 W:
mosquitto_pub -t "myhome/eos_connect/control/override_charge_power/set" -m "1500"
Notes:
- The
<mqtt_configured_prefix>is set in your configuration file (seeconfig.yaml). - Payloads must match the expected format for each topic.
- Any value other than those listed for system mode will be ignored or rejected.
- These topics allow you to remotely control and override the energy management system in real time.
With the first start of EOS connect a default config.yaml will be generated in the \src folder. For full documentation for the different entries go to CONFIG_README
Note: With the default config and a valid EOS server IP/DNS name entry ('eos -> server') - EOS connect should be running out of the box with some static defaults as a start point for a step-by-step commissioning.
The tool will use historical data from Home Assistant's local database. By default, this database is configured with a retention period of 10 days.
To improve the accuracy of load forecasts, it is recommended to use data from the last 2 weeks.
You can extend the retention period by modifying the recorder configuration in Home Assistant's configuration.yaml file. If the recorder section is not already present, you can add it as shown below:
recorder:
purge_keep_days: 15 # Keep data for 15 daysAfter making this change, restart Home Assistant for the new retention period to take effect.
Note: Increasing the retention period will require more storage space, depending on the number of entities being recorded.
If you do not change the retention period, the tool will still work, but it will use the available 10 days of data, which may result in less accurate load forecasts.
No specific info yet.
The application will start fetching energy data from OpenHAB or HomeAssistant and processing it. You can access the web interface at http://localhost:8081. For local usage the port is configurable see CONFIG_README. For docker usage change the mapped port in docker-compose.yml.
To run this project, you need to have the following installed:
- Python >= 3.11
You can run EOS Connect in three ways. Choose the method that best fits your environment:
1. Home Assistant Add-on (Recommended for Home Assistant users)
- Easiest way if you already use Home Assistant.
- Install the EOS Add-on and EOS connect Add-on from the ohAnd/ha_addons repository.
- Configure both add-ons via the Home Assistant UI.
- Both EOS and EOS Connect will run as managed add-ons.
2. Docker (Recommended for most users)
- Works on any system with Docker and Docker Compose.
- Pull and run the latest image:
git clone https://github.com/ohAnd/EOS_connect.git cd EOS_connect docker-compose up --pull always -d - The web dashboard will be available at http://localhost:8081 by default.
- Configure by editing
src/config.yaml.
3. Local Installation (Advanced users, for development or custom setups)
- Requires Python 3.11+ and pip.
- Clone the repository and install dependencies:
git clone https://github.com/ohAnd/EOS_connect.git cd EOS_connect pip install -r requirements.txt python src/eos_connect.py - Configure by editing
src/config.yaml.
For all methods, you need a running instance of EOS (Energy Optimization System).
See the Quick Start section for more details.
Contributions are welcome! Please submit a pull request or open an issue for any suggestions or improvements.
Show Glossary
| Term / Abbreviation | Meaning |
|---|---|
| EOS | Energy Optimization System – the backend optimizer this project connects to. |
| SOC | State of Charge – the current charge level of your battery, usually in percent (%). |
| PV | Photovoltaic – refers to solar panels and their energy production. |
| EV | Electric Vehicle. |
| EVCC | Electric Vehicle Charge Controller – software/hardware for managing EV charging. |
| HA | Home Assistant – popular open-source smart home platform. |
| OpenHAB | Another open-source smart home platform. |
| MQTT | Lightweight messaging protocol for IoT and smart home integration. |
| API | Application Programming Interface – allows other software to interact with EOS Connect. |
| Add-on | A packaged extension for Home Assistant, installable via its UI. |
| Grid | The public electricity network. |
| Dashboard | The web interface provided by EOS Connect for monitoring and control. |
This project is licensed under the MIT License. See the LICENSE file for more details.
