Nanoleaf RGB Light

Packet Parser → HTTP

Trimis de

Ultima actualizare: 04. 2026

Nanoleaf este o familie de produse de iluminat LED Wi-Fi — panouri modulare de perete, benzi LED, becuri, lămpi de podea și ghirlande luminoase de sărbători — care folosesc toate același API REST local pe portul TCP 16021. Un singur șablon TapHome acoperă toate produsele Nanoleaf accesibile prin Wi-Fi: TapHome interoghează controlerul prin HTTP în rețeaua locală și pune la dispoziție întreaga configurație ca o singură lumină HSB cu temperatură de culoare.

Modele acceptate

Produs	Cod model	Note
Light Panels (fost Aurora)	NL22	Fără control prin atingere
Shapes Hexagons	NL42	Cu control prin atingere
Shapes Triangles	NL47	Cu control prin atingere
Shapes Mini Triangles	NL48	Cu control prin atingere
Canvas (Squares)	NL29	Cu control prin atingere
Elements Hexagons (Wood Look)	NL52	Interval CCT mai îngust (1500–4000 K)
Lines	NL59	Cu control prin atingere
Matter WiFi Essentials (Bulbs, Lightstrips, Holiday String Lights, Floor Lamp, A19)	—	Doar firmware 3.0.10+; limită minimă de luminozitate mai strictă și interval CCT mai îngust (2127–6535 K)

Nanoleaf Essentials doar cu Thread și Nanoleaf Skylight nu sunt acceptate — șablonul necesită un controler accesibil prin Wi-Fi, care folosește Open API pe portul 16021.

Funcțiile dispozitivului

Lumină (HSB + temperatură de culoare)

Șablonul pune la dispoziție o singură lumină HSB cu pornire/oprire, luminozitate, nuanță, saturație și temperatură de culoare. La fiecare ciclu de interogare (500 ms), modulul trimite

1
GET /api/v1/{authToken}/

și păstrează întregul JSON al dispozitivului în variabila personalizată StatusJson. Scripturile de citire pentru fiecare proprietate extrag apoi câmpurile din aceste date păstrate:

Pornire/oprire — state.on.value
Luminozitate — state.brightness.value (0–100), normalizată la intervalul TapHome 0,0–1,0
Nuanță — state.hue.value (0–360°) — se citește doar când state.colorMode == "hs"
Saturație — state.sat.value (0–100) — se citește doar când state.colorMode == "hs"
Temperatură de culoare — state.ct.value (Kelvin) — se citește doar când state.colorMode == "ct"

Toate scrierile se trimit la PUT /api/v1/{authToken}/state, cu un corp JSON pentru fiecare proprietate:

1
2
3
4
{ "brightness": { "value": 75 } }
{ "hue":        { "value": 212 } }
{ "sat":        { "value": 100 } }
{ "ct":         { "value": 4000 } }

Șablonul declară 1800–6500 K ca interval al temperaturii de culoare — un subset practic al intervalului acceptat efectiv de hardware. Valorile din afara intervalului fizic al dispozitivului sunt limitate fără avertizare de firmware-ul Nanoleaf (consultați Note și limitări).

Citirea în funcție de modul de culoare

Controlerele Nanoleaf se află întotdeauna în exact unul dintre cele trei moduri de culoare:

`colorMode`	Semnificație
`hs`	Mod nuanță / saturație — valorile nuanței și saturației sunt active
`ct`	Mod temperatură de culoare — valoarea CCT este activă
`effect`	Rulează o scenă dinamică

Scripturile de citire TapHome respectă acest lucru: citirile nuanței și saturației returnează NULL când controlerul este în modul ct sau effect, iar citirea temperaturii de culoare returnează NaN când este în modul hs sau effect. Astfel, în dashboard nu ajung valori învechite din alt mod. Scrierea oricărei valori de nuanță / saturație comută controlerul în modul hs, iar scrierea unei valori CCT îl comută în modul ct — ambele opresc efectul care rulează.

Configurare

1. Asocierea controlerului în aplicația Nanoleaf

Montați panourile / becul / banda, instalați aplicația mobilă Nanoleaf și conectați controlerul la rețeaua Wi-Fi locală prin procesul de asociere din aplicație. Notați adresa IPv4 a controlerului — aplicația o afișează în setările dispozitivului → Info sau o puteți citi din tabelul de atribuiri DHCP al routerului.

Atribuiți controlerului Nanoleaf o rezervare DHCP (sau o adresă IP statică), ca adresa să nu se schimbe după reînnoirea atribuirii. Șablonul TapHome păstrează adresa IP în parametrii de import și nu o descoperă automat.

2. Generarea tokenului Open API

Nanoleaf Open API necesită o asociere între TapHome și controler, care se face o singură dată. Asocierea produce un auth_token permanent de 32 de caractere, care rămâne valabil după reporniri și actualizări de firmware.

