Installation Zendure Home Assistant integration – Tutorial - Kieft-C/Zendure-BKW-PV GitHub Wiki

Installation der Zendure Home Assistant Integration – Tutorial

Dieses Tutorial führt dich Schritt für Schritt durch die Installation der offiziellen Zendure-Integration (ursprünglich von FireSon programmiert, mittlerweile von Zendure selbst übernommen) in Home Assistant. Am Ende kannst du deine Zendure-Geräte in HA anzeigen, automatisieren und optional komplett ohne Zendure-Cloud betreiben (lokale MQTT-Verbindung).

Kurzüberblick, was dich erwartet:

  1. Voraussetzungen prüfen
  2. HACS installieren (falls nötig)
  3. Zendure-Integration über HACS hinzufügen
  4. Integration einrichten (Token, Sensoren, optional lokales MQTT)
  5. Optional: von Cloud auf lokale Verbindung umschalten
  6. Fehlerbehebung, falls etwas nicht klappt

1. Voraussetzungen

Bevor du startest, stelle sicher, dass Folgendes erfüllt ist:

  • Home Assistant läuft als Basissystem.
  • HACS (Home Assistant Community Store) ist installiert und erreichbar.
  • Zendure-Integration Version ≥ 1.25 oder 1.3.1 – aktuelle Version gibt es unter https://github.com/Zendure/Zendure-HA (die Integration wurde von FireSon an Zendure übergeben, dort läuft jetzt die Weiterentwicklung).
  • Optional, nur für lokales MQTT: je nach Gerätetyp wird ein Bluetooth-Stick bzw. eine aktivierte Bluetooth-Funktion in HA benötigt – das hängt von deinem Gerät ab (siehe unten).

Wichtig: Welches Gerät braucht welche Umschaltungsart?

Die Zendure-Integration unterscheidet bei der Umschaltung auf lokales MQTT zwischen zwei Technologien. Das solltest du kennen, bevor du dich mit Bluetooth beschäftigst:

Gerät Umschaltung Cloud → Lokal Klarheit
Hub1200, Hub2000, AIO2400, Hyper2000, ACE1500 Bluetooth (BLE) rel. gesichert
SolarFlow 800, 800 Pro, 2400AC, 800 Plus ZenSDK, kein Bluetooth rel. gesichert
SolarFlow 1600 AC+, 2400 AC+, 2400 Pro (2026er Generation) ZenSDK, kein Bluetooth rel. gesichert

Mehr zu ZenSDK: https://github.com/Zendure/zenSDK/blob/main/docs/de.md

Prüfe also zuerst, zu welcher Gruppe dein Gerät gehört – das entscheidet, ob du überhaupt einen Bluetooth-Stick brauchst oder die Zusatz BLE Tool Web-Seite von FireSon nutzen kannst.

2. Schritt 1 – HACS installieren (falls noch nicht vorhanden)

Falls HACS bei dir noch nicht läuft, folge dieser Anleitung: https://hobbyblogging.de/home-assistant-hacs-installation

3. Schritt 2 – Zendure-Integration über HACS hinzufügen

  1. Schnellzugriff: Klicke auf diesen Link, um die Integration direkt in HACS zu öffnen: Zendure-Integration in HACS öffnen
  2. Beim ersten Zugriff auf HACS musst du dich eventuell mit deinem GitHub-Konto autorisieren.
  3. Falls der Schnellzugriff nicht funktioniert, füge das Repository manuell hinzu:
    • Oben rechts in HACS auf die drei Punkte klicken
    • „Benutzerdefiniertes Repository hinzufügen" wählen
    • URL eintragen: https://github.com/Zendure/Zendure-HA, Kategorie: Integration
  4. Klicke auf „Herunterladen" bzw. „Installieren".
    • Du kannst hier auch eine ältere Version wählen – nützlich, falls ein neues Release Probleme verursacht und du zurückspringen willst.
  5. Home Assistant fragt danach nach einem Neustart – falls nicht automatisch, starte manuell neu.

4. Schritt 3 – Zendure-Integration einrichten

