TapHome

Nanoleaf RGB-Leuchte

Packet Parser → HTTP
Eingereicht von
Zuletzt aktualisiert: 04. 2026
Nanoleaf RGB-Leuchte

Nanoleaf ist eine Familie von Wi-Fi-LED-Leuchten — modulare Wandpaneele, LED-Streifen, Leuchtmittel, Stehlampen und Weihnachtslichterketten —, die alle dieselbe lokale REST-API auf TCP-Port 16021 sprechen. Eine einzige TapHome-Vorlage deckt jedes WiFi-erreichbare Nanoleaf-Produkt ab: TapHome fragt den Controller per HTTP im LAN ab und stellt das gesamte Setup als eine HSB-Leuchte mit Farbtemperatur bereit.

Unterstützte Modelle

ProduktModellcodeHinweise
Light Panels (früher Aurora)NL22Ohne Touch
Shapes HexagonsNL42Mit Touch
Shapes TrianglesNL47Mit Touch
Shapes Mini TrianglesNL48Mit Touch
Canvas (Quadrate)NL29Mit Touch
Elements Hexagons (Holzoptik)NL52Engerer CCT-Bereich (1500–4000 K)
LinesNL59Mit Touch
Matter WiFi Essentials (Leuchtmittel, Lightstrips, Weihnachtslichterketten, Stehlampe, A19)—Nur Firmware 3.0.10+; strengere Helligkeitsuntergrenze und engerer CCT-Bereich (2127–6535 K)

Reine Thread-Varianten von Nanoleaf Essentials und das Nanoleaf Skylight werden nicht unterstützt — die Vorlage erfordert einen WiFi-erreichbaren Controller, der die Open API auf Port 16021 spricht.

Gerätefunktionen

Leuchte (HSB + Farbtemperatur)

Die Vorlage stellt eine HSB-Leuchte mit Ein/Aus, Helligkeit, Farbton, Sättigung und Farbtemperatur bereit. In jedem Abfragezyklus (500 ms) sendet das Modul

1

GET /api/v1/{authToken}/

und speichert das vollständige Geräte-JSON in der benutzerdefinierten Variable StatusJson. Die Lese-Skripte für die einzelnen Eigenschaften parsen dann Felder aus diesem zwischengespeicherten Objekt:

  • Ein/Aus — state.on.value
  • Helligkeit — state.brightness.value (0–100), normalisiert auf den TapHome-Bereich 0,0–1,0
  • Farbton — state.hue.value (0–360°) — nur gelesen, wenn state.colorMode == "hs"
  • Sättigung — state.sat.value (0–100) — nur gelesen, wenn state.colorMode == "hs"
  • Farbtemperatur — state.ct.value (in Kelvin) — nur gelesen, wenn state.colorMode == "ct"

Alle Schreibvorgänge gehen an PUT /api/v1/{authToken}/state mit einem JSON-Body pro Eigenschaft:

1
2
3
4

{ "brightness": { "value": 75 } }
{ "hue":        { "value": 212 } }
{ "sat":        { "value": 100 } }
{ "ct":         { "value": 4000 } }

Die Vorlage deklariert 1800–6500 K als Farbtemperaturbereich — eine praktische Teilmenge dessen, was die Hardware tatsächlich unterstützt. Werte außerhalb des physischen Bereichs des Geräts werden von der Nanoleaf-Firmware stillschweigend begrenzt (siehe Hinweise und Einschränkungen).

Farbmodus-Gating

Nanoleaf-Controller befinden sich immer in genau einem von drei Farbmodi:

colorModeBedeutung
hsFarbton/Sättigungs-Modus — Farbton- und Sättigungswerte sind aktiv
ctFarbtemperaturmodus — CCT-Wert ist aktiv
effectEine dynamische Szene läuft

Die TapHome-Leseskripte beachten dies: Farbton- und Sättigungsabfragen geben NULL zurück, wenn sich der Controller im Modus ct oder effect befindet, und die Farbtemperatur-Abfrage gibt NaN zurück, wenn er im Modus hs oder effect ist. Dies verhindert, dass veraltete Werte aus einem anderen Modus in das Dashboard gelangen. Das Schreiben eines beliebigen Farbton- oder Sättigungswerts versetzt den Controller in den hs-Modus, das Schreiben eines CCT-Werts in den ct-Modus — beide stoppen einen laufenden Effekt.

Konfiguration

1. Controller in der Nanoleaf-App koppeln

Montieren Sie die Paneele / Leuchtmittel / den Streifen, installieren Sie die mobile Nanoleaf-App und verbinden Sie den Controller über den App-Kopplungsvorgang mit dem lokalen Wi-Fi-Netzwerk. Notieren Sie sich die IPv4-Adresse des Controllers — die App zeigt sie unter Geräteeinstellungen → Info an, oder sie kann aus der DHCP-Lease-Tabelle des Routers gelesen werden.

