Advanced Features

REST API

EOS Connect provides a comprehensive RESTful web API for real-time data access and remote control on port 8081 (configurable). All endpoints return JSON and can be accessed via HTTP requests.

Main Endpoints

Endpoint	Method	Description
/json/current_controls.json	GET	Current system control states (AC/DC charge, mode, discharge state) - reflects final combined state after all overrides
/json/optimize_request.json	GET	Last optimization request sent to EOS
/json/optimize_response.json	GET	Last optimization response from EOS
/controls/mode_override	POST	Override system mode, duration, and grid charge power
/logs	GET	Retrieve application logs with optional filtering
/logs/alerts	GET	Retrieve warning and error logs for alert system
/logs/clear	POST	Clear all stored logs from memory (file logs remain intact)
/logs/alerts/clear	POST	Clear only alert logs from memory
/logs/stats	GET	Get buffer usage statistics for log storage

API Examples

Get Current Control States

curl http://localhost:8081/json/current_controls.json

Response Example:

{
  "current_states": {
    "current_ac_charge_demand": 0,
    "current_dc_charge_demand": 10000.0,
    "current_discharge_allowed": true,
    "inverter_mode": "MODE DISCHARGE ALLOWED",
    "inverter_mode_num": 2,
    "override_active": false,
    "override_end_time": 0
  },
  "battery": {
    "soc": 23.8,
    "usable_capacity": 3867.11,
    "max_charge_power_dyn": 10000,
    "max_charge_power_fix": 10000,
    "charging_curve_enabled": true,
    "temperature": 25.4,
    "max_grid_charge_rate": 10000,
    "stored_energy": {
      "stored_energy_price": 0.000215,
      "duration_of_analysis": 96,
      "charged_energy": 12450.5,
      "charged_from_pv": 8500.0,
      "charged_from_grid": 3950.5,
      "ratio": 68.3,
      "charging_sessions": [
        {
          "start_time": "2025-12-21T11:58:06+00:00",
          "end_time": "2025-12-21T14:03:17+00:00",
          "charged_energy": 772.9,
          "charged_from_pv": 772.3,
          "charged_from_grid": 0.6,
          "ratio": 99.9,
          "cost": 0.0002,
          "is_inventory": true,
          "inventory_energy": 772.9
        }
      ],
      "last_update": "2025-12-22T10:15:00Z"
    }
  },
  "localization": {
    "currency": "EUR",
    "currency_symbol": "€",
    "currency_minor_unit": "ct"
  },
  "evcc": {
    "charging_state": false,
    "current_sessions": [...]
  },
  "state": {
    "request_state": "response received",
    "last_request_timestamp": "2024-11-14T22:28:56.678704+02:00",
    "last_response_timestamp": "2024-11-14T22:30:01.194684+02:00",
    "next_run": "2024-11-14T22:35:01.196502+02:00"
  },
  "used_optimization_source": "eos_server",
  "used_time_frame_base": 3600,
  "eos_connect_version": "0.2.01.138-develop",
  "timestamp": "2024-06-01T12:00:00+02:00",
  "api_version": "0.0.3"
}

Response Field Reference

current_states

Field	Type	Description
current_ac_charge_demand	Integer (W)	AC charge power demand from optimizer (after overrides)
current_dc_charge_demand	Float (W)	DC charge power demand from optimizer (after overrides)
current_discharge_allowed	Boolean	Whether battery discharge is allowed (final state after all overrides)
inverter_mode	String	Current inverter mode as human-readable text
inverter_mode_num	Integer	Current inverter mode as number (see mode table)
override_active	Boolean	Whether manual mode override is currently active
override_end_time	Integer (timestamp)	Unix timestamp when override ends (0 if not active)

battery

Field	Type	Description
soc	Float (%)	Battery state of charge percentage
usable_capacity	Float (Wh)	Current usable battery capacity
max_charge_power_dyn	Integer (W)	Dynamic maximum charge power (adjusted by temperature/SOC)
max_charge_power_fix	Integer (W)	Fixed maximum charge power from configuration
charging_curve_enabled	Boolean	Whether temperature-based charging curve is enabled
temperature	Float (°C)	Current battery temperature (if available)
max_grid_charge_rate	Integer (W)	Maximum allowed grid charge rate from configuration
stored_energy	Object	Battery price analysis results (see stored_energy section below)

stored_energy (Battery Price Analysis)

