Lokale Home-Assistant-Integration für Lampen mit der ninlight-Firmware (migrierte Klyqa-Lampen auf WinnerMicro W600: GU10, E27, E14, G95). Keine Cloud, kein Konto – HA spricht direkt mit der REST-API der Lampe auf Port 3333.

Voraussetzungen

Home Assistant 2026.9 oder neuer
Lampen mit ninlight-Firmware im selben Netz

Installation

Das Repo ist privat und nicht über HACS verfügbar. Den Ordner custom_components/ninlight nach <config>/custom_components/ninlight der Home-Assistant-Instanz kopieren (z. B. per /usr/bin/scp -r oder über das Samba-/SSH-Add-on) und Home Assistant neu starten. Für ein Update denselben Ordner ersetzen und erneut neu starten.

Einrichtung

Lampen werden per mDNS (_ninlight._tcp) gefunden und unter Einstellungen → Geräte & Dienste angeboten. Alternativ „Integration hinzufügen → ninlight" und IP-Adresse oder ninlight-xxxx.local eingeben.

Das Token-Feld ist mit dem öffentlichen Vorgabe-Token aabbccddeeff0011223344 vorbelegt. Solange eine Lampe dieses Token nutzt, kann jeder in deinem Netz sie neu konfigurieren, neu starten und neu flashen; HA zeigt dafür einen Reparaturhinweis. Schalten und Dimmen sind ohne auth_all ohnehin für jeden im Netz möglich – ein eigenes Token allein schützt nicht davor.

Eigenes Token auf der Lampe setzen (PUT /api/v1/system/settings mit {"type":"token","token":"…"}) und in HA über Neu konfigurieren eintragen. Willst du zusätzlich das Schalten schützen, aktiviere auth_all auf der Lampe:

PUT /api/v1/system/settings
{"type": "auth", "all": true}

Mit aktiviertem auth_all verlangt jede Abfrage – auch lesende – das Token; ein falsches oder fehlendes Token führt dann sofort zur Neuanmeldung.

Wechselt eine Lampe ihre IP, aktualisiert mDNS den Eintrag selbst (Identität ist die MAC). Das gilt ungeprüft: Ein Gerät im selben Netz, das dieselbe MAC per mDNS ankündigt, übernimmt damit den Host-Eintrag und kann so an Anfragen mit Token gelangen, die eigentlich an die echte Lampe gehen (relevant nur in einem bereits kompromittierten Netz).

Entitäten

Entität	Art	Hinweis
Lampe	Licht	An/Aus, Helligkeit, Farbe (RGB-Lampen), Farbtemperatur, Übergang
Einblenden, Ausblenden, Standardübergang	Zahl (Konfiguration)	Millisekunden
Einschaltverhalten	Auswahl (Konfiguration)	letzter Zustand / ein / aus
Bei Änderung einschalten	Schalter (Konfiguration)
Neustart	Taste (Konfiguration)	Werksreset wird bewusst nicht angeboten
Signalstärke	Sensor (Diagnose)
IP-Adresse, freier Speicher, letzter Update-Fehler, letzter Start	Sensor (Diagnose)	standardmäßig deaktiviert
Firmware	Update	siehe unten

Verfügbarkeit

Kurze Aussetzer werden toleriert: Erst nach 3 fehlgeschlagenen Abfragen in Folge gilt die Lampe als nicht verfügbar. Beim Standardintervall von 30 s und 10 s Timeout sind das 90–120 s (gemessen an der G95: 90 s und 110 s). Fehlgeschlagene Schaltbefehle werden dagegen sofort als Fehler gemeldet. Im HA-Debug-Log erscheinen tolerierte Fehlschläge als „poll failed (n/3)“ und trotzdem mit „success: True“, weil der zuletzt bekannte Zustand weiterverwendet wird.

Firmware-Updates

Home Assistant bietet Updates aus dem Ordner <config>/ninlight_firmware/ an (wird beim ersten Start angelegt). Dort *_ota.img-Dateien ablegen; Dateinamen sind egal. HA liest Gerätetyp und Version aus dem Trailer des Images, prüft die Prüfsumme und bietet jeder Lampe nur Images ihres Gerätetyps an, die neuer sind als ihre Firmware.

Die Lampe lädt das Image über reines http:// direkt von Home Assistant, unter einer zufälligen Adresse, die nur während dieses einen Updates gilt. Erreichen die Lampen die interne URL von HA nicht über http:// (z. B. HA hinter HTTPS oder in Docker auf macOS), in den Optionen der Integration „Adresse, unter der Lampen Home Assistant erreichen" setzen, etwa http://192.168.1.50:8123.

WLAN-Sicherung – wichtig

Eine Lampe kennt ihr WLAN entweder aus gespeicherten Einstellungen oder nur aus der einkompilierten Firmware (GET /api/v1/system/settings → wifi.source). Im zweiten Fall würde ein Image ohne WLAN-Zugangsdaten die Lampe nach dem Update aus dem Netz werfen – sie startet dann im Onboarding-Zugangspunkt.

Deshalb bietet HA einer solchen Lampe nur Images an, die die SSID ihres aktuellen WLANs enthalten. Liegt ein neueres Image ohne diese Zugangsdaten im Ordner, erscheint stattdessen ein Reparaturhinweis.

Das Release-Archiv der Firmware enthält Images ohne Zugangsdaten. Für Lampen, die ihr WLAN aus der Firmware beziehen, eigene Images mit Zugangsdaten bauen (config.local.cmake im Firmware-Repo).

Grenzen der Prüfung: geprüft wird die SSID, nicht das Passwort; und eine Heim-SSID, die zufällig einem Text der Firmware gleicht (z. B. ninlight-recovery), würde fälschlich als vorhanden erkannt.

Diagnose

Gerät → ⋮ → Diagnose herunterladen liefert Zustand, Systeminfo und passende Firmware-Dateien. Token, WLAN-Name, MAC und IP sind geschwärzt.

Entwicklung

uv venv --python /opt/homebrew/bin/python3.14 .venv && uv pip install --python .venv/bin/python -r requirements_dev.txt
scripts/check.sh

Home Assistant 2026.9 braucht Python ≥ 3.14.2. Vor jedem Push scripts/check.sh laufen lassen – das Repo liegt im Gitea ohne CI.

tests_unit/ läuft ohne Home-Assistant-Instanz (HTTP-Client gegen einen lokalen Server, Firmware-Logik), tests/ gegen eine Test-Instanz.

README.md Unescape Escape

ninlight für Home Assistant