Weisen Sie dem Nanoleaf-Controller eine DHCP-Reservierung (oder eine statische IP) zu, damit sich die Adresse nach einer Lease-Erneuerung nicht ändert. Die TapHome-Vorlage speichert die IP in ihren Importparametern und führt keine automatische Erkennung durch.

2. Open API-Token generieren

Die Nanoleaf Open API erfordert eine einmalige Kopplung zwischen TapHome und dem Controller. Die Kopplung erzeugt einen permanenten 32-stelligen auth_token, der Neustarts und Firmware-Updates übersteht.

  1. Halten Sie auf dem Nanoleaf-Controller (kleine Inline-Einheit bei Paneelen, oder das Gerät selbst bei Leuchtmitteln / Streifen) die Ein-/Aus-Taste 5–7 Sekunden gedrückt, bis die weiße LED in einem Muster zu blinken beginnt. Das Gerät befindet sich nun 30 Sekunden im Kopplungsmodus.

  2. Senden Sie innerhalb des 30-Sekunden-Fensters einen leeren POST an den Kopplungs-Endpoint — zum Beispiel mit curl, PowerShell oder Postman:

    1

    curl -X POST http://{controller-ip}:16021/api/v1/new

    Der Controller antwortet mit:

    1

    { "auth_token": "xxxKJISJCjY2hfAyilpyIOfGixxxx" }

  3. Kopieren Sie die 32-stellige Zeichenkette auth_token.

Wenn das Fenster abläuft, bevor der POST eintrifft, gibt der Endpoint 403 Forbidden zurück — halten Sie die Ein-/Aus-Taste erneut und versuchen Sie es erneut.

Einige Essentials-Bauformen (Leuchtmittel, Streifen) haben keine physische Taste. Starten Sie in diesem Fall die Kopplung aus den Geräteeinstellungen in der Nanoleaf-App — die App aktiviert das 30-Sekunden-Fenster für Sie.

3. Vorlage in TapHome importieren
  1. Erstellen Sie in TapHome ein neues PacketParser-Gerät aus der Vorlage Nanoleaf RGB light.
  2. Geben Sie die IPv4-Adresse des Controllers als Importparameter ipAddress ein. Der Port ist fest auf 16021 gesetzt und muss nicht geändert werden.
  3. Öffnen Sie die Geräteeigenschaften, suchen Sie die benutzerdefinierte Variable authToken und fügen Sie den in Schritt 2 generierten 32-stelligen Token ein.
  4. Speichern. Das Modul fragt /api/v1/{authToken}/ alle 500 ms ab und füllt die HSB-Leuchte mit dem aktuellen Status.

Wenn der Token falsch ist oder abgelaufen ist, schlägt jede Leseoperation mit 401 Unauthorized im TapHome-Log fehl.

Netzwerkanforderungen
  • Nur ausgehendes TCP 16021 vom TapHome CCU zum Nanoleaf-Controller. Keine Cloud-Aufrufe, kein MQTT-Broker, keine HTTPS-Zertifikate.
  • Das CCU und der Controller müssen sich im selben LAN / VLAN befinden. Wenn Wi-Fi- und kabelgebundene Netze segmentiert sind, fügen Sie eine Firewall-Regel hinzu, die TCP 16021 zwischen ihnen erlaubt.
  • Nanoleaf-Controller werben den Dienst _nanoleafapi._tcp über mDNS. Die Vorlage benötigt eine direkte IP, aber mDNS kann zur Erkennung mit avahi-browse -r _nanoleafapi._tcp (Linux) oder dns-sd -B _nanoleafapi._tcp (macOS) verwendet werden.

Die Nanoleaf Open API ist nur HTTP — es gibt kein HTTPS und keine Transportverschlüsselung. Sie ist innerhalb des LAN sicher, darf aber niemals im öffentlichen Internet freigegeben werden. Leiten Sie Port 16021 nicht über den Router weiter.

Hinweise und Einschränkungen

Farbtemperaturbereich hängt von der Modellfamilie ab

Die TapHome-Vorlage deklariert 1800–6500 K als schreibbaren CCT-Bereich. Der zugrunde liegende Hardware-Bereich unterscheidet sich je nach Familie:

FamilieHardware-CCT-BereichVerhalten außerhalb des Bereichs
Light Panels, Shapes, Canvas, Lines1200–6500 KVon Firmware begrenzt
Elements Hexagons1500–4000 KVon Firmware begrenzt
Matter WiFi Essentials2127–6535 KVon Firmware begrenzt; 1800 K liegt unter der 2127-K-Untergrenze, daher begrenzen Essentials auf 2127 K

