Proteus API Integration for Home Assistant

Integrace pro Home Assistant umožňující ovládání a monitorování fotovoltaické soustavy přes Proteus API od Delta Green.

Varování

• Používá nestabilní a nedokumentované API, takže se při změnách může rozbít.
• Stav se načítá jednou za 10 sekund.

Funkce

• Sensory - sledování stavu flexibility, zisku z flexibility, předpovědí výroby a spotřeby
• Binární sensory - sledování stavu manuálních ovládání
• Přepínače - ovládání manuálních funkcí a automatického režimu
• Automatická aktualizace - data se aktualizují každých 10 sekund
• Předpověď FVE v panelu Energie - hodinová předpověď výroby z Proteusu pro dnešek a zítřek, obnovovaná každých 15 minut

Instalace

Přes HACS (doporučeno)

1. Otevřete HACS v Home Assistant
2. V HACS tři tečky -> vlastní repozitáře -> zkopírovat URL adresu repozitáře na github: https://github.com/nijel/proteus-api-ha. Zvolit že to je integrace a Přidat.
3. Přejděte na Integrations
4. Klikněte na Explore & Download Repositories
5. Vyhledejte "Proteus API"
6. Klikněte na Download
7. Restartujte Home Assistant

Manuální instalace

1. Stáhněte nebo naklonujte tento repozitář
2. Zkopírujte složku custom_components/proteus_api do config/custom_components/proteus_api
3. Restartujte Home Assistant

Konfigurace

