ČEZ Distribuce – integrace pro Home Assistant

Integrace pro Home Assistant, která získává data z portálu ČEZ Distribuce a z aplikace Proud.

Umožňuje sledovat stav HDO, odečty elektroměru, spotřebu, cenu elektřiny, poruchy a plánované odstávky. U chytrých elektroměrů podporuje také import hodinové spotřeby a dodávky do dlouhodobých statistik Home Assistantu.

Ukázky

Spotřeba

Přetoky a výroba

Instalace

Instalace přes HACS

1. Otevřete HACS → Integrace → ⋮ → Vlastní repozitáře.
2. Přidejte URL tohoto repozitáře a jako kategorii zvolte Integrace.
3. Vyhledejte integraci ČEZ a nainstalujte ji.
4. Restartujte Home Assistant.
5. Přejděte do Nastavení → Zařízení a služby → Přidat integraci → ČEZ.

Ruční instalace

1. Zkopírujte složku custom_components/cez do adresáře config/custom_components/ ve své instalaci Home Assistantu.
2. Restartujte Home Assistant.
3. Přejděte do Nastavení → Zařízení a služby → Přidat integraci → ČEZ.

Nastavení

Integrace vyžaduje přihlašovací údaje k portálu ČEZ Distribuce. Přihlášení prostřednictvím účtu Google nebo Apple zatím není podporováno.

Po přidání integrace zadejte:

• Uživatelské jméno – e-mail používaný pro přihlášení k portálu ČEZ Distribuce.
• Heslo – heslo k portálu ČEZ Distribuce.

Přihlášení probíhá přes přihlašovací službu ČEZ (CAS). Po ověření údajů se portál vrací přes endpoint common-api?path=/common/header, který založí kontext portálové relace. Teprve potom integrace načte API token a seznam odběrných míst. Návrat na kořenovou stránku /irj/portal se nepoužívá, protože může skončit chybou HTTP 404 ještě před dokončením inicializace portálu.

Pokud máte více odběrných míst, průvodce vás vyzve k výběru konkrétního místa. Při výběru HDO signálu nastavíte také:

• Cenu VT (Kč/kWh)
• Cenu NT (Kč/kWh)

Více odběrných míst

Každé odběrné místo (EAN) je v Home Assistantu samostatná položka integrace. Pro další EAN přidejte integraci znovu přes Nastavení → Zařízení a služby → ČEZ → Přidat položku, zadejte stejné přihlašovací údaje a v průvodci vyberte další odběrné místo. Pokud vyberete EAN, který už je nakonfigurovaný, průvodce skončí hláškou, že odběrné místo je již nakonfigurováno.

Účet s více prostředími (Domácnost a Podnikatel)

Pokud máte pod jedním e-mailem více prostředí portálu, například osobní účet (Domácnost) a podnikatelský účet (Podnikatel), portál po přihlášení v prohlížeči nabídne jejich výběr. Integrace tento krok provádí automaticky:

• Po přihlášení zkontroluje, zda portál výběr prostředí vyžaduje (landing?path=check). U účtů s jedním prostředím se nic dalšího neděje.
• V průvodci přidáním integrace načte odběrná místa ze všech prostředí a u každého místa zobrazí, do kterého prostředí patří.
• Do konfigurace uloží prostředí a partnera vybraného odběrného místa a při každém dalším přihlášení vybere právě toto prostředí.
• U položek vytvořených ve starší verzi integrace, které prostředí uložené nemají, integrace při startu sama dohledá prostředí, ve kterém je jejich EAN vidět, a uloží ho.

Například podnikatelský účet s jedním EAN a osobní účet se třemi EAN tak budou v Home Assistantu čtyři položky integrace se stejnými přihlašovacími údaji.

Změna hesla a rekonfigurace

• Pokud portál odmítne uložené heslo, Home Assistant nabídne opětovné přihlášení a vyzve vás k zadání nového hesla.
• Přes ⋮ → Překonfigurovat u položky integrace můžete změnit e-mail a heslo. Integrace přitom znovu dohledá prostředí portálu, ve kterém je odběrné místo vidět. Samotné odběrné místo (EAN) změnit nelze, protože jsou na něj navázané entity i dlouhodobé statistiky. Pro jiné odběrné místo přidejte novou položku integrace.

Dostupné entity