Das Schreiben eines Wertes außerhalb des physischen Bereichs des Geräts löst keinen Fehler aus — der Controller verwendet stillschweigend seinen eigenen Grenzwert. Bevorzugen Sie beim Entwurf von Dashboards für Essentials CCT-Werte im gemeinsamen Fenster 2127–6500 K.

Essentials lehnen Helligkeit = 0 ab

Klassische Controller (Light Panels, Shapes, Canvas, Elements, Lines) akzeptieren brightness: 0. Matter WiFi Essentials erzwingen ein Minimum von 1 und lehnen 0 mit HTTP 400 ab. Um eine Essentials-Leuchte oder einen Essentials-Streifen auszuschalten, verwenden Sie den Ein/Aus-Kanal, anstatt die Helligkeit auf Null zu setzen.

Farbton-/Sättigungs-/CCT-Lesevorgänge können NULL oder NaN zurückgeben

Da hs und ct sich gegenseitig ausschließen und beide während eines laufenden Effekts inaktiv sind, geben Lesevorgänge im falschen Modus absichtlich NULL (Farbton / Sättigung) oder NaN (ct) zurück. Dies ist erwartetes Verhalten, kein Fehler. Ein Schreibvorgang für Farbton / Sättigung / ct bringt den Controller in den Modus hs oder ct zurück, und die Lesevorgänge werden fortgesetzt.

Ein Token pro Controller, nicht pro Panel

Ein Shapes- oder Canvas-Layout mit mehreren Panels ist ein einzelnes TapHome-Gerät. Der Auth-Token wird auf Controller-Ebene ausgegeben und deckt jedes an ihn angeschlossene Panel ab.

IPv6-mDNS-Instabilität bei Firmware 8.5.2+

Die openHAB-Community hat berichtet, dass IPv6-mDNS-Einträge bei einigen Controllern mit Firmware 8.5.2+ zwischen ONLINE und OFFLINE wechseln. Wenn die mDNS-Erkennung instabil ist, legen Sie eine feste IPv4-DHCP-Reservierung fest und verwenden Sie die IP direkt — die TapHome-Vorlage verlässt sich ohnehin nicht auf mDNS.

Fehlerbehebung

401 Unauthorized bei jedem Lesevorgang

Der authToken ist falsch, abgelaufen oder wurde widerrufen. Generieren Sie einen neuen Token (halten Sie die Ein-/Aus-Taste 5–7 s und senden Sie POST an /api/v1/new) und fügen Sie ihn in die benutzerdefinierte Variable authToken ein.

403 Forbidden beim Generieren eines Tokens

Das 30-Sekunden-Kopplungsfenster ist geschlossen. Halten Sie die Ein-/Aus-Taste erneut, bis die LED in einem Muster blinkt, und senden Sie dann sofort POST /api/v1/new.

Farbton / Sättigung zeigen NULL im Dashboard

Der Controller ist im Modus ct oder ein Effekt läuft. Schreiben Sie einen beliebigen Farbton- oder Sättigungswert, um den Controller zurück in den Modus hs zu bringen, oder stellen Sie eine Farbe mit der HSB-Auswahl ein. Die Vorlage kann keinen Farbton-/Sättigungswert ableiten, wenn das Gerät keinen erzeugt.

Farbtemperatur liest sich als NaN

Der Controller ist im Modus hs oder ein Effekt läuft. Schreiben Sie einen CCT-Wert, um in den Modus ct zu wechseln, oder stellen Sie eine Farbtemperatur über das Dashboard ein. Wenn ein Effekt läuft, stoppen Sie ihn aus der Nanoleaf-App (oder schreiben Sie einen beliebigen HSB- / CCT-Wert — dies stoppt ebenfalls den Effekt).

Helligkeits-Schreibvorgang schlägt bei Essentials fehl

Matter WiFi Essentials lehnen brightness: 0 ab. Steuern Sie den Ein/Aus-Kanal, um auszuschalten, anstatt 0 in die Helligkeit zu schreiben. Werte von 1–100 werden auf allen Modellen akzeptiert.

Controller fällt bei Firmware 8.5.2+ offline

Wenn das TapHome CCU den Controller wiederholt verliert, weisen Sie eine statische IPv4-DHCP-Reservierung zu und verwenden Sie die IP im Importparameter ipAddress — die IPv6-mDNS-Schicht kann auf diesem Firmware-Zweig instabil sein.

Verfügbare Geräte

