⚡ Shelly Energy Analyzer

Self-hosted energy monitoring, cost tracking and smart automation for 115+ Shelly devices (Gen 1–4). No cloud. No subscription. No data lock-in.

⚠️ Please read before installing

This project is written with AI assistance. Code, documentation and this README are largely AI-generated and reviewed by a human, not the other way round. Treat it as a hobby project, not as audited software.

It is provided "as is", with no warranty and no liability of any kind — for errors, for wrong numbers, for lost or corrupted data, for damage to connected equipment, or for anything that follows from using it. You use it at your own risk.

Two things deserve saying plainly, because they touch money and real hardware:

The figures are estimates, not meter readings. Consumption, cost, CO2 and the tenant sub-metering reports are derived from what the devices report and from the tariff you configure. They are not calibrated, billing-grade measurements. Do not use them as the sole basis of a utility bill, a tenant settlement or any other claim — check them against the official meter first.

The automations switch real devices. PV-surplus control turns boilers, wallboxes and similar loads on and off. Wrong configuration switches the wrong thing; set it up deliberately and watch it before you leave it alone.

Not affiliated with, endorsed by, or supported by Shelly / Allterco. Product and brand names belong to their respective owners.

🎯 Why Shelly Energy Analyzer?

You bought Shelly EM / 3EM meters. You want to know how much you spend, when you spend it, and what to change — without your data leaving your home and without a monthly bill.

Commercial energy dashboards lock you into subscriptions, truncate history after a few months, ignore your actual tariff, and push you toward proprietary clouds. Shelly Energy Analyzer is a single self-hosted Flask web app that reads your Shellys directly over LAN and turns their data into 23 real dashboards with real-time cost, real-time CO₂ and real automation.

What it does that others don't

🎨 A dashboard you'll actually want to leave open — the Aurora skin puts glass cards over an animated circuit whose current is your current: the charge travelling behind the interface speeds up and changes colour with the live load, from teal at idle to rose at peak. Prefer the old look? Settings → Display → Design → Classic. Nothing was removed.
🚗☀️ Charging the car on sunshine costs nothing — and the log says so. Every other charge log multiplies kWh by your tariff. This one asks where the energy actually came from: each charge is split into the part that came from the sun, from your battery and from the grid, minute by minute, and only the grid part is billed. Open a charge and its curve unfolds, the area under it coloured by what was feeding the car at that moment — including the case that turns out to be the most common of all, several sources at once. Measured on a real installation: 116.60 € → 15.21 € for the same 90 days. See it
💰 Knows your exact tariff — fixed, time-of-use, dynamic spot market (EU via Energy-Charts / aWATTar, USA via EIA, Australia via AEMO), multi-step schedules with future price changes — and shows live € cost per device, per second
⚖️ One rule for every CO₂ figure — within an hour the house is one bus: every consumed kWh (owner or tenant) carries that hour's mix of grid import (live grid mix), direct PV (panel manufacturing) and battery discharge (what was stored, plus the storage's manufacturing). Feed-in is charged nothing and credited as "avoided in the grid". CO₂ tab, Costs, Plots, heatmap, MQTT and digests all read the same chain, so they always add up
☀️ Solar tab & PV forecast — where the roof's energy went and what served the house, today hour by hour, 30 days stacked by origin, month by month, battery cycles and round trip, records, season-adjusted economics and CO₂ payback — plus a 7-day PV/battery/grid expectation that calibrates the roof on its own measured output against Open-Meteo irradiance (no panel data needed)
🔀 Energy flow — an SVG hub diagram of PV, battery, grid, house and every consumer with animated flows, live in watts or per period in kWh
🔋 Battery tab — the last 24 h of charge/discharge power with the state of charge, a 7-day charge history (measured, once the analyzer has stored it), 30 days stacked by origin against discharge, the rhythm of the day with typical full/empty times, cycles with depth and round-trip efficiency, time spent full or empty, and what the battery earns in euros per month and per year
🌱 Real grid CO₂ intensity — EU via ENTSO-E (with cross-border flow correction), rest of the world via Electricity Maps (92 zones across North & South America, Asia, Oceania, Africa and the Middle East) — never a flat 380 g/kWh average
🔮 Trend + weather CO₂ forecast (6 h ahead) — per-hour-of-day median of the last 14 days × Open-Meteo wind / sun / temp / rain × per-zone generation-mix profile (150+ zones). Rendered as a dashed continuation of the main CO₂ chart, plus a 6-cell strip with weather icons
🧠 Built-in NILM — confirmed power steps are paired into runs and classified on size, run length, rhythm and time of day (a fridge is its 20-minute runs around the clock, not its wattage). ~30 built-in device profiles; when nothing fits, the pattern is named honestly with the candidates and their scores
☀️ PV surplus automation — state machine that switches boilers / wallboxes on when solar excess is available, off when it drops, with priority-ordered consumer list and debounce
⏰ Smart scheduling — finds the cheapest 1–12 h time block tomorrow from day-ahead spot prices and can push the schedule to a Shelly Gen2 relay automatically
🔐 Password-protected Shellys supported — Gen 1 (Basic auth), Gen 2 / 3 / 4 Plus / Pro (Digest auth), all on Windows / macOS / Linux. Per-host credentials with auto-detection of the correct scheme; setup wizard and device card prompt for the password whenever a device responds 401
🏠 Native Home Assistant integration via MQTT auto-discovery — sensors appear automatically, no extra YAML
📱 iOS & Android home-screen widgets — iOS via Scriptable (3 sizes), Android/any browser via PWA web widget (/w). Configurable profiles: choose which data sections to show (power, cost, spot price, CO₂, charts), filter by device, set refresh interval. Live preview in Settings before deploying
🌐 Full REST API v1 + InfluxDB line-protocol push + Prometheus /metrics for your own stack
🔒 100 % self-hosted — your energy data never leaves your LAN
🆓 Zero subscription — no cloud, no accounts, no analytics
⬆ Self-updating — background thread polls GitHub every hour for new releases; the Live tab shows a one-click banner to install or roll back to any of the last 10 versions, entirely from the browser

