TapHome

Nanoleaf RGB light

Packet Parser → HTTP
Autor
Posljednje ažuriranje: 04. 2026
Nanoleaf RGB light

Nanoleaf je obitelj Wi-Fi LED rasvjetnih proizvoda (modularni zidni paneli, LED trake, žarulje, podne svjetiljke i blagdanski svjetlosni nizovi) koji svi koriste isto lokalno REST sučelje na TCP portu 16021. Jedan predložak TapHome pokriva svaki proizvod Nanoleaf dostupan preko Wi-Fi mreže: TapHome preko HTTP-a u lokalnoj mreži periodički očitava upravljač i cijeli raspored panela prikazuje kao jedno HSB svjetlo s temperaturom boje.

Podržani modeli

ProizvodOznaka modelaNapomene
Light Panels (prije Aurora)NL22Bez dodira
Shapes HexagonsNL42Podržava dodir
Shapes TrianglesNL47Podržava dodir
Shapes Mini TrianglesNL48Podržava dodir
Canvas (Squares)NL29Podržava dodir
Elements Hexagons (Wood Look)NL52Uži raspon temperature boje (1500–4000 K)
LinesNL59Podržava dodir
Matter WiFi Essentials (Bulbs, Lightstrips, Holiday String Lights, Floor Lamp, A19)—Samo firmver 3.0.10+; stroža donja granica svjetline i uži raspon temperature boje (2127–6535 K)

Nanoleaf Essentials koji rade samo preko Threada i Nanoleaf Skylight nisu podržani. Predložak zahtijeva upravljač dostupan preko Wi-Fi mreže koji podržava Open API na portu 16021.

Mogućnosti uređaja

Svjetlo (HSB + temperatura boje)

Predložak daje jedno HSB svjetlo s uključivanjem i isključivanjem, svjetlinom, nijansom, zasićenošću i temperaturom boje. U svakom ciklusu očitavanja (500 ms) modul šalje

1

GET /api/v1/{authToken}/

i cijeli JSON uređaja sprema u korisničku varijablu StatusJson. Skripte za čitanje pojedinih svojstava zatim iz tog spremljenog bloka raščlanjuju polja:

  • Uključeno/isključeno — state.on.value
  • Svjetlina — state.brightness.value (0–100), pretvorena u raspon 0,0–1,0 koji koristi TapHome
  • Nijansa — state.hue.value (0–360°), čita se samo kada je state.colorMode == "hs"
  • Zasićenost — state.sat.value (0–100), čita se samo kada je state.colorMode == "hs"
  • Temperatura boje — state.ct.value (kelvini), čita se samo kada je state.colorMode == "ct"

Svi upisi idu na PUT /api/v1/{authToken}/state s JSON tijelom za pojedino svojstvo:

1
2
3
4

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

Predložak kao raspon temperature boje navodi 1800–6500 K, praktičan dio onoga što hardver stvarno podržava. Vrijednosti izvan fizičkog raspona uređaja firmver Nanoleaf bez upozorenja ograničava (vidi Napomene i ograničenja).

Ovisnost o načinu boje

Upravljači Nanoleaf uvijek su u točno jednom od tri načina boje:

colorModeZnačenje
hsNačin nijanse i zasićenosti: vrijednosti nijanse i zasićenosti su aktualne
ctNačin temperature boje: vrijednost temperature boje je aktualna
effectPokrenuta je dinamična scena

Skripte za čitanje TapHome to poštuju: čitanje nijanse i zasićenosti vraća NULL kada je upravljač u načinu ct ili effect, a čitanje temperature boje vraća NaN kada je u načinu hs ili effect. Tako se na Dashboard ne prenose zastarjele vrijednosti iz drugog načina. Upis bilo koje vrijednosti nijanse ili zasićenosti prebacuje upravljač u način hs, a upis temperature boje u način ct. Oba upisa zaustavljaju pokrenuti efekt.

Konfiguracija

1. Uparite upravljač u aplikaciji Nanoleaf

Postavite panele, žarulju ili traku, instalirajte mobilnu aplikaciju Nanoleaf i postupkom uparivanja u aplikaciji spojite upravljač na lokalnu Wi-Fi mrežu. Zapišite IPv4 adresu upravljača. Aplikacija je prikazuje u postavkama uređaja → Info, a može se pročitati i iz tablice DHCP zakupa na usmjerivaču.

Upravljaču Nanoleaf dodijelite DHCP rezervaciju (ili statičku IP adresu) kako se adresa ne bi promijenila nakon obnove zakupa. Predložak TapHome sprema IP adresu u parametre uvoza i ne pronalazi uređaj automatski.

2. Generirajte token za Open API