Nanoleaf Modul
Benutzerdefinierte Variablen
authToken (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx32-stelliger Nanoleaf Open API-Kopplungstoken. Einmalig generieren, indem die Ein-/Aus-Taste des Controllers 5–7 Sekunden lang gehalten und innerhalb von 30 Sekunden POST http://{ip}:16021/api/v1/new gesendet wird — den zurückgegebenen auth_token hier einfügen. Der Token übersteht Neustarts und Firmware-Updates.
1) Hold the controller's on-off button for 5–7 seconds until the LED flashes in a pattern. 2) Within 30 seconds, send an empty POST request to http://{ip}:16021/api/v1/new (curl, Postman, or any HTTP client). 3) Copy the 32-character auth_token from the response and paste it into this variable.

Nanoleaf

Lesen (Modul)
#Generate an authorization token
# 1. On the Nanoleaf controller, hold the on-off button for 5-7 seconds until the LED starts flashing in a pattern.

# 2. Send a POST request to the authorization endpoint within 30 seconds of activating pairing, like this (substituting the IP address and port for your central controller):
#http://$[IpAddress]:16021/api/v1/new


VAR response := SENDHTTPREQUEST("/api/v1/"+authToken+"/", "GET");
IF response.IsSuccess
 StatusJson := response.Content;
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Nanoleaf RGB-Leuchte HSB-Licht

HSB-Leuchte mit dualem Farbmodus — Farbton und Sättigung (0–360° / 0–100 %) oder Farbtemperatur (1800–6500 K deklariert, Hardware-Bereich hängt vom Modell ab). Helligkeit 0–100 %. Farbton-/Sättigungs-Lesevorgänge sind nur im hs-Modus aktiv; CCT-Lesevorgänge sind nur im ct-Modus aktiv; beide sind während eines laufenden Effekts inaktiv.

HSBLight json

Nanoleaf RGB-Leuchte

Lesen (Modul)
var value := PARSEJSON(StatusJson, "state.on.value");
IF(ISNULL(value), NaN, IF(value, 1, 0));
Helligkeit lesen
var value := PARSEJSON(StatusJson, "state.brightness.value")/100;
IF(ISNULL(value), NaN, value);
Helligkeit schreiben
var content:="{\"brightness\" : {\"value\":"+ROUND(Hb*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Farbton lesen
var colorMode := PARSEJSON(StatusJson, "state.colorMode",1);
IF colorMode = "hs"
  var value := PARSEJSON(StatusJson, "state.hue.value",1);
  RETURN(IF(ISNULL(value), NaN, value));
ELSE
  RETURN(NULL);
END
Farbton schreiben
var content:="{\"hue\" : {\"value\":"+ROUND(Hd)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Sättigung lesen
var colorMode := PARSEJSON(StatusJson, "state.colorMode",1);
IF colorMode = "hs"
  var value := PARSEJSON(StatusJson, "state.sat.value",1);
  RETURN(IF(ISNULL(value), NaN, value/100));
ELSE
  RETURN(NULL);
END
Sättigung schreiben
var content:="{\"sat\" : {\"value\":"+ROUND(Sa*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Farbtemperatur lesen
var colorMode := PARSEJSON(StatusJson, "state.colorMode",1);
IF colorMode = "ct"
  var value := PARSEJSON(StatusJson, "state.ct.value",1);
  RETURN(IF(ISNULL(value), NaN, value));
ELSE
  RETURN(NaN);
END
Farbtemperatur schreiben
var content:="{\"ct\" : {\"value\":"+ROUND(Ct)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Verbindung: Packet Parser → HTTP
Mögliche Verbesserungen (10)
  • Effects / Scenes — PacketParserHSBLight ignores the /effects endpoint — dynamic scenes (Color Burst, Cyan Sky, user plugins, etc.) can only be started from the Nanoleaf app. Once an effect is running, TapHome can still drive on/off and brightness over it.
  • Custom effect creation — Plugin-based and static custom effects (animType = plugin / static / custom) are not supported by the template.
  • Identify — Flashes the panels for 2–3 seconds so the installer can confirm which controller they are addressing. Not exposed as a service action.
  • Panel layout — Per-panel positions, shapes, and global rotation are available from the API but not surfaced — TapHome treats the whole controller as a single HSB light.
  • Rhythm module — Audio-reactive Rhythm add-on status (connected, active, mode, aux availability) not exposed.
  • External UDP streaming — Real-time per-panel RGBW streaming for music visualizers / screen mirror is outside the scope of PacketParserHSBLight.
  • Server-Sent Events push — Push notifications for state / layout / effect / touch changes. Template uses 500 ms polling instead — adequate for HS/CT/brightness/on-off.
  • Touch / gesture input — Single tap, double tap, long press, swipe gestures on Canvas and touch-enabled Shapes are not exposed.
  • Fade transitions — The brightness PUT accepts an optional `duration` field for hardware-level fades — template writes bare value without transition.
  • Revoke auth token — Tokens can be explicitly revoked via DELETE. Not exposed as a service action — removal must be done manually with curl.

Quellen