Installation der Home-Assistant-Integration

Diese Integration zeigt die Daten Ihres JK BMS Web Gateway (Zellspannungen, Gesamtspannung/-strom/-leistung, SOC/SOH, Temperaturen, MOSFET- und Alarmstatus) direkt in Home Assistant an — ganz ohne Firmware-Änderungen. Sie verbindet sich einfach mit der bestehenden lokalen Schnittstelle des Geräts, genau wie dessen eigenes Web-Dashboard.

Wichtig: Diese Integration funktioniert nur in Ihrem lokalen Netzwerk — Home Assistant muss sich im selben WLAN/LAN wie das Gerät selbst befinden. Die Überwachung von überall ohne gemeinsames Netzwerk ist eine separate, noch nicht umgesetzte Idee für die Zukunft.

Was Sie benötigen

Ein JK BMS Web Gateway mit aktivierter Lizenz (über seine eigene Webseite — das Feld „Licencia" in der Kopfzeile). Ohne dies schlägt die Einrichtung der Integration mit einem Lizenzfehler fehl.
Home Assistant, erreichbar im selben lokalen Netzwerk wie das Gerät.
Eine Möglichkeit, Dateien in den config-Ordner Ihres Home Assistant hochzuladen — z. B. die Add-ons Studio Code Server, Samba share oder File editor (alle im Add-on Store verfügbar).

1. Integration herunterladen und installieren

Integrationsdateien herunterladen

Integration herunterladen (.zip)

Das Zip enthält einen Ordner jkbms_web_gateway/, genau in der von Home Assistant erwarteten Form.

In den Ordner `custom_components` entpacken

Das Ergebnis muss config/custom_components/jkbms_web_gateway/manifest.json sein, mit den übrigen Dateien direkt in diesem Ordner (nicht eine Ebene tiefer). Legen Sie den Ordner custom_components in config zuerst an, falls er noch nicht existiert.

Home Assistant neu starten

Einstellungen → System → Neu starten.

Integration hinzufügen

Einstellungen → Geräte & Dienste → Integration hinzufügen und nach „JK BMS Web Gateway" suchen.

Geräteadresse eingeben

Die IP-Adresse des Gateways (z. B. 192.168.0.239) oder jkbms.local, falls mDNS in Ihrem Netzwerk funktioniert. Den Port bei 80 belassen, falls Sie ihn nicht geändert haben.

Nach erfolgreichem Hinzufügen erscheinen zwei neue Geräte: „JK BMS Gateway" (Firmware, IP, Lizenz, CAN/NTP-Status und ein „Rescan bus"-Button) und „JK BMS" (Ihre Batterie — Spannung, Strom, Leistung, einzelne Zellen, Temperaturen, Status).

Mehrere Batterien am selben RS485-Bus? Die Integration erkennt automatisch jede angeschlossene Batterie (Adressen 0–15) und erstellt dafür ein eigenes Gerät. Nach dem Anschließen einer weiteren Batterie genügt ein Druck auf den Button „Rescan bus" am Gerät „JK BMS Gateway" — das neue Gerät erscheint ohne Neustart von Home Assistant. Ihre bestehenden Entitäten bleiben unverändert.

⚠️ Wichtig bei mehreren Batterien: Adresse 0 niemals verwenden. Bestätigt: Eine Batterie mit Adresse 0 verhält sich von selbst als „Master" und durchsucht fortlaufend den gesamten Bus — das blockiert das Auslesen von ihr und den benachbarten Batterien, selbst bei korrekter Verkabelung, Terminierung und Erdung. Das ist kein Fehler im Gateway oder dieser Integration. Lösung: Stellen Sie die Adresse jeder Batterie über die DIP-Schalter (oder die Hersteller-App) auf 1-15 ein — bei zwei Batterien z. B. 1 und 2, nicht 0 und 1.

2. Dashboard hinzufügen

Das fertige Dashboard finden Sie im obigen Download sowie direkt im Projekt-Repository (dashboards/jkbms-dashboard.yaml). Es lässt sich auf zwei Arten verwenden:

Als neuer Tab in einem vorhandenen Dashboard

Dashboard öffnen → ⋮ (oben rechts) → Dashboard bearbeiten → ⋮ → Im YAML-Editor bearbeiten. Fügen Sie unter der Liste views: den Block - title: JK-BMS (von dieser Zeile bis zum nächsten - title:) als weiteren Eintrag ein. Speichern.

Oder als völlig neues Dashboard

Einstellungen → Dashboards → Dashboard hinzufügen → Neues Dashboard von Grund auf → ⋮ → Im YAML-Editor bearbeiten → den gesamten Dateiinhalt anstelle des Platzhalterinhalts einfügen. Speichern.

Falls „Im YAML-Editor bearbeiten" beim Standard-Dashboard nicht angeboten wird, ist das normal — Home Assistant bietet diese Option erst an, nachdem das Dashboard einmal übernommen/bearbeitet wurde, oder verwenden Sie ein neues Dashboard von Grund auf, das sie sofort anbietet.

Das Dashboard geht von einem 16-zelligen Pack aus. Falls Ihr Gerät eine andere Zellenzahl hat, passen Sie die Zeilen sensor.jk_bms_cell_<n>_voltage / _resistance entsprechend an.

Sensoren werden kurz „Unavailable" — das ist normal

Wenn manche Sensoren gelegentlich für ein paar Sekunden „Unavailable" anzeigen und dann mit einem echten Wert zurückkehren, ist das kein Fehler der Integration oder des Dashboards — genau so reagiert das System, wenn das Gerät gerade keine Daten vom BMS über den RS485-Bus lesen konnte (z. B. vorübergehende Störung). Die Integration zeigt bewusst nie einen veralteten oder erfundenen Wert an. Sind Sensoren dauerhaft nicht verfügbar, liegt ein anderes, echtes Problem vor — siehe Fehlerbehebung unten.

Fehlerbehebung

Lizenzfehler beim Hinzufügen: öffnen Sie zuerst die eigene Webseite des Geräts und aktivieren Sie dort die Lizenz (Licencia → Overiť), dann erneut versuchen.
„Cannot connect" beim Hinzufügen: IP-Adresse/Host prüfen und ob das Gerät von Home Assistant aus überhaupt erreichbar ist — versuchen Sie, http://<Geräte-IP>/api/info im Browser im selben Netzwerk zu öffnen.
Sensoren sind dauerhaft nicht verfügbar, nicht nur gelegentlich: prüfen Sie die Diagnosesensoren „License verified" und „Last error" unter dem Gerät in Home Assistant sowie, ob das Gateway überhaupt eingeschaltet und erreichbar ist.
Option „Im YAML-Editor bearbeiten" fehlt: ein Standard-Dashboard bietet diese Option erst an, nachdem Sie es einmal bearbeitet oder ein neues von Grund auf angelegt haben.