---
title: "Nanoleaf lampa RGB"
description: "Integracja Nanoleaf paneli, taśm i żarówek z TapHome. Lokalne sterowanie HTTP HSB i temperaturą barwową na porcie 16021 — bez chmury."
url: "https://taphome.com/pl/compatibility/nanoleaf-rgb-light/"
language: pl
lastmod: 2026-04-15
generator: hugo
ai:
  topics: ["http","lighting","wifi","rgb","cct","packet-parser"]
  questions: ["Jak zintegrować Nanoleaf Light Panels z TapHome?","Jak wygenerować auth_token Nanoleaf dla TapHome?","Które modele Nanoleaf są obsługiwane przez szablon TapHome?","Dlaczego TapHome zwraca NULL dla odcienia i nasycenia na Nanoleaf?","Czy TapHome może uruchomić efekty lub sceny Nanoleaf?","Dlaczego moja żarówka Nanoleaf Essentials nie wyłącza się przy jasności 0?"]
---

# Nanoleaf lampa RGB

Komunikacja: Packet Parser → HTTP

- [Dokumentacja Nanoleaf Open API](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)

> Adres w sieci
> 
> TapHome łączy się z urządzeniem pod adresem podanym przy imporcie. Nadaj urządzeniu stały adres — rezerwację IP w routerze albo jego nazwę mDNS, jeśli ją obsługuje — inaczej integracja przestanie działać, gdy router zmieni adres.
> 
> [Przygotowanie sieci](https://taphome.com/pl/docs/setup/network-preparation/)

## Poradnik integracji

Nanoleaf to rodzina produktów oświetleniowych Wi-Fi LED — modułowe panele ścienne, taśmy LED, żarówki, lampy stojące i świąteczne łańcuchy świetlne — które wszystkie używają tego samego lokalnego REST API na porcie TCP **16021**. Pojedynczy szablon TapHome obejmuje każdy produkt Nanoleaf dostępny przez WiFi: TapHome odpytuje kontroler poprzez HTTP w sieci LAN i udostępnia cały układ jako pojedynczą lampę HSB z temperaturą barwową.

## Obsługiwane modele

| Produkt | Kod modelu | Uwagi |
|---------|-----------|-------|
| Light Panels (dawniej Aurora) | NL22 | Bez dotyku |
| Shapes Hexagons | NL42 | Z dotykiem |
| Shapes Triangles | NL47 | Z dotykiem |
| Shapes Mini Triangles | NL48 | Z dotykiem |
| Canvas (kwadraty) | NL29 | Z dotykiem |
| Elements Hexagons (wygląd drewna) | NL52 | Węższy zakres CCT (1500–4000 K) |
| Lines | NL59 | Z dotykiem |
| Matter WiFi Essentials (żarówki, taśmy LED, świąteczne łańcuchy świetlne, lampa stojąca, A19) | — | Tylko firmware 3.0.10+; ostrzejszy dolny limit jasności i węższy zakres CCT (2127–6535 K) |

> [!INFO]
> Warianty Nanoleaf Essentials wyłącznie z protokołem Thread oraz Nanoleaf Skylight **nie są obsługiwane** — szablon wymaga kontrolera dostępnego przez WiFi, który obsługuje Open API na porcie 16021.

## Funkcje urządzenia

### Lampa (HSB + temperatura barwowa)

Szablon udostępnia pojedynczą lampę HSB z funkcjami włączania/wyłączania, jasności, odcienia, nasycenia i temperatury barwowej. W każdym cyklu odpytywania (500 ms) moduł wysyła

```
GET /api/v1/{authToken}/
```

i zapisuje kompletny JSON urządzenia w zmiennej niestandardowej `StatusJson`. Skrypty odczytu dla poszczególnych właściwości następnie parsują pola z tego zapisanego obiektu:

- **Włączanie/wyłączanie** — `state.on.value`
- **Jasność** — `state.brightness.value` (0–100), znormalizowana do zakresu TapHome 0,0–1,0
- **Odcień** — `state.hue.value` (0–360°) — odczytywany tylko gdy `state.colorMode == "hs"`
- **Nasycenie** — `state.sat.value` (0–100) — odczytywane tylko gdy `state.colorMode == "hs"`
- **Temperatura barwowa** — `state.ct.value` (w Kelwinach) — odczytywana tylko gdy `state.colorMode == "ct"`

Wszystkie zapisy trafiają do `PUT /api/v1/{authToken}/state` z treścią JSON dla każdej właściwości:

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

Szablon deklaruje **1800–6500 K** jako zakres temperatury barwowej — praktyczny podzbiór tego, co hardware faktycznie obsługuje. Wartości poza fizycznym pasmem urządzenia są po cichu ograniczane przez firmware Nanoleaf (zob. [Uwagi i ograniczenia](https://taphome.com/pl/compatibility/nanoleaf-rgb-light/#notes-and-limitations)).

### Rozróżnianie trybów kolorów

Kontrolery Nanoleaf zawsze znajdują się dokładnie w jednym z trzech trybów kolorów:

| `colorMode` | Znaczenie |
|-------------|-----------|
| `hs` | Tryb odcień/nasycenie — wartości odcienia i nasycenia są aktywne |
| `ct` | Tryb temperatury barwowej — wartość CCT jest aktywna |
| `effect` | Działa scena dynamiczna |

Skrypty odczytu TapHome respektują ten stan: odczyty odcienia i nasycenia zwracają `NULL`, gdy kontroler jest w trybie `ct` lub `effect`, a odczyt temperatury barwowej zwraca `NaN`, gdy jest w trybie `hs` lub `effect`. Zapobiega to przedostawaniu się nieaktualnych wartości z innego trybu do dashboardu. Zapis dowolnej wartości odcienia lub nasycenia przełącza kontroler w tryb `hs`, a zapis wartości CCT przełącza go w tryb `ct` — oba zatrzymują działający efekt.

## Konfiguracja

### 1. Sparowanie kontrolera w aplikacji Nanoleaf

Zamontuj panele / żarówkę / taśmę, zainstaluj mobilną aplikację **Nanoleaf** i podłącz kontroler do lokalnej sieci Wi-Fi za pomocą procesu parowania w aplikacji. Zanotuj adres IPv4 kontrolera — aplikacja wyświetla go w Ustawieniach urządzenia → Info, lub można go odczytać z tabeli dzierżaw DHCP routera.

### 2. Wygenerowanie tokenu Open API

Nanoleaf Open API wymaga jednorazowego parowania między TapHome a kontrolerem. Parowanie generuje stały 32-znakowy `auth_token`, który przetrwa restarty i aktualizacje firmware'u.

1. Na **kontrolerze Nanoleaf** (mała jednostka liniowa dla paneli, lub samo urządzenie w przypadku żarówek / taśm) przytrzymaj przycisk włączania/wyłączania przez **5–7 sekund**, aż biała dioda LED zacznie migać według wzorca. Urządzenie jest teraz w trybie parowania przez **30 sekund**.
2. W ciągu 30-sekundowego okna wyślij pusty `POST` na endpoint parowania — na przykład za pomocą `curl`, PowerShell lub Postman:

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

   Kontroler odpowiada:

   ```json
   { "auth_token": "xxxKJISJCjY2hfAyilpyIOfGixxxx" }
   ```

3. Skopiuj 32-znakowy ciąg `auth_token`.

Jeśli okno wygaśnie przed nadejściem POST, endpoint zwraca **403 Forbidden** — ponownie przytrzymaj przycisk włączania/wyłączania i spróbuj jeszcze raz.

> [!TIP]
> Niektóre warianty Essentials (żarówki, taśmy) nie mają fizycznego przycisku. W takim przypadku rozpocznij parowanie z ustawień urządzenia w aplikacji Nanoleaf — aplikacja aktywuje 30-sekundowe okno za Ciebie.

### 3. Import szablonu w TapHome

1. W TapHome utwórz nowe urządzenie PacketParser z szablonu **Nanoleaf RGB light**.
2. Wprowadź adres IPv4 kontrolera jako parametr importu `ipAddress`. Port jest stały na **16021** i nie wymaga zmiany.
3. Otwórz właściwości urządzenia, znajdź zmienną niestandardową `authToken` i wklej 32-znakowy token wygenerowany w kroku 2.
4. Zapisz. Moduł będzie odpytywał `/api/v1/{authToken}/` co 500 ms i wypełni lampę HSB aktualnym stanem.

Jeśli token jest nieprawidłowy lub wygasł, każdy odczyt kończy się błędem **401 Unauthorized** w logu TapHome.

### Wymagania sieciowe

- Tylko wychodzący **TCP 16021** z CCU TapHome do kontrolera Nanoleaf. Brak wywołań do chmury, brak brokera MQTT, brak certyfikatów HTTPS.
- CCU i kontroler muszą znajdować się w tej samej sieci **LAN / VLAN**. Jeśli sieci Wi-Fi i przewodowe są rozdzielone, dodaj regułę firewalla zezwalającą na TCP 16021 między nimi.
- Kontrolery Nanoleaf ogłaszają usługę `_nanoleafapi._tcp` przez mDNS. Szablon wymaga bezpośredniego IP, ale mDNS może być użyty do wykrywania za pomocą `avahi-browse -r _nanoleafapi._tcp` (Linux) lub `dns-sd -B _nanoleafapi._tcp` (macOS).

> [!WARNING]
> Nanoleaf Open API jest **tylko HTTP** — nie ma HTTPS ani szyfrowania transportu. Jest bezpieczne w obrębie sieci LAN, ale nigdy nie może być wystawiane do publicznego internetu. Nie przekierowuj portu 16021 przez router.

## Uwagi i ograniczenia

### Zakres temperatury barwowej zależy od rodziny modelu

Szablon TapHome deklaruje **1800–6500 K** jako zapisywalny zakres CCT. Podstawowe pasmo hardwarowe różni się w zależności od rodziny:

| Rodzina | Hardwarowy zakres CCT | Zachowanie poza zakresem |
|---------|------------------------|---------------------------|
| Light Panels, Shapes, Canvas, Lines | 1200–6500 K | Ograniczone przez firmware |
| Elements Hexagons | 1500–4000 K | Ograniczone przez firmware |
| Matter WiFi Essentials | 2127–6535 K | Ograniczone przez firmware; 1800 K jest poniżej dolnej granicy 2127 K, więc Essentials ograniczają do 2127 K |

Zapis wartości poza fizycznym pasmem urządzenia nie generuje błędu — kontroler po cichu używa własnego limitu. Projektując dashboardy ukierunkowane na Essentials, preferuj wartości CCT we wspólnym oknie 2127–6500 K.

### Essentials odrzucają jasność = 0

Klasyczne kontrolery (Light Panels, Shapes, Canvas, Elements, Lines) akceptują `brightness: 0`. **Matter WiFi Essentials** wymuszają minimum **1** i odrzucają `0` z HTTP 400. Aby wyłączyć żarówkę lub taśmę Essentials, użyj kanału włączania/wyłączania zamiast ustawiania jasności na zero.

### Odczyty odcienia / nasycenia / CCT mogą zwracać NULL lub NaN

Ponieważ tryby `hs` i `ct` wzajemnie się wykluczają, a oba są nieaktywne podczas działającego efektu, odczyty z niewłaściwego trybu celowo zwracają `NULL` (odcień / nasycenie) lub `NaN` (ct). Jest to oczekiwane zachowanie, a nie błąd. Zapis wartości odcienia / nasycenia / ct przywraca kontroler do trybu `hs` lub `ct` i odczyty są wznawiane.

### Jeden token na kontroler, a nie na panel

Wielopanelowy układ Shapes lub Canvas to pojedyncze urządzenie TapHome. Token auth jest wydawany na poziomie kontrolera i obejmuje każdy podłączony panel.

### Niestabilność IPv6 mDNS na firmware 8.5.2+

Społeczność openHAB zgłosiła, że rekordy IPv6 mDNS naprzemiennie zmieniają stany ONLINE i OFFLINE na niektórych kontrolerach z firmware 8.5.2+. Jeśli wykrywanie mDNS jest niestabilne, ustaw stałą rezerwację DHCP IPv4 i użyj IP bezpośrednio — szablon TapHome i tak nie polega na mDNS.

## Rozwiązywanie problemów

### 401 Unauthorized przy każdym odczycie

`authToken` jest nieprawidłowy, wygasł lub został unieważniony. Wygeneruj nowy token (przytrzymaj przycisk włączania/wyłączania przez 5–7 s i wyślij POST na `/api/v1/new`) i wklej go do zmiennej niestandardowej `authToken`.

### 403 Forbidden podczas generowania tokenu

30-sekundowe okno parowania zostało zamknięte. Ponownie przytrzymaj przycisk włączania/wyłączania, aż LED zacznie migać wzorem, a następnie natychmiast wyślij `POST /api/v1/new`.

### Odcień / nasycenie pokazują NULL na dashboardzie

Kontroler jest w trybie `ct` lub działa efekt. Zapisz dowolną wartość odcienia lub nasycenia, aby przełączyć kontroler z powrotem w tryb `hs`, lub ustaw kolor za pomocą wybieraka HSB. Szablon nie może wywnioskować odczytu odcienia / nasycenia, gdy urządzenie go nie produkuje.

### Temperatura barwowa odczytuje się jako NaN

Kontroler jest w trybie `hs` lub działa efekt. Zapisz wartość CCT, aby przełączyć w tryb `ct`, lub ustaw temperaturę barwową z dashboardu. Jeśli działa efekt, zatrzymaj go w aplikacji Nanoleaf (lub zapisz dowolną wartość HSB / CCT — to również zatrzyma efekt).

### Zapis jasności kończy się niepowodzeniem na Essentials

Matter WiFi Essentials odrzucają `brightness: 0`. Użyj kanału włączania/wyłączania do wyłączania zamiast zapisywać 0 w jasności. Wartości 1–100 są akceptowane na wszystkich modelach.

### Kontroler rozłącza się na firmware 8.5.2+

Jeśli CCU TapHome wielokrotnie traci kontroler, przypisz statyczną rezerwację DHCP IPv4 i użyj IP w parametrze importu `ipAddress` — warstwa IPv6 mDNS może być niestabilna w tej gałęzi firmware'u.

## Dostępne urządzenia 1

Te urządzenia pojawią się w TapHome po imporcie.

Nanoleaf Moduł

Zmienne niestandardowe

`authToken` (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx 32-znakowy token parowania Nanoleaf Open API. Wygeneruj go jednorazowo przytrzymując przycisk włączania/wyłączania kontrolera przez 5–7 sekund i wysyłając POST http://{ip}:16021/api/v1/new w ciągu 30 sekund — wklej tu zwrócony auth\_token. Token przetrwa restarty i aktualizacje firmware'u.

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.

Odczyt (moduł)

```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 lampa RGB Światło HSB Odczyt i zapis

Lampa HSB z podwójnym trybem kolorów — odcień i nasycenie (0–360° / 0–100 %) lub temperatura barwowa (zadeklarowano 1800–6500 K, zakres hardwarowy zależy od modelu). Jasność 0–100 %. Odczyty odcienia / nasycenia są aktywne tylko w trybie hs; odczyty CCT są aktywne tylko w trybie ct; oba są nieaktywne podczas działającego efektu.

HSBLight json

Odczyt (moduł)

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

Odczyt jasności

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

Zapis jasności

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

Odczyt odcienia

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

Zapis odcienia

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

Odczyt nasycenia

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

Zapis nasycenia

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

Odczyt temperatury barwowej

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

Zapis temperatury barwowej

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

**Połączenie:** Packet Parser → HTTP

Możliwe ulepszenia (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.

## Parametry importu

Te wartości podajesz podczas importu pliku XML.

| Pytanie w aplikacji | Domyślnie     |
|---------------------|---------------|
| Adres IP            | `192.168.0.1` |

## Źródła

- 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

## Powiązana dokumentacja

- [Integracja Packet Parser](https://taphome.com/pl/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/pl/docs/integration/packet-parser/)
- [Funkcje Packet parser](https://taphome.com/pl/docs/script/packet-parser/)
- [Funkcje parsowania](https://taphome.com/pl/docs/script/parsing-functions/)