On this page

Home Assistant · Custom integration

Energy monitoring, costs & diagnostics

Configure suppliers and tariffs, track kWh and daily cost, optional solar estimation and multi-battery support — with a Lovelace card served from /hub_energie/.

At a glance

Overview #

This page is a guided companion to the README. Use the steps below in order when setting up for the first time.

  • Config flow: supplier (EDF vs custom), tariff (flat, HP–HC, multi-slot, EDF Tempo + RTE/API/sensor), grid and optional solar/battery wiring.
  • Energy: positive deltas from total_increasing meters → slot-day accounting (Paris day) and SSOT total sensors owned by the integration.
  • Costs: daily estimate (€), subscription split, per-slot detail in attributes.
  • EDF Tempo: colours, quotas, next-change times.
  • Diagnostics: réinjection split, data quality, delta telemetry, unknown bucket, staleness; health sensor (ok / degraded / rebuilding / inconsistent / no_input) with a readable cause.
  • Optional clear-sky PV and solar resale when configured.
  • Lovelace assets under /hub_energie/ after build.

  • Power-flow battery charge origin split when sensors are partial or noisy.
  • Solar production estimation (model-based, not a physical meter).
  • Opportunity-cost style diagnostics for exported kWh.
Behaviour depends on your hardware and entity choices (especially the Energy dashboard). The lists above describe intent, not a warranty for every edge case.

Data sources (SSOT) #

Knowing what is authoritative avoids misconfiguring the Energy panel or the wrong attributes.

  1. 1
    Physical meters (external SSOT)

    The energy entities you select (grid_import_energy, solar, export, per-battery in/out). Recorder history is ground truth for total kWh from hardware or upstream integrations.

  2. 2
    Internal accounting

    The coordinator accumulates positive deltas into totals and per-day slot kWh. Integration total_increasing SSOT sensors reflect this internal sum, not a full re-read of the meter every cycle.

  3. 3
    Long-term per-slot kWh (daily)

    After each Paris day, external statistics hub_energie:slot_<source>_<slot>_kwh are written. Use these (or physical meters) for historical analytics — not raw cost_detail attribute history alone.

Installation #

Install the repository exactly as one package under your HA config: 

<config>/custom_components/hub_energie/

Home Assistant must load custom_components/hub_energie/manifest.json. Avoid a nested folder such as hub_energie/hub_energie/.

Choose your path

  1. 1
    Add custom repository

    In HACS: menu (⋮) → Custom repositories → paste the GitLab URL → category Integration → Add.

    Screenshot: HACS → Custom repositories Replace this block with <img src="img/hacs-custom-repo.png" alt="…" />
    Optional — drop your PNG/WebP into public/img/ and reference it here.
  2. 2
    Download the integration

    HACS → Integrations → find Hub Énergie → Download. HACS installs from the custom_components/hub_energie/ folder in the repository (standard layout).

  3. 3
    Restart Home Assistant

    Full restart — not only “Reload YAML”. Then continue with Configure in HA below.

  1. 1
    Clone into the right folder
    git clone <your-repo-url> hub-energie-src
cp -a hub-energie-src/custom_components/hub_energie /path/to/homeassistant/config/custom_components/hub_energie
  2. 2
    Restart & add the integration

    Same as HACS: full restart, then Configure in HA.

  1. 1
    Copy the full tree

    From this repository, copy only the custom_components/hub_energie/ tree into your Home Assistant config/custom_components/hub_energie/ — all subfolders (battery/, energy/, frontend/, etc.). Do not copy the repo root into HA.

  2. 2
    Restart & add the integration

    Full restart, then Configure in HA.

If you use the Lovelace card

Build the frontend bundle once on the host where the files live: 

cd custom_components/hub_energie/frontend
npm ci
npm run build

Then restart HA again if needed. For reproducible installs, use a Git tag matching manifest.json version (e.g. v0.2.2).

Lovelace card #

Vite builds hub-energie-card-boot.js (registers hub-energie-card) plus chunks under frontend/dist/. HA serves them at /hub_energie/.

  1. 1
    Storage-mode dashboards (default)

    On startup the integration adds /hub_energie/hub-energie-card-boot.js as a JavaScript module (same as Settings → Dashboards → Resources). Usually nothing to do manually.

  2. 2
    YAML-managed resources

    Add the boot URL yourself:

    resources:
  - url: /hub_energie/hub-energie-card-boot.js
    type: module

    Replace legacy URLs such as /hub_energie/dist/hub-energie-card.js with the boot URL. Do not register duplicate modules for the same card.

  3. 3
    Add the card
    type: custom:hub-energie-card
# Optional: hide sections via card config
Screenshot: Dashboard with Hub Énergie card
Swap the placeholder for an <img> when you have a capture.

Configure in Home Assistant #

After a full restart, add the integration from the UI and walk through the config flow in this order:

1
Supplier
EDF or custom provider
2
Phase type
Single-phase or three-phase
3
Tariff
Auto (EDF) or manual: flat, TOU, schedule
4
Contract
Power (kVA), name
5
Grid sensors
Import energy (required), export, power
6
Solar
Energy, power, resale, optional PV estimation
7
Batteries
Per-battery in/out; optional power, SOC, capacity
Screenshot: Integrations → Hub Énergie → config flow
Helps readers match each step to the UI.

Device model #

One Home Assistant device per logical scope. Entity placement follows measured or configured domains; see CHANGELOG.md for finer detail.

Device Purpose
Offre Tariff, supplier, contract
Réseau Grid energy / power sensors
Solaire Solar measurement / estimation
Batterie <name> Per-battery system (0..N)
Batteries (total) Aggregated battery summary
Bilan énergétique Computed energy flows (kWh)
Coûts Monetary values (€)
Diagnostics Health, reinjection diagnostics

Services #

Service Description
hub_energie.refresh Force coordinator refresh
hub_energie.refresh_tariffs Re-fetch EDF tariffs (auto mode)

Limitations #

  • Recorder retention limits history, charts, and rebuild-from-recorder paths.
  • Optional solar estimation is clear-sky output — indicative, not a production meter.
  • The card’s power graph needs statistics; missing state_class or history can leave it empty.
  • Health states aggregate many checks; brief rebuilding after a recorder rebuild is expected.
  • Deep dives: docs/troubleshooting.md in the repository (trust, unknown bucket, recovery).

Measured, reconstructed, estimated #

Kind Meaning
Measured From configured HA entities (total_increasing kWh, power where wired).
Reconstructed Internal totals and per-slot kWh from deltas and optional recorder replay.
Estimated Model-based solar and other best-effort paths without a direct meter.