User Guide

Quick Start

Get EOS Connect running in 4 simple steps:

Step 1: Requirements

• Home Assistant (recommended for most users) OR
• Docker with Docker Compose OR
• Python 3.11+ for local installation
• Running EOS Server: You must have an instance of Akkudoktor EOS or EVopt already running and reachable

Step 2: Install

Option A: Home Assistant Add-on

1. Add repository: ohAnd/ha_addons
2. Option A: Install EOS Server add-on: Duetting/ha_eos_addon or thecem/ha_eos_addon
3. Option B: Install EVopt add-on: thecem/hassio-evopt
4. Install "EOS Connect" add-on
5. Easily configure the EOS_connect add-on using the Home Assistant add-on UI—no manual editing of config files is needed, and EOS or EVopt require no special setup. For advanced options or details, see the user-guide/configuration.
6. Start all add-ons

Option B: Docker

Option B: Docker

For EOS backend, see Akkudoktor EOS. For EVopt backend, see EVopt.

git clone https://github.com/ohAnd/EOS_connect.git
cd EOS_connect
docker-compose up --pull always -d

Option C: Local Python

Option C: Local Python

For EOS backend, see Akkudoktor EOS. For EVopt backend, see EVopt.

git clone https://github.com/ohAnd/EOS_connect.git
cd EOS_connect
pip install -r requirements.txt
python src/eos_connect.py

Step 3: Configure

Edit src/config.yaml with your system details:

# Minimum configuration
eos:
  server: 192.168.1.94  # Your EOS server IP
  port: 8503
  time_frame: 900  # 15-minute intervals

battery:
  capacity_wh: 11059
  max_charge_power_w: 5000

pv_forecast:
  - name: myPV
    lat: 52.5200
    lon: 13.4050
    azimuth: 180
    tilt: 25
    power: 5000

Step 4: Access Web Dashboard

Open your browser to:

• Home Assistant: http://homeassistant.local:8081
• Docker/Local: http://localhost:8081

EOS Configuration Requirements

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.

# 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

What EOS Connect Handles

• 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

Troubleshooting EOS Configuration

Data Collection Requirements

EOS Connect collects historical load data from your smart home platform to create accurate forecasts for optimization.

How Data Collection Works

EOS Connect is a self-running system that periodically collects:

• Local energy consumption data (from Home Assistant or OpenHAB)
• PV solar forecasts for the next 48 hours
• Upcoming energy prices

Home Assistant Data Collection

Load data is retrieved using time-based averaging:

• Today: One week ago, averaged with two weeks ago
• Tomorrow: One week ago, averaged with 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

Home Assistant Persistence Configuration

To extend retention, add this to your configuration.yaml:

# configuration.yaml
recorder:
  purge_keep_days: 15  # Extend to 15 days minimum

After editing, restart Home Assistant. Note that longer retention requires more storage space.

OpenHAB Data Collection

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

Note: Detailed OpenHAB persistence configuration guidance will be added in a future update.

Configuration Overview

EOS Connect uses a YAML configuration file (config.yaml) with the following main sections:

Common Tasks

For a detailed breakdown of the dashboard interface, see the Dashboard Overview.

Force Battery Charging from Grid

1. Open web dashboard
2. Select "ChargeFromGrid" mode
3. Set desired charge power (e.g., 3000 W)
4. Set override duration (e.g., 02:00 for 2 hours)
5. System will automatically return to Auto mode after duration

Switch to PV-Only Charging

1. Select "PVOnly" mode
2. Battery will only charge from solar surplus
3. Grid charging will be disabled

View Optimization Schedule

1. Check "Last Optimization" timestamp in dashboard
2. View "Next Optimization" countdown
3. Charts show planned battery SOC curve

Battery Energy Pricing

EOS Connect can track the cost of energy stored in your battery in three different ways. Understanding which pricing mode you're using helps you understand optimization decisions.

Three Battery Pricing Modes

Mode 1: Fixed Static Price (Default)

• Battery energy cost set to a single fixed value (€/Wh)
• Simple but inaccurate - doesn't reflect actual charging sources
• Configuration: battery.price_euro_per_wh_accu: 0.00004 (default)
• Use case: Quick setup when you don't have sensor data available