Who it's for

🏠 Home owners with any Shelly device — EM / 3EM, Plus 1PM, Pro 4PM, Plug S, dimmers, RGBW lights, roller shutters, and 115+ more models (Gen 1 through Gen 4)
☀️ PV / solar prosumers tracking self-consumption, autarky, feed-in and investment amortisation
🏢 Landlords needing per-tenant sub-metering and Nebenkostenabrechnung PDFs
⚡ Dynamic-tariff customers worldwide — Tibber, aWATTar, Ostrom, 1Komma5°, E.ON Spot in Europe; Griddy/Rhythm/ERCOT Retailers in Texas; Amber Electric in Australia; and anyone comparing their fixed contract against live wholesale prices
🔧 Home Assistant / Node-RED tinkerers pulling metrics into MQTT, InfluxDB or Prometheus
📊 Data nerds who want raw SQLite access, CSV/PDF/Excel exports and a REST API

⚡ Quickstart

git clone https://github.com/robeertm/shelly-energy-analyzer.git
cd shelly-energy-analyzer

# macOS
./start.command

# Linux
chmod +x start.sh && ./start.sh

# Windows
start.bat

Open https://localhost:8765 and follow the 12-step setup wizard — pick demo mode for a zero-hardware tour, or connect real Shellys via mDNS, set your tariff, and you're live. Every optional step is skippable.

No Shellys yet? Enable Demo Mode in Settings → Advanced to explore the full UI with realistic generated data. Great for seeing what the tool can do before buying hardware.

Screenshots

Every image on this page comes from simulated data — the app's own demo mode (Settings → Demo mode, or the setup wizard's "Try it with demo data"), or the reproducible installation scripts/simulate_dataset.py builds: a 9.8 kWp roof, a 10 kWh battery, a house meter, a tenant flat, an 11 kW wallbox and a signed grid meter over 60 days, written through the app's own storage layer. No real installation, meter reading or name appears here.

Aurora — desktop

Live	Costs	Heatmap

The live hero: what the house draws right now, over a circuit board whose charge runs at the speed of that same number — teal and slow when idle, red and fast under load.	Today / week / month / year with per-device breakdown and the month projection.	A year of consumption as a calendar, plus the hour-of-day grid.

NILM	Goals	Standby

Appliance signatures learned from the load curve alone.	Streaks, levels and savings targets.	What the house costs while nobody is using it.

Forecast	CO₂	Calibration

Consumption forecast with a confidence band.	Live grid intensity, the 6 h forecast and the footprint by period.	Meter structure and dated correction factors.

⚖️ One rule for every CO₂ figure

Within an hour the house is one bus: every consumed kWh — owner or tenant — carries that hour's mix of grid import, direct PV and battery discharge. Feed-in is charged nothing and credited as avoided in the grid. The same chain feeds the CO₂ tab, Costs, Plots, the heatmap, MQTT and the digests, so they always add up.

Origin & manufacturing	The last 24 hours, by source	Phone

Grid, PV (panel manufacturing) and battery (what was stored + storage manufacturing) per period; owner + tenant = house, always.	The Solar tab's 30 days: PV split into direct use, storage and feed-in, grid import under the line, autarky as a dashed curve.	The same table at phone width.

☀️ Solar, energy flow, outlook

Solar	Energy flow	Solar & storage outlook

From the roof into the house: what the production became and what served the load, autarky, self-consumption, money.	PV, battery, grid, house and every consumer as one hub — line width is energy, the dots run with the flow; live in watts or per period in kWh.	Seven days from the irradiance forecast, calibrated on the roof's own measured yield, then the season's average: PV, import, export, autarky and the month's end.

Solar — light	Solar — phone	Energy flow — phone

🔋 Battery

Now, 24 h, 7 days	Day by day, rhythm of the day	Cycles, use, what it earns

State of charge, power, today's in/out and the round-trip efficiency; the last 24 h of charge and discharge with the SOC on the right axis; a week of charge history — measured once the analyzer has stored it.	Thirty days of charged-from-the-sun / from-the-grid against discharged with each day's SOC range; the average day hour by hour, and when the battery is typically full or empty.	Full cycles with a per-year estimate, depth of discharge, capacity turnover, time spent full or empty, every detected cycle — and the euros: grid power replaced, feed-in given up, net benefit per month and per year.

Light	Phone

Plots	Settings

One row per device, its metrics side by side.	Every option the app has, including the skin picker.

☀️ Where the energy came from

The EV log does not multiply kWh by a tariff. It reconstructs, from the grid meter, the PV series and the battery, what was feeding the car at every minute — and charges only what was bought.