Field	Type	Description
stored_energy_price	Float (€/Wh)	Calculated cost per Wh of energy currently in battery
duration_of_analysis	Integer (hours)	How far back historical data was analyzed
charged_energy	Float (Wh)	Total energy charged in analysis period
charged_from_pv	Float (Wh)	Energy charged from solar PV
charged_from_grid	Float (Wh)	Energy charged from grid
ratio	Float (%)	Percentage of energy from PV vs grid
charging_sessions	Array	Detailed list of charging sessions (see charging_sessions below)
last_update	ISO timestamp	When this analysis was last updated

charging_sessions (Individual Sessions)

Field	Type	Description
start_time	ISO timestamp	When this charging session started
end_time	ISO timestamp	When this charging session ended
charged_energy	Float (Wh)	Total energy charged in this session
charged_from_pv	Float (Wh)	Energy from PV in this session
charged_from_grid	Float (Wh)	Energy from grid in this session
ratio	Float (%)	PV percentage for this session
cost	Float (€)	Cost of grid energy in this session
is_inventory	Boolean	Whether this session's energy is currently in the battery (LIFO model)
inventory_energy	Float (Wh)	How much energy from this session is still in the battery

localization

Field	Type	Description
currency	String	Currency code (e.g., EUR, USD, DKK)
currency_symbol	String	Currency symbol (e.g., €, $, kr)
currency_minor_unit	String	Minor unit name (e.g., ct for cents, øre)

evcc

Field	Type	Description
charging_state	Boolean	Whether any EVCC charger is currently active
charging_mode	String	Current EVCC charging mode (off, pv, minpv, now)
current_sessions	Array	Detailed data for each configured EVCC charger (vehicle status, charging details, etc.)

inverter

Field	Type	Description
inverter_special_data	Object / null	Fronius-specific telemetry data (temperatures, fan speeds) - only available for Fronius Gen24 inverters

state (Optimization Scheduler)

Field	Type	Description
request_state	String	Current state of optimizer (e.g., "response received")
last_request_timestamp	ISO timestamp	When the last optimization request was sent
last_response_timestamp	ISO timestamp	When the last optimization response was received
next_run	ISO timestamp	When the next optimization will run

Root Level Fields

Field	Type	Description
used_optimization_source	String	Which optimizer backend is being used (eos_server or evopt)
used_time_frame_base	Integer (seconds)	Optimization cycle time frame (3600 = 1 hour, 900 = 15 min)
eos_connect_version	String	EOS Connect software version
timestamp	ISO timestamp	When this response was generated
api_version	String	API version (current: 0.0.3)

Override System Mode

curl -X POST http://localhost:8081/controls/mode_override \
  -H "Content-Type: application/json" \
  -d '{
    "mode": 1,
    "duration": "02:00",
    "grid_charge_power": 2.0
  }'

Request Parameters:

• mode - Integer (see mode table below)
• duration - String, format "HH:MM"
• grid_charge_power - Float, kW (e.g., 2.0 for 2000 W)

Success Response:

{
  "status": "success",
  "message": "Mode override applied",
  "applied_settings": {
    "mode": 1,
    "mode_name": "ChargeFromGrid",
    "duration": "02:00",
    "grid_charge_power": 2000,
    "end_time": "2024-06-01T14:00:00+02:00"
  }
}

System Mode Reference

Mode Name	Mode Number	Description
Auto	-2	Fully automatic optimization (default mode)
StartUp	-1	System startup state
Charge from Grid	0	Force battery charging from the grid
Avoid Discharge	1	Prevent battery discharge
Discharge Allowed	2	Allow battery discharge
Avoid Discharge EVCC FAST	3	Avoid discharge with EVCC fast charge
Discharge Allowed EVCC PV	4	Allow discharge with EVCC PV mode
Discharge Allowed EVCC MIN+PV	5	Allow discharge with EVCC MIN+PV mode
Charge from Grid EVCC FAST	6	Grid charging during fast EV charge

Logging API

Get Recent Logs

# Get last 50 error logs
curl "http://localhost:8081/logs?level=ERROR&limit=50"

# Get logs since specific time
curl "http://localhost:8081/logs?since=2024-06-01T11:00:00Z"

Query Parameters:

• level - Filter by log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• limit - Maximum number of records (default: 100)
• since - ISO timestamp to get logs since that time

Get System Alerts

curl http://localhost:8081/logs/alerts

Response Example:

{
  "alerts": [...],
  "grouped_alerts": {
    "WARNING": [...],
    "ERROR": [...],
    "CRITICAL": [...]
  },
  "alert_counts": {
    "WARNING": 1,
    "ERROR": 0,
    "CRITICAL": 0
  }
}

Get Log Buffer Statistics

curl http://localhost:8081/logs/stats

Response Example:

{
  "buffer_stats": {
    "main_buffer": {
      "current_size": 3456,
      "max_size": 5000,
      "usage_percent": 69.1
    },
    "alert_buffer": {
      "current_size": 23,
      "max_size": 2000,
      "usage_percent": 1.2
    }
  }
}

Sensor Auto-Detection

EOS Connect automatically detects battery and grid sensor polarity using a lightweight energy balance validation. This ensures correct attribution of battery charging between PV and Grid — even if your sensors report inverted signs.

• What it solves: Prevents PV attribution at night when PV≈0 by recognizing inverted grid import sensors
• How it works: Tests 4 sign combinations and selects the one that balances PV + Grid + Battery = Load across recent samples
• Performance: Uses ≤200 samples from the last 48h; detection typically runs in <100 ms

Log Example:

[BATTERY-PRICE] Detected conventions: battery=negative_charging grid=negative_import (counts: 49,2,201,2 from 203 samples)

MQTT Integration

EOS Connect publishes real-time system data and control states to MQTT topics, and subscribes to control commands for remote system management.

Configuration

mqtt:
  enabled: true
  broker: localhost
  port: 1883
  user: mqtt_user
  password: mqtt_password
  tls: false
  ha_mqtt_auto_discovery: true
  ha_mqtt_auto_discovery_prefix: homeassistant

Published Topics (Read System State)

EOS Connect publishes comprehensive real-time data to these topics:

Topic Suffix	Type	Description
Optimization & Control
optimization/state	String	Current optimization request state ("ok", "error")
optimization/last_run	ISO timestamp	Timestamp of last optimization run
optimization/next_run	ISO timestamp	Timestamp of next scheduled run
control/overall_state	Integer	Current system mode (see mode table)
control/override_active	Boolean	Whether manual override is active
control/override_end_time	ISO timestamp	When override ends
control/override_charge_power	Integer (W)	Override grid charge power
control/eos_ac_charge_demand	Integer (W)	AC charge demand from optimizer
control/eos_dc_charge_demand	Integer (W)	DC charge demand from optimizer
control/eos_discharge_allowed	Boolean	Discharge allowed (final effective state after all overrides)
control/eos_homeappliance_released	Boolean	Home appliance scheduling released
control/eos_homeappliance_start_hour	Integer (hour)	Optimal home appliance start hour
Battery Data
battery/soc	Float (%)	Battery state of charge
battery/remaining_energy	Integer (Wh)	Usable battery capacity
battery/dyn_max_charge_power	Integer (W)	Dynamic maximum charge power
Inverter Data (Fronius Only)
inverter/special/temperature_inverter	Float (°C)	Inverter ambient temperature
inverter/special/temperature_ac_module	Float (°C)	AC module temperature
inverter/special/temperature_dc_module	Float (°C)	DC module temperature
inverter/special/temperature_battery_module	Float (°C)	Battery module temperature
inverter/special/fan_control_01	Integer	Fan control 1 status
inverter/special/fan_control_02	Integer	Fan control 2 status
EVCC Data (if configured)
evcc/[name]/mode	String	EVCC charging mode (off, pv, minpv, now)
evcc/[name]/connected	Boolean	Vehicle connection status
evcc/[name]/charging	Boolean	Active charging status
System Status
status	String	Always "online" when running

Subscribed Topics (Send Control Commands)

Control EOS Connect by publishing messages to these topics:

Topic Suffix	Expected Payload	Description
control/overall_state/set	Integer or String (see table)	Change system mode
control/override_remain_time/set	String "HH:MM"	Set override duration (e.g., "02:00")
control/override_charge_power/set	Integer (watts)	Set grid charge power (e.g., 2000)

System Mode Control Reference

When publishing to control/overall_state/set, use either mode name or number:

Mode Name	Mode Number	Description
Auto	-2	Fully automatic optimization (default)
Charge from Grid	0	Force battery charging from grid
Avoid Discharge	1	Prevent battery discharge
Discharge Allowed	2	Allow battery discharge

MQTT Command Examples

Set System to Automatic Mode

mosquitto_pub -t "myhome/eos_connect/control/overall_state/set" -m "Auto"
# or
mosquitto_pub -t "myhome/eos_connect/control/overall_state/set" -m "-2"

Force Grid Charging

mosquitto_pub -t "myhome/eos_connect/control/overall_state/set" -m "Charge from Grid"
# or
mosquitto_pub -t "myhome/eos_connect/control/overall_state/set" -m "0"

Set Override Duration to 1.5 Hours

mosquitto_pub -t "myhome/eos_connect/control/override_remain_time/set" -m "01:30"

Set Grid Charge Power to 1500W