Pe controlerul Nanoleaf (unitatea mică de pe cablu la panouri sau dispozitivul însuși la becuri / benzi), țineți apăsat butonul de pornire/oprire timp de 5–7 secunde, până când LED-ul alb începe să clipească într-o anumită secvență. Dispozitivul este acum în modul de asociere timp de 30 de secunde.
În acest interval de 30 de secunde, trimiteți un POST gol către endpointul de asociere — de exemplu cu curl, PowerShell sau Postman:
1
curl -X POST http://{controller-ip}:16021/api/v1/new
Controlerul răspunde cu:
1
{ "auth_token": "xxxKJISJCjY2hfAyilpyIOfGixxxx" }
Copiați șirul auth_token de 32 de caractere.

Dacă intervalul expiră înainte de sosirea cererii POST, endpointul returnează 403 Forbidden — țineți din nou apăsat butonul de pornire/oprire și încercați din nou.

Unele variante Essentials (becuri, benzi) nu au buton fizic. În acest caz, porniți asocierea din setările dispozitivului în aplicația Nanoleaf — aplicația deschide pentru dvs. intervalul de 30 de secunde.

3. Importul șablonului în TapHome

În TapHome, creați un nou dispozitiv PacketParser din șablonul Lumină RGB Nanoleaf.
Introduceți adresa IPv4 a controlerului în parametrul de import ipAddress. Portul este fix, 16021, și nu este necesar să fie schimbat.
Deschideți proprietățile dispozitivului, găsiți variabila personalizată authToken și lipiți tokenul de 32 de caractere generat la pasul 2.
Salvați. Modulul va interoga /api/v1/{authToken}/ la fiecare 500 ms și va actualiza lumina HSB cu starea curentă.

Dacă tokenul este greșit sau a expirat, fiecare citire eșuează cu 401 Unauthorized în jurnalul TapHome.

Cerințe de rețea

Doar trafic de ieșire TCP 16021 de la unitatea centrală TapHome (CCU) către controlerul Nanoleaf. Fără apeluri în cloud, fără broker MQTT, fără certificate HTTPS.
CCU și controlerul trebuie să fie în aceeași rețea locală / VLAN. Dacă rețelele Wi-Fi și cea prin cablu sunt separate, adăugați o regulă de firewall care permite TCP 16021 între ele.
Controlerele Nanoleaf își anunță serviciul _nanoleafapi._tcp prin mDNS. Șablonul necesită o adresă IP directă, dar mDNS poate fi folosit pentru descoperire cu avahi-browse -r _nanoleafapi._tcp (Linux) sau dns-sd -B _nanoleafapi._tcp (macOS).

Nanoleaf Open API funcționează doar prin HTTP — nu există HTTPS și nici criptarea transportului. Este sigur în rețeaua locală, dar nu trebuie expus niciodată în internetul public. Nu redirecționați portul 16021 prin router.

Note și limitări

Intervalul temperaturii de culoare depinde de familia de modele

Șablonul TapHome declară 1800–6500 K ca interval CCT în care pot fi setate valori. Intervalul hardware diferă în funcție de familie:

Familie	Interval CCT hardware	Comportament în afara intervalului
Light Panels, Shapes, Canvas, Lines	1200–6500 K	Limitat de firmware
Elements Hexagons	1500–4000 K	Limitat de firmware
Matter WiFi Essentials	2127–6535 K	Limitat de firmware; 1800 K este sub limita minimă de 2127 K, așa că Essentials va limita valoarea la 2127 K

Scrierea unei valori din afara intervalului fizic al dispozitivului nu generează o eroare — controlerul folosește fără avertizare propria limită. Când creați dashboarduri pentru Essentials, preferați valori CCT din intervalul comun 2127–6500 K.

Essentials resping luminozitatea = 0

Controlerele clasice (Light Panels, Shapes, Canvas, Elements, Lines) acceptă brightness: 0. Matter WiFi Essentials impun un minim de 1 și resping 0 cu HTTP 400. Pentru a opri un bec sau o bandă Essentials, folosiți canalul de pornire/oprire în loc să reduceți luminozitatea la zero.

Citirile nuanței / saturației / CCT pot returna NULL sau NaN

Deoarece hs și ct se exclud reciproc și ambele sunt inactive cât timp rulează un efect, citirile din modul greșit returnează intenționat NULL (nuanță / saturație) sau NaN (ct). Acesta este comportamentul așteptat, nu o defecțiune. O scriere a nuanței / saturației / CCT readuce controlerul în modul hs sau ct, iar citirile se reiau.

Un token pentru fiecare controler, nu pentru fiecare panou

O configurație Shapes sau Canvas cu mai multe panouri este un singur dispozitiv TapHome. Tokenul de autentificare este emis la nivelul controlerului și acoperă toate panourile conectate la acesta.

