---
title: "Nanoleaf RGB svetlo"
description: "Integrácia Nanoleaf panelov, pásikov a žiaroviek do TapHome. Lokálne HTTP ovládanie HSB a farebnej teploty na porte 16021 — bez cloudu."
url: "https://taphome.com/sk/compatibility/nanoleaf-rgb-light/"
language: sk
lastmod: 2026-04-15
generator: hugo
ai:
  topics: ["http","lighting","wifi","rgb","cct","packet-parser"]
  questions: ["Ako integrovať Nanoleaf Light Panels s TapHome?","Ako vygenerovať auth_token pre Nanoleaf a TapHome?","Ktoré modely Nanoleaf sú podporované TapHome šablónou?","Prečo TapHome vracia NULL pre odtieň a sýtosť na Nanoleaf?","Môže TapHome spúšťať efekty alebo scény na Nanoleaf?","Prečo sa moja žiarovka Nanoleaf Essentials nevypne pri jase 0?"]
---

# Nanoleaf RGB svetlo

Komunikácia: Packet Parser → HTTP

- [Dokumentácia 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 v sieti
> 
> TapHome komunikuje so zariadením na adrese zadanej pri importe. Dajte zariadeniu stálu adresu — rezerváciu IP v routeri, alebo jeho mDNS meno, ak ho podporuje —, inak integrácia prestane fungovať, keď router adresu zmení.
> 
> [Príprava siete](https://taphome.com/sk/docs/setup/network-preparation/)

## Návod na integráciu

Nanoleaf je rodina Wi-Fi LED svietidiel — modulárne nástenné panely, LED pásiky, žiarovky, stojanové lampy a vianočné reťaze — ktoré všetky hovoria rovnakým lokálnym REST API na TCP porte **16021**. Jediná TapHome šablóna pokrýva každý WiFi dosiahnuteľný produkt Nanoleaf: TapHome dotazuje ovládač cez HTTP v LAN sieti a vystavuje celú zostavu ako jedno HSB svetlo s farebnou teplotou.

## Podporované modely

| Produkt | Kód modelu | Poznámky |
|---------|-----------|----------|
| Light Panels (pôvodne Aurora) | NL22 | Bez dotyku |
| Shapes Hexagons | NL42 | S dotykom |
| Shapes Triangles | NL47 | S dotykom |
| Shapes Mini Triangles | NL48 | S dotykom |
| Canvas (štvorce) | NL29 | S dotykom |
| Elements Hexagons (drevený dizajn) | NL52 | Užší rozsah CCT (1500–4000 K) |
| Lines | NL59 | S dotykom |
| Matter WiFi Essentials (žiarovky, LED pásiky, vianočné reťaze, stojanová lampa, A19) | — | Iba firmvér 3.0.10+; prísnejší dolný limit jasu a užší rozsah CCT (2127–6535 K) |

> [!INFO]
> Verzie Nanoleaf Essentials s výlučne Thread protokolom a Nanoleaf Skylight **nie sú podporované** — šablóna vyžaduje WiFi dosiahnuteľný ovládač komunikujúci cez Open API na porte 16021.

## Funkcie zariadenia

### Svetlo (HSB + farebná teplota)

Šablóna vystavuje jedno HSB svetlo s funkciami zapnutie/vypnutie, jas, odtieň, sýtosť a farebná teplota. V každom cykle dotazovania (500 ms) modul posiela

```
GET /api/v1/{authToken}/
```

a ukladá kompletný JSON zariadenia do vlastnej premennej `StatusJson`. Čítacie skripty pre jednotlivé vlastnosti potom parsujú polia z tohto uloženého záznamu:

- **Zapnutie/vypnutie** — `state.on.value`
- **Jas** — `state.brightness.value` (0–100), normalizované do rozsahu TapHome 0,0–1,0
- **Odtieň** — `state.hue.value` (0–360°) — čítané iba pri `state.colorMode == "hs"`
- **Sýtosť** — `state.sat.value` (0–100) — čítané iba pri `state.colorMode == "hs"`
- **Farebná teplota** — `state.ct.value` (v Kelvinoch) — čítané iba pri `state.colorMode == "ct"`

Všetky zápisy idú na `PUT /api/v1/{authToken}/state` s JSON telom pre každú vlastnosť:

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

Šablóna deklaruje **1800–6500 K** ako rozsah farebnej teploty — praktickú podmnožinu toho, čo hardvér skutočne podporuje. Hodnoty mimo fyzického pásma zariadenia sú ticho orezané firmvérom Nanoleaf (pozri [Poznámky a obmedzenia](https://taphome.com/sk/compatibility/nanoleaf-rgb-light/#notes-and-limitations)).

### Rozlišovanie farebných režimov

Ovládače Nanoleaf sú vždy v jednom z troch farebných režimov:

| `colorMode` | Význam |
|-------------|--------|
| `hs` | Režim odtieňa/sýtosti — hodnoty odtieňa a sýtosti sú aktívne |
| `ct` | Režim farebnej teploty — hodnota CCT je aktívna |
| `effect` | Beží dynamická scéna |

Čítacie skripty TapHome tento stav rešpektujú: čítanie odtieňa a sýtosti vráti `NULL`, keď je ovládač v režime `ct` alebo `effect`, a čítanie farebnej teploty vráti `NaN`, keď je v režime `hs` alebo `effect`. Tým sa zabráni, aby sa do dashboardu dostávali zastarané hodnoty z iného režimu. Zápis akejkoľvek hodnoty odtieňa alebo sýtosti prepne ovládač do režimu `hs`, zápis hodnoty CCT ho prepne do `ct` — oba zápisy zastavia bežiaci efekt.

## Konfigurácia

### 1. Spárovanie ovládača v aplikácii Nanoleaf

Namontujte panely / žiarovku / pásik, nainštalujte mobilnú aplikáciu **Nanoleaf** a pripojte ovládač k lokálnej Wi-Fi sieti cez párovací proces v aplikácii. Poznačte si IPv4 adresu ovládača — aplikácia ju zobrazí v nastaveniach zariadenia → Info, alebo ju možno prečítať z tabuľky DHCP záznamov routera.

### 2. Vygenerovanie Open API tokenu

Nanoleaf Open API vyžaduje jednorazové spárovanie medzi TapHome a ovládačom. Toto spárovanie vygeneruje permanentný 32-znakový `auth_token`, ktorý prežije reštarty a aktualizácie firmvéru.

1. Na **ovládači Nanoleaf** (malá jednotka v linke pre panely, alebo samotné zariadenie pri žiarovkách / pásikoch) podržte tlačidlo zapnutia/vypnutia **5–7 sekúnd**, kým biela LED nezačne blikať vzorom. Zariadenie je teraz v párovacom režime na **30 sekúnd**.
2. Do 30-sekundového okna pošlite prázdny `POST` na párovací endpoint — napríklad pomocou `curl`, PowerShell alebo Postman:

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

   Ovládač odpovie:

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

3. Skopírujte 32-znakový reťazec `auth_token`.

Ak okno uplynie pred prijatím POST, endpoint vráti **403 Forbidden** — znovu podržte tlačidlo zapnutia/vypnutia a skúste znova.

> [!TIP]
> Niektoré formáty Essentials (žiarovky, pásiky) nemajú fyzické tlačidlo. V tom prípade spustite párovanie z nastavení zariadenia v aplikácii Nanoleaf — aplikácia aktivuje 30-sekundové okno za vás.

### 3. Import šablóny v TapHome

1. V TapHome vytvorte nové PacketParser zariadenie zo šablóny **Nanoleaf RGB light**.
2. Zadajte IPv4 adresu ovládača ako parameter importu `ipAddress`. Port je pevný **16021** a netreba ho meniť.
3. Otvorte vlastnosti zariadenia, nájdite vlastnú premennú `authToken` a vložte 32-znakový token vygenerovaný v kroku 2.
4. Uložte. Modul bude dotazovať `/api/v1/{authToken}/` každých 500 ms a naplní HSB svetlo aktuálnym stavom.

Ak je token nesprávny alebo vypršal, každé čítanie zlyhá s **401 Unauthorized** v TapHome logu.

### Sieťové požiadavky

- Iba odchádzajúci **TCP 16021** z TapHome CCU k ovládaču Nanoleaf. Žiadne cloudové volania, žiadny MQTT broker, žiadne HTTPS certifikáty.
- CCU a ovládač musia byť v rovnakej **LAN / VLAN** sieti. Ak sú Wi-Fi a drôtové siete oddelené, pridajte pravidlo firewallu povoľujúce TCP 16021 medzi nimi.
- Ovládače Nanoleaf inzerujú službu `_nanoleafapi._tcp` cez mDNS. Šablóna vyžaduje priamu IP, ale mDNS možno použiť pri objavovaní pomocou `avahi-browse -r _nanoleafapi._tcp` (Linux) alebo `dns-sd -B _nanoleafapi._tcp` (macOS).

> [!WARNING]
> Nanoleaf Open API je **iba HTTP** — neexistuje HTTPS ani šifrovanie prenosu. Je bezpečné v rámci LAN siete, ale nikdy nesmie byť vystavené verejnému internetu. Neforwardujte port 16021 cez router.

## Poznámky a obmedzenia

### Rozsah farebnej teploty závisí od rodiny modelu

TapHome šablóna deklaruje **1800–6500 K** ako zapisovateľný rozsah CCT. Hardvérové pásmo sa líši podľa rodiny:

| Rodina | Hardvérový rozsah CCT | Správanie mimo rozsahu |
|--------|------------------------|--------------------------|
| Light Panels, Shapes, Canvas, Lines | 1200–6500 K | Orezané firmvérom |
| Elements Hexagons | 1500–4000 K | Orezané firmvérom |
| Matter WiFi Essentials | 2127–6535 K | Orezané firmvérom; 1800 K je pod dolnou hranicou 2127 K, takže Essentials orezú na 2127 K |

Zápis hodnoty mimo fyzického pásma zariadenia nevyvolá chybu — ovládač ticho použije vlastný limit. Pri návrhu dashboardov zameraných na Essentials preferujte hodnoty CCT v spoločnom okne 2127–6500 K.

### Essentials odmietajú jas = 0

Klasické ovládače (Light Panels, Shapes, Canvas, Elements, Lines) akceptujú `brightness: 0`. **Matter WiFi Essentials** vynucujú minimum **1** a odmietajú `0` s HTTP 400. Na vypnutie Essentials žiarovky alebo pásika použite kanál zapnutie/vypnutie namiesto nastavenia jasu na nulu.

### Čítanie odtieňa / sýtosti / CCT môže vrátiť NULL alebo NaN

Keďže režimy `hs` a `ct` sú vzájomne exkluzívne a oba sú neaktívne počas bežiaceho efektu, čítania z nesprávneho režimu zámerne vracajú `NULL` (odtieň / sýtosť) alebo `NaN` (ct). Je to očakávané správanie, nie chyba. Zápis hodnoty odtieňa / sýtosti / ct vráti ovládač do režimu `hs` alebo `ct` a čítania sa obnovia.

### Jeden token na ovládač, nie na panel

Viac-panelové zostavy Shapes alebo Canvas sú jedným TapHome zariadením. Auth token je vydaný na úrovni ovládača a pokrýva každý pripojený panel.

### Nestabilita IPv6 mDNS na firmvéri 8.5.2+

Komunita openHAB hlásila, že IPv6 mDNS záznamy striedajú stavy ONLINE a OFFLINE na niektorých ovládačoch s firmvérom 8.5.2+. Ak je mDNS objavovanie nestabilné, nastavte pevnú IPv4 DHCP rezerváciu a použite IP priamo — TapHome šablóna sa na mDNS aj tak nespolieha.

## Riešenie problémov

### 401 Unauthorized pri každom čítaní

`authToken` je nesprávny, vypršal alebo bol zrušený. Vygenerujte nový token (podržte tlačidlo zapnutia/vypnutia 5–7 s a pošlite POST na `/api/v1/new`) a vložte ho do vlastnej premennej `authToken`.

### 403 Forbidden pri generovaní tokenu

30-sekundové párovacie okno sa zavrelo. Znovu podržte tlačidlo zapnutia/vypnutia, kým LED nezačne blikať vzorom, a potom ihneď pošlite `POST /api/v1/new`.

### Odtieň / sýtosť zobrazujú NULL v dashboarde

Ovládač je v režime `ct` alebo beží efekt. Zapíšte akúkoľvek hodnotu odtieňa alebo sýtosti, aby sa ovládač prepol späť do režimu `hs`, alebo nastavte farbu cez HSB výber. Šablóna nevie odvodiť čítanie odtieňa / sýtosti, keď zariadenie takú hodnotu neprodukuje.

### Farebná teplota sa číta ako NaN

Ovládač je v režime `hs` alebo beží efekt. Zapíšte hodnotu CCT, aby sa prepol do režimu `ct`, alebo nastavte farebnú teplotu z dashboardu. Ak beží efekt, zastavte ho z aplikácie Nanoleaf (alebo zapíšte akúkoľvek HSB / CCT hodnotu — tiež zastaví efekt).

### Zápis jasu zlyhá na Essentials

Matter WiFi Essentials odmietajú `brightness: 0`. Na vypnutie použite kanál zapnutia/vypnutia namiesto zápisu 0 do jasu. Hodnoty 1–100 sú akceptované na všetkých modeloch.

### Ovládač sa odpája na firmvéri 8.5.2+

Ak TapHome CCU opakovane stráca ovládač, priraďte statickú IPv4 DHCP rezerváciu a použite IP v parametri importu `ipAddress` — vrstva IPv6 mDNS môže byť na tomto vetvovaní firmvéru nestabilná.

## Dostupné zariadenia 1

Tieto zariadenia sa po importe zobrazia v TapHome.

Nanoleaf Modul

Vlastné premenné

`authToken` (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx 32-znakový párovací token Nanoleaf Open API. Vygenerujte ho jednorazovo podržaním tlačidla zapnutia/vypnutia na ovládači 5–7 sekúnd a odoslaním POST http://{ip}:16021/api/v1/new do 30 sekúnd — vrátený auth\_token vložte sem. Token prežije reštarty a aktualizácie firmvéru.

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.

Čítanie (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 svetlo HSB svetlo Čítanie aj zápis

HSB svetlo s dvoma farebnými režimami — odtieň a sýtosť (0–360° / 0–100 %) alebo farebná teplota (deklarovaných 1800–6500 K, hardvérový rozsah závisí od modelu). Jas 0–100 %. Čítanie odtieňa / sýtosti je aktívne iba v režime hs; čítanie CCT je aktívne iba v režime ct; oba sú neaktívne počas bežiaceho efektu.

HSBLight json

Čítanie (modul)

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

Čítanie jasu

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

Zápis jasu

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

Čítanie odtieňa

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

Zápis odtieňa

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

Čítanie saturácie

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

Zápis saturácie

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

Čítanie farebnej teploty

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

Zápis farebnej teploty

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

**Pripojenie:** Packet Parser → HTTP

Možné vylepšenia (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.

## Parametre importu

Tieto hodnoty zadáte pri importe XML.

| Pýta sa v aplikácii | Predvolené    |
|---------------------|---------------|
| IP adresa           | `192.168.0.1` |

## Zdroje

- 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

## Súvisiaca dokumentácia

- [Integrácia Packet Parser](https://taphome.com/sk/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/sk/docs/integration/packet-parser/)
- [Funkcie Packet parsera](https://taphome.com/sk/docs/script/packet-parser/)
- [Parsovacie funkcie](https://taphome.com/sk/docs/script/parsing-functions/)