---
title: "Luce RGB Nanoleaf"
description: "Integrazione Nanoleaf pannelli, strisce e lampadine in TapHome. Controllo HTTP locale di HSB e temperatura di colore sulla porta 16021 — senza cloud."
url: "https://taphome.com/it/compatibility/nanoleaf-rgb-light/"
language: it
lastmod: 2026-04-15
generator: hugo
ai:
  topics: ["http","lighting","wifi","rgb","cct","packet-parser"]
  questions: ["Come integrare i Nanoleaf Light Panels con TapHome?","Come generare un auth_token Nanoleaf per TapHome?","Quali modelli Nanoleaf sono supportati dal template TapHome?","Perché TapHome restituisce NULL per tonalità e saturazione su Nanoleaf?","TapHome può avviare effetti o scene Nanoleaf?","Perché la mia lampadina Nanoleaf Essentials non si spegne con luminosità 0?"]
---

# Luce RGB Nanoleaf

Comunicazione: Packet Parser → HTTP

- [Documentazione 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)

> Indirizzo di rete
> 
> TapHome raggiunge il dispositivo all'indirizzo inserito durante l'importazione. Assegna al dispositivo un indirizzo fisso — una prenotazione IP nel router, oppure il suo nome mDNS se lo supporta —, altrimenti l'integrazione smette di funzionare quando il router cambia l'indirizzo.
> 
> [Preparazione della rete](https://taphome.com/it/docs/setup/network-preparation/)

## Guida all'integrazione

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

| Prodotto | Codice modello | Note |
|----------|----------------|------|
| Light Panels (ex Aurora) | NL22 | Senza touch |
| Shapes Hexagons | NL42 | Touch abilitato |
| Shapes Triangles | NL47 | Touch abilitato |
| Shapes Mini Triangles | NL48 | Touch abilitato |
| Canvas (quadrati) | NL29 | Touch abilitato |
| Elements Hexagons (effetto legno) | NL52 | Range CCT più stretto (1500–4000 K) |
| Lines | NL59 | Touch 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) |

> [!INFO]
> 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

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

```json
{ "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](https://taphome.com/it/compatibility/nanoleaf-rgb-light/#notes-and-limitations)).

### Gating delle modalità di colore

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

| `colorMode` | Significato |
|-------------|-------------|
| `hs` | Modalità tonalità/saturazione — i valori di tonalità e saturazione sono attivi |
| `ct` | Modalità 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.

### 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:

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

   Il controller risponde con:

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

> [!TIP]
> 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).

> [!WARNING]
> 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:

| Famiglia | Range CCT hardware | Comportamento fuori range |
|----------|---------------------|----------------------------|
| Light Panels, Shapes, Canvas, Lines | 1200–6500 K | Limitato dal firmware |
| Elements Hexagons | 1500–4000 K | Limitato dal firmware |
| Matter WiFi Essentials | 2127–6535 K | Limitato 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 1

Questi dispositivi compaiono in TapHome dopo l'importazione.

Nanoleaf Modulo

Variabili personalizzate

`authToken` (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx Token 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.

Lettura (modulo)

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

Luce RGB Nanoleaf Luce HSB Lettura e scrittura

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

Lettura (modulo)

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

Lettura luminosità

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

Scrittura luminosità

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

Lettura tonalità

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

Scrittura tonalità

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

Lettura saturazione

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

Scrittura saturazione

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

Lettura temperatura colore

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

Scrittura temperatura colore

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

## Parametri di importazione

Inserisci questi valori quando importi l'XML.

| Richiesto nell'app | Predefinito   |
|--------------------|---------------|
| Indirizzo IP       | `192.168.0.1` |

## Fonti

- 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

## Documentazione correlata

- [Integrazione Packet Parser](https://taphome.com/it/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/it/docs/integration/packet-parser/)
- [Funzioni Packet parser](https://taphome.com/it/docs/script/packet-parser/)
- [Funzioni di parsing](https://taphome.com/it/docs/script/parsing-functions/)