Entita	Typ	Popis
sensor.stav_hdo	Senzor	Aktuální stav HDO – VT nebo NT
sensor.spinani_hdo_dnes	Senzor	Počet intervalů NT pro dnešní den; podrobný rozpis je dostupný v atributech
sensor.spotreba_vt	Senzor (kWh)	Poslední naměřený stav elektroměru ve vysokém tarifu
sensor.spotreba_nt	Senzor (kWh)	Poslední naměřený stav elektroměru v nízkém tarifu
sensor.celkova_spotreba	Senzor (kWh)	Celkový odběr aktivní energie – součet VT a NT
sensor.aktualni_cena	Senzor (Kč/kWh)	Aktuální cena podle stavu HDO; ceny VT a NT se nastavují při konfiguraci
sensor.vysoky_tarif_start	Senzor	Začátek aktuálního nebo nejbližšího období VT
sensor.vysoky_tarif_konec	Senzor	Konec aktuálního nebo nejbližšího období VT
sensor.nizky_tarif_start	Senzor	Začátek aktuálního nebo nejbližšího období NT
sensor.nizky_tarif_konec	Senzor	Konec aktuálního nebo nejbližšího období NT
sensor.odpocet_do_konce_vysokeho_tarifu	Senzor (min)	Počet minut do konce aktuálního nebo nejbližšího období VT; ve výchozím stavu je skrytý
sensor.odpocet_do_konce_nizkeho_tarifu	Senzor (min)	Počet minut do konce aktuálního nebo nejbližšího období NT; ve výchozím stavu je skrytý
binary_sensor.porucha_odstavka	Binární senzor	Hlášená porucha nebo plánovaná odstávka
sensor.hodinova_data_spotreby_k	Diagnostický senzor	Konec poslední hodiny spotřeby importované do dlouhodobých statistik

Výroba a mikrozdroj

Pokud přidáte odběrné místo typu Výroba, Mikrozdroj nebo Výrobna bez licence (FVE; typ V, M nebo B z get_supply_points), vytvoří se jiná sada entit:

• nevytvoří se HDO a tarifové senzory ani sensor.spotreba_vt a sensor.spotreba_nt, protože se netýkají dodávky do sítě;
• místo sensor.celkova_spotreba se vytvoří sensor.celkova_dodavka_do_site;
• vytvoří se diagnostická entita sensor.hodinova_data_dodavky_k.

Podrobnosti o výpočtu dodávky do sítě najdete v části Celková dodávka do sítě.

Hodinová spotřeba

Important

Tato funkce vyžaduje chytrý elektroměr a používá neoficiální, reverzně analyzované API mobilní aplikace Proud, které je odlišné od API portálu dip.cezdistribuce.cz. ČEZ může toto API kdykoliv změnit bez předchozího upozornění. U odběrných míst bez chytrého elektroměru se import hodinových dat tiše přeskočí a ostatní části integrace fungují beze změny.

Pokud máte chytrý elektroměr, integrace stahuje hodinovou spotřebu a ukládá ji jako dlouhodobou statistiku Home Assistantu:

cez:<ean>_consumption

Statistiku lze zobrazit například pomocí karty Graf statistik nebo ji přidat jako zdroj do Energy dashboardu.

Ukázka YAML konfigurace karty statistics-graph:

type: statistics-graph
grid_options:
  columns: 24
  rows: 3
entities:
  - cez:812345678910111213_consumption
days_to_show: 3
period: hour
chart_type: bar-stack
stat_types:
  - change

Diagnostickou entitu Hodinová data spotřeby k najdete v Nastavení → Zařízení a služby → ČEZ → zařízení. Pokud se její hodnota přestane posouvat, import hodinové spotřeby pravděpodobně vázne. V takovém případě zkontrolujte log komponenty custom_components.cez.coordinator.

K ručnímu ověření a ladění bez spuštěného Home Assistantu slouží skript scripts/test_pnd_consumption.py. Podrobnosti jsou uvedené v komentářích přímo ve skriptu.

Za reverzní analýzu aplikace Proud a první implementaci děkuji Romanu Vohradníkovi.

Frekvence aktualizací

Data se aktualizují každou hodinu. Odečty elektroměru jsou na straně ČEZ obvykle dostupné jednou denně.

Celková dodávka do sítě

Pokud máte FVE nebo mikrozdroj, dodávka (přetok) do sítě je vedena jako samostatné odběrné místo s jiným EAN. V odpovědi get_supply_points má toto místo typ V (Výroba), M (Mikrozdroj) nebo B (Výrobna bez licence).

Integraci přidejte znovu přes Nastavení → Zařízení a služby → ČEZ → Přidat zařízení a v průvodci vyberte výrobní odběrné místo. Vytvoří se samostatná položka konfigurace:

• bez HDO a tarifových senzorů;
• se senzorem sensor.celkova_dodavka_do_site;
• s hodinovou statistikou cez:<ean>_production.

Zdroj dat pro celkovou dodávku

Historie odečtů z portálu (meter-reading-history, pole stavVt a stavNt) vrací i pro výrobní EAN registry odběru stejného elektroměru (+E VT/NT). Jde tedy o stejné hodnoty, jaké poskytuje spotřební EAN. Registr dodávky (−E) v této historii dostupný není; denní stav registru je viditelný pouze na Portálu naměřených dat.

Verze 2.0.7 tyto odečty sčítala jako „dodávku“, a proto výsledná hodnota v kWh odpovídala celkové spotřebě. Od verze 2.0.8 je sensor.celkova_dodavka_do_site kumulativním součtem hodinové dodávky z pnd/data s assemblyCode 06. Jde o stejná data, která se ukládají do statistiky cez:<ean>_production.