Nanoleaf Open API zahtijeva jednokratno uparivanje sustava TapHome i upravljača. Uparivanjem nastaje trajni auth_token od 32 znaka koji ostaje valjan i nakon ponovnog pokretanja i ažuriranja firmvera.

  1. Na upravljaču Nanoleaf (mala jedinica na kabelu kod panela, odnosno sam uređaj kod žarulja i traka) držite tipku za uključivanje i isključivanje 5–7 sekundi dok bijela LED dioda ne počne treptati određenim ritmom. Uređaj je sada 30 sekundi u načinu uparivanja.

  2. Unutar tih 30 sekundi pošaljite prazan zahtjev POST na adresu za uparivanje, na primjer pomoću alata curl, PowerShell ili Postman:

    1

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

    Upravljač odgovara:

    1

    { "auth_token": "xxxKJISJCjY2hfAyilpyIOfGixxxx" }

  3. Kopirajte niz auth_token od 32 znaka.

Ako vrijeme istekne prije nego što zahtjev POST stigne, adresa vraća 403 Forbidden. Ponovno držite tipku za uključivanje i isključivanje i pokušajte opet.

Neke izvedbe Essentials (žarulje, trake) nemaju fizičku tipku. U tom slučaju pokrenite uparivanje iz postavki uređaja u aplikaciji Nanoleaf. Aplikacija umjesto vas otvara razdoblje od 30 sekundi.

3. Uvezite predložak u TapHome
  1. U sustavu TapHome izradite novi uređaj PacketParser iz predloška Nanoleaf RGB svjetlo.
  2. IPv4 adresu upravljača unesite kao parametar uvoza ipAddress. Port je fiksno postavljen na 16021 i nije ga potrebno mijenjati.
  3. Otvorite svojstva uređaja, pronađite korisničku varijablu authToken i zalijepite token od 32 znaka generiran u koraku 2.
  4. Spremite. Modul će svakih 500 ms očitavati /api/v1/{authToken}/ i HSB svjetlu postaviti trenutačno stanje.

Ako je token pogrešan ili je istekao, svako čitanje završava pogreškom 401 Unauthorized u zapisniku TapHome.

Mrežni zahtjevi
  • Potreban je samo odlazni TCP 16021 od centralne jedinice TapHome prema upravljaču Nanoleaf. Nema poziva u oblak, MQTT brokera ni HTTPS certifikata.
  • Centralna jedinica i upravljač moraju biti u istoj lokalnoj mreži / VLAN-u. Ako su Wi-Fi i žičana mreža odvojene, dodajte pravilo vatrozida koje između njih dopušta TCP 16021.
  • Upravljači Nanoleaf oglašavaju uslugu _nanoleafapi._tcp preko mDNS-a. Predložak zahtijeva izravnu IP adresu, ali mDNS se može koristiti za pronalaženje pomoću avahi-browse -r _nanoleafapi._tcp (Linux) ili dns-sd -B _nanoleafapi._tcp (macOS).

Nanoleaf Open API radi samo preko HTTP-a: nema HTTPS-a ni šifriranja prijenosa. Unutar lokalne mreže je siguran, ali nikada ne smije biti izložen javnom internetu. Port 16021 nemojte prosljeđivati preko usmjerivača.

Napomene i ograničenja

Raspon temperature boje ovisi o obitelji modela

Predložak TapHome kao raspon temperature boje za upis navodi 1800–6500 K. Stvarni raspon hardvera razlikuje se po obiteljima:

ObiteljRaspon temperature boje hardveraPonašanje izvan raspona
Light Panels, Shapes, Canvas, Lines1200–6500 KFirmver ograničava vrijednost
Elements Hexagons1500–4000 KFirmver ograničava vrijednost
Matter WiFi Essentials2127–6535 KFirmver ograničava vrijednost; 1800 K je ispod donje granice 2127 K, pa Essentials vrijednost ograničava na 2127 K

Upis vrijednosti izvan fizičkog raspona uređaja ne javlja pogrešku: upravljač bez upozorenja koristi vlastitu granicu. Kada izrađujete Dashboard za Essentials, koristite vrijednosti temperature boje u zajedničkom rasponu 2127–6500 K.

Essentials odbijaju svjetlinu 0

Klasični upravljači (Light Panels, Shapes, Canvas, Elements, Lines) prihvaćaju brightness: 0. Matter WiFi Essentials zahtijevaju najmanje 1, a 0 odbijaju s HTTP 400. Žarulju ili traku Essentials isključite kanalom za uključivanje i isključivanje, a ne postavljanjem svjetline na nulu.

Čitanje nijanse, zasićenosti i temperature boje može vratiti NULL ili NaN

Budući da se hs i ct međusobno isključuju i da su oba neaktivna dok radi efekt, čitanja iz pogrešnog načina namjerno vraćaju NULL (nijansa / zasićenost) ili NaN (temperatura boje). To je očekivano ponašanje, a ne kvar. Upis nijanse, zasićenosti ili temperature boje vraća upravljač u način hs ili ct i čitanja se nastavljaju.

Jedan token po upravljaču, ne po panelu

Raspored Shapes ili Canvas s više panela jedan je uređaj u sustavu TapHome. Token se izdaje na razini upravljača i vrijedi za svaki panel spojen na njega.

