---
title: "Nanoleaf RGB light"
description: "Integrirajte Nanoleaf panele, trake i žarulje sa sustavom TapHome. Lokalno HTTP upravljanje HSB i temperaturom boje na portu 16021, bez oblaka."
url: "https://taphome.com/hr/compatibility/nanoleaf-rgb-light/"
language: hr
lastmod: 2026-04-15
generator: hugo
ai:
  topics: ["http","lighting","wifi","rgb","cct","packet-parser"]
  questions: ["Kako integrirati Nanoleaf Light Panels sa sustavom TapHome?","Kako generirati Nanoleaf auth_token za TapHome?","Koje modele Nanoleaf podržava predložak TapHome?","Zašto TapHome kod Nanoleafa vraća NULL za nijansu i zasićenost?","Može li TapHome pokrenuti efekte ili scene Nanoleaf?","Zašto se moja žarulja Nanoleaf Essentials ne isključuje pri svjetlini 0?"]
---

# Nanoleaf RGB light

Komunikacija: Packet Parser → HTTP

- [Dokumentacija za 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 u mreži
> 
> TapHome komunicira s uređajem na adresi unesenoj pri uvozu. Dodijelite uređaju stalnu adresu — rezervaciju IP adrese u usmjerivaču ili njegovo mDNS ime ako ga podržava — inače integracija prestaje raditi kada usmjerivač promijeni adresu.
> 
> [Priprema mreže](https://taphome.com/hr/docs/setup/network-preparation/)

## Upute za integraciju

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

| Proizvod | Oznaka modela | Napomene |
|---------|-----------|-------|
| Light Panels (prije Aurora) | NL22 | Bez dodira |
| Shapes Hexagons | NL42 | Podržava dodir |
| Shapes Triangles | NL47 | Podržava dodir |
| Shapes Mini Triangles | NL48 | Podržava dodir |
| Canvas (Squares) | NL29 | Podržava dodir |
| Elements Hexagons (Wood Look) | NL52 | Uži raspon temperature boje (1500–4000 K) |
| Lines | NL59 | Podrž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) |

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

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

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

### Ovisnost o načinu boje

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

| `colorMode` | Značenje |
|-------------|---------|
| `hs` | Način nijanse i zasićenosti: vrijednosti nijanse i zasićenosti su aktualne |
| `ct` | Način temperature boje: vrijednost temperature boje je aktualna |
| `effect` | Pokrenuta 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.

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

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

   Upravljač odgovara:

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

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

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

| Obitelj | Raspon temperature boje hardvera | Ponašanje izvan raspona |
|--------|--------------------|--------------------------|
| Light Panels, Shapes, Canvas, Lines | 1200–6500 K | Firmver ograničava vrijednost |
| Elements Hexagons | 1500–4000 K | Firmver ograničava vrijednost |
| Matter WiFi Essentials | 2127–6535 K | Firmver 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 1

Ovi se uređaji pojavljuju u TapHomeu nakon uvoza.

Nanoleaf Modul

Prilagođene varijable

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

Čitanje (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
```

Nanoleaf RGB svjetlo HSB svjetlo Čitanje i pisanje

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

Čitanje (modul)

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

Čitanje svjetline

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

Zapis svjetline

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

Čitanje nijanse

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

Zapis nijanse

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

Čitanje zasićenosti

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

Zapis zasićenosti

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

Čitanje temperature boje

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

Zapis temperature boje

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

## Parametri uvoza

Ove vrijednosti unosite pri uvozu XML-a.

| Pitanje u aplikaciji | Zadano        |
|----------------------|---------------|
| IP adresa            | `192.168.0.1` |

## Izvori

- 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

## Povezana dokumentacija

- [Packet Parser Integration](https://taphome.com/hr/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/hr/docs/integration/packet-parser/)
- [Funkcije Packet parsera](https://taphome.com/hr/docs/script/packet-parser/)
- [Funkcije za raščlambu](https://taphome.com/hr/docs/script/parsing-functions/)