Je proto potřeba počítat s následujícím chováním:

• Hodnota se sčítá od nejstarší hodiny, kterou se podařilo získat. Při prvním spuštění se integrace pokusí dohledat až tři roky historie podle toho, odkdy je chytrý elektroměr dostupný.
• Nejde o stav registru −E od instalace elektroměru. Od hodnoty na Portálu naměřených dat se proto může lišit o dodávku před začátkem dostupné historie.
• Rozsah součtu zobrazují atributy od a do. Atribut statistic_id odkazuje na příslušnou dlouhodobou statistiku.
• Do Energy dashboardu doporučujeme přidat přímo statistiku cez:<ean>_production jako Vrácení do sítě, protože obsahuje celou dostupnou hodinovou historii.
• Entita zůstává ve stavu unknown, dokud se hodinová dodávka nenaimportuje. Pokud tento stav přetrvává, zkontrolujte diagnostickou entitu Hodinová data dodávky k a log integrace.

Ověření assemblyCode

Pokud víte, který assemblyCode vrací přímo stav registru −E, můžete pomoci s dalším vývojem. Spusťte:

scripts/test_pnd_consumption.py --ean <výrobní EAN> --assembly 02,04,06,08,10,12

Skript stáhne všechny uvedené kódy a vypíše srovnávací tabulku obsahující jednotku, časový krok, první a poslední hodnotu a součet. Anonymizovaný výstup prosím přiložte k issue #30.

MEPAS gateway nabízí pro výrobní a mikrozdrojové EAN samostatnou sadu sudých hodnot assemblyCode (02, 04, 06, 08, 10, 12) jako protějšek liché sady používané u spotřeby (01, 03, 05, 07, 09, 11) na stejném partnerovi. Seznam dostupný pro váš účet zjistíte příkazem:

scripts/test_pnd_consumption.py --status

Kód 05 u výrobního EAN vrací HTTP 400. Integrace proto používá kód 06, který podle živého ověření v issue #24 vrací přímo hodinovou energii v kWh. Jde o stejný vzor jako u kódu 05 pro spotřebu; hodnoty byly potvrzeny křížovou kontrolou proti kódu 02, který poskytuje 15minutový výkon v kW obdobně jako kód 03 u spotřeby.

Řešení problémů

Chyby při přihlášení

Hláška	Význam a řešení
Nesprávné přihlašovací údaje	Portál odmítl e-mail nebo heslo. Ověřte je přihlášením na dip.cezdistribuce.cz.
Portál ČEZ Distribuce po přihlášení vyžaduje akci	Portál chce potvrdit nové podmínky používání nebo smlouvu, případně se nepodařilo vybrat prostředí. Přihlaste se jednou na dip.cezdistribuce.cz v prohlížeči, potvrďte požadovaný krok a zkuste to znovu. Už nakonfigurovaná integrace se po potvrzení obnoví sama.
Odběrné místo této integrace není vidět v žádném prostředí portálu	EAN položky integrace už pod tímto účtem není dostupný v žádném prostředí. Zkontrolujte účet na portálu, případně položku překonfigurujte nebo přidejte znovu.
Nepodařilo se připojit k ČEZ API	Portál nebo síť nejsou dostupné, nebo se změnil přihlašovací proces. Home Assistant nastavení integrace zkouší opakovat automaticky; pokud problém přetrvává, zapněte debug logování.

Debug logování

Do souboru configuration.yaml přidejte:

logger:
  logs:
    custom_components.cez: debug

Po uložení konfigurace restartujte Home Assistant a následně zkontrolujte protokol. Při neplatné JSON odpovědi se v debug logu zobrazí stav HTTP, cílový host a cesta, názvy query parametrů, informace o přesměrování a bezpečný popis struktury případné HTML stránky (například názvy polí formuláře). Surové tělo odpovědi, hodnoty formulářových polí, cookies ani autorizační hlavičky se do tohoto diagnostického záznamu nevypisují. Před odesláním logu přesto zkontrolujte celý výpis a odstraňte všechny osobní údaje nebo přístupové údaje.

U účtů s více prostředími hledejte v logu řádky Landing check: a Výběr prostředí:. Ukazují, zda portál výběr vyžadoval a která prostředí nabídl; jména ani čísla partnerů se do nich nevypisují.

Intervaly přes půlnoc

Integrace správně slučuje navazující intervaly NT přes půlnoc. Například 22:00–24:00 a 00:00–00:16 vyhodnotí jako jeden souvislý interval 22:00–00:16.

Důležité informace

• Integrace využívá neoficiální REST API portálu ČEZ Distribuce a mobilní aplikace Proud.
• API i struktura odpovědí se mohou bez předchozího upozornění změnit.
• V případě problémů nejprve ověřte, zda používáte nejnovější verzi integrace, a přiložte relevantní debug log.