Configuration Reference

Quick Navigation

Optimizer Configuration

Choose your optimization backend. EOS Connect ships with a built-in optimizer (local_evopt) that requires no external server, plus connectors to the Akkudoktor EOS server and the external EVopt server.

eos.source

eos.server

eos.port

Built-in Optimizer Settings (local_evopt)

These settings are only active when eos.source = local_evopt. They control the strategy, battery reserve, and optional grid limits used by the built-in MILP solver.

eos.local_evopt_charging_strategy

eos.local_evopt_discharging_strategy

eos.local_evopt_emergency_reserve_pct

eos.local_evopt_max_grid_import_w

eos.local_evopt_max_grid_export_w

eos.local_evopt_num_threads

eos.local_evopt_time_limit

eos.time_frame

eos.timeout

eos.dyn_override_discharge_allowed_pv_greater_load

eos.pv_battery_charge_control_enabled

eos:
  source: eos_server
  server: 192.168.1.50
  port: 8503
  time_frame: 3600
  dyn_override_discharge_allowed_pv_greater_load: true  # Enable

[OPTIMIZATION] Dynamic PV>Load override ACTIVATED for step 3 (14:00): PV=2500 Wh > Load=1800 Wh - discharge allowed overridden to TRUE

EVCC Configuration

evcc.url

Inverter Configuration

Configure inverter control for automated battery management.

inverter.type

inverter.address

inverter.user

inverter.password

Victron MultiPlus Configuration

Requirements:

• Victron MultiPlus 3-phase system (single-phase support is experimental)
• ESS (Energy Storage System) mode enabled on the Victron device
• Network connectivity between EOS Connect and the Victron device's IP address
• Default Modbus/TCP port: 502 (standard)

How It Works:

1. Discharge Allowed Mode: Normal ESS operation - Victron's internal logic manages battery discharge and grid interaction
2. Avoid Discharge Mode (Hold): ESS switches to External Control, setpoint writes 0W to all phases - prevents battery discharge and grid import
3. Charge from Grid: Positive power setpoint written to MultiPlus - inverter regulates grid import to charge batteries
4. Auto Restore: When EOS Connect disconnects, original ESS mode is automatically restored

inverter.max_grid_charge_rate

inverter.max_pv_charge_rate

Home Assistant Service Call Sequences

When using inverter.type: homeassistant, define the HA service calls to execute for each battery control mode. Each field accepts a JSON array of service call objects.

inverter.charge_from_grid

[
  {"service":"number.set_value","entity_id":"number.charge_power","data_template":{"value":"{{ power }}"}},
  {"service":"select.select_option","entity_id":"select.mode","data":{"option":"Charge"}}
]

inverter.avoid_discharge

[
  {"service":"select.select_option","entity_id":"select.sungrow_mode","data":{"option":"Backup"}}
]

inverter.discharge_allowed

[
  {"service":"select.select_option","entity_id":"select.mode","data":{"option":"Self Use"}}
]

Data Source

Define the primary data connection that EOS Connect uses to read sensor values and send control commands.

data_source.type

data_source.url

data_source.access_token

data_source.ssl_ignore

Troubleshooting Connection Errors

If you see SSL certificate errors like:

Step 1 (Recommended): Install a valid certificate using Let's Encrypt (free) via your reverse proxy or DNS.

Step 2: If Step 1 isn't feasible, enable this option in Settings → Data Source, then restart EOS Connect.

Example Configuration

data_source:
  type: homeassistant
  url: https://homeassistant.local:8123  # Self-signed certificate
  access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  ssl_ignore: true  # ⚠️ Only because of self-signed cert in private network

Battery Configuration

Configure your battery system for state-of-charge monitoring and optimization.

battery.source

battery.url

battery.soc_sensor

battery.access_token

battery.capacity_wh

battery.charge_efficiency

battery.discharge_efficiency

battery.max_charge_power_w

battery.min_soc_percentage

battery.max_soc_percentage

battery.charging_curve_enabled

battery.sensor_battery_temperature