Charge log	One charge, unfolded

Solar / battery / grid for the window, what it cost, and what it would have cost bought entirely from the grid. Every charge carries its own three-colour bar and a Surplus charge badge when almost nothing was bought.	The curve of one charge, the area under it stacked by source: the sun carries it, the battery takes over as the sun drops, and the grid finishes the job. Hover for the exact kW per source at that minute; below it, how long each source actually ran.

Light	Phone	Phone — curve

Set it under Settings → EV Charging → Surplus charging: detect automatically (default), always split by source, or off. A charge the meters did not cover keeps the full tariff and says so — an unmeasured charge is never presented as free sunshine.

Aurora — light

Catppuccin Latte, not an inverted dark theme: its own palette, with accents darkened enough to hold contrast on a pale ground.

Live	Costs

Aurora — phone

Live	Costs	Heatmap	Goals

Classic

The design shipped up to v16.70, still selectable in Settings → Display → Design. With the skin off the dashboard is byte-for-byte what it was — this is not a compatibility mode.

Classic live

More classic screenshots (4K desktop, iPhone 16 Pro Max)

Live	Costs	Heatmap

Weather	CO₂	Anomalies

Forecast	Standby	Energy Flow

Goals	NILM

Plots	Compare	Schedule

Tariff comparison	Export	Control

Sync	Settings	Live (chart zoom)

Mobile:

Live	Costs	Heatmap

Forecast	Standby	Energy Flow

Widgets (iOS Scriptable / Android PWA)

Small	Medium	Large

Android / any browser: open /w and add to home screen — no app required.

Key Features

🎨 Two designs, one click apart

Aurora (default since v16.71.0) — Catppuccin palette, glass cards, a floating navigation rail, tabular figures, and a live hero above the device cards: what the house is drawing right now on a banded gauge, next to today's energy, today's cost, the solar share and the biggest consumer.
The background is the house's own current. Conductors with 45° elbows, junction nodes and charge travelling along them — the rate, the brightness and the hue all come from the live draw. At night it is nearly still; when the oven goes on it comes alive. A mains waveform along the bottom edge grows with the same number.
Classic — the flat card design shipped up to v16.70, unchanged and still selectable in Settings → Display → Design. It is not a compatibility mode: every rule of the new skin is scoped to an attribute the classic page never carries, so with the skin off the dashboard is byte-for-byte what it was.
Both designs have a light and a dark variant (Catppuccin Mocha and Latte), and the existing Theme setting keeps working across both.
Kind to the machine it runs on: 30 fps, capped pixel ratio, paused in a background tab, and no motion at all when the system asks for prefers-reduced-motion.

📊 Live Monitoring

Real-time power, voltage, current and grid frequency (Hz)
Neutral conductor current (I_N) for 3-phase devices — computed via phasor vector sum with per-phase power-factor angles
1-phase and 3-phase devices (L1 / L2 / L3 + total)
Live cost display (kWh x configured price)
Phase balance indicator for 3-phase devices (detects imbalance)
Interactive legend toggle on live plots (click L1/L2/L3/N to show/hide)
Day / Night / Auto theme switching — all tabs and charts respect the selected theme
Rolling 2 h history survives restarts and in-app updates — the live buffer is snapshotted every 30 s and restored on startup, so the chart comes back fully populated instead of refilling from scratch
Tariff schedule — define future price changes with start dates; the app automatically uses the correct price for any date range

💰 Cost Dashboard

Dedicated "Costs" tab with today / week / month / year overview
Monthly cost projection based on current usage
Previous month comparison (% change)
Per-device breakdown with cost share and bar chart
Solar-aware energy balance — with a PV and/or grid source configured, an Energy balance table breaks down each period into PV production, self-consumption, grid import, feed-in, battery discharge and self-sufficiency (kWh), then the money: grid drawn, feed-in earned, self-consumption saved, and the net electricity cost (grid drawn − feed-in earned). A separate tenant (billed) line prices any configured tenant sub-circuits at the full consumer tariff. Derived generically from the configured grid meter, PV/battery series and tenant device keys, so it works with any inverter/battery — Shelly-measured or bridged in via the external PV source.
CO2 tracking with real grid data — per-device CO2 footprint (Today / Week / Month / Year / Forecast in kg) using real hourly grid intensity. EU via ENTSO-E (EIC bidding zones + cross-border flow correction), rest of the world via Electricity Maps (92 global zones — USA CAISO/ERCOT/ISO-NE/NYISO/PJM/MISO, all Canadian provinces, Mexico, Brazil regions, Argentina, Chile, Japan by region, South Korea, Taiwan, China, India, Indonesia, Australia NEM, NZ, South Africa, Israel, Turkey, UAE, Saudi Arabia, …). Falls back to a configurable static intensity (g/kWh) if neither provider is configured.
Embodied CO₂ / solar footprint — self-consumed PV and battery output are not zero-carbon: the CO₂ tab shows the embodied (manufacturing) emissions of the panels and cells amortised over their output, the net footprint and effective intensity (g/kWh), and the CO₂ avoided by solar versus buying the same energy from the grid. Lifecycle factors are configurable (default 40 g/kWh for PV, 60 g/kWh for battery throughput).
Dynamic spot price comparison — shows what each period would cost with a dynamic tariff (EPEX Spot + configurable markup + VAT) alongside your fixed tariff; orange-highlighted delta per card
24h spot market price chart — rolling bar chart with colour-coded bars (green = cheap, red = expensive) and fixed-price reference line; shown in both desktop and web dashboard

