---
title: "Nanoleaf RGB light"
description: "Integrați panourile, benzile și becurile Nanoleaf cu TapHome. Control HTTP local al HSB și al temperaturii de culoare pe portul 16021 — fără cloud."
url: "https://taphome.com/ro/compatibility/nanoleaf-rgb-light/"
language: ro
lastmod: 2026-04-15
generator: hugo
ai:
  topics: ["http","lighting","wifi","rgb","cct","packet-parser"]
  questions: ["Cum integrez Nanoleaf Light Panels cu TapHome?","Cum generez un auth_token Nanoleaf pentru TapHome?","Ce modele Nanoleaf sunt acceptate de șablonul TapHome?","De ce returnează TapHome NULL pentru nuanță și saturație la Nanoleaf?","Poate TapHome să pornească efecte sau scene Nanoleaf?","De ce becul meu Nanoleaf Essentials nu se oprește la luminozitatea 0?"]
---

# Nanoleaf RGB light

Comunicație: Packet Parser → HTTP

- [Documentația 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)

> Adresa în rețea
> 
> TapHome comunică cu dispozitivul la adresa introdusă la import. Atribuiți dispozitivului o adresă fixă — o rezervare IP în router sau numele său mDNS, dacă îl acceptă —, altfel integrarea nu mai funcționează când routerul schimbă adresa.
> 
> [Pregătirea rețelei](https://taphome.com/ro/docs/setup/network-preparation/)

## Ghid de integrare

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

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

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

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

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

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

1. 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**.
2. În acest interval de 30 de secunde, trimiteți un `POST` gol către endpointul de asociere — de exemplu cu `curl`, PowerShell sau Postman:

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

   Controlerul răspunde cu:

   ```json
   { "auth_token": "xxxKJISJCjY2hfAyilpyIOfGixxxx" }
   ```

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

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

1. În TapHome, creați un nou dispozitiv PacketParser din șablonul **Lumină RGB Nanoleaf**.
2. Introduceți adresa IPv4 a controlerului în parametrul de import `ipAddress`. Portul este fix, **16021**, și nu este necesar să fie schimbat.
3. Deschideți proprietățile dispozitivului, găsiți variabila personalizată `authToken` și lipiți tokenul de 32 de caractere generat la pasul 2.
4. 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).

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

Aceste dispozitive apar în TapHome după import.

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.

Citire (modul)

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

Lumină RGB Nanoleaf Lumină HSB Citire și scriere

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

Citire (modul)

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

Citirea luminozității

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

Scrierea luminozității

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

Citirea nuanței

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

Scrierea nuanței

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

Citirea saturației

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

Scrierea saturației

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

Citirea temperaturii de culoare

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

Scrierea temperaturii de culoare

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

## Parametri de import

Introduceți aceste valori când importați XML-ul.

| Solicitat în aplicație | Implicit      |
|------------------------|---------------|
| Adresă IP              | `192.168.0.1` |

## Surse

- 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

## Documentație asociată

- [Packet Parser Integration](https://taphome.com/ro/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/ro/docs/integration/packet-parser/)
- [Funcții Packet parser](https://taphome.com/ro/docs/script/packet-parser/)
- [Funcții de parsare](https://taphome.com/ro/docs/script/parsing-functions/)

