FoxESS Smart-Home-Integration, kostenlos und Open Source
FoxESS-Wechselrichter und -Batterien über die FoxESS Cloud: Solar, Haus, Netz, Batterie.
Veröffentlicht von guim31
- Geräte
- Version 1.0.1
- Erfordert Gladys >=5.1.0
- ★ 0
FoxESS-Wechselrichter und -Batterien (Serien H1, H3, KH, AIO, T und F…) in Gladys, über die offizielle Open API der FoxESS Cloud: Solarproduktion, Hausverbrauch, Netzbezug und Netzeinspeisung, Batterieladung, Status und Störungen des Wechselrichters, auf deinem Dashboard und in deinen Szenen.
Diese Integration wurde ohne die Hardware entwickelt, anhand der Dokumentation der Open API und der Open-Source-Projekte, die sie nutzen: Rückmeldungen sind willkommen. Die Integration ist nicht mit FoxESS verbunden.
Was du bekommst
- Ein Gerät pro Wechselrichter deines FoxESS-Cloud-Kontos, standardmäßig alle 5 Minuten gelesen.
- Die Energieflüsse: Solarleistung (gesamt und pro PV-String), Hausverbrauch, Netzbezug und Netzeinspeisung, Laden und Entladen der Batterie.
- Die Zähler: Produktion heute, Gesamtproduktion (der Index, den die Energieüberwachung von Gladys liest), Netzbezugs- und Netzeinspeisezähler, Lade- und Entlade-Index der Batterie.
- Die Batterie: Batteriestand und Temperatur.
- Den Wechselrichter: Status (am Netz, Inselbetrieb, Störung…), aktueller Alarm, online oder nicht, Temperatur.
- Ein Dashboard-Widget mit den Flüssen eines Wechselrichters, seiner Batterie und seinem Arbeitsmodus.
- Einen Szenen-Auslöser, wenn der Wechselrichter eine neue Störung meldet.
- Eine optionale Steuerung (standardmäßig aus): Arbeitsmodus und Mindestladung der Batterie, aus Szenen und dem Widget.
Voraussetzungen
- Gladys Assistant 5.1.0 oder neuer.
- Ein FoxESS-Cloud-Konto (foxesscloud.com), in dem dein Wechselrichter erscheint: dasselbe Konto wie in der FoxESS-App.
- Ein API-Schlüssel für dieses Konto: Öffne auf foxesscloud.com dein Profil (oben rechts), User Profile, API Management, dann Generate API key. Kopiere den langen Schlüssel.
- Der Gladys-Server braucht Internet und eine richtig gehende Uhr (die Anfragen werden mit der Uhrzeit signiert: Eine Uhr, die mehr als eine Minute abweicht, wird abgelehnt).
Konfiguration
Installiere die Integration (Integrationen → Von GitHub installieren, oder aus dem Store) und fülle dann ihre Konfiguration aus:
| Feld | Was eintragen |
|---|---|
| API-Schlüssel | Der unter API Management erzeugte Schlüssel. |
| Seriennummern der Wechselrichter | Leer, um alle Wechselrichter des Kontos anzuzeigen, sonst die zu behaltenden Seriennummern, durch Kommas getrennt (FoxESS Cloud, Device, Inverter). |
| Aktualisierungsintervall | 5 Minuten (Standard) bis 1 Stunde. Die FoxESS Cloud aktualisiert ihre Werte etwa alle 5 Minuten: Schneller zu lesen würde nur das Kontingent verbrauchen. |
| Anzahl der PV-Strings | 0 (Standard): eine Funktion pro String, den der Wechselrichter meldet. Manche Modelle melden 4 oder 6 Strings, obwohl 2 angeschlossen sind: Trage 2 ein, um 1 und 2 zu behalten. |
| Sprache der Funktionsnamen | Die Sprache der Funktionsnamen, wenn ein Wechselrichter hinzugefügt wird (Gladys behält sie danach), und der Statustexte. |
| Steuerung des Wechselrichters erlauben | Standardmäßig aus. Siehe Szenen-Aktionen. |
Verbindung testen listet die Wechselrichter des Kontos und, wenn die Cloud sie liefert, die Zahl der heute verbleibenden API-Aufrufe auf. Öffne dann den Reiter Erkennung und füge deine Wechselrichter hinzu.
Das Wechselrichter-Gerät
| Funktion | Typ in Gladys | Einheit | Hinweise |
|---|---|---|---|
| Solarleistung | Produktionsleistung | W | Alle PV-Strings zusammen. |
| PV-String | Produktionsleistung | W | Einer pro String: „PV-String 1“, „PV-String 2“… |
| Produktion heute | Tagesproduktion | kWh | Um Mitternacht wieder 0 (Zeit der Anlage). |
| Gesamtproduktion | Produktionsindex | kWh | Lebenszeitzähler, für die Energieüberwachung. |
| Hausverbrauch | Leistung | W | Was das Haus bezieht, egal aus welcher Quelle. |
| Netzbezug | Netzbezugsleistung | W | |
| Netzeinspeisung | Netzeinspeiseleistung | W | |
| Netzbezugszähler | Netzbezugszähler | kWh | Lebenszeitzähler des Netzzählers des Wechselrichters. |
| Netzeinspeisezähler | Netzeinspeisezähler | kWh | |
| Batteriestand | Batteriestand | % | Nur Wechselrichter mit Batterie, wie die fünf folgenden. |
| Batterieladung | Ladeleistung | W | |
| Batterieentladung | Entladeleistung | W | |
| Lade-Index Batterie | Lade-Index | kWh | |
| Entlade-Index Batterie | Entlade-Index | kWh | |
| Batterietemperatur | Temperatur | °C | |
| Wechselrichtertemperatur | Temperatur | °C | |
| Wechselrichterstatus | Text | Online, Am Netz, Inselbetrieb (Notstrom), Störung, Offline… | |
| Wechselrichteralarm | Text | Die Störung, die FoxESS meldet, sonst „Keiner“. | |
| Online | Status des Eingangs | 1, wenn der Wechselrichter mit der FoxESS Cloud spricht. |
Ein Wechselrichter, den die FoxESS Cloud als offline meldet (nachts bei einem Wechselrichter ohne Batterie, oder wenn sein WLAN-Dongle aus ist), aktualisiert nur seinen Status und „Online“: Die Cloud würde sonst seine letzten Werte liefern, als wären sie aktuell.
Die Gesamtproduktion ist ein kumulativer Produktionsindex für die Energieüberwachung von Gladys; sein Verlauf wird gespeichert. Ob Gladys daraus eine 30-Minuten-Produktion berechnet, hängt von deiner Gladys-Version ab: 5.2.1 tut das automatisch nur für Verbrauchsindizes.
Dashboard-Widget
FoxESS Solar zeigt für den in seinen Einstellungen gewählten Wechselrichter (den ersten hinzugefügten, wenn keiner gewählt ist):
- Kacheln für Solarleistung, Hausverbrauch, Batteriestand, Netzbezug und Netzeinspeisung, Produktion heute — live, sie folgen den Zuständen;
- den Status des Wechselrichters, seinen aktuellen Alarm, was die Batterie tut (lädt, entlädt, ruhend), ihre Mindestladung, den Arbeitsmodus und die Uhrzeit der letzten Messung;
- mit erlaubter Steuerung und einer Batterie: drei Schaltflächen Eigenverbrauch, Einspeisung zuerst und Notstrom, jede mit einer Bestätigung. Der aktuelle Modus trägt ein Häkchen. Mit den Schaltflächen ist Platz für vier Kacheln: Netzeinspeisung und Produktion heute werden zu Statuszeilen.
Szenen-Auslöser
Störung des Wechselrichters löst aus, wenn der Wechselrichter eine Störung meldet, die bei der vorigen Messung nicht da war (eine neue Störung, oder eine andere, die sie ersetzt). Filtere auf einen Wechselrichter oder lass das Feld für alle leer. Die Variable Störung enthält die Beschreibung von FoxESS (zum Beispiel „Grid Lost Fault“). Eine Störung, die schon beim Start der Integration da ist, löst nicht aus, ebenso wenig eine Störung, die verschwindet: Die Funktion „Wechselrichteralarm“ zeigt dann wieder „Keiner“.
Szenen-Aktionen
Beide Aktionen werden abgelehnt, solange „Steuerung des Wechselrichters erlauben“ aus ist, der Standard: Eine Szene, die die Nutzung der Batterie ändert, darf nie aus Versehen laufen. Schalte es in der Konfiguration ein, um sie zu nutzen. Beide brauchen einen Wechselrichter mit Batterie.
- Arbeitsmodus des Wechselrichters setzen: Eigenverbrauch (die Batterie deckt zuerst das Haus), Einspeisung zuerst (der Solarstrom geht zuerst ins Netz) oder Notstrom (die Batterie bleibt für einen Stromausfall voll). Ausgabe: der gesetzte Modus.
- Mindestladung der Batterie setzen: die Ladung, die die Batterie ohne Netz und am Netz behält, 10 bis 100 %, die am Netz nicht unter der anderen. Ausgaben: beide gesetzten Werte.
Diese Einstellungen laufen über die offizielle Open API (setting/set mit dem Schlüssel
WorkMode, und battery/soc/set). Wenn in der FoxESS-App ein Zeitplan (Zeitfenster) aktiv
ist, lehnt der Wechselrichter sie ab: Die Aktion schlägt mit „In der FoxESS-App ist ein Zeitplan
aktiv“ fehl. Die erzwungenen Lade- und Entladefenster des FoxESS-Zeitplans werden nicht angeboten.
Szenen-Beispiele
- Störungsmeldung: Auslöser „Störung des Wechselrichters“, Aktion „Nachricht senden“: „FoxESS: {{triggerEvent.data.fault}}“.
- Gewitter angekündigt: Wenn das Wetter ein Gewitter vorhersagt, „Arbeitsmodus des Wechselrichters setzen“ auf Notstrom; am nächsten Morgen zurück auf Eigenverbrauch.
- Überschuss nutzen: Wenn „Netzeinspeisung“ 15 Minuten lang über 2.000 W bleibt und „Batteriestand“ über 90 % liegt, den Warmwasserbereiter einschalten.
API-Kontingent
Die FoxESS Cloud erlaubt 1.440 Aufrufe der Open API pro Tag (im Schnitt einen pro Minute) und lehnt Bursts ab. Die Integration hält mindestens eine Sekunde zwischen ihren Aufrufen und liest pro Zyklus:
- die Echtzeitwerte aller hinzugefügten Wechselrichter, in einem Aufruf;
- höchstens alle 15 Minuten: die Liste der Wechselrichter (online, Alarm, offline) und die Produktion heute jedes Wechselrichters;
- jede Stunde, für einen Wechselrichter mit Batterie: seine Mindestladung und seinen Arbeitsmodus.
Aufrufe pro Tag für einen Wechselrichter mit Batterie:
| Aktualisierungsintervall | Aufrufe pro Tag |
|---|---|
| 5 Minuten | 528 |
| 10 Minuten | 384 |
| 15 Minuten | 336 |
| 30 Minuten | 192 |
| 1 Stunde | 120 |
Ohne Batterie 48 weniger. Jeder weitere Wechselrichter fügt 96 Aufrufe hinzu (seine Produktion), plus 48 mit Batterie. Das Kontingent wird mit allen anderen Werkzeugen geteilt, die denselben API-Schlüssel nutzen (Home Assistant, ein Skript…): Gib jedem seinen eigenen Schlüssel, oder verlangsame die Aktualisierung. Wenn die Cloud einen Aufruf wegen Kontingent oder Burst ablehnt, pausieren die Messungen 30 Minuten, und der Konfigurationsbildschirm zeigt es an.
Fehlerbehebung
- „Die FoxESS Cloud lehnt den API-Schlüssel ab“: Der Schlüssel ist ungültig, oder er wurde gelöscht oder neu erzeugt. Erzeuge einen neuen unter API Management und füge ihn wieder ein. Nach einer Ablehnung pausieren die Messungen eine Stunde, oder bis sich die Konfiguration ändert.
- „Die FoxESS Cloud lehnt die Signatur der Anfragen ab“: Die Uhr des Gladys-Servers weicht um mehr als eine Minute ab. Stelle sie richtig (NTP).
- „Aufruflimit der FoxESS Cloud erreicht“: Ein anderes Werkzeug nutzt denselben Schlüssel, oder die Aktualisierung ist zu schnell. Siehe API-Kontingent.
- „Seriennummer(n) nicht in diesem Konto“: Vergleiche die Seriennummern der Konfiguration mit FoxESS Cloud, Device, Inverter, oder lass das Feld leer.
- Kein PV-String, oder zu viele: Die Strings kommen aus dem, was der Wechselrichter meldet; stelle „Anzahl der PV-Strings“ ein und „Aktualisiere“ den Wechselrichter im Reiter Erkennung.
- „Kein aktueller Wert“ bei einem stabilen Wert: Werte, die sich nicht ändern, werden alle 6 Stunden erneut gesendet, das reicht; ein Wechselrichter offline behält seine letzten Werte.
- Mehr Details: Setze
LOG_LEVEL=debugfür die Integration und lies ihre Logs. Der API-Schlüssel erscheint dort nie.
Grenzen
- Nur Cloud: kein lokaler Zugriff (Modbus). Für eine lokale Verbindung gibt es
foxess_modbusfür Home Assistant; es ist nicht Teil dieser Integration. - Keine Echtzeit: Die FoxESS Cloud aktualisiert sich etwa alle 5 Minuten, eine Messung kann so alt sein.
- Ohne die Hardware entwickelt: Die Antworten der API stammen aus ihrer Dokumentation und aus den Projekten, die sie nutzen. Felder, die bei manchen Modellen anders heißen, können fehlen: Sag uns Bescheid.
- Mindestladung und Arbeitsmodus werden einmal pro Stunde gelesen: Eine Änderung in der FoxESS-App erscheint innerhalb einer Stunde im Widget.
- Die erzwungenen Lade- oder Entladefenster und der Zeitplan der FoxESS-App werden nicht angeboten; ebenso wenig die Einspeisebegrenzung oder die Batterieheizung.
- Der Verbrauchsindex des Hauses wird nicht veröffentlicht (nur seine Leistung): Von der Energieüberwachung bepreist, würde er selbst verbrauchten Solarstrom als aus dem Netz gekauft zählen.
- Nicht mit FoxESS verbunden. FoxESS ist eine Marke ihres Inhabers.
Konfigurationseinstellungen
Diese Einstellungen fragt FoxESS in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Dein FoxESS-Cloud-Konto | section | Nein | Öffne auf foxesscloud.com dein Profil (oben rechts), User Profile, API Management, dann Generate API key. Die FoxESS Cloud erlaubt 1.440 API-Aufrufe pro Tag und Wechselrichter: Lass die Aktualisierung bei 5 Minuten oder mehr. |
| API-Schlüssel | secret | Ja | Der Schlüssel, der unter API Management in deinem FoxESS-Cloud-Profil erzeugt wurde. |
| Seriennummern der Wechselrichter | string | Nein | Leer: alle Wechselrichter des Kontos. Sonst die anzuzeigenden Seriennummern, durch Kommas getrennt (Device, Inverter in der FoxESS Cloud). |
| Aktualisierungsintervall | select | Nein | Die FoxESS Cloud selbst aktualisiert ihre Werte etwa alle 5 Minuten. |
| Anzahl der PV-Strings | number | Nein | 0: alle Strings, die der Wechselrichter meldet. Sonst bekommen nur die Strings 1 bis zu dieser Zahl eine Funktion. |
| Sprache der Funktionsnamen | select | Nein | Wird verwendet, wenn ein Wechselrichter zu Gladys hinzugefügt wird, und für die Statustexte. |
| Steuerung des Wechselrichters | section | Nein | Standardmäßig aus. Eingeschaltet können Szenen und das Dashboard-Widget den Arbeitsmodus und die Mindestladung der Batterie ändern. Eine falsche Einstellung kann die Batterie bei einem Stromausfall leer lassen. |
| Steuerung des Wechselrichters erlauben | boolean | Nein |
So installierst du FoxESS in Gladys
- Öffne in Gladys Integrationen: FoxESS erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/guim31/gladys-foxess:1.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-foxess.
FoxESS benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
FoxESS ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation