TapHome

Luce RGB Nanoleaf

Packet Parser → HTTP
Inviato da
Ultimo aggiornamento: 04. 2026
Luce RGB Nanoleaf

Nanoleaf è una famiglia di prodotti di illuminazione LED Wi-Fi — pannelli da parete modulari, strisce LED, lampadine, lampade da terra e catene luminose natalizie — che parlano tutti la stessa REST API locale sulla porta TCP 16021. Un unico template TapHome copre ogni prodotto Nanoleaf raggiungibile via WiFi: TapHome interroga il controller via HTTP sulla LAN ed espone l’intera configurazione come un’unica luce HSB con temperatura di colore.

Modelli supportati

ProdottoCodice modelloNote
Light Panels (ex Aurora)NL22Senza touch
Shapes HexagonsNL42Touch abilitato
Shapes TrianglesNL47Touch abilitato
Shapes Mini TrianglesNL48Touch abilitato
Canvas (quadrati)NL29Touch abilitato
Elements Hexagons (effetto legno)NL52Range CCT più stretto (1500–4000 K)
LinesNL59Touch abilitato
Matter WiFi Essentials (lampadine, strisce LED, catene luminose, lampade da terra, A19)—Solo firmware 3.0.10+; minimo di luminosità più rigido e range CCT più stretto (2127–6535 K)

Le varianti Nanoleaf Essentials solo-Thread e il Nanoleaf Skylight non sono supportate — il template richiede un controller raggiungibile via WiFi che parli l’Open API sulla porta 16021.

Funzionalità del dispositivo

Luce (HSB + temperatura di colore)

Il template espone un’unica luce HSB con accensione/spegnimento, luminosità, tonalità, saturazione e temperatura di colore. Ad ogni ciclo di polling (500 ms) il modulo invia

1

GET /api/v1/{authToken}/

e memorizza il JSON completo del dispositivo nella variabile personalizzata StatusJson. Gli script di lettura per ciascuna proprietà analizzano quindi i campi da questo oggetto memorizzato:

  • Accensione/spegnimento — state.on.value
  • Luminosità — state.brightness.value (0–100), normalizzata nel range TapHome 0,0–1,0
  • Tonalità — state.hue.value (0–360°) — letta solo quando state.colorMode == "hs"
  • Saturazione — state.sat.value (0–100) — letta solo quando state.colorMode == "hs"
  • Temperatura di colore — state.ct.value (in Kelvin) — letta solo quando state.colorMode == "ct"

Tutte le scritture vanno a PUT /api/v1/{authToken}/state con un corpo JSON per ciascuna proprietà:

1
2
3
4

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

Il template dichiara 1800–6500 K come range di temperatura di colore — un sottoinsieme pratico di ciò che l’hardware supporta realmente. I valori al di fuori della banda fisica del dispositivo vengono silenziosamente limitati dal firmware Nanoleaf (vedere Note e limitazioni).

Gating delle modalità di colore

I controller Nanoleaf sono sempre esattamente in una delle tre modalità di colore:

colorModeSignificato
hsModalità tonalità/saturazione — i valori di tonalità e saturazione sono attivi
ctModalità temperatura di colore — il valore CCT è attivo
effectÈ in esecuzione una scena dinamica

Gli script di lettura TapHome rispettano questa logica: le letture di tonalità e saturazione restituiscono NULL quando il controller è in modalità ct o effect, e la lettura della temperatura di colore restituisce NaN quando è in modalità hs o effect. Questo evita che valori obsoleti di una modalità diversa vengano inviati alla dashboard. Scrivere un qualsiasi valore di tonalità/saturazione riporta il controller alla modalità hs, mentre scrivere un valore CCT lo riporta alla modalità ct — entrambe le scritture interrompono qualsiasi effetto in esecuzione.

Configurazione

1. Associare il controller nell’app Nanoleaf

Monta i pannelli / la lampadina / la striscia, installa l’app mobile Nanoleaf e collega il controller alla rete Wi-Fi locale tramite il flusso di associazione dell’app. Annota l’indirizzo IPv4 del controller — l’app lo mostra in Impostazioni dispositivo → Info, oppure può essere letto dalla tabella dei lease DHCP del router.

Assegna al controller Nanoleaf una prenotazione DHCP (o un IP statico) in modo che l’indirizzo non cambi dopo un rinnovo del lease. Il template TapHome memorizza l’IP nei parametri di importazione e non effettua il rilevamento automatico.

2. Generare il token Open API

La Nanoleaf Open API richiede un’associazione una tantum tra TapHome e il controller. L’associazione produce un auth_token permanente di 32 caratteri che sopravvive a riavvii e aggiornamenti del firmware.

  1. Sul controller Nanoleaf (la piccola unità in linea per i pannelli, o il dispositivo stesso per lampadine/strisce), tieni premuto il tasto di accensione/spegnimento per 5–7 secondi finché il LED bianco non inizia a lampeggiare con un pattern. Il dispositivo è ora in modalità associazione per 30 secondi.

  2. Entro la finestra di 30 secondi, invia un POST vuoto all’endpoint di associazione — ad esempio con curl, PowerShell o Postman:

    1

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

    Il controller risponde con:

    1

    { "auth_token": "xxxKJISJCjY2hfAyilpyIOfGixxxx" }

  3. Copia la stringa auth_token di 32 caratteri.

Se la finestra scade prima che arrivi il POST, l’endpoint restituisce 403 Forbidden — tieni premuto di nuovo il tasto di accensione/spegnimento e riprova.

Alcuni formati Essentials (lampadine, strisce) non hanno un pulsante fisico. In tal caso, avvia l’associazione dalle impostazioni del dispositivo nell’app Nanoleaf — l’app attiva la finestra di 30 secondi per te.

3. Importare il template in TapHome
  1. In TapHome, crea un nuovo dispositivo PacketParser dal template Nanoleaf RGB light.
  2. Inserisci l’indirizzo IPv4 del controller come parametro di importazione ipAddress. La porta è fissa a 16021 e non deve essere modificata.
  3. Apri le proprietà del dispositivo, trova la variabile personalizzata authToken e incolla il token di 32 caratteri generato al passo 2.
  4. Salva. Il modulo eseguirà il polling di /api/v1/{authToken}/ ogni 500 ms e popolerà la luce HSB con lo stato corrente.

Se il token è errato o scaduto, ogni lettura fallisce con 401 Unauthorized nel log di TapHome.

Requisiti di rete
  • Solo TCP 16021 in uscita dal CCU TapHome al controller Nanoleaf. Nessuna chiamata cloud, nessun broker MQTT, nessun certificato HTTPS.
  • Il CCU e il controller devono essere sulla stessa rete LAN / VLAN. Se le reti Wi-Fi e cablate sono segregate, aggiungi una regola firewall che consenta TCP 16021 tra di esse.
  • I controller Nanoleaf pubblicizzano il servizio _nanoleafapi._tcp via mDNS. Il template richiede un IP diretto, ma mDNS può essere usato per il rilevamento con avahi-browse -r _nanoleafapi._tcp (Linux) o dns-sd -B _nanoleafapi._tcp (macOS).

La Nanoleaf Open API è solo HTTP — non c’è HTTPS né crittografia del trasporto. È sicura all’interno della LAN ma non deve mai essere esposta a internet pubblico. Non inoltrare la porta 16021 attraverso il router.

Note e limitazioni

Il range di temperatura di colore dipende dalla famiglia del modello

Il template TapHome dichiara 1800–6500 K come range CCT scrivibile. La banda hardware sottostante varia per famiglia:

FamigliaRange CCT hardwareComportamento fuori range
Light Panels, Shapes, Canvas, Lines1200–6500 KLimitato dal firmware
Elements Hexagons1500–4000 KLimitato dal firmware
Matter WiFi Essentials2127–6535 KLimitato dal firmware; 1800 K è al di sotto del limite inferiore di 2127 K, quindi gli Essentials limitano a 2127 K

Scrivere un valore al di fuori della banda fisica del dispositivo non genera errori — il controller usa silenziosamente il proprio limite. Quando progetti dashboard destinate agli Essentials, preferisci valori CCT nella finestra comune 2127–6500 K.

Gli Essentials rifiutano luminosità = 0

I controller classici (Light Panels, Shapes, Canvas, Elements, Lines) accettano brightness: 0. I Matter WiFi Essentials impongono un minimo di 1 e rifiutano 0 con HTTP 400. Per spegnere una lampadina o striscia Essentials, usa il canale di accensione/spegnimento invece di portare la luminosità a zero.

Le letture di tonalità / saturazione / CCT possono restituire NULL o NaN

Poiché hs e ct si escludono a vicenda e entrambi sono inattivi durante un effetto in esecuzione, le letture della modalità errata restituiscono intenzionalmente NULL (tonalità / saturazione) o NaN (ct). Questo è il comportamento atteso, non un errore. Una scrittura di tonalità / saturazione / ct riporta il controller alla modalità hs o ct e le letture riprendono.

Un token per controller, non per pannello

Un layout Shapes o Canvas multi-pannello è un unico dispositivo TapHome. L’auth token viene emesso a livello di controller e copre ogni pannello ad esso collegato.

Instabilità mDNS IPv6 su firmware 8.5.2+

La community openHAB ha segnalato che i record mDNS IPv6 alternano stati ONLINE e OFFLINE su alcuni controller con firmware 8.5.2+. Se il rilevamento mDNS è instabile, imposta una prenotazione DHCP IPv4 fissa e usa l’IP direttamente — il template TapHome non si affida comunque a mDNS.

Risoluzione dei problemi

401 Unauthorized a ogni lettura

L’authToken è errato, scaduto o è stato revocato. Genera un nuovo token (tieni premuto il tasto di accensione/spegnimento per 5–7 s e invia POST a /api/v1/new) e incollalo nella variabile personalizzata authToken.

403 Forbidden durante la generazione del token

La finestra di associazione di 30 secondi si è chiusa. Tieni premuto di nuovo il tasto di accensione/spegnimento finché il LED non lampeggia con un pattern, quindi invia immediatamente POST /api/v1/new.

Tonalità / saturazione mostrano NULL sulla dashboard

Il controller è in modalità ct o è in esecuzione un effetto. Scrivi un qualsiasi valore di tonalità o saturazione per riportare il controller alla modalità hs, oppure imposta un colore con il selettore HSB. Il template non può dedurre una lettura di tonalità/saturazione quando il dispositivo non la produce.

La temperatura di colore viene letta come NaN

Il controller è in modalità hs o è in esecuzione un effetto. Scrivi un valore CCT per passare alla modalità ct, oppure imposta una temperatura di colore dalla dashboard. Se è in esecuzione un effetto, interrompilo dall’app Nanoleaf (o scrivi un qualsiasi valore HSB / CCT — anche questo arresta l’effetto).

La scrittura della luminosità fallisce sugli Essentials

I Matter WiFi Essentials rifiutano brightness: 0. Usa il canale di accensione/spegnimento per spegnere invece di scrivere 0 nella luminosità. I valori 1–100 sono accettati su tutti i modelli.

Il controller va offline su firmware 8.5.2+

Se il CCU TapHome perde ripetutamente il controller, assegna una prenotazione DHCP IPv4 statica e usa l’IP nel parametro di importazione ipAddress — il livello mDNS IPv6 può essere instabile su questo ramo firmware.

Dispositivi disponibili

Nanoleaf Modulo
Variabili personalizzate
authToken (string) = xxxKJISJCjY2hfAyilpyIOfGixxxxToken di associazione Nanoleaf Open API di 32 caratteri. Generalo una sola volta tenendo premuto il tasto di accensione/spegnimento del controller per 5–7 secondi e inviando POST http://{ip}:16021/api/v1/new entro 30 secondi — incolla qui l'auth_token restituito. Il token sopravvive a riavvii e aggiornamenti del 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

Lettura (modulo)
#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
Luce RGB Nanoleaf Luce HSB

Luce HSB con doppia modalità di colore — tonalità e saturazione (0–360° / 0–100 %) o temperatura di colore (1800–6500 K dichiarati, il range hardware dipende dal modello). Luminosità 0–100 %. Le letture di tonalità / saturazione sono attive solo in modalità hs; le letture CCT sono attive solo in modalità ct; entrambe sono inattive durante un effetto in esecuzione.

HSBLight json

Luce RGB Nanoleaf

Lettura (modulo)
var value := PARSEJSON(StatusJson, "state.on.value");
IF(ISNULL(value), NaN, IF(value, 1, 0));
Lettura luminosità
var value := PARSEJSON(StatusJson, "state.brightness.value")/100;
IF(ISNULL(value), NaN, value);
Scrittura luminosità
var content:="{\"brightness\" : {\"value\":"+ROUND(Hb*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Lettura tonalità
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
Scrittura tonalità
var content:="{\"hue\" : {\"value\":"+ROUND(Hd)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Lettura saturazione
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
Scrittura saturazione
var content:="{\"sat\" : {\"value\":"+ROUND(Sa*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Lettura temperatura colore
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
Scrittura temperatura colore
var content:="{\"ct\" : {\"value\":"+ROUND(Ct)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Connessione: Packet Parser → HTTP
Possibili miglioramenti (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.

Fonti