TapHome

Nanoleaf lampa RGB

Packet Parser → HTTP
Dodane przez
Ostatnia aktualizacja: 04. 2026
Nanoleaf lampa RGB

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

ProduktKod modeluUwagi
Light Panels (dawniej Aurora)NL22Bez dotyku
Shapes HexagonsNL42Z dotykiem
Shapes TrianglesNL47Z dotykiem
Shapes Mini TrianglesNL48Z dotykiem
Canvas (kwadraty)NL29Z dotykiem
Elements Hexagons (wygląd drewna)NL52Węższy zakres CCT (1500–4000 K)
LinesNL59Z 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)

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

1

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:

1
2
3
4

{ "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).

Rozróżnianie trybów kolorów

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

colorModeZnaczenie
hsTryb odcień/nasycenie — wartości odcienia i nasycenia są aktywne
ctTryb temperatury barwowej — wartość CCT jest aktywna
effectDział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.

Przypisz kontrolerowi Nanoleaf rezerwację DHCP (lub statyczny IP), aby adres nie zmieniał się po odnowieniu dzierżawy. Szablon TapHome przechowuje IP w parametrach importu i nie wykrywa go automatycznie.

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:

    1

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

    Kontroler odpowiada:

    1

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

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).

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:

RodzinaHardwarowy zakres CCTZachowanie poza zakresem
Light Panels, Shapes, Canvas, Lines1200–6500 KOgraniczone przez firmware
Elements Hexagons1500–4000 KOgraniczone przez firmware
Matter WiFi Essentials2127–6535 KOgraniczone 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

Nanoleaf Moduł
Zmienne niestandardowe
authToken (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx32-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.

Nanoleaf

Odczyt (moduł)
#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

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

Nanoleaf lampa RGB

Odczyt (moduł)
var value := PARSEJSON(StatusJson, "state.on.value");
IF(ISNULL(value), NaN, IF(value, 1, 0));
Odczyt jasności
var value := PARSEJSON(StatusJson, "state.brightness.value")/100;
IF(ISNULL(value), NaN, value);
Zapis jasności
var content:="{\"brightness\" : {\"value\":"+ROUND(Hb*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Odczyt odcienia
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
var content:="{\"hue\" : {\"value\":"+ROUND(Hd)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Odczyt nasycenia
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
var content:="{\"sat\" : {\"value\":"+ROUND(Sa*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Odczyt temperatury barwowej
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
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.

Źródła