1. Přejděte na Nastavení → Zařízení a služby
2. Klikněte na Přidat integraci
3. Vyhledejte "Proteus API"
4. Zadejte požadované údaje:
   • E-mail a heslo: V Proteovi musí být nastavené přihlašování heslem (ne proklikem z https://moje.deltagreen.cz/, ale vytvořením přihlašovacích údajů na https://proteus.deltagreen.cz/)

Integrace automaticky objeví všechny invertory dostupné ve vašem účtu a vytvoří entity pro každý z nich.

Předpověď výroby v panelu Energie

V nastavení panelu Energie upravte zdroj Solární výroba a jako předpověď vyberte svou integraci Proteus API. Předpověď se zobrazí v grafu solární výroby. Senzor skutečně vyrobené energie nadále poskytuje integrace vašeho střídače. Po aktualizaci integrace restartujte Home Assistant, aby načetl metadata pro nabídku předpovědí.

U každého střídače jsou také senzory Předpověď výroby FVE dnes a Předpověď výroby FVE zítra s denním součtem v kWh a atributem wh_hours s hodinovou předpovědí ve Wh. Tyto senzory slouží k zobrazení a automatizacím; v nastavení předpovědi panelu Energie se vybírá celá integrace Proteus API.

Předpověď pochází z inverters.productionPredictions a používá hodinovou energii v Wh. Načítá se pro dnešek a zítřek podle časového pásma Home Assistantu; zobrazí se intervaly, pro které Proteus vrátí data. U účtu s více střídači jde o součet jejich předpovědí, proto tento účet vyberte u odpovídající celkové výroby jen jednou. Při dočasném výpadku zůstává dostupná poslední platná předpověď v tomto časovém rozsahu.

Dostupné entity

Sensory

• sensor.proteus_flexibilita_dostupna - Stav dostupnosti flexibility (USABLE/NOT_USABLE)
• sensor.proteus_rezim - Aktuální režim (AUTOMATIC/MANUAL)
• sensor.proteus_rezim_flexibility - Režim flexibility (FULL/NONE)
• sensor.proteus_obchodovani_flexibility_dnes - Dnešní odměna za flexibilitu (včetně DPH)
• sensor.proteus_obchodovani_flexibility_za_mesic - Měsíční odměna za flexibilitu (včetně DPH)
• sensor.proteus_obchodovani_flexibility_celkem - Celková odměna za flexibilitu (včetně DPH), state_class: total, použitelný jako kompenzace v Energy dashboardu
  • jednotkou všech tří je měna hlášená API (currencyCode, typicky CZK), bez ní CZK
• sensor.proteus_odmena_za_flexibilitu - Nulový nosič (0 kWh) pro napojení odměny za flexibilitu do Energy dashboardu; jeho název se zobrazí jako řádek v přehledu zdrojů, viz níže
• sensor.proteus_prikaz_flexibility - Aktuální příkaz flexibility
  • atributy: command_id, command_source, command_start, command_effective_end, command_is_testing, flexibility_price_kwh, price_up_kwh, price_down_kwh
  • UP_POWER - Dodávka do sítě
  • DOWN_BATTERY_SOLAR_CURTAILMENT_POWER - Odběr ze sítě
  • DOWN_SOLAR_CURTAILMENT_POWER - Zákaz přetoků
  • BALANCING_SERVICES - Výkonová rovnováha
  • NONE - Žádný
• sensor.proteus_cena_flexibility - Aktuální cena flexibility v Kč/kWh
  • atributy: flexibility_price_mwh, price_up_kwh, price_down_kwh
• sensor.proteus_konec_flexibility - Konec příkazu flexibility
• sensor.proteus_rezim_baterie - Režim baterie
• sensor.proteus_zalozhni_rezim_baterie - Záložní režim baterie
• sensor.proteus_rezim_vyroby - Režim výroby
• sensor.proteus_cilovy_soc - Cílový SOC baterie
• sensor.proteus_odhad_vyroby - Předpovězená výroba
• sensor.proteus_odhad_spotreby - Předpovězená spotřeba
• sensor.proteus_cena_spotreby - Aktuální cena spotřeby v Kč/kWh
  • atributy: price_consumption_mwh, price_mwh, commodity_price_from_grid_mwh, consumption_prices_type, distribution_price, distribution_tariff_type, fee_electricity_buy, fee_electricity_sell, tax_electricity, system_services, poze, vat_rate, price_list (kompletní ceník spotřeby na aktuální a další den, pole objektů {start, price_kwh})
• sensor.proteus_cena_vyroby - Aktuální cena výroby v Kč/kWh
  • atributy: price_production_mwh, commodity_price_to_grid_mwh, production_prices_type, fee_electricity_sell, price_list (kompletní ceník výroby na aktuální a další den, pole objektů {start, price_kwh})
• sensor.proteus_distribucni_tarif - Aktuální distribuční tarif (HT = High tariff, LT = Low tariff)
• sensor.proteus_plan_rizeni - Počet kroků v aktivním plánu řízení
  • atributy: steps (celý plán řízení - pole kroků s start, duration_minutes, flexalgo_battery, flexalgo_pv, target_soc, is_prediction, price_consumption_kwh, price_production_kwh, distribution_tariff_type), plan_id, plan_created_at

Binární sensory

Tyto sensory zachovávají kompatibilitu se staršími automatizacemi a zobrazují stejné stavy jako přepínače. Na stránce zařízení jsou zařazeny do diagnostiky.

• binary_sensor.proteus_prodej_do_site_misto_nabijeni - Prodej do sítě místo nabíjení
• binary_sensor.proteus_prodej_z_baterie_do_site - Prodej z baterie do sítě
• binary_sensor.proteus_setreni_energie_v_baterii - Šetření energie v baterii
• binary_sensor.proteus_nabijeni_baterie_ze_site - Nabíjení baterie ze sítě
• binary_sensor.proteus_zakaz_pretoku - Zákaz přetoků

Přepínače

• switch.proteus_obchodovani_flexiblity - Přepínání obchodování flexibility
• switch.proteus_optimalizace_algoritmem - Přepínání mezi automatickým a manuálním režimem
• switch.proteus_prodej_do_site_misto_nabijeni - Ovládání prodeje do sítě místo nabíjení
• switch.proteus_prodej_z_baterie_do_site - Ovládání prodeje z baterie do sítě
• switch.proteus_setreni_energie_v_baterii - Ovládání šetření energie v baterii
• switch.proteus_nabijeni_baterie_ze_site - Ovládání nabíjení baterie ze sítě
• switch.proteus_zakaz_pretoku - Ovládání zákazu přetoků
• switch.proteus_rizeni_fve - Povolení řízení FVE

Služby

V rozhraní vyberte zařízení invertoru v poli Invertor. V YAML se výběr zadává jako data.device_id; dosavadní volání s target.device_id nebo target.entity_id zůstávají podporovaná.

Všechny časy musí být začátky hodin a nesmí se opakovat ani po převodu do UTC. Naivní čas se interpretuje v časové zóně Home Assistantu. Predikční služby přijímají nejvýše 96 položek; delší seznam je třeba rozdělit do samostatných volání. Úpravy plánu musí patřit do aktuálně vráceného okna.

proteus_api.set_predictions

Přepíše předpověď spotřeby a/nebo výroby, se kterou plánuje optimalizační algoritmus Protea (stejná funkce jako ruční úprava v Proteovi na stránce plánu). Užitečné, když má člověk vlastní, přesnější předpověď (např. Solcast) nebo ví o něčem, co Proteus vědět nemůže.

Cíl služby je zařízení (invertor); bez cíle se předpověď zapíše všem nakonfigurovaným invertorům.

Pole predictions je seznam hodinových hodnot, každá položka obsahuje:

• time - začátek hodiny (naivní čas se bere v časové zóně Home Assistantu)
• consumption_kwh - předpokládaná spotřeba za tu hodinu v kWh (volitelné)
• production_kwh - předpokládaná výroba FVE za tu hodinu v kWh (volitelné)

Aspoň jedna z hodnot musí být uvedená. Vynechaná veličina zůstane na předpovědi Protea, takže jde přepsat třeba jen výrobu a spotřebu nechat na Proteovi.

action: proteus_api.set_predictions
data:
  device_id: 0123456789abcdef0123456789abcdef
  predictions:
    - time: "2026-08-09T19:00:00"
      consumption_kwh: 0.7
      production_kwh: 0.3
    - time: "2026-08-09T20:00:00"
      production_kwh: 0.0

proteus_api.clear_predictions

Zruší přepsané předpovědi pro dané hodiny; Proteus pak zase plánuje podle svých vlastních (stejné jako tlačítko reset v Proteovi). Cíl služby je stejný jako u set_predictions.

Pole times je seznam začátků hodin, u kterých se má přepis odstranit.

action: proteus_api.clear_predictions
data:
  device_id: 0123456789abcdef0123456789abcdef
  times:
    - "2026-08-09T19:00:00"
    - "2026-08-09T20:00:00"

proteus_api.set_plan_steps

Predikce mění očekávanou spotřebu/výrobu; služby set_plan_steps a clear_plan_steps mění akce baterie a FVE pro vybrané hodiny. Vyžadují explicitní cíl odpovídající právě jednomu invertoru. Integrace načte čerstvé sloučené okno plánu a zachová ostatní hodiny i jejich ruční příznaky.

action: proteus_api.set_plan_steps
data:
  device_id: 0123456789abcdef0123456789abcdef
  steps:
    - time: "2026-09-21T16:00:00+02:00"
      flexalgo_battery: default
      flexalgo_pv: fully_restricted
    - time: "2026-09-21T17:00:00+02:00"
      flexalgo_battery: charge_from_grid
      target_soc: 80

Každý krok vyžaduje time a alespoň jedno měněné pole. Vynechaná pole si zachovají aktuální hodnoty. is_manually_locked: true hodinu výslovně zamkne. target_soc přijímá procenta 0–100 nebo null; číselný cíl se uloží pouze při nabíjení/vybíjení ze/do sítě nebo zamčení hodiny. Nepodporované kombinace se odmítnou před zápisem, včetně neplatných kombinací v nezměněných hodinách.

Stavy baterie: charge_from_grid, charge_from_pv, default, do_not_charge, do_not_discharge, discharge_to_household, discharge_to_grid, unknown. Stavy FVE: unrestricted, restricted_to_household (výroba pro domácnost), fully_restricted (vypnutí výroby), unknown.

proteus_api.clear_plan_steps

Zruší ruční příznaky pro hodiny uvedené v poli times. Vyžaduje výběr právě jednoho invertoru.

action: proteus_api.clear_plan_steps
data:
  device_id: 0123456789abcdef0123456789abcdef
  times:
    - "2026-09-21T16:00:00+02:00"

Server při editaci zamyká i dřívější hodiny. Zrušení ručních příznaků jedné hodiny proto nemusí odstranit její kaskádový zámek, pokud zůstává pozdější upravená či zamčená hodina. Pozdější úpravy integrace automaticky nemaže.

Obnovení plánu a stav sensoru

Úspěch služby znamená přijetí zápisu. Přepočet se sleduje na pozadí každých 10 sekund (s respektováním omezení API), po dokončení opět každých 15 minut. Sensor plánu nabízí atributy is_recalculating_plan, plan_refresh_pending, grid_overflow_enabled a po načtení schopností forbidden_plan_combinations. Kroky obsahují také manually_edited, manually_locked, locked, původní akce a predikční kontext v jednotkách API. Při nejasném výsledku zápisu se požadavek automaticky neopakuje; nejprve se načte stav serveru.

Úplný seznam steps je dostupný v aktuálním stavu sensoru pro dashboardy a automatizace, ale neukládá se do historie recorderu kvůli jeho velikosti. Stav sensoru (počet kroků) a ostatní atributy se nadále zaznamenávají.

Odměna za flexibilitu v Energy dashboardu

Odměna za flexibilitu je jedna částka za všechny vykonané povely bez ohledu na směr (dodávka do sítě, odběr ze sítě do baterie i zákaz přetoků). Na faktuře od Delta Green se objeví jako zvýhodněná cena za daný měsíc, hodnoty v sensorech jsou včetně DPH.

Energy dashboard nemá zdroj „jen peníze": kompenzace se vždy váže na sensor energie v kWh a u jednoho sensoru lze zvolit buď cenu za kWh, nebo entitu s celkovou částkou. Skutečná dodávka do sítě už obvykle cenu za kWh má, proto integrace poskytuje vlastní nulový nosič sensor.proteus_odmena_za_flexibilitu (trvale 0 kWh) a sensor sensor.proteus_obchodovani_flexibility_celkem má state_class: total, aby pro něj Home Assistant vedl dlouhodobé statistiky. Objem energie pod povely je pro odměnu nepodstatný, cena se mění s každým povelem; dashboard bere částku přímo z celkové odměny.

V Nastavení → Ovládací panely → Energie klikněte v sekci „Elektrická síť" na „Přidat připojení k síti" a v dialogu „Nastavit připojení k síti":

1. Pole „Energie importovaná ze sítě" nechte prázdné.
2. V části „Energie vrácená do sítě" vyberte položku Odměna za flexibilitu (entita sensor.proteus_odmena_za_flexibilitu). Nabídka zobrazuje názvy a pod nimi zařízení, ne ID entit; nabízí jen sensory energie v kWh, sensor s odměnou tu nehledejte. Máte-li v účtu více invertorů, je položek víc se stejným názvem, vyberte tu, pod kterou je uvedeno zařízení skutečně řízeného invertoru (například „Solax Inverter", ne cloudové „Solax Api Inverter").
3. V části „Kompenzace exportu" přepněte volbu na „Použít entitu sledující celkovou kompenzaci". Teprve potom se zobrazí pole „Entita s celkovou kompenzací", kde vyberte Obchodování flexibility celkem (entita sensor.proteus_obchodovani_flexibility_celkem) u stejného zařízení.
4. „Typ měření výkonu" nechte na „Žádný senzor výkonu", nosič žádný výkon nemá.
5. Uložte.

Odměna se pak zobrazí ve sloupci výnosů vedle prodeje do sítě; vazba na „vráceno do sítě" je jen omezení dashboardu, nic o směru povelů neříká. Řádek „Odměna za flexibilitu" má 0 kWh (nulový nosič) a zápornou částku, tedy výnos:

Dashboard nabízí jen entity, které už mají dlouhodobé statistiky. Ty se počítají každých 5 minut, takže se sensory po aktualizaci integrace objeví v nabídce až po několika minutách. Statistiky běží od první zaznamenané hodnoty: ta se bere jako nulový bod, zpětně se nic nedopočítá. state_class: total (ne total_increasing) je zvolen proto, aby případná zpětná oprava částky ze strany Protea nebyla brána jako reset měřidla.

Stejný sensor lze použít i mimo dashboard, například v statistics-graph nebo apexcharts-card se stat_types: change po dnech či měsících.

Denní objemy flexibility

Integrace poskytuje tři sensory objemu flexibility v kWh s názvy povelů „Dodávka do sítě", „Odběr ze sítě" a „Zákaz přetoků". „Dodávka do sítě" znamená změnu směrem k větší dodávce do sítě nebo menšímu odběru; „Odběr ze sítě" znamená změnu směrem k většímu odběru ze sítě nebo menší dodávce. Jde o změnu chování celé domácnosti vůči síti oproti výchozímu stavu. Objem povelu „Odběr ze sítě" tedy nemusí znamenat nabíjení baterie.

Například přechod z dodávky 10 kW na odběr 10 kW představuje změnu 20 kW ve směru povelu „Odběr ze sítě". Pokud trvá hodinu, odpovídá objemu flexibility 20 kWh, zatímco skutečný odběr za tuto hodinu je 10 kWh.

Hodnoty pocházejí z jednotlivých povelů v households.commandListWithStats a aktualizují se každých 5 minut. Jde o součty za aktuální den v časovém pásmu Home Assistantu, nikoli o celoživotní hodnoty. Sensory používají state_class: total a explicitní denní last_reset, takže oprava hodnoty směrem dolů není reset měřidla. Při neúplné odpovědi zůstává poslední známá hodnota; po půlnoci je hodnota neznámá, dokud se nepodaří načíst nový den.

API vrací hodnoty za domácnost. Invertory ve stejné domácnosti proto zobrazují stejné objemy. Statistiky se zaznamenávají od zapnutí sensorů; historické dny ani dodatečné opravy minulých dnů se nestahují.

Tyto objemy lze zobrazit v samostatných grafech. Nejsou měřidly skutečné dodávky ani odběru, proto je nepoužívejte jako toky elektrické sítě v Energy dashboardu: zkreslily by energetickou bilanci. Pro zobrazení odměny v Energy dashboardu nadále používejte nulový nosič popsaný výše.

Vývoj

Projekt používá uv a závislosti pro testy jsou definované v pyproject.toml.

Instalace vývojového prostředí:

uv sync --group dev

Spuštění testů:

uv run --group dev python -m pytest tests -v

Dočasný diagnostický záznam plánu

Pro zachycení zbývajících příkladů zamčení/resetu zapněte konkrétní logger:

logger:
  logs:
    custom_components.proteus_api.plan_diagnostics: debug

Po restartu integrace zaznamená první a následně změněné sloučené plány při běžném obnovení, včetně ručních příznaků a původních hodnot. Jednou načte a zaznamená zakázané kombinace. Pro okamžité načtení plánu zavolejte homeassistant.update_entity pro sensor plánu; omezení API se nadále respektují. Výpis obsahuje JSON a čas zachycení, nezahrnuje adresu, přihlašovací údaje ani vnořenou konfiguraci účtu. Stejné plány se opakovaně nevypisují. Diagnostický logger po sběru vypněte; dočasný výpis bude odstraněn před vydáním po ověření fixture souborů.

Licence

MIT License

Podpora

Pro hlášení chyb nebo návrhy vylepšení použijte GitHub Issues.