battery.price_euro_per_wh_accu

Battery Price Calculation Sensors

To enable dynamic price calculation, configure these sensors in the web UI ( Settings → Battery):

battery.price_euro_per_wh_sensor

Dynamic Battery Price Calculation

battery.price_calculation_enabled

battery.price_update_interval

battery.price_history_lookback_hours

battery.battery_power_sensor

battery.pv_power_sensor

battery.grid_power_sensor

battery.load_power_sensor

battery.price_sensor

battery.charging_threshold_w

battery.grid_charge_threshold_w

battery.battery_price_include_feedin

Load Configuration

Configure how EOS Connect reads your household power consumption data.

load.source

load.url

load.access_token

load.load_sensor

load.car_charge_load_sensor

load.additional_load_1_sensor

load.additional_load_1_runtime

load.additional_load_1_consumption

Electricity Price Configuration

Configure dynamic electricity pricing for cost optimization.

price.source

price.token

price.fixed_price_adder_ct

price.relative_price_multiplier

price.fixed_24h_array

price.feed_in_price

price.feed_in_source

price.feed_in_zone

price.data_url

price.data_path

price.data_token

price.feed_in_static_adder

price.feed_in_multiplier

Dynamic Feed-In Pricing Comparison

Configuration Examples

# Example 1: Fixed German tariff
price:
  feed_in_source: fixed
  feed_in_price: 8  # 8 ct/kWh

# Example 2: Danish dynamic pricing with adjustment
price:
  feed_in_source: elpris_dk
  feed_in_zone: DK1
  feed_in_static_adder: 2.5  # +2.5 ct/kWh for transport
  feed_in_multiplier: 0.95    # Conservative: 95% of spot

# Example 3: EPEX-Spot with cost adjustment
price:
  feed_in_source: epex_spot
  feed_in_static_adder: -1.0  # -1 ct/kWh fee
  feed_in_multiplier: 1.0     # Full spot price

# Example 4: EVCC real-time feed-in tariff
price:
  feed_in_source: evcc  # Requires EVCC URL configured
  # EVCC feed-in prices are used as-is (no adjustments)
  # The EVCC charger provides real-time tariff data

price.feed_in_negative_price_switch

Smart Price Prediction (Energyforecast.de)

How It Works

Instead of simple price repetition or fixed markups, EOS Connect:

1. Learns the relationship between your primary source (e.g., Tibber) and EPEX spot prices
2. Calculates both multiplicative factor (for VAT) and offset (for grid fees)
3. Applies this learned pattern to future EPEX forecasts

When It Activates

• Primary Source First: Uses your configured source (Tibber, SmartEnergy, etc.)
• Smart Detection: Only triggers when tomorrow's prices aren't available
• Seamless: Real prices when available, intelligent predictions when needed

Configuration Parameters

price.energyforecast_enabled

price.energyforecast_token

price.energyforecast_market_zone

Example Configuration

price:
  source: tibber
  token: "YOUR_TIBBER_TOKEN"
  feed_in_source: fixed
  feed_in_price: 0.08
  feed_in_negative_price_switch: true

  # Smart price prediction with energyforecast.de
  energyforecast_enabled: true
  energyforecast_token: "YOUR_ENERGYFORECAST_TOKEN"
  energyforecast_market_zone: "DE-LU"

Benefits

• Early optimization: Start at 11am instead of waiting for 1pm Tibber update
• Smart learning: Automatically adapts to YOUR grid fees and taxes
• Handles negatives: Correctly applies grid fees even when EPEX is negative
• No manual calibration: No need for fixed_price_adder_ct
• 31.4% more accurate: Than simple price repetition (validated with real data)

Technical Details

Adaptive Learning Algorithm:

• Uses linear regression: customer_price = factor × epex_spot + offset
• Factor (typically 1.5-3.0): Captures VAT and percentage markups
• Offset (typically 5-15 ct/kWh): Captures fixed grid fees and taxes
• Timestamp-based alignment ensures accuracy regardless of fetch timing
• Requires minimum 6 hours of overlapping data for learning

