---
title: "Nanoleaf RGB světlo"
description: "Integrace Nanoleaf panelů, pásků a žárovek do TapHome. Lokální HTTP ovládání HSB a teploty barvy na portu 16021 — bez cloudu."
url: "https://taphome.com/cs/compatibility/nanoleaf-rgb-light/"
language: cs
lastmod: 2026-04-15
generator: hugo
ai:
  topics: ["http","lighting","wifi","rgb","cct","packet-parser"]
  questions: ["Jak integrovat Nanoleaf Light Panels s TapHome?","Jak vygenerovat auth_token pro Nanoleaf a TapHome?","Které modely Nanoleaf jsou podporovány šablonou TapHome?","Proč TapHome vrací NULL pro odstín a sytost na Nanoleaf?","Může TapHome spouštět efekty nebo scény na Nanoleaf?","Proč se moje žárovka Nanoleaf Essentials nevypne při jasu 0?"]
---

# Nanoleaf RGB světlo

Komunikace: Packet Parser → HTTP

- [Dokumentace 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 síti
> 
> TapHome komunikuje se zařízením na adrese zadané při importu. Dejte zařízení stálou adresu — rezervaci IP v routeru, nebo jeho mDNS jméno, pokud ho podporuje —, jinak integrace přestane fungovat, když router adresu změní.
> 
> [Příprava sítě](https://taphome.com/cs/docs/setup/network-preparation/)

## Návod na integraci

Nanoleaf je rodina Wi-Fi LED svítidel — modulární nástěnné panely, LED pásky, žárovky, stojanové lampy a vánoční řetězy — které všechny mluví stejným lokálním REST API na TCP portu **16021**. Jediná šablona TapHome pokrývá každý WiFi dostupný produkt Nanoleaf: TapHome dotazuje ovladač přes HTTP v LAN síti a vystavuje celou sestavu jako jedno HSB světlo s teplotou barvy.

## Podporované modely

| Produkt | Kód modelu | Poznámky |
|---------|-----------|----------|
| Light Panels (původně Aurora) | NL22 | Bez dotyku |
| Shapes Hexagons | NL42 | S dotykem |
| Shapes Triangles | NL47 | S dotykem |
| Shapes Mini Triangles | NL48 | S dotykem |
| Canvas (čtverce) | NL29 | S dotykem |
| Elements Hexagons (dřevěný design) | NL52 | Užší rozsah CCT (1500–4000 K) |
| Lines | NL59 | S dotykem |
| Matter WiFi Essentials (žárovky, LED pásky, vánoční řetězy, stojanová lampa, A19) | — | Pouze firmware 3.0.10+; přísnější dolní limit jasu a užší rozsah CCT (2127–6535 K) |

> [!INFO]
> Verze Nanoleaf Essentials s výlučně protokolem Thread a Nanoleaf Skylight **nejsou podporovány** — šablona vyžaduje WiFi dostupný ovladač komunikující přes Open API na portu 16021.

## Funkce zařízení

### Světlo (HSB + teplota barvy)

Šablona vystavuje jedno HSB světlo s funkcemi zapnutí/vypnutí, jas, odstín, sytost a teplota barvy. V každém dotazovacím cyklu (500 ms) modul posílá

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

a ukládá kompletní JSON zařízení do vlastní proměnné `StatusJson`. Čtecí skripty pro jednotlivé vlastnosti poté parsují pole z tohoto uloženého záznamu:

- **Zapnutí/vypnutí** — `state.on.value`
- **Jas** — `state.brightness.value` (0–100), normalizováno do rozsahu TapHome 0,0–1,0
- **Odstín** — `state.hue.value` (0–360°) — čteno pouze při `state.colorMode == "hs"`
- **Sytost** — `state.sat.value` (0–100) — čteno pouze při `state.colorMode == "hs"`
- **Teplota barvy** — `state.ct.value` (v Kelvinech) — čteno pouze při `state.colorMode == "ct"`

Všechny zápisy jdou na `PUT /api/v1/{authToken}/state` s JSON tělem pro každou vlastnost:

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

Šablona deklaruje **1800–6500 K** jako rozsah teploty barvy — praktickou podmnožinu toho, co hardware skutečně podporuje. Hodnoty mimo fyzické pásmo zařízení jsou tiše oříznuty firmwarem Nanoleaf (viz [Poznámky a omezení](https://taphome.com/cs/compatibility/nanoleaf-rgb-light/#notes-and-limitations)).

### Rozlišování barevných režimů

Ovladače Nanoleaf jsou vždy v jednom ze tří barevných režimů:

| `colorMode` | Význam |
|-------------|--------|
| `hs` | Režim odstínu/sytosti — hodnoty odstínu a sytosti jsou aktivní |
| `ct` | Režim teploty barvy — hodnota CCT je aktivní |
| `effect` | Běží dynamická scéna |

Čtecí skripty TapHome tento stav respektují: čtení odstínu a sytosti vrátí `NULL`, když je ovladač v režimu `ct` nebo `effect`, a čtení teploty barvy vrátí `NaN`, když je v režimu `hs` nebo `effect`. Tím se zabrání, aby se do dashboardu dostávaly zastaralé hodnoty z jiného režimu. Zápis jakékoliv hodnoty odstínu nebo sytosti přepne ovladač do režimu `hs`, zápis hodnoty CCT ho přepne do `ct` — oba zápisy zastaví běžící efekt.

## Konfigurace

### 1. Spárování ovladače v aplikaci Nanoleaf

Namontujte panely / žárovku / pásek, nainstalujte mobilní aplikaci **Nanoleaf** a připojte ovladač k lokální Wi-Fi síti pomocí párovacího procesu v aplikaci. Poznamenejte si IPv4 adresu ovladače — aplikace ji zobrazí v nastavení zařízení → Info, nebo ji lze přečíst z tabulky DHCP záznamů routeru.

### 2. Vygenerování Open API tokenu

Nanoleaf Open API vyžaduje jednorázové spárování mezi TapHome a ovladačem. Toto párování vygeneruje permanentní 32znakový `auth_token`, který přežije restarty a aktualizace firmwaru.

1. Na **ovladači Nanoleaf** (malá jednotka v lince pro panely, nebo samotné zařízení u žárovek / pásků) podržte tlačítko zapnutí/vypnutí **5–7 sekund**, dokud bílá LED nezačne blikat vzorem. Zařízení je nyní v párovacím režimu po dobu **30 sekund**.
2. Do 30sekundového okna odešlete prázdný `POST` na párovací endpoint — například pomocí `curl`, PowerShell nebo Postman:

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

   Ovladač odpoví:

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

3. Zkopírujte 32znakový řetězec `auth_token`.

Pokud okno vyprší před přijetím POST, endpoint vrátí **403 Forbidden** — znovu podržte tlačítko zapnutí/vypnutí a zkuste znovu.

> [!TIP]
> Některé formáty Essentials (žárovky, pásky) nemají fyzické tlačítko. V takovém případě spusťte párování z nastavení zařízení v aplikaci Nanoleaf — aplikace aktivuje 30sekundové okno za vás.

### 3. Import šablony v TapHome

1. V TapHome vytvořte nové PacketParser zařízení ze šablony **Nanoleaf RGB light**.
2. Zadejte IPv4 adresu ovladače jako parametr importu `ipAddress`. Port je pevný **16021** a není třeba ho měnit.
3. Otevřete vlastnosti zařízení, najděte vlastní proměnnou `authToken` a vložte 32znakový token vygenerovaný v kroku 2.
4. Uložte. Modul bude dotazovat `/api/v1/{authToken}/` každých 500 ms a naplní HSB světlo aktuálním stavem.

Pokud je token nesprávný nebo vypršel, každé čtení selže s **401 Unauthorized** v logu TapHome.

### Síťové požadavky

- Pouze odchozí **TCP 16021** z TapHome CCU k ovladači Nanoleaf. Žádné cloudové volání, žádný MQTT broker, žádné HTTPS certifikáty.
- CCU a ovladač musí být ve stejné **LAN / VLAN** síti. Pokud jsou Wi-Fi a drátové sítě oddělené, přidejte pravidlo firewallu povolující TCP 16021 mezi nimi.
- Ovladače Nanoleaf inzerují službu `_nanoleafapi._tcp` přes mDNS. Šablona vyžaduje přímou IP, ale mDNS lze použít při objevování pomocí `avahi-browse -r _nanoleafapi._tcp` (Linux) nebo `dns-sd -B _nanoleafapi._tcp` (macOS).

> [!WARNING]
> Nanoleaf Open API je **pouze HTTP** — neexistuje HTTPS ani šifrování přenosu. Je bezpečné v rámci LAN sítě, ale nikdy nesmí být vystaveno veřejnému internetu. Nepřesměrovávejte port 16021 přes router.

## Poznámky a omezení

### Rozsah teploty barvy závisí na rodině modelu

Šablona TapHome deklaruje **1800–6500 K** jako zapisovatelný rozsah CCT. Hardwarové pásmo se liší podle rodiny:

| Rodina | Hardwarový rozsah CCT | Chování mimo rozsah |
|--------|------------------------|----------------------|
| Light Panels, Shapes, Canvas, Lines | 1200–6500 K | Oříznuto firmwarem |
| Elements Hexagons | 1500–4000 K | Oříznuto firmwarem |
| Matter WiFi Essentials | 2127–6535 K | Oříznuto firmwarem; 1800 K je pod dolní hranicí 2127 K, takže Essentials oříznou na 2127 K |

Zápis hodnoty mimo fyzické pásmo zařízení nevyvolá chybu — ovladač tiše použije vlastní limit. Při návrhu dashboardů zaměřených na Essentials preferujte hodnoty CCT ve společném okně 2127–6500 K.

### Essentials odmítají jas = 0

Klasické ovladače (Light Panels, Shapes, Canvas, Elements, Lines) akceptují `brightness: 0`. **Matter WiFi Essentials** vynucují minimum **1** a odmítají `0` s HTTP 400. Pro vypnutí žárovky nebo pásku Essentials použijte kanál zapnutí/vypnutí místo nastavení jasu na nulu.

### Čtení odstínu / sytosti / CCT může vrátit NULL nebo NaN

Protože režimy `hs` a `ct` jsou vzájemně exkluzivní a oba jsou neaktivní během běžícího efektu, čtení z nesprávného režimu záměrně vrací `NULL` (odstín / sytost) nebo `NaN` (ct). Jde o očekávané chování, ne o chybu. Zápis hodnoty odstínu / sytosti / ct vrátí ovladač do režimu `hs` nebo `ct` a čtení se obnoví.

### Jeden token na ovladač, ne na panel

Vícepanelové sestavy Shapes nebo Canvas jsou jedním zařízením TapHome. Auth token je vydán na úrovni ovladače a pokrývá každý připojený panel.

### Nestabilita IPv6 mDNS na firmwaru 8.5.2+

Komunita openHAB hlásila, že IPv6 mDNS záznamy střídají stavy ONLINE a OFFLINE na některých ovladačích s firmwarem 8.5.2+. Pokud je mDNS objevování nestabilní, nastavte pevnou IPv4 DHCP rezervaci a použijte IP přímo — šablona TapHome na mDNS stejně nespoléhá.

## Řešení problémů

### 401 Unauthorized při každém čtení

`authToken` je nesprávný, vypršel nebo byl zrušen. Vygenerujte nový token (podržte tlačítko zapnutí/vypnutí 5–7 s a pošlete POST na `/api/v1/new`) a vložte ho do vlastní proměnné `authToken`.

### 403 Forbidden při generování tokenu

30sekundové párovací okno se zavřelo. Znovu podržte tlačítko zapnutí/vypnutí, dokud LED nezačne blikat vzorem, a poté ihned pošlete `POST /api/v1/new`.

### Odstín / sytost zobrazují NULL v dashboardu

Ovladač je v režimu `ct` nebo běží efekt. Zapište jakoukoliv hodnotu odstínu nebo sytosti, aby se ovladač přepnul zpět do režimu `hs`, nebo nastavte barvu pomocí HSB výběru. Šablona neumí odvodit čtení odstínu / sytosti, když zařízení takovou hodnotu neprodukuje.

### Teplota barvy se čte jako NaN

Ovladač je v režimu `hs` nebo běží efekt. Zapište hodnotu CCT, aby se přepnul do režimu `ct`, nebo nastavte teplotu barvy z dashboardu. Pokud běží efekt, zastavte ho z aplikace Nanoleaf (nebo zapište jakoukoliv hodnotu HSB / CCT — také zastaví efekt).

### Zápis jasu selhává na Essentials

Matter WiFi Essentials odmítají `brightness: 0`. Pro vypnutí použijte kanál zapnutí/vypnutí místo zápisu 0 do jasu. Hodnoty 1–100 jsou akceptovány na všech modelech.

### Ovladač se odpojuje na firmwaru 8.5.2+

Pokud TapHome CCU opakovaně ztrácí ovladač, přiřaďte statickou IPv4 DHCP rezervaci a použijte IP v parametru importu `ipAddress` — vrstva IPv6 mDNS může být na tomto větvení firmwaru nestabilní.

## Dostupná zařízení 1

Tato zařízení se po importu zobrazí v TapHome.

Nanoleaf Modul

Vlastní proměnné

`authToken` (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx 32znakový párovací token Nanoleaf Open API. Vygenerujte ho jednorázově podržením tlačítka zapnutí/vypnutí na ovladači po dobu 5–7 sekund a odesláním POST http://{ip}:16021/api/v1/new do 30 sekund — vrácený auth\_token vložte sem. Token přežije restarty a aktualizace firmwaru.

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.

Čtení (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 světlo HSB světlo Čtení i zápis

HSB světlo se dvěma barevnými režimy — odstín a sytost (0–360° / 0–100 %) nebo teplota barvy (deklarovaných 1800–6500 K, hardwarový rozsah závisí na modelu). Jas 0–100 %. Čtení odstínu / sytosti je aktivní pouze v režimu hs; čtení CCT je aktivní pouze v režimu ct; oba jsou neaktivní během běžícího efektu.

HSBLight json

Čtení (modul)

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

Čtení 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);
```

Čtení odstínu

```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 odstínu

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

Čtení saturace

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

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

Čtení barevné 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 barevné teploty

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

**Připojení:** Packet Parser → HTTP

Možná vylepšení (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.

## Parametry importu

Tyto hodnoty zadáte při importu XML.

| Ptá se v aplikaci | Výchozí       |
|-------------------|---------------|
| 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

## Související dokumentace

- [Integrace Packet Parser](https://taphome.com/cs/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/cs/docs/integration/packet-parser/)
- [Funkce Packet parser](https://taphome.com/cs/docs/script/packet-parser/)
- [Funkce pro parsování](https://taphome.com/cs/docs/script/parsing-functions/)