⚡ Dynamic Spot Market Prices — Worldwide

Automatic price import from free public APIs — provider is auto-selected based on the chosen bidding zone:
- 🇪🇺 Europe — Energy-Charts (Fraunhofer ISE, 15-min resolution from Oct 2025) and aWATTar (hourly, history from 2015). 45 bidding zones: DE-LU, AT, CH, BE, BG, CZ, DK1/DK2, EE, ES, FI, FR, GB, GR, HR, HU, IE, IT (7 regions), LT, LV, ME, MK, NL, NO1–NO5, PL, PT, RO, RS, SE1–SE4, SI, SK. No API key needed.
- 🇺🇸 USA — EIA open data wholesale daily LMP per NERC region: US-CAL, US-CAR, US-CENT, US-FLA, US-MIDA (PJM), US-MIDW (MISO), US-NE (ISO-NE), US-NW (BPA), US-NY (NYISO), US-SE, US-SW, US-TEN, US-TEX (ERCOT). Free API key required (register at eia.gov/opendata/register.php).
- 🇦🇺 Australia — AEMO NEM dispatch feed: AU-NSW, AU-QLD, AU-SA, AU-TAS, AU-VIC. No API key needed.
Automatic currency conversion — USD and AUD prices are converted to EUR/MWh via daily ECB rates so all cost math and dashboards work unchanged regardless of which region you're in.
Background service backfills from oldest measurement timestamp, auto-dispatches by zone prefix — you pick a zone, the app picks the right provider.
Configurable markup (default 16 ct/kWh net) covering grid fees, taxes, and supplier margin
VAT toggle — apply your configured VAT rate on top of spot price + markup
Plots sub-tab "Dyn. Preis" — grouped bar chart comparing fixed vs. dynamic tariff costs per hour/day/week/month
Compare tab "vs. Dynamic Tariff" — one-click toggle to compare your fixed tariff against spot prices for any period
Negative wholesale hours are visible — the spot-price chart renders bidirectional bars (positive bars grow up from a zero line, negative ones hang below in a distinct purple), so the "you earn money" slots on a dynamic tariff are obvious at a glance. Cost math passes negative prices through 1:1, in line with how Tibber / aWATTar bill them

💱 Time-of-Use (TOU) Tariffs

Define multiple time-based electricity price zones (peak, off-peak, etc.)
Automatic cost calculation using the correct rate per time window
Configurable per day-of-week and hour range
Seamless integration with cost dashboard and exports

📈 Historical Analysis & Consumption Forecast

Plots for W / V / A / kWh / VAR / cos phi / Hz (grid frequency) / CO2 emissions / dynamic prices
CO2 emissions plot tab — hourly energy x real grid CO2 intensity (ENTSO-E), colour-coded bars by intensity level
Dynamic price plot tab — grouped bar chart comparing fixed tariff cost vs. spot market cost per period, with totals and delta display
Per-device and per-phase views
SQLite-based storage (fast range queries, WAL mode)
Consumption forecasting — linear regression with weekday/hourly seasonality on historical daily data; trend analysis (rising/falling/stable in %/month); projected costs for next month and next year; confidence bands; weekday and hourly profile charts with color-coded patterns (red = above average, green = below average)

🗓 Heatmap Calendar

Calendar-style heatmap showing daily energy consumption at a glance
Hourly heatmap view — spot usage patterns by hour-of-day vs. day-of-week
Two unit modes: kWh and g CO2 — CO2 mode uses real ENTSO-E hourly grid intensity data with distinct colour scheme
Colour intensity scales automatically to the selected period

🔍 Comparison Mode

Compare two arbitrary date ranges side-by-side (e.g. this week vs. last week)
Quick-compare buttons — one click to compare Month, Quarter, Half-Year or Year against the previous period
"vs. Dynamic Tariff" toggle — compare your fixed tariff costs against spot market prices for any period
Overlaid line charts for any metric (kWh, W, cost, ...)
Weekly granularity — aggregate daily data into ISO calendar weeks
Percentage delta indicators for quick at-a-glance diff

⚠️ Automatic Anomaly Detection

Rolling mean +/- N x sigma (configurable sigma multiplier) algorithm
Detects consumption spikes and unexpected dips in real time and in history
Anomaly log with timestamp, device, metric and deviation magnitude
Automatic periodic detection with configurable interval
Notification via Telegram, Webhook and E-mail

☀️ PV / Solar Dashboard & Amortization

Feed-in energy tracking (kWh exported to grid)
Self-consumption calculation (solar energy used locally)
Autarky rate (% of demand covered by own solar production)
Time-series chart of production, consumption and net grid draw
CO2 savings — displays avoided CO2 (kg), tree-day and car-km equivalents using real ENTSO-E grid intensity
PV amortization calculator — investment payback analysis with configurable investment amount, installation year, and panel degradation rate; shows annual savings, payback period, ROI after 20 years, total CO2 saved; amortization timeline chart with cumulative savings vs. investment crossover point
System config — configurable installed capacity (kWp), battery storage (kWh), embodied CO2 per kWp
External PV / battery data source — for systems not measured by a Shelly, pull PV production, battery power, battery state-of-charge and (optionally) the grid connection from Home Assistant entities (works with any inverter integrated in HA — Huawei, SolarEdge, Fronius, SMA, Kostal, Sungrow, …) or from MQTT topics. Ingested as synthetic pv / battery / grid_ext devices so autarky, self-consumption, energy-flow and battery SOC use real data. As an HA add-on it uses the Supervisor proxy — no URL or token needed

