Core concepts
How sources, metrics and dashboard cards fit together.
First-run setup
The setup wizard, the admin password and the pages you'll use.
Data sources
Find the right source for your inverter, battery and other devices.
Everything in Epilykos follows one simple path. Sources read your equipment, each reading is saved under a name as a metric, and the cards on your dashboards show those metrics.
Sources
A source is one connection to a device or system: an inverter's Wi-Fi dongle, a Modbus cable, a Bluetooth battery, Home Assistant, an MQTT broker and so on. You add them in Settings → Sources, and most types can hold several devices, for example one card per dongle or per battery pack.
For each source, you choose which of its values to keep and what to call them. Sources that use a device profile (Modbus, RS232 and WiFi dongle) suggest names for you.
Data sources explains each type.
Metrics
A metric is a reading with a name, such as battery_soc or pv1_power. That name is what ties your
hardware to the dashboard: a card simply shows whichever metric you pick for it.
Naming conventions
- Use lowercase with underscores:
battery_voltage, notBatteryVoltage. - Be specific:
pv1_powertells you more thansolar. - Stick to the usual endings:
_power,_voltage,_current,_energy,_soc,_temp. - Number multiple solar strings:
pv1_power,pv2_power.
Bluetooth batteries name their readings for you, as bms_<name>_<key>, for example
bms_pack1_voltage.
Metric roles
Roles tell Epilykos which of your metrics is which: this one is the solar power, that one is the battery level, and so on. The setup wizard fills them in, and you can change them any time in Settings → Metrics → Metric roles. The power and energy charts, the daily and monthly tables, the energy, flow and cost cards, and your savings all rely on them.
| Role | Unit | Typical metric names |
|---|---|---|
| Solar power | W | pv_power, solar_power |
| Consumption (home use) | W | load_power, ac_output_power |
| Battery charge / discharge power | W | battery_power (one signed value fills both), or separate charge and discharge metrics |
| Grid import / export | W | grid_power, grid_import, grid_export |
| Battery SOC | % | battery_soc |
| Solar voltage | V | pv_voltage, pv1_voltage |
| Daily solar, consumption, battery charge and discharge, grid import and export | kWh today | daily_solar, pv_energy_today (reset at midnight by the inverter) |
| Generator power and daily generator energy | W, kWh today | generator_power, generator_energy_today (for inverters with a generator input) |
Missing a daily energy reading for one of the roles? A combined metric can work it out from power, or add up the readings of several inverters.
Cards and dashboards
A dashboard is a grid of cards, and each card shows one or more metrics as a flow diagram, a gauge, a chart, a table, a forecast and so on. You can have as many dashboards as you like (say "Overview", "Battery" and "TV display") and choose which one opens on computers and which on phones. See Layout editor.
How often readings update
Epilykos runs its main cycle every 30 seconds, and each source also has its own read interval. New readings are pushed to every open dashboard as they arrive, so there's no need to reload. Charts and tables fill in as history builds up.
Readings are kept in full for 30 days, and after that as 5-minute averages. Text readings, such as an inverter's mode, aren't kept beyond 30 days.
Who can see what
The dashboard is open to anyone who can reach it, without signing in. Settings, the layout editor, the card showcase and the Controls page need the admin password, and changing a device setting asks for it once more. See Security.
Last updated on