Instabilitatea mDNS IPv6 la firmware 8.5.2+

Comunitatea openHAB a raportat că înregistrările mDNS IPv6 alternează între ONLINE și OFFLINE la unele controlere cu firmware 8.5.2+. Dacă descoperirea prin mDNS este instabilă, setați o rezervare DHCP IPv4 fixă și folosiți direct adresa IP — oricum, șablonul TapHome nu se bazează pe mDNS.

Rezolvarea problemelor

401 Unauthorized la fiecare citire

authToken este greșit, a expirat sau a fost revocat. Generați un token nou (țineți apăsat butonul de pornire/oprire timp de 5–7 s și trimiteți POST /api/v1/new) și lipiți-l în variabila personalizată authToken.

403 Forbidden la generarea tokenului

Intervalul de asociere de 30 de secunde s-a încheiat. Țineți din nou apăsat butonul de pornire/oprire până când LED-ul clipește într-o anumită secvență, apoi trimiteți imediat POST /api/v1/new.

Nuanța / saturația apar ca NULL în dashboard

Controlerul este în modul ct sau rulează un efect. Scrieți orice valoare de nuanță sau saturație pentru a readuce controlerul în modul hs sau setați o culoare cu selectorul HSB. Șablonul nu poate deduce nuanța / saturația când dispozitivul nu le furnizează.

Temperatura de culoare apare ca NaN

Controlerul este în modul hs sau rulează un efect. Scrieți o valoare CCT pentru a comuta în modul ct sau setați o temperatură de culoare din dashboard. Dacă rulează un efect, opriți-l din aplicația Nanoleaf (sau scrieți orice valoare HSB / CCT — și aceasta oprește efectul).

Scrierea luminozității eșuează la Essentials

Matter WiFi Essentials resping brightness: 0. Pentru oprire, folosiți canalul de pornire/oprire în loc să scrieți 0 în luminozitate. Valorile 1–100 sunt acceptate de toate modelele.

Controlerul se deconectează la firmware 8.5.2+

Dacă CCU TapHome pierde în mod repetat legătura cu controlerul, atribuiți o rezervare DHCP IPv4 statică și folosiți adresa IP în parametrul de import ipAddress — stratul mDNS IPv6 poate fi instabil în această ramură de firmware.

Dispozitive disponibile

Nanoleaf Modul

Variabile personalizate

authToken (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx

Token de asociere Nanoleaf Open API de 32 de caractere. Generați-l o singură dată ținând apăsat butonul de pornire/oprire al controlerului timp de 5–7 secunde și trimițând POST http://{ip}:16021/api/v1/new în decurs de 30 de secunde — lipiți aici auth_token-ul returnat. Tokenul rămâne valabil după reporniri și actualizări de firmware.

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

Citire (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

Lumină RGB Nanoleaf Lumină HSB

Lumină HSB cu două moduri de culoare — nuanță și saturație (0–360° / 0–100 %) sau temperatură de culoare (interval declarat 1800–6500 K, intervalul hardware depinde de model). Luminozitate 0–100 %. Citirea nuanței / saturației este activă doar în modul hs; citirea CCT este activă doar în modul ct; ambele sunt inactive cât timp rulează un efect.

HSBLight json

Lumină RGB Nanoleaf

Citire (modul)

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

Citirea luminozității

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

Scrierea luminozității

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

Citirea nuanței

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

Scrierea nuanței

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

Citirea saturației

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

Scrierea saturației

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

Citirea temperaturii de culoare

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

Scrierea temperaturii de culoare

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

Conexiune: Packet Parser → HTTP

Îmbunătățiri posibile (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.

Descărcați șablon

Surse

Nanoleaf OpenAPI — Complete HTTP Reference
gist.github.com 2026-04-15
Nanoleaf Matter WiFi Essentials Open API Documentation
nanoleaf.atlassian.net 2026-04-15
Home Assistant Nanoleaf Integration
www.home-assistant.io 2026-04-15
loebi-ch/nanoleaf — Enhanced HA Custom Integration
github.com 2026-04-15
openHAB Nanoleaf Binding
www.openhab.org 2026-04-15
MylesMor/nanoleafapi — Python 3 Wrapper
github.com 2026-04-15

Ați găsit o problemă la acest șablon de dispozitiv?

Spuneți-ne ce nu funcționează, ce lipsește sau cum ar trebui să se comporte șablonul. Feedbackul dvs. ne ajută să păstrăm catalogul corect.

Verificat de TapHome

Doriți să folosiți acest șablon în TapHome Core?

Deschideți acest șablon în Customer Portal pentru a-l aplica într-una dintre locuințele dvs. sau pentru a propune o îmbunătățire și a o trimite înapoi în catalog.

Deschideți în portal