🔌 Standby Killer Report

Identifies devices with constant base load (standby consumers)
Per-device analysis: base load (W), annual standby kWh, annual standby cost, share of total
Risk classification (high / medium / low) based on annual standby cost
24h load profile per device with standby threshold line
Cost comparison bar chart sorted by savings potential

🌡️ Weather Correlation

Integration with OpenWeatherMap API — current weather display (temperature, humidity, wind, clouds)
Temperature vs. consumption correlation — Pearson correlation coefficient (r), scatter plot with trend line
Heating Degree Days (HDD) and Cooling Degree Days (CDD) analysis
kWh per HDD/CDD for heating/cooling efficiency assessment
Automatic interpretation (heating correlation / cooling correlation / no dependency)
Weather data persisted hourly in SQLite for historical correlation
Graceful handling when paired data is still being collected

⚡ Energy Flow Diagram

Visual energy flow: Grid -> House -> Devices and PV -> Self-consumption / Feed-in
Per-device consumption breakdown with percentage shares
Period selector (Today / Week / Month / Year)

📡 Home Assistant MQTT Integration

MQTT publisher for any MQTT broker (Mosquitto, HiveMQ, etc.)
Home Assistant auto-discovery — creates sensor entities automatically for each Shelly device
Publishes: power (W), voltage (V), current (A), energy (kWh), frequency (Hz), power factor, CO2 rate (g/h)
Per-phase metrics (L1/L2/L3) for 3-phase devices
Configurable broker, port, username/password, TLS, topic prefix, publish interval
Graceful fallback when paho-mqtt is not installed

🏠 Tenant Utility Billing (Nebenkostenabrechnung)

Multi-tenant support — assign Shelly devices to tenants via checkbox UI in settings
Per-tenant contact data — address, phone, email, VAT ID stored per tenant; automatically used as invoice recipient (no separate "customer" field needed)
Per-tenant annual utility bill with line items, subtotal, VAT, and gross total
Common area electricity — split among all tenants by person count
Pro-rated base fee allocation
Move-in date — billing calculation starts from the configured move-in date
Device exclusivity — devices assigned to one tenant are grayed out for others
PDF invoice export per tenant — customer data pulled from tenant profile
Invoice logo upload — upload PNG/JPG directly from Settings, no manual path entry
Cost comparison bar chart and kWh share pie chart
Donut chart for single-tenant view

🔌 ML-Enhanced NILM Appliance Detection

Non-Intrusive Load Monitoring — identifies which appliances are running from live wattage alone
~25 built-in device profiles (fridge, washing machine, dishwasher, EV charger, heat pump, etc.)
ML learning engine — k-means clustering on power transitions (step changes) to discover recurring appliance patterns automatically
Learned clusters matched against built-in database with confidence scoring
Cluster data persisted across sessions
Dedicated NILM statistics tab — top-10 pattern cards with sparkline plots, hourly activity heatmap, category donut chart, per-device breakdown, recent transitions timeline, appliance signature database reference

📤 Exports & E-mail Reports

CSV / PDF / Excel

CSV export for further analysis
Excel export — .xlsx with one sheet per device, optionally filtered by date range
Rich daily PDF report: 6 KPI tiles, device breakdown, stacked 24h chart, per-device mini-charts
Rich monthly PDF report: KPI tiles, comparison to previous month, weekday vs. weekend analysis, Top-5 consumer ranking

Invoices (PDF)

Professional A4 invoice with sender/recipient from BillingConfig
Invoice number format {Prefix}-{YYYY}-{MM}-001 (configurable prefix)
Optional company logo, coloured table header, alternating row shading
Per-device invoices: each device gets its own individual invoice PDF

Scheduled E-mail

Automated daily and monthly e-mail reports via SMTP with rich PDF attachments
Monthly e-mail invoice attachment — optional per device + combined
Send-now buttons for immediate on-demand delivery

🔔 Notifications

Telegram bot — threshold alerts (W, V, A, VAR, cos phi, Hz) with optional plots; daily & monthly summaries with kWh bar charts, CO2 charts, and dynamic spot price comparison (total spot cost, average price, per-device delta vs. fixed tariff)
E-mail reports — automated daily and monthly PDF reports now include spot price KPIs (total spot cost, average ct/kWh, current price, fixed tariff comparison)
Webhook notifications — HTTP POST to any endpoint (Home Assistant, n8n, Zapier, ...) on threshold breach or scheduled events; configurable JSON payload template

📦 Device Grouping

Logical groups across multiple physical Shelly devices
Aggregated energy, power and cost view per group

⏰ Device Scheduling

Create on/off schedules for Shelly Gen2 devices via the official RPC API
Visual schedule editor (time slots, days-of-week)
Manage and delete existing schedules directly from the app

🎛 Device Control

