API EVU

Tip

Diese Seite richtet sich an smartENERGY als EVU sowie Betreiber der Strompreis-API und nicht an Endanwender der Integration.

Was ist Home Assistant?

Home Assistant ist eine quelloffene Heimautomatisierungsplattform. Anders als bei einem klassischen Cloud-Dienst betreibt jede Nutzerin und jeder Nutzer eine eigene, lokale Instanz – typischerweise auf einem Raspberry Pi oder Mini-PC im eigenen Haushalt. Es gibt keine zentrale Instanz eines Anbieters, die stellvertretend für alle Installationen Daten abruft: Jede Installation ruft die Tarifpreis-API unabhängig und eigenständig auf.

Was diese Integration tut

smartENERGY Strompreishelfer ist eine Community-Integration (installiert über HACS). Sie bildet je nach Wahl der Nutzerin/des Nutzers smartTIMES, smartCONTROL oder smartNIGHT in Home Assistant als Preis-Sensoren ab – inklusive der üblichen variablen Nebenkosten (Steuern, Abgaben, Netzentgelte). smartNIGHT wird dabei rein lokal aus der smartTIMES-Antwort berechnet (Off-Peak-Preis des Tages, zwischen 07:00 und 23:00 Uhr zuzüglich 30 %) und ruft keinen zusätzlichen Endpunkt ab – am Anfragemuster unten ändert er nichts. Zusätzlich stellt sie je Verbraucher einen „Günstige Stunde“-Sensor bereit, den Nutzerinnen und Nutzer typischerweise per Automatisierung nutzen, um Lasten wie Boiler oder Wallbox gezielt in günstige Preisfenster zu schalten.

Lastglättung der „Günstige Stunde“-Sensoren

Viele unabhängige Home-Assistant-Instanzen folgen demselben öffentlichen Preissignal. Um eine synchronisierte Lastspitze zu vermeiden, wirkt die Integration clientseitig entgegen (custom_components/smartenergy/jitter.py):

• Jeder „Günstige Stunde“-Sensor verschiebt seine Schaltflanken um einen deterministischen, aus der (nutzerseitig nicht editierbaren) Subentry-ID abgeleiteten Versatz (SHA-256-Hash, Funktion cheap_phase). Der Versatz wirkt pseudozufällig, ist aber stabil – kein Flackern bei der minütlichen Neuberechnung – und über viele Sensoren hinweg gleichverteilt.
• Beide Schaltflanken wandern nach innen, um denselben Betrag aus einer Breite (Konstante JITTER_SPAN_SECONDS = 10 Minuten), berechnet in jittered_window: eingeschaltet wird 0–10 Minuten nach Beginn des günstigen Zeitfensters, ausgeschaltet ebenso 0–10 Minuten vor dessen Ende. Das Schaltfenster liegt damit immer vollständig innerhalb des günstigen Blocks – die Last läuft nie in die angrenzende, teurere Preiszone hinein, weder vor dem Beginn noch nach dem Ende.
• Weil beide Flanken denselben Versatz teilen, verschiebt sich das Fenster als Ganzes und ist für jeden Sensor gleich lang (Blocklänge minus 10 Minuten). Der Preis dafür ist ein fester Laufzeitverlust von 10 Minuten je Block – bewusst in Kauf genommen, um nie zum teureren Preis zu laufen.
• Dadurch rampt die aggregierte Nachfrage vieler Haushalte über ein rund zehnminütiges Fenster statt als Sprungfunktion zur vollen Stunde bzw. Fenstergrenze – jeder einzelne Sensor bleibt für sich genommen deterministisch und reproduzierbar.

Die Glättung passiert vollständig lokal in Home Assistant: Weder smartENERGY noch der Maintainer dieser Integration erhalten eine Rückmeldung, welche Haushalte wann tatsächlich schalten (siehe Datenschutz).

Anfragemuster

Weil jede Home-Assistant-Instanz unabhängig und lokal läuft, kommt der Traffic dieser Integration von vielen verschiedenen, üblicherweise privaten IP-Adressen verteilt über den Tag – nicht konzentriert von einem zentralen Server. Gesteuert wird das über custom_components/smartenergy/coordinator.py (_needs_fetch, _retry_delay, _fetch_allowed). Pro Instanz gilt – genauer: pro eingerichtetem Eintrag; wer mehrere Zähler hat, richtet die Integration je Zähler einmal ein, und jeder Eintrag ruft für sich ab:

• ~1 Abruf pro Tag, plus ein einmaliger Abruf beim Start von Home Assistant.
• Die Morgen-Preise für den Folgetag werden ab 17 Uhr (Konstante NEXT_DAY_PRICES_HOUR) abgerufen, mit einem deterministischen, aus der Entry-ID und dem Kalendertag abgeleiteten Jitter über ein 20-Minuten-Fenster (FETCH_JITTER_MINUTES) – so entsteht keine Lastspitze exakt zur vollen Stunde.
• Retry bei Fehlern: Der erste erneute Versuch erfolgt nach 30 Minuten (FETCH_RETRY_INTERVAL_MINUTES), danach verdoppelt sich die Wartezeit bei jedem weiteren Fehlschlag bis maximal 2 Stunden (FETCH_RETRY_MAX_INTERVAL_MINUTES). Ein Retry-After-Header wird respektiert, sofern er länger ist als die eigene Wartezeit. Eine dauerhafte Ablehnung (4xx außer 408/429) wird nicht in kurzen Abständen erneut versucht, sondern springt sofort auf das Maximal-Intervall.
• Ein hartes Sicherheitsnetz (Konstante MIN_FETCH_INTERVAL_MINUTES) verhindert unabhängig davon, dass zwei echte Abrufe derselben Instanz jemals weniger als 5 Minuten auseinander liegen.
• Schlägt ein Abruf fehl, bleiben zuvor abgerufene Preise im lokalen Cache erhalten – es gibt also keinen "Retry-Sturm" bei einer länger andauernden Störung.

User-Agent

Jede Anfrage trägt einen aussagekräftigen User-Agent-Header nach dem Schema (aufgebaut in custom_components/smartenergy/api.py, Funktion _build_user_agent):

HomeAssistant-Strompreishelfer/<Version> (+<Link auf diese Seite>)

Beispiel: HomeAssistant-Strompreishelfer/4.0.0 (+https://github.com/da-sa-li/HA-smartenergy-Tarif/wiki/API-EVU)

Damit lässt sich der Traffic dieser Integration in den Server-Logs eindeutig von anderem Traffic unterscheiden.

Important

Bei Auffälligkeiten (Rate-Limiting, Blocking, Fragen zum Traffic-Muster) bitte über ein GitHub Issue melden.