Mode 2: External Sensor-Based Price

• Battery cost comes from a sensor you provide (e.g., from Home Assistant)
• Can be dynamically updated by external systems
• Configuration: battery.price_euro_per_wh_sensor: sensor.battery_price
• Use case: Integration with other energy management systems that already calculate battery cost

Mode 3: Dynamic Historical Analysis (LIFO Inventory) - Recommended

• Analyzes actual charging history to determine real energy cost
• Automatically detects whether energy came from solar (PV) or grid
• Uses Last-In-First-Out (LIFO) inventory model for accurate current battery value
• Provides detailed charging session breakdown with costs
• Configuration: battery.price_calculation_enabled: true
• Use case: Most accurate representation of stored energy value for optimization

Setting Up Dynamic Price Calculation (Recommended)

This mode automatically calculates the real cost of energy currently in your battery by forensically analyzing your charging history over the past 48-96 hours.

Step 1: Enable Dynamic Calculation

battery:
  price_calculation_enabled: true  # Enable historical analysis
  price_update_interval: 900  # Update every 15 minutes (adjust as needed)
  price_history_lookback_hours: 96  # Analyze last 4 days (default: 96)

Step 2: Configure Required Sensors

Dynamic calculation requires 5 mandatory sensor feeds from your Home Assistant or OpenHAB:

battery:
  price_calculation_enabled: true
  
  # Real-time power sensors
  battery_power_sensor: sensor.battery_power        # Battery charge/discharge in W
  pv_power_sensor: sensor.total_pv_power           # Total PV generation in W
  grid_power_sensor: sensor.grid_power             # Grid import/export in W
  load_power_sensor: sensor.household_load         # Household consumption in W
  price_sensor: sensor.electricity_price           # Current market price in €/kWh or ct/kWh
  
  # Thresholds (adjust based on your system noise)
  charging_threshold_w: 50                         # Minimum power to count as "charging" event
  grid_charge_threshold_w: 100                     # Minimum grid import to attribute to grid vs PV

Step 3: Verify Sensor Conventions

Good news: You do not need to manually set sensor polarity. EOS Connect automatically detects and normalizes battery and grid conventions using an energy balance check:

• Battery Power: Auto-detected (charging vs discharging sign)
• Grid Power: Auto-detected (import vs export sign)
• PV Power: Always positive (production)
• Load Power: Always positive (consumption)
• Price Sensor: €/kWh or ct/kWh — auto-detected

How Dynamic Calculation Works

1. Event Detection: System scans your battery power history and identifies all periods where battery was charging (above threshold)
2. Source Attribution: For each charging period, compares PV generation vs grid import to determine energy source
3. Cost Assignment:
   • Energy from PV → valued at €0 (no per-kWh cost for solar generation)
   • Energy from Grid → valued at actual market price when charging occurred
4. Inventory Valuation (LIFO): Instead of averaging all sessions, uses Last-In-First-Out approach
   • Looks at most recent charging sessions
   • Works backward until reaching your current battery level
   • Results in accurate price reflecting the actual energy currently stored
5. Optimization Input: Final price is sent to optimizer so it knows when discharging is profitable

Viewing Battery Price Information

The Battery Overview screen shows detailed pricing information:

• Stored Energy Price Card - Shows current calculated price in ct/kWh (cents per kilowatt-hour)
• Price Label - Shows calculation method:
  • "Inventory Valuation" = Dynamic (LIFO) calculation
  • "External Sensor" = From sensor feed
  • "Fixed Value" = Static configured price
• PV Share Card - Shows what percentage of stored energy came from solar vs grid
• Recent Charging Sessions Chart - Visual timeline of charging events over analysis period
• Detailed Session Table - Lists all detected charging sessions with:
  • Session timing
  • Total energy charged (kWh)
  • PV vs Grid breakdown
  • Cost of that session (€)
  • Green highlight = Sessions currently in your inventory

Common Issues & Solutions

Example Configuration

Complete example for Home Assistant with common sensor entities:

battery:
  source: homeassistant
  url: http://homeassistant:8123
  access_token: your_long_lived_access_token
  
  # Pricing configuration
  price_calculation_enabled: true  # Enable dynamic calculation
  price_update_interval: 900       # Update every 15 minutes
  price_history_lookback_hours: 96 # Analyze 4 days of history
  
  # Required sensors
  battery_power_sensor: sensor.battery_power
  pv_power_sensor: sensor.pv_total_power
  grid_power_sensor: sensor.grid_power
  load_power_sensor: sensor.home_load_power
  price_sensor: sensor.tibber_current_price
  
  # Thresholds
  charging_threshold_w: 50
  grid_charge_threshold_w: 100
  
  # Feed-in price (for valuing PV surplus energy)
  feed_in_price: 0.04  # €0.04/kWh when not charging from grid

Battery Overview

The Battery Overview section displays comprehensive information about your battery system, including temperature monitoring and charging status.

Battery Information Displayed

Temperature Status Indicators

Battery temperature is displayed with visual indicators that show the battery's thermal status:

• Cold (Blue Snowflake) - Temperature below 0°C
  • Cold protection active to prevent battery damage
  • Charging power may be reduced or disabled
  • Battery will warm up gradually during operation
• Reduced Power (Orange Warning) - Temperature between 0-15°C or 45-55°C
  • Battery is outside optimal operating temperature range
  • Maximum charge power is reduced to protect battery lifespan
  • System will return to full power when temperature stabilizes in optimal range
• Optimal (Green Checkmark) - Temperature between 15-45°C
  • Battery is in ideal operating temperature range
  • Maximum charging power is available
  • No thermal restrictions applied
• Heat Protection (Red Fire) - Temperature above 55°C
  • Heat protection active to prevent battery damage
  • Charging power severely reduced or disabled
  • Ensure adequate ventilation around battery enclosure

Desktop vs Mobile View

The Battery Overview adapts its display based on screen size:

• Desktop View - Full temperature display showing "Temp: 25.1°C" with status icon in the charging power section
• Mobile View - Compact display showing temperature only when it affects charging power (e.g., "● 10.0kW | ❄ 5°C")
• Color codes remain consistent across all view sizes for quick recognition

Configuration

To monitor battery temperature, ensure the following is configured in your config.yaml:

battery:
  sensor_battery_temperature: sensor.your_battery_temp_sensor  # Required for temperature monitoring
  # Temperature threshold defaults (adjust if needed):
  # Cold protection: < 0°C
  # Reduced power: 0-15°C or 45-55°C  
  # Optimal range: 15-45°C
  # Heat protection: > 55°C

See Battery Configuration for detailed settings.

Troubleshooting

Common issues and solutions for EOS Connect.

Connection Issues

Optimization Issues

Data Collection Issues

Inverter Control Issues

MQTT Integration Issues

Getting Help

EOS/EVopt Server Setup

EOS Connect requires a running optimization backend to calculate energy strategies.

Installing the Optimization Backend

Option 1: Home Assistant Add-on

Install via Home Assistant add-on store:

• EOS: Duetting/ha_eos_addon or thecem/ha_eos_addon
• EVopt: thecem/hassio-evopt

Option 2: Docker

Run EOS in a separate Docker container (see EOS repository for docker-compose configuration).

Option 3: Local Installation

Clone and run EOS locally (requires Python). See EOS documentation.

EOS Server Configuration

Required EOS Prediction Settings

In your EOS configuration, ensure these are set:

prediction_hours: 48
pv_prognose_today: 0.0
pv_prognose_tomorrow: 0.0
eauto: 0
gesamtlast: 0.0

What EOS Connect Provides

EOS Connect automatically sends these values in optimization requests:

• PV forecasts (from your configured provider)
• Load predictions (from historical data or default profile)
• Current battery SOC
• Electricity price forecasts
• EVCC requirements (if configured)

Troubleshooting EOS Connection

• Connection refused: Check EOS server is running on configured port
• Timeout: Increase eos.timeout in config (default 180s)
• Wrong results: Verify EOS is in prediction mode, not using test data

Next Steps