Control tab for directly operating Shelly devices from the dashboard (enable in Settings → Features)
Room assignment — organize devices into rooms (living room, kitchen, basement, …) with 58 selectable emoji icons; devices grouped by room in the Control tab, unassigned devices shown separately
Switches & plugs — on/off toggle with live power readout
Dimmers — brightness slider (0–100%) via Light.Set RPC (Gen 2+) with Gen 1 REST fallback
RGBW lights — colour picker (RGB), colour temperature slider (2700–6500 K), brightness
Roller shutters / covers — Open / Stop / Close buttons + position slider (0–100%) via Cover.GoToPosition RPC
Auto-detects device category from model ID and shows the appropriate controls
Works with password-protected devices (credentials from device config)

🗂 Supported Device Registry

115 Shelly models catalogued across all generations: Gen 1 (Classic), Gen 2 (Plus & Pro), Gen 3, Gen 4
Categories: energy meters, switches, plugs, dimmers, RGBW / lighting, covers / shutters, sensors, displays
Each entry carries: model ID, product name, generation, series, category, power metering flag, phase count, channel count, EMData history support
Searchable & filterable list in Settings → Advanced → Supported Devices — browse every recognized model with capability badges (⚡ Power, 📊 EMData, phase count, channels)
Discovery enriched: probe_device() resolves model IDs to human-readable product names (e.g. "Shelly Pro 3EM" instead of "SPEM-003CEBEU")

🔄 Data Sync

Pull historical data from Shelly devices into the local SQLite database
Sync progress bar with real-time status (e.g. "Device 2/3 - Chunk 5/12")
Retention policy: raw data compressed to monthly aggregates after 2 years

🧙 First-Run Setup Wizard (Web)

Browser-based 12-step wizard at /setup (auto-redirected on first launch when no devices are configured). Every optional step is skippable — you can race through the minimum setup in a handful of clicks or take your time and configure everything up-front:

Welcome — intro
Language & theme — 9 UI languages, dark/light/auto
Mode — pick demo mode (2 simulated Shellys, zero hardware) or real devices
Devices — mDNS auto-scan or manual IP (skipped in demo mode)
Tariff — price per kWh, base fee, VAT
Spot prices (optional) — bidding zone for Tibber/aWATTar/Ostrom
CO₂ (optional) — ENTSO-E / Electricity Maps zone and token
Solar (optional) — peak kWp, feed-in tariff, battery capacity
Notifications (optional) — Telegram bot token + chat ID, with live test button
Integrations (optional) — MQTT (Home Assistant), InfluxDB, Prometheus, all with test buttons
Widget (optional) — direct links to iOS (Scriptable) and Android/Web widget
Summary — checklist of what was configured vs skipped

🎭 Demo Mode

Activated with one click from the setup wizard ("Mode" step) or via POST /api/setup/enable-demo
Creates 4 simulated Shellys — a 3-phase house meter, a 1-phase garage switch, a wallbox and a signed grid meter (+ import / − export) — with realistic consumption profiles (morning + evening peaks, base load, stochastic jitter)
Adds the supply side too: a 4.2 kWp PV array and a 5 kWh battery, written to the same synthetic series an external inverter source uses. So the Solar dashboard, the Battery tab and the EV log's source split all work — the pages that need to know what fed the house, not just what it drew
The simulated month deliberately contains all three stories a source split has to tell apart: sunny midday surplus charges, afternoon charges that run into the evening (sun → battery → grid), and night charges that are pure grid
Populates historical CSVs so the dashboard shows real patterns immediately
Great for testing all features, screenshots, and demos without Shelly hardware
Toggle off anytime in Settings

🌐 Web Dashboard (Mobile-Friendly SPA)