Gehe zu Einstellungen → Geräte & Dienste → „+ Integration hinzufügen" und suche nach „Zendure".

Im folgenden Konfigurationsdialog werden mehrere Angaben abgefragt:

Zendure-Token

  • Den API-Token findest du in der Zendure-App: Profil → „Autorisierung Cloud-Schlüssel".
  • Der Token wird für dich erstellt – niemals mit anderen teilen.
  • Wichtig: Der Token muss aus dem Zendure-Hauptaccount stammen, in dem die Geräte registriert sind – nicht aus einem Zweitaccount (z. B. falls du die Integration früher noch ohne Token, mit einem separaten Account genutzt hast).

P1-Sensor für Smart Matching

  • Wird nur benötigt, wenn du nicht nur Daten anzeigen, sondern auch eine Nulleinspeiseregelung nutzen willst.
  • Trage hier die Entität ein, die zum Abgleich der Einspeisung dient (z. B. der „Total Active Power"-Sensor eines Shelly 3EM Pro).
  • Grundsätzlich funktioniert jeder Sensor, der den passenden Wert liefert.

MQTT-Kommunikation loggen

  • Empfehlenswert zu aktivieren, wenn du bei Problemen ein Debug-Log erstellst – die MQTT-Kommunikation wird dann mit protokolliert und hilft enorm bei der Fehlersuche.

Lokalen Mosquitto-MQTT-AddOn verwenden

Nur aktivieren, wenn du dich von der Zendure-Cloud abkoppeln möchtest.

Für Einsteiger nicht empfohlen – dieser Schritt braucht etwas mehr technisches Verständnis. Wenn du unsicher bist, überspringe ihn zunächst und betreibe die Integration erst eine Weile über die Cloud. Voraussetzung: Das Mosquitto MQTT-AddOn muss vorher installiert sein → https://www.home-assistant.io/integrations/mqtt/ Wenn aktiviert, fragt ein weiteres Fenster folgende Daten ab:

Feld Bedeutung
mqttserver IP-Adresse deines HA-Servers (nicht core-mosquitto eintragen – das ist keine echte Netzwerkadresse!)
mqttport Standard: 1883
mqttuser Nutzer aus dem Mosquitto-AddOn oder unter HA → Einstellungen → Personen → Benutzer
mqttpsw Passwort des angelegten Nutzers
Wifi SSID Name deines WLANs (bevorzugt 2,4 GHz)
Wifi Passwort Passwort zum WLAN

Nach korrekter Eingabe und Bestätigung sollten deine Geräte in einer Liste erscheinen.

Prüf-Tipp: Mit dem MQTT Explorer kannst du kontrollieren, ob Daten vom HA-Server korrekt ankommen.

Angelegte Geräte

Nach der Einrichtung werden folgende Geräte-Typen getrennt angelegt:

  • Zendure Manager – zentrale Steuerungslogik, siehe Abschnitt „Der Zendure Manager und seine Betriebsmodi" weiter unten
  • jeder Akku einzeln
  • jedes „Kopf"-Gerät (z. B. Hyper, SF800) einzeln

Zwingend erforderlich: Jedem „Kopf"-Gerät muss eine Sicherungsgruppe (Fusegroup) zugewiesen werden – ohne diese Zuordnung funktioniert der Smartmatch-Modus nicht.

So gehst du vor:

  1. Gehe zu jedem Gerät und wähle dessen „Gerätesicherungsgruppe" aus.
  2. Sind mehrere Geräte auf derselben Phase, wählt eines „Sicherungsgruppe max. Y Watt" (Y = maximale Leistung des Wechselstromanschlusses).
  3. Die übrigen Geräte auf dieser Phase wählen „Teil von Gerät X Sicherungsgruppe".
  4. Steht ein Gerät allein auf seiner Phase, wähle „Gerät hat eigenen Stromkreis/eigene Phase".

Der Zendure Manager und seine Betriebsmodi

Sobald die Fusegroups gesetzt sind, die Integration grundsätzlich läuft und (falls gewünscht) ein P1-Sensor zum Netzabgleich hinterlegt ist, stehen über den Zendure Manager verschiedene Modi zur Steuerung deiner Geräte bereit. Über dessen Entität select.zendure_manager_operation (bzw. „Betriebsmodus" in der deutschen Übersetzung) wählst du, wie gesteuert wird. Folgende Modi stehen zur Verfügung:

Modus Bedeutung
Aus / None Der Zendure Manager greift nicht ein – die Geräte laufen nach ihren eigenen, in der Zendure-App eingestellten Programmen.
Smarte Leistungsregelung / Smart Matching (CT-Modus) Der Standardmodus für die Nulleinspeiseregelung. Der Manager gleicht die Leistung laufend anhand deines P1-/Netz-Sensors ab, sodass möglichst nichts unnötig ins Netz eingespeist wird.
Manuelle Leistungsregelung / Manual Power Du gibst direkt einen festen Watt-Wert vor (z. B. über eine Automation oder ein Helper-Entity), den der Manager an die Geräte weitergibt – nützlich zum Testen oder für eigene Steuerlogiken.
Smartes Laden / Smart Charging Es wird nur geladen, auch wenn gerade nicht genug PV-Überschuss vorhanden wäre – sinnvoll z. B. um in einer günstigen Strompreisphase gezielt zu laden.
Smartes Entladen / Smart Discharging Es wird nur entladen, selbst wenn eigentlich Solarleistung zum Laden verfügbar wäre – sinnvoll z. B. um Batteriekapazität vor einer teuren Netzbezugsphase gezielt freizugeben.

ℹ️ Praxis-Tipp: Bei stark wechselnder Sonneneinstrahlung (viele Wolken) kann der Standard-Smart-Matching-Modus häufig zwischen Laden/Entladen hin- und herspringen. In solchen Fällen kann es sinnvoll sein, tagsüber gezielt „Smartes Laden" und abends „Smarte Leistungsregelung" bzw. „Smartes Entladen" zu nutzen, um unnötiges Hin-und-Her-Schalten zu vermeiden.

Der Zendure Manager liefert außerdem eigene Sensoren, u. a.:

  • Verfügbare Energie / Available Energy – wie viel Energie aktuell in deinem System gespeichert ist
  • Global SOC – der gewichtete Ladezustand über alle Online-Geräte hinweg
  • Leistung / Power – die aktuell vom Manager gesteuerte Gesamtleistung

Warum das Ganze über Home Assistant statt direkt in der Zendure-App? Die Zendure-App erlaubt dir nur, zwischen ihren fest vorgegebenen Programmen zu wählen. Da der Zendure Manager aber eine ganz normale Home-Assistant-Entität ist, kannst du ihn mit allem anderen in deinem Smart Home kombinieren: Automationen, die je nach Strompreis, Tageszeit, Wetterprognose oder dem Zustand ganz anderer Geräte den Modus wechseln; Zusammenspiel mit weiteren Entitäten (z. B. Wärmepumpe, Wallbox, andere Batteriespeicher); oder einfache, selbst gebaute Regellogiken, die so in der Zendure-App gar nicht abbildbar wären. Das ist letztlich der Kernvorteil dieser Integration gegenüber der reinen Herstellersteuerung – es gibt darüber hinaus noch viele weitere Einstellmöglichkeiten und Optionen in der Integration, die hier nicht alle im Detail behandelt werden können.

5. Schritt 4 – Optional: Umschaltung „Cloud" → „Lokal"

Wenn du dich von der Cloud lösen möchtest und der Smartmatch-Modus bereits sauber läuft, kannst du pro „Kopf"-Gerät die Verbindungsart umstellen. Der Ablauf unterscheidet sich je nach Umschaltungsart deines Geräts (siehe Tabelle in Kapitel 1).

5.1 Geräte mit ZenSDK – der einfache Weg

Diese Geräte brauchen kein Bluetooth. Die Umschaltung erfolgt direkt über die Integration, ohne den BLE-Umweg:

  1. Stelle bei korrekt eingegebenen lokalen MQTT-Daten die Verbindungsart auf „lokal" um.
  2. Das Gerät verbindet sich direkt über ZenSDK/WLAN mit deinem lokalen MQTT-Server.
  3. Es ist deutlich seltener mit Problemen verbunden als bei Bluetooth-Geräten, da kein Bluetooth-Zwischenschritt nötig ist.

5.2 Geräte mit Bluetooth-Umschaltung – via BLE

So gehst du vor:

  1. Bluetooth-Stick muss installiert und in HA unter „Bluetooth" sichtbar sein.
  2. Stelle die Verbindungsart bei korrekt eingegebenen lokalen MQTT-Daten auf „lokal" um.
  3. ⏱️ Wichtig: Nach jedem Umschaltvorgang mindestens 5 Minuten warten, bevor du erneut umschaltest. Die Umstellung und das Update der Bluetooth-Daten laufen nur alle 5 Minuten.
  4. Bluetooth wird nur für den einmaligen Wechsel benötigt – danach läuft die Kommunikation per WLAN/MQTT weiter.

Ab Version 1.1.4 bekommst du bei erfolgreicher Umstellung eine Benachrichtigung in Home Assistant.

📡 Kein Bluetooth-Stick vorhanden oder Gerät zu weit weg? Für genau diesen Fall hat FireSon eine browserbasierte Alternative entwickelt: ZendureBle. Mehr dazu in Kapitel 6.2.

Verbindungsstatus verstehen

Die Entität „Verbindungsstatus" (ab Version 1.1.4) zeigt dir, ob die Umschaltung erfolgreich war:

Wert Bedeutung
0 Offline / nie gesehen
1 SoC-Status leer
2 HEMS aktiv
3 Fuse-Group „unused"
10 Verbunden (Cloud)
11 Verbunden (Lokal)
12 Verbunden (ZenSDK)

6. Fehlerbehebung: Cloud ↔ Lokal MQTT

Dieser Abschnitt sammelt die häufigsten Fehlerbilder speziell rund um die Umschaltung zwischen Cloud- und lokaler MQTT-Verbindung – inklusive dem, was die jeweilige Meldung tatsächlich bedeutet.

6.1 „Device XXXXX nicht autorisiert" im MQTT-Log

Diese Meldung taucht auf, wenn das Gerät versucht, sich lokal mit MQTT zu verbinden, aber der zugehörige HA-Benutzer (den die Integration automatisch anlegt) noch nicht existiert oder nicht korrekt registriert wurde.

Lösungsweg:

  1. Prüfe unter Einstellungen → Personen → Benutzer, ob „Device XXXXX" dort bereits aufgelistet ist.
  2. Falls nicht:
    • Debug-Log der Zendure-Integration starten
    • Home Assistant neu starten
    • Zendure-Integration über die drei Punkte bei „Geräte & Dienste" neu laden
  3. Erneut unter „Personen → Benutzer" prüfen, ob der Benutzer jetzt angelegt wurde.
  4. Ist das der Fall, die Umschaltung von Cloud → Lokal erneut durchführen.

den Benutzer NICHT manuell anlegen, weder in Mosquitto noch in der Benutzer Übersicht, die Integration selbst muss dies anlegen beim setup.

6.2 Bluetooth-Verbindung wird nicht oder nur sporadisch angezeigt

Dieses Problem betrifft nur Geräte mit Bluetooth-Umschaltung (siehe Tabelle in Kapitel 1) – Geräte mit ZenSDK sind davon nicht betroffen, da sie kein Bluetooth nutzen.

Die häufigste Ursache ist Reichweite: Der Bluetooth-Stick ist zu weit vom Zendure-Gerät entfernt oder es gibt Störungen (Wände, Metall, andere 2,4-GHz-Geräte).

Lösungsweg über den HA-Bluetooth-Stick:

  • Abstand zwischen Bluetooth-Stick und Zendure-Gerät verringern.
  • Bei der Umschaltung testweise Fenster/Türen öffnen.
  • Mit dem Bermuda-Tool die Signalstärke (RSSI) der Geräte genauer einschätzen.
  • Prüfen, ob beim „Kopf"-Gerät überhaupt eine Bluetooth-MAC-Adresse angezeigt wird – das ist das Zeichen, dass die BLE-Verbindung grundsätzlich funktioniert. Die Integration scannt alle 90 Sekunden danach.

Alternative, wenn kein Bluetooth-Stick vorhanden ist oder das Gerät zu weit vom HA-Server entfernt steht: ZendureBle

FireSon hat für genau diesen Fall eine kleine, browserbasierte Web-App entwickelt, mit der du ein Gerät mit Bluetooth-Umschaltung direkt über Bluetooth deines Smartphones/Laptops auf einen lokalen MQTT-Server umschalten kannst – unabhängig vom Bluetooth-Stick deines HA-Servers.

So funktioniert es:

  1. Öffne die App mit einem Gerät (Smartphone, Laptop), das in Bluetooth-Reichweite deines Zendure-Geräts ist – du bist also nicht mehr auf die Position deines HA-Servers/Bluetooth-Sticks angewiesen.
  2. Die App zeigt dir einen Benutzernamen und ein Passwort, die du in deinem MQTT-Server hinterlegen musst:
    • EMQX-AddOn: keine Aktion nötig, da anonymer Zugriff standardmäßig erlaubt ist.
    • Mosquitto-AddOn: den angezeigten Benutzernamen als Benutzer in Home Assistant anlegen (genau wie bei der regulären Umschaltung über die Integration).
  3. Verbinde dich per Web-Bluetooth mit dem Zendure-Gerät und trage die MQTT-Zieldaten (Server, Port, Zugangsdaten) ein.
  4. Nach erfolgreicher Umschaltung kommuniziert das Gerät wie gewohnt per WLAN/MQTT mit deinem lokalen Server – die Zendure-Integration erkennt es genauso wie bei einer Umschaltung über den HA-eigenen Bluetooth-Stick.

6.3 Umschaltung schlägt fehl oder hängt

Wichtige Regeln, bevor du in Panik gerätst:

  • Der komplette Umschaltvorgang kann bis zu 15 Sekunden dauern und aus mehreren Gründen fehlschlagen.
  • Nach dem Versuch erscheint eine HA-Benachrichtigung mit dem Ergebnis (Erfolg oder Fehler).
  • Bei Fehlschlag: den MQTT-Reset-Button nutzen, um den Vorgang erneut zu starten – je nach Bluetooth-Verbindung können mehrere Versuche nötig sein.
  • Zwischen zwei Umschaltversuchen immer mindestens 5 Minuten Pause einhalten – die Aktualisierung der BLE-Daten läuft nur in diesem Takt.

Checkliste, falls die Umschaltung dauerhaft nicht klappt:

  • Ist der Bluetooth-Stick korrekt installiert, von HA erkannt und in Reichweite?
  • Steht beim Zendure-„Kopf"-Gerät eine Bluetooth-MAC-Adresse? (Zeichen für funktionierende BLE-Verbindung)
  • Zeigt „Verbindungsstatus" mindestens „Verbunden (Cloud)"? Falls nein: Integration neu konfigurieren und alle Eingaben (Token, MQTT-Daten) prüfen.

6.4 Neuere, klarere Setup-Fehlermeldungen (ab entsprechender Version)

Die Integration wurde überarbeitet, sodass ein fehlgeschlagenes Setup nicht mehr nur „ungültige Eingabe" anzeigt, sondern konkret sagt, woran es liegt. Mögliche Meldungen und was sie bedeuten:

Fehlermeldung (sinngemäß) Bedeutung / Lösung
Ungültiger/fehlerhafter Token Token falsch kopiert oder aus dem falschen Account (siehe Abschnitt „Zendure-Token" oben)
Netzwerkproblem HA kann die Zendure-Cloud-API nicht erreichen – Internetverbindung des HA-Servers prüfen
API-Ablehnung (mit Zendure-eigener Meldung) Die Zendure-Cloud selbst lehnt die Anfrage ab – der Integrations-Dialog zeigt hier direkt Zendures Original-Fehlertext an
Gültiger Token, aber keine Geräte gefunden Der Token ist technisch korrekt, gehört aber zu einem Account/einer Region ohne registrierte Geräte – meist ein Zweitaccount statt Hauptaccount
Fehlender MQTT-Server Bei aktiviertem „Lokales MQTT" wurde kein gültiger Server eingetragen (siehe Feld mqttserver oben)

Falls du eine dieser Meldungen siehst: Der Integrations-Dialog nennt dir jetzt die tatsächliche Ursache – meist reicht es, den Token neu zu kopieren (aus dem Hauptaccount!) oder die MQTT-Felder erneut zu prüfen.

6.5 Sonstige häufige Probleme (nicht MQTT-spezifisch, aber relevant)

  • Ein Gerät wird nicht angezeigt: Zwei Geräte dürfen nicht denselben Namen tragen – vorab in der Zendure-App umbenennen, Sonderzeichen vermeiden.
  • Überschuss-Laden hängt bei 50 W oder startet nicht: Vermutlich wurden benötigte Sensoren/Entitäten deaktiviert (u. a. gridInputPower, outputHomePower, packInputPower, outputPackPower, socLimit, outputLimit, inputLimit, minSoc, socSet, socStatus, pass, electricLevel, acMode, hemsState, ggf. solarInputPower, gridOffPower).
  • Nach einem Update funktioniert plötzlich nichts mehr: Meist ein Upgrade von einer sehr alten Version – seit Einführung des API-Tokens ist das alte Zwei-Account-Modell nicht mehr kompatibel. Integration entfernen (aus „Geräte & Dienste" und HACS) und komplett neu einrichten.

6.6 „no shared cipher" / „Protocol error" im Mosquitto-Log nach einem Firmware-Update

Wenn nach einem Firmware-Update deines Zendure-Geräts (z. B. Hyper 2000) plötzlich alle Entitäten keine Daten mehr liefern und im Mosquitto-Log Meldungen wie

OpenSSL Error while trying to get the error[0]: error:0A0000C1:SSL routines::no shared cipher
Client <IP> disconnected: Protocol error.

auftauchen, liegt das nicht an einem Zertifikatsproblem, sondern an einer neuen TLS-Pflicht: Neuere Firmware verbindet sich lokal jetzt verschlüsselt auf Port 8883 (EU-Vorgabe EN 18031), und der Standard-Mosquitto-Broker bietet dafür noch keine passende Cipher-Suite an.

Kurzlösung: Dem Mosquitto-Broker ein selbstsigniertes RSA-Zertifikat hinterlegen (das Gerät verbindet sich per IP und validiert das Zertifikat nicht). Die HA-eigene MQTT-Integration bleibt davon unberührt, da sie weiterhin unverschlüsselt auf Port 1883 läuft – ein erneutes Pairing ist nicht nötig, das Gerät verbindet sich automatisch neu, sobald der Broker akzeptiert wird.

Ausführliche Schritt-für-Schritt-Anleitung inkl. Verbindungstest: Troubleshoot: TLS-Cipher-Fehler bei lokalem MQTT

7. Wenn gar nichts hilft: Debug-Log erstellen und Issue eröffnen

  1. Debug-Protokollierung bei der Zendure-Integration aktivieren (drei Punkte oben rechts → „Debug-Protokoll aktivieren").
  2. Integration unter „Geräte & Dienste" löschen (HACS-Installation bleibt bestehen).
  3. Home Assistant neu starten (nur HA, nicht das ganze System) und 5 Minuten warten, bis alles initialisiert ist.
  4. Zendure-Integration erneut über „Geräte & Dienste" hinzufügen.
  5. Nach 5–10 Minuten das Debug-Log wieder deaktivieren – dann liegen genug Daten vor.
  6. Über dein GitHub-Konto (das du ohnehin für HACS hast) ein neues Issue eröffnen: https://github.com/Zendure/Zendure-HA/issues/new/choose
  7. Problem möglichst genau, aber kurz beschreiben und das Debug-Log anhängen.

Weiterführende Links