Nestabilan IPv6 mDNS na firmveru 8.5.2+

Zajednica openHAB prijavila je da se IPv6 mDNS zapisi na nekim upravljačima s firmverom 8.5.2+ izmjenjuju između ONLINE i OFFLINE. Ako je pronalaženje preko mDNS-a nestabilno, postavite fiksnu IPv4 DHCP rezervaciju i izravno koristite IP adresu. Predložak TapHome ionako ne ovisi o mDNS-u.

Otklanjanje poteškoća

401 Unauthorized pri svakom čitanju

authToken je pogrešan, istekao je ili je opozvan. Generirajte novi token (držite tipku za uključivanje i isključivanje 5–7 s i pošaljite POST na /api/v1/new) i zalijepite ga u korisničku varijablu authToken.

403 Forbidden pri generiranju tokena

Razdoblje od 30 sekundi za uparivanje je isteklo. Ponovno držite tipku za uključivanje i isključivanje dok LED dioda ne počne treptati određenim ritmom, a zatim odmah pošaljite POST /api/v1/new.

Nijansa i zasićenost na Dashboardu prikazuju NULL

Upravljač je u načinu ct ili je pokrenut efekt. Upišite bilo koju vrijednost nijanse ili zasićenosti kako biste upravljač vratili u način hs ili postavite boju pomoću HSB birača. Predložak ne može odrediti nijansu i zasićenost kada ih uređaj ne daje.

Temperatura boje očitava se kao NaN

Upravljač je u načinu hs ili je pokrenut efekt. Upišite vrijednost temperature boje kako biste prešli u način ct ili postavite temperaturu boje na Dashboardu. Ako je pokrenut efekt, zaustavite ga u aplikaciji Nanoleaf (ili upišite bilo koju HSB vrijednost ili temperaturu boje, što također zaustavlja efekt).

Upis svjetline na Essentials ne uspijeva

Matter WiFi Essentials odbijaju brightness: 0. Za isključivanje koristite kanal za uključivanje i isključivanje umjesto upisa 0 u svjetlinu. Vrijednosti 1–100 prihvaćaju svi modeli.

Upravljač nestaje s mreže na firmveru 8.5.2+

Ako centralna jedinica TapHome stalno gubi vezu s upravljačem, postavite statičku IPv4 DHCP rezervaciju i tu IP adresu unesite u parametar uvoza ipAddress. Sloj IPv6 mDNS na ovoj grani firmvera može biti nestabilan.

Dostupni uređaji

Nanoleaf Modul
Prilagođene varijable
authToken (string) = xxxKJISJCjY2hfAyilpyIOfGixxxxToken za uparivanje Nanoleaf Open API od 32 znaka. Generirajte ga jednom: držite tipku za uključivanje i isključivanje na upravljaču 5–7 sekundi i unutar 30 sekundi pošaljite POST http://{ip}:16021/api/v1/new, a vraćeni auth_token zalijepite ovdje. Token ostaje valjan i nakon ponovnog pokretanja i ažuriranja firmvera.
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

Čitanje (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 svjetlo HSB svjetlo

HSB svjetlo s dva načina boje: nijansa i zasićenost (0–360° / 0–100 %) ili temperatura boje (u predlošku 1800–6500 K, stvarni raspon ovisi o modelu). Svjetlina 0–100 %. Nijansa i zasićenost čitaju se samo u načinu hs, temperatura boje samo u načinu ct, a dok radi efekt ne čita se ništa od toga.

HSBLight json

Nanoleaf RGB svjetlo

Čitanje (modul)
var value := PARSEJSON(StatusJson, "state.on.value");
IF(ISNULL(value), NaN, IF(value, 1, 0));
Čitanje svjetline
var value := PARSEJSON(StatusJson, "state.brightness.value")/100;
IF(ISNULL(value), NaN, value);
Zapis svjetline
var content:="{\"brightness\" : {\"value\":"+ROUND(Hb*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Čitanje nijanse
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 nijanse
var content:="{\"hue\" : {\"value\":"+ROUND(Hd)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Čitanje zasićenosti
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 zasićenosti
var content:="{\"sat\" : {\"value\":"+ROUND(Sa*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Čitanje temperature boje
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 temperature boje
var content:="{\"ct\" : {\"value\":"+ROUND(Ct)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Povezivanje: Packet Parser → HTTP
Moguća poboljšanja (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.

Izvori

Pronašli ste problem s ovim predloškom uređaja?

Recite nam što ne radi, što nedostaje ili kako bi se predložak trebao ponašati. Vaše povratne informacije pomažu nam da katalog bude točan.

Provjerio TapHome

Želite ovo koristiti u svojoj centralnoj jedinici TapHome Core?

Otvorite ovaj predložak na portalu Customer Portal kako biste ga primijenili na jedan od svojih domova ili predložili poboljšanje i poslali ga natrag u katalog.

Otvorite na portalu