Full single-page app (SPA) accessible from any device on the local network — the sole UI of the application
24 tabs:
- Live — real-time device cards with colour-coded power, sparkline charts, collapsible detail rows, NILM appliance chips, freeze button, time-scale selector
- Plots — interactive historical charts (W/V/A/VAR/cos φ) with phase selection, time ranges, and kWh totals (Plotly.js)
- Costs — per-device cost overview with ENTSO-E CO2 tracking, dynamic spot price comparison, and 24h spot market price chart; current spot price prominently displayed with color-coded delta
- Heatmap — interactive yearly calendar heatmap and weekday x hour heatmap; horizontally scrollable on mobile with readable 3-char month labels
- Solar — PV dashboard with feed-in, self-consumption, autarky %, CO2 savings, inline settings
- Weather — weather correlation analysis: consumption vs. temperature timeline
- Comparison — period-over-period comparison with device selectors, grouped bar chart, delta display
- CO2 — live grid intensity, 24h chart, fuel mix, per-device CO2 rates, summary cards
- Anomalies — detected events with type, timestamp, sigma, description
- Forecast — consumption forecast with history + prediction bar chart, weekday and hourly profile charts (Canvas-based, matching CO2 tab style)
- Standby — standby cost summary, per-device cards with risk badges, cost bar chart and 24h load profile (Canvas-based)
- Energy Flow — summary cards + per-device consumption breakdown chart with period selector
- NILM — ML pattern statistics: top-10 patterns with sparkline plots, hourly activity heatmap, category donut, per-device breakdown, transitions timeline, appliance signature database
- Export — PDF summaries, reports, invoices, Excel, ZIP bundles; inline preview
- Schedule — smart time-based scheduling for Shelly switches
- EV Log — electric vehicle charging session history, each charge split into the energy that came from PV, from the battery and from the grid, with only the grid share billed (surplus charging: auto / always / off)
- Tariff — electricity tariff comparison
- Battery — home battery / storage simulation
- Advisor — AI energy advisor with personalised tips
- Goals — energy saving goals with progress tracking
- Tenants — multi-tenant sub-metering and utility cost allocation
- Control — direct device control: switch toggles, dimmer sliders, RGB colour picker, roller shutter open/stop/close with position slider
- Sync — live data synchronisation log with status panel
Two designs — Aurora (glass + animated circuit, default) and Classic (up to v16.70), switchable in Settings → Display → Design
Dark / Light mode toggle with auto-detection and localStorage persistence
Full i18n — all 9 supported languages
Device order & visibility settings via gear icon modal
Gzip-compressed HTML (~75% smaller payload) for fast mobile page loads
Single-row horizontal scrolling nav bar — all tabs accessible without wrapping
Mobile-first design: bottom navigation, min 44px touch targets, 360px to 1920px viewport
SSL/HTTPS support — three modes: Auto (self-signed), Custom (Let's Encrypt / own certs), Off (plain HTTP)

📱 Widgets (iOS, Android, Web)

Configurable Widget Profiles

Multiple profiles — create unlimited widget profiles in Settings, each with its own data sections, device filter, and refresh interval
12 toggleable sections — Power, Today, Month, Forecast, Spot price, Spot chart, CO₂, CO₂ chart, Device list, Power 24h chart, Daily 7d chart, Hourly today chart
Device filter — per-profile checkbox selection of which Shellys to include
Live preview — see exactly how the widget will look (Small / Medium / Large) before deploying, with real data from your server
/api/widget?profile=<id> — API returns only the data sections enabled in the profile

iOS (Scriptable)

Native iOS home screen widget via the Scriptable app
Three widget sizes (small / medium / large) with progressively more detail
Spot price chart — color-coded bars relative to fixed tariff with reference line
CO₂ intensity chart — color-coded bars with green/dirty threshold lines
Power / Daily / Hourly charts — DrawContext mini bar charts on medium + large widgets
Tap-to-refresh — tapping opens a live detail view in Scriptable with per-device breakdown
Auto-refresh — configurable interval per profile (default 5 min)
Per-profile scripts — each profile generates its own Scriptable script (Copy / Download buttons)
Dark/Light mode support (follows iOS system appearance)

Android / Web (`/w`)

Standalone widget page at /w (or /w?profile=<id>) — works in any browser
PWA support — "Add to Home Screen" on Android/Chrome for a native app-like experience with ⚡ icon
Auto-refreshing — updates at the profile's configured interval
Dark/Light auto-detection — follows system prefers-color-scheme
All widget sections — power, spot price, CO₂, SVG mini charts, device list, link to full dashboard
No third-party app required — just open the URL and bookmark it

🔒 SSL / Let's Encrypt

SSL mode selector in Settings → Web Dashboard: Auto (self-signed), Custom (own certs), Off (HTTP only)
Let's Encrypt integration — use certbot certificates for trusted HTTPS without browser warnings
Certificate monitoring — daily background check of certificate expiry with color-coded status indicator (green >30d, orange ≤30d, red ≤7d)
Auto-renewal — optional automatic certbot renew when certificate is within configured threshold (default: 30 days); copies renewed certs to app directory

⏱ Smart Scheduling (Spot Price Optimizer)

Find cheapest time blocks from day-ahead spot market prices for running large appliances
Configurable duration (0.5–12 hours), shows average price and savings vs. daily average

🎚 Auto-Switching Rules (Spot-Price-Driven)

One rule per Shelly relay — "find today's cheapest N-hour block within hours X..Y on these weekdays, drive this relay ON during it and OFF outside"
Optional max-price filter so the rule only fires when the cheapest block actually drops below your threshold
Two safety layers before anything switches: each rule defaults to dry-run (decisions logged + shown in UI, no relay touched), and a global live switch sits above all rules. Both off by default — upgrading can never start toggling hardware unexpectedly
Never fights manual user toggles — the controller only turns a relay off if it itself turned it on. Daily run cap (default 1) prevents oscillation
Live decision panel in Settings with current decision badge (ON / OFF / IDLE / SKIP / NO DATA), the cheapest block found, today's run counter and any switching errors — auto-polls every 30 s so you can verify in dry-run that a rule fires when expected before going live

☀️ PV Surplus Control

Automatic relay switching based on solar excess power with state machine (IDLE → PENDING_ON → ON → PENDING_OFF)
Configurable thresholds (on/off), debounce timer, and priority-ordered consumer list
Switches on consumers (boiler, wallbox) when surplus exceeds threshold; switches off when surplus drops

🚗 EV Charging Log

Automatic detection of electric vehicle charging sessions from wallbox power patterns
Logs each session: start/end time, energy (kWh), peak power, duration, and cost
Monthly summary with total sessions, kWh, and cost breakdown
Charge-log link for a car app — a read-only /api/v1/ev/* a car tracker (e.g. EV Charge Tracker) can pull finished charges from: kWh, the split into sun / battery / grid, the cost of that mix, and the charge curve itself. It has a key of its own, which opens nothing but the charge log, and only hands out charges that have been over for a while — while a car is still drawing, the entry keeps growing and its id moves with it. Off by default; the switch in Settings brings its own key

💱 Tariff Comparison

Compare actual consumption costs across 8 pre-defined German electricity tariffs (Stadtwerke, Tibber, 1Komma5°, Ostrom, E.ON, Vattenfall, EnBW, HT/NT)
Simulates fixed, time-of-use, and dynamic spot tariff models
Shows annual savings potential per tariff

🔋 Battery Storage Monitoring

Track battery state of charge (SOC), charge/discharge cycles, and round-trip efficiency
SOC timeline chart, cycle detection, optimal charging time recommendations based on spot prices

📊 InfluxDB / Prometheus Export

InfluxDB: Push energy metrics via HTTP line protocol (v1.x + v2.x). Configurable interval, measurement name, authentication
Prometheus: Expose /metrics endpoint in text exposition format. Gauges for power, voltage, current, frequency per device/phase

🔌 REST API v1

Formalized API: /api/v1/devices, /api/v1/devices/{key}/samples, /api/v1/costs, /api/v1/spot_prices, /api/v1/co2, /api/v1/openapi.json
/api/v1/ev/info, /api/v1/ev/charges, /api/v1/ev/curve — the charge-log link above, behind its own token
Bearer token authentication, CORS headers, rate limiting

🤖 AI Energy Advisor

Rule-based tips from standby analysis, spot price spreads, consumption trends, and weather data
Optional LLM enrichment via Ollama (local), OpenAI, or Anthropic API for natural language summaries
Sorted by savings potential (€/year)

🏆 Gamification (Goals & Achievements)

Weekly and monthly consumption goals with auto-calculated targets (90% of previous period)
10 badges: Energy Saver, Standby Killer, Solar Champion, 7/30-day Streak, Night Saver, Peak Avoider, and more
Streak tracking with progress visualization

🏠 Multi-Location Support

Manage multiple sites (home, office, vacation home) with separate device sets
Optional separate databases per location
Location switcher in the web dashboard; aggregate view across all locations

🖥 Cross-Platform

macOS / Windows / Linux
One-click start scripts — opens dashboard at https://localhost:8765 in your default browser

Quick Start (End Users)

macOS

Double-click start.command

If macOS blocks it: run chmod +x start.command in Terminal first.

Windows

Double-click start.bat

Linux

chmod +x start.sh
./start.sh

Demo Mode

Demo Mode lets you test the full application without any Shelly devices — enable it in Settings → Advanced. It generates realistic live data (with jitter + load spikes) and CSV history for plots and exports.

Languages

The UI supports 9 languages. The app always starts in English — switch to any other language in Settings → Language during the session; the next restart resets back to English.

Code	Language
`en`	English (default)
`de`	German
`es`	Spanish
`fr`	French
`pt`	Portuguese
`it`	Italian
`pl`	Polish
`cs`	Czech
`ru`	Russian

Password-Protected Shellys

If you have set an admin password on your Shelly's web UI, the analyzer will reach it transparently — both the setup wizard and the Settings → Devices page prompt for the password whenever a device responds 401 Unauthorized.

Generation	Models	Auth scheme
Gen 1	Shelly 1, 1PM, 2.5, EM, 3EM, Plug S	HTTP Basic
Gen 2	Plus 1, Plus 1PM, Plus 2PM, Plus Plug S	HTTP Digest
Gen 3	Pro 1, Pro 1PM, Pro 4PM, Pro 3EM	HTTP Digest
Gen 4	latest Plus / Pro firmware	HTTP Digest

The HTTP client (io/http.py) registers per-host credentials, tries Digest first, parses the WWW-Authenticate header on 401, falls back to Basic if needed, and caches the working scheme so subsequent calls go through with one round trip. Works on Windows / macOS / Linux without any platform-specific code (built on requests.auth.HTTPDigestAuth / HTTPBasicAuth).

Credentials are stored in config.json per-device (username + password) and never returned to the browser — GET /api/devices only exposes the username and a has_password: bool flag, and PUT /api/devices/<key> honours the *** masked placeholder so the saved password isn't accidentally overwritten when you edit other fields.

All HTTP touch-points pick up the credentials automatically: the live poller, historical CSV sync, the local scheduler, switch toggling, firmware OTA, mDNS rescan and the "Probe" button on the Settings page.

Running From Source (Developers)

Requirements: Python 3.10+ (3.11+ recommended)

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -U pip
pip install -r requirements.txt
python -m shelly_analyzer

Updates (GitHub Releases)

The built-in updater checks the latest release on GitHub automatically.

If you are offline or GitHub is blocked by DNS/VPN/firewall, the app will show an "offline/timeout" message.
Download & install is only enabled when a newer version than the current one is available.
Version history — the updater shows the last 10 releases; you can install any of them, including older versions (downgrade).

To publish an update:

git add -A
git commit -m "Description of changes"
git push
git tag v14.3.6
git push origin v14.3.6

The GitHub Actions workflow will automatically build the release ZIP and publish it.

Changelog

See CHANGELOG.md for the full version history.

Name		Name	Last commit message	Last commit date
.github		.github
docs/screenshots		docs/screenshots
scripts		scripts
src/shelly_analyzer		src/shelly_analyzer
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SECURITY.md		SECURITY.md
config.example.json		config.example.json
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
start.bat		start.bat
start.command		start.command
start.sh		start.sh

Latest commit

History

Folders and files

Repository files navigation