mosquitto_pub -t "myhome/eos_connect/control/override_charge_power/set" -m "1500"

Monitor Battery SOC

mosquitto_sub -t "myhome/eos_connect/battery/soc"

Home Assistant MQTT Auto Discovery

When enabled (ha_mqtt_auto_discovery: true), EOS Connect automatically creates Home Assistant entities for all sensors and controls.

All entities are automatically organized under the EOS Connect device in Home Assistant.

External Integrations

Home Assistant Integration

Add-on Installation

1. Add repository: ohAnd/ha_addons
2. Install EOS Connect add-on
3. Configure via add-on UI
4. Enable MQTT in config for auto-discovery

Using Sensors

Configure sensor sources in config.yaml:

battery:
  source: homeassistant
  url: http://homeassistant:8123
  access_token: "your_long_lived_access_token"
  soc_sensor: sensor.battery_soc

OpenHAB Integration

load:
  source: openhab
  url: http://openhab:8080
  load_sensor: Load_Power

battery:
  source: openhab
  url: http://openhab:8080
  soc_sensor: Battery_SOC

EVCC Integration

As Data Source

evcc:
  url: http://192.168.1.100:7070

pv_forecast_source:
  source: evcc  # Use EVCC's PV forecasts

As Control Target

EOS Connect can monitor and control EVCC charging modes:

• PV-only charging
• Min+PV mode
• Fast charge
• Off

Fronius Inverter Integration

Enhanced Interface (Recommended)

inverter:
  type: fronius_gen24
  address: 192.168.1.12
  user: customer
  password: your_password
  max_grid_charge_rate: 5000
  max_pv_charge_rate: 5000

Legacy Interface

Use type: fronius_gen24_legacy for corner cases or troubleshooting.

EVCC External Battery Control

Universal interface for all EVCC-supported inverters:

inverter:
  type: evcc
  # Inverter controlled via EVCC's external battery API

Automation Examples

Home Assistant Automations

Charge Battery During Cheap Hours

automation:
  - alias: "Charge battery during low prices"
    trigger:
      - platform: numeric_state
        entity_id: sensor.electricity_price
        below: 0.15  # €0.15/kWh
    condition:
      - condition: numeric_state
        entity_id: sensor.eos_connect_battery_soc
        below: 80
    action:
      - service: mqtt.publish
        data:
          topic: "myhome/eos_connect/control/overall_state/set"
          payload: "Charge from Grid"
      - service: mqtt.publish
        data:
          topic: "myhome/eos_connect/control/override_remain_time/set"
          payload: "02:00"

Stop Discharge During High Load

automation:
  - alias: "Preserve battery during high consumption"
    trigger:
      - platform: numeric_state
        entity_id: sensor.house_power
        above: 5000  # 5 kW
    action:
      - service: mqtt.publish
        data:
          topic: "myhome/eos_connect/control/overall_state/set"
          payload: "Avoid Discharge"

Node-RED Flows

Use MQTT nodes to:

• Monitor EOS Connect status
• Trigger controls based on external events
• Create custom dashboards
• Log data to databases

Python Automation Script

import requests
import json

# Get battery status
response = requests.get('http://localhost:8081/api/battery')
battery = response.json()

# If SOC below 20% and prices are low, force charge
if battery['soc'] < 0.20:
    requests.post('http://localhost:8081/api/controls/mode',
        json={'mode': 'ChargeFromGrid', 'duration_minutes': 120})

Advanced Configuration Tips

Dynamic Battery Price Calculation

Enable for real cost tracking:

battery:
  price_calculation_enabled: true
  price_update_interval: 900  # 15 minutes
  price_history_lookback_hours: 96  # 4 days
  battery_power_sensor: sensor.battery_power
  pv_power_sensor: sensor.pv_power
  grid_power_sensor: sensor.grid_power
  price_sensor: sensor.electricity_price

Multiple PV Installations

pv_forecast:
  - name: Main_Roof_South
    azimuth: 180
    tilt: 25
    power: 5000
  - name: Garage_East
    azimuth: 90
    tilt: 15
    power: 2500
  - name: Carport_West
    azimuth: 270
    tilt: 10
    power: 3000

Solcast with Rate Limiting

pv_forecast_source:
  source: solcast
  api_key: "your_api_key"

# EOS Connect auto-extends to 2.5h intervals for Solcast
# to stay within 10 API calls/day limit

Temperature-Based Battery Protection

battery:
  charging_curve_enabled: true
  sensor_battery_temperature: sensor.byd_battery_temperature
  # Automatic power reduction in extreme temperatures

Next Steps