Safety Checks:

• Factor must be between 0.5 and 5.0
• Offset must be within ±50 ct/kWh
• Falls back to simple repetition if validation fails

Supported Price Sources:

• Tibber (EUR - with smart price prediction)
• SmartEnergy AT (EUR - with smart price prediction)
• Stromligning (DKK - currency not yet supported)
• Akkudoktor (no effect - uses optimization prices)

Limitations

• EUR prices only: Currently supports EUR-based price sources (Tibber, SmartEnergy AT)
• Currency conversion: Support for DKK (Stromligning) and other currencies will be added when requested by users
• Minimum overlap: Requires at least 6 hours of overlapping price data to learn the pattern

Troubleshooting

PV Forecast Configuration

Configure solar generation forecasts from various providers.

pv_forecast_source.source

pv_forecast_source.use_real_data_correction

pv_forecast_source.api_key

pv_forecast_source.data_url

pv_forecast_source.data_path

pv_forecast_source.data_token

pv_forecast[].resource_id

pv_forecast[].lat

pv_forecast[].lon

pv_forecast[].azimuth

pv_forecast[].tilt

pv_forecast[].power

pv_forecast[].powerInverter

pv_forecast[].inverterEfficiency

pv_forecast[].horizon

Understanding the Horizon Parameter

The horizon parameter describes obstruction heights around your PV installation in different directions. Each value represents the elevation angle (height) of an obstacle that blocks sunlight from that direction.

Practical Examples

horizon: 10,20,10,15

horizon: 10t0.3,15t0.8

horizon: 10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10,10

horizon: 0,0,0,0,0,0,0,0,50t0.4,70,0,0,0,0,0,0,0,0

How to Determine Your Horizon Values

1. Visual assessment: Stand at your PV installation and identify obstacles (trees, buildings, mountains) in each direction
2. Measure obstacle HEIGHT: Use a smartphone app (e.g., clinometer/inclinometer) to measure the elevation angle of the top of each obstacle:
   • Point the app at the top of the obstacle (roof edge, tree crown, mountain peak)
   • The angle shown is the obstruction height – this is what you enter as the horizon value
   • Example: Building top appears at 35° elevation angle → enter 35 for that direction
3. Assign to segments: Divide 360° by your number of values (e.g., 18 values = 20° per segment) and assign measured obstacle heights to each segment
4. Test and refine: Start with measured values, then compare actual generation with forecast to fine-tune:
   • If forecast is higher than reality → obstacles are higher than measured (increase values)
   • If forecast is lower than reality → obstacles are lower than measured (decrease values)

MQTT Configuration

Configure MQTT broker connection and Home Assistant Auto Discovery.

mqtt.enabled

mqtt.broker

mqtt.port

mqtt.user

mqtt.password

mqtt.tls

mqtt.ha_mqtt_auto_discovery

mqtt.ha_mqtt_auto_discovery_prefix

Other Configuration Settings

General application settings and behavior.

refresh_time

time_zone

eos_connect_web_port

log_level

request_timeout

Understanding refresh_time and time_frame

Optimization Configuration

Important timing and configuration concepts for optimization requests and responses.

Understanding refresh_time and time_frame

Time Slot Configuration & Optimizer Constraints

The time_frame setting determines the granularity of optimization data:

EVCC as Price Source (price.source: evcc)

Use EVCC (Electric Vehicle Charging Controller) as your price source when you have an EVCC instance managing your electricity pricing or tariff data.

When to Use EVCC Price Source

• EVCC Integration: You already have EVCC configured with tariff/pricing data
• Unified Control: Want to use the same EVCC instance for both EV charging and battery optimization
• Automatic Tariff Sync: Tariff rates automatically synchronize between EVCC and EOS Connect
• Multiple Tariffs: Need access to both grid consumption prices and feed-in tariffs from EVCC

Configuration Steps

