---
title: "Nanoleaf RGB-Leuchte"
description: "Nanoleaf-Panels, -Strips und -Leuchtmittel in TapHome integrieren. Lokale HTTP-Steuerung von HSB und Farbtemperatur auf Port 16021 — ohne Cloud."
url: "https://taphome.com/de/compatibility/nanoleaf-rgb-light/"
language: de
lastmod: 2026-04-15
generator: hugo
ai:
  topics: ["http","lighting","wifi","rgb","cct","packet-parser"]
  questions: ["Wie integriere ich Nanoleaf Light Panels in TapHome?","Wie generiere ich einen Nanoleaf auth_token für TapHome?","Welche Nanoleaf-Modelle werden von der TapHome-Vorlage unterstützt?","Warum gibt TapHome NULL für Farbton und Sättigung bei Nanoleaf zurück?","Kann TapHome Nanoleaf-Effekte oder -Szenen starten?","Warum schaltet sich meine Nanoleaf Essentials-Leuchte bei Helligkeit 0 nicht aus?"]
---

# Nanoleaf RGB-Leuchte

Kommunikation: Packet Parser → HTTP

- [Nanoleaf Open API Dokumentation](https://gist.github.com/dennishn/ae06bf574748727bcce5127394a8ba43)
- [Nanoleaf Matter WiFi Essentials Open API](https://nanoleaf.atlassian.net/wiki/spaces/nlapid/pages/2296381472/Nanoleaf+Matter+WiFi+Essentials+Open+API+Documentation)

> Netzwerkadresse
> 
> TapHome erreicht dieses Gerät unter der beim Import eingegebenen Adresse. Geben Sie dem Gerät eine feste Adresse — eine IP-Reservierung im Router oder seinen mDNS-Namen, falls es einen unterstützt —, sonst funktioniert die Integration nicht mehr, sobald der Router die Adresse ändert.
> 
> [Netzwerkvorbereitung](https://taphome.com/de/docs/setup/network-preparation/)

## Integrationsanleitung

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

| Produkt | Modellcode | Hinweise |
|---------|-----------|----------|
| Light Panels (früher Aurora) | NL22 | Ohne Touch |
| Shapes Hexagons | NL42 | Mit Touch |
| Shapes Triangles | NL47 | Mit Touch |
| Shapes Mini Triangles | NL48 | Mit Touch |
| Canvas (Quadrate) | NL29 | Mit Touch |
| Elements Hexagons (Holzoptik) | NL52 | Engerer CCT-Bereich (1500–4000 K) |
| Lines | NL59 | Mit Touch |
| Matter WiFi Essentials (Leuchtmittel, Lightstrips, Weihnachtslichterketten, Stehlampe, A19) | — | Nur Firmware 3.0.10+; strengere Helligkeitsuntergrenze und engerer CCT-Bereich (2127–6535 K) |

> [!INFO]
> 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

```
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:

```json
{ "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](https://taphome.com/de/compatibility/nanoleaf-rgb-light/#notes-and-limitations)).

### Farbmodus-Gating

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

| `colorMode` | Bedeutung |
|-------------|-----------|
| `hs` | Farbton/Sättigungs-Modus — Farbton- und Sättigungswerte sind aktiv |
| `ct` | Farbtemperaturmodus — CCT-Wert ist aktiv |
| `effect` | Eine 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.

### 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:

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

   Der Controller antwortet mit:

   ```json
   { "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.

> [!TIP]
> 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.

> [!WARNING]
> 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:

| Familie | Hardware-CCT-Bereich | Verhalten außerhalb des Bereichs |
|---------|-----------------------|-----------------------------------|
| Light Panels, Shapes, Canvas, Lines | 1200–6500 K | Von Firmware begrenzt |
| Elements Hexagons | 1500–4000 K | Von Firmware begrenzt |
| Matter WiFi Essentials | 2127–6535 K | Von 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 1

Diese Geräte erscheinen nach dem Import in TapHome.

Nanoleaf Modul

Benutzerdefinierte Variablen

`authToken` (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx 32-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.

Lesen (Modul)

```taphome
#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 Lesen und Schreiben

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

Lesen (Modul)

```taphome
var value := PARSEJSON(StatusJson, "state.on.value");
IF(ISNULL(value), NaN, IF(value, 1, 0));
```

Helligkeit lesen

```taphome
var value := PARSEJSON(StatusJson, "state.brightness.value")/100;
IF(ISNULL(value), NaN, value);
```

Helligkeit schreiben

```taphome
var content:="{\"brightness\" : {\"value\":"+ROUND(Hb*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
```

Farbton lesen

```taphome
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

```taphome
var content:="{\"hue\" : {\"value\":"+ROUND(Hd)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
```

Sättigung lesen

```taphome
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

```taphome
var content:="{\"sat\" : {\"value\":"+ROUND(Sa*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
```

Farbtemperatur lesen

```taphome
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

```taphome
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.

## Importparameter

Diese Werte geben Sie beim Import des XML ein.

| In der App abgefragt | Standard      |
|----------------------|---------------|
| IP-Adresse           | `192.168.0.1` |

## Quellen

- Nanoleaf OpenAPI — Complete HTTP Reference
  
  [gist.github.com](https://gist.github.com/dennishn/ae06bf574748727bcce5127394a8ba43) 2026-04-15
- Nanoleaf Matter WiFi Essentials Open API Documentation
  
  [nanoleaf.atlassian.net](https://nanoleaf.atlassian.net/wiki/spaces/nlapid/pages/2296381472/Nanoleaf+Matter+WiFi+Essentials+Open+API+Documentation) 2026-04-15
- Home Assistant Nanoleaf Integration
  
  [www.home-assistant.io](https://www.home-assistant.io/integrations/nanoleaf/) 2026-04-15
- loebi-ch/nanoleaf — Enhanced HA Custom Integration
  
  [github.com](https://github.com/loebi-ch/nanoleaf) 2026-04-15
- openHAB Nanoleaf Binding
  
  [www.openhab.org](https://www.openhab.org/addons/bindings/nanoleaf/) 2026-04-15
- MylesMor/nanoleafapi — Python 3 Wrapper
  
  [github.com](https://github.com/MylesMor/nanoleafapi) 2026-04-15

## Verwandte Dokumentation

- [Packet-Parser-Integration](https://taphome.com/de/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/de/docs/integration/packet-parser/)
- [Packet-Parser-Funktionen](https://taphome.com/de/docs/script/packet-parser/)
- [Parsing-Funktionen](https://taphome.com/de/docs/script/parsing-functions/)