1. Configure EVCC Interface:
   • Set evcc.enabled: true
   • Set evcc.url to your EVCC instance (e.g., http://evcc.local:7070)
2. Enable EVCC Price Source:
   • Set price.source: evcc
   • price.token should remain empty (EVCC API doesn't require authentication)
3. Optional - Add Feed-In Tariff (EVCC 0.132+):
   • If your EVCC instance publishes /api/tariff/feedin data, it will be used automatically for feed-in pricing
   • Set price.feed_in_source: evcc to use EVCC's published feed-in tariff

EVCC Price Data Format

EVCC provides electricity prices via the grid tariff API endpoint with 15-minute resolution:

GET http://evcc.local:7070/api/tariff/grid

Response:
{
  "rates": [
    {
      "start": "2026-06-15T00:00:00+02:00",
      "end": "2026-06-15T00:15:00+02:00",
      "value": 0.3236
    },
    {
      "start": "2026-06-15T00:15:00+02:00",
      "end": "2026-06-15T00:30:00+02:00",
      "value": 0.3113
    }
  ]
}

Price Unit Conversion

Important: EVCC provides prices in EUR/kWh. EOS Connect automatically converts these to EUR/Wh for internal calculations:

• EVCC price: 0.120 EUR/kWh
• Converted: 0.000120 EUR/Wh (÷ 1000)
• Display: Always shown in EUR/kWh in the web UI

Automatic Updates

EVCC prices are fetched:

• On startup: Initial price load
• Every refresh cycle: Default 10 minutes (configurable via refresh_time)
• On configuration change: When price.source is changed to/from evcc, prices are fetched immediately (hot-reload)
• On EVCC URL change: Automatic reconnection with new URL

Troubleshooting EVCC Price Source

Example Configuration (config.yaml)

evcc:
  enabled: true
  url: "http://evcc.local:7070"

price:
  source: evcc
  token:                    # Leave empty for EVCC
  feed_in_source: evcc      # Optional: if EVCC publishes /api/tariff/feedin

{
  "data": [
    {
      "start": "2024-06-12T14:00:00Z",
      "end": "2024-06-12T15:00:00Z",
      "value": 0.25
    },
    {
      "start": "2024-06-12T15:00:00Z",
      "end": "2024-06-12T16:00:00Z",
      "value": 0.28
    }
  ]
}

{
  "entity_id": "sensor.grid_prices",
  "attributes": {
    "data": [
      {"start": "2024-06-12T14:00:00Z", "end": "2024-06-12T15:00:00Z", "value": 0.25},
      {"start": "2024-06-12T15:00:00Z", "end": "2024-06-12T16:00:00Z", "value": 0.28}
    ]
  }
}

{
  "prices": [
    {"start": "2024-06-12T14:00:00Z", "end": "2024-06-12T15:00:00Z", "value": 0.25},
    {"start": "2024-06-12T15:00:00Z", "end": "2024-06-12T16:00:00Z", "value": 0.28}
  ]
}

POST /api/config/test-timeseries
Content-Type: application/json

{
  "source": "price",
  "data_url": "http://homeassistant.local:8123/api/states/sensor.grid_prices",
  "data_path": "attributes.data",
  "data_token": "eyJhbGciOiJIUzI1NiI..."
}

{
  "success": true,
  "message": "Successfully fetched 24 price values",
  "sample_count": 24,
  "first_entry": {
    "start": "2024-06-12T14:00:00Z",
    "end": "2024-06-12T15:00:00Z",
    "value": 0.25
  },
  "last_entry": {
    "start": "2024-06-13T14:00:00Z",
    "end": "2024-06-13T15:00:00Z",
    "value": 0.22
  }
}

[
  {
    "service": "select.select_option",
    "entity_id": "select.mt1_betriebsmodus",
    "data": {"option": "Manuell"}
  },
  {
    "service": "select.select_option",
    "entity_id": "select.mt1_erzwungene_operation",
    "data": {"option": "Zwangsladen"}
  },
  {
    "service": "number.set_value",
    "entity_id": "number.mt1_ziel_leistung_manuell",
    "data_template": {"value": "{{ power }}"}
  }
]