TapHome

Nanoleaf RGB světlo

Packet Parser → HTTP
Přidal
Poslední aktualizace: 04. 2026
Nanoleaf RGB světlo

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

ProduktKód modeluPoznámky
Light Panels (původně Aurora)NL22Bez dotyku
Shapes HexagonsNL42S dotykem
Shapes TrianglesNL47S dotykem
Shapes Mini TrianglesNL48S dotykem
Canvas (čtverce)NL29S dotykem
Elements Hexagons (dřevěný design)NL52Užší rozsah CCT (1500–4000 K)
LinesNL59S 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)

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á

1

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:

1
2
3
4

{ "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í).

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

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

colorModeVýznam
hsRežim odstínu/sytosti — hodnoty odstínu a sytosti jsou aktivní
ctRežim teploty barvy — hodnota CCT je aktivní
effectBěží 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.

Přiřaďte ovladači Nanoleaf DHCP rezervaci (nebo statickou IP), aby se adresa po obnovení nájmu neměnila. Šablona TapHome ukládá IP v parametrech importu a neaktualizuje ji automaticky.

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:

    1

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

    Ovladač odpoví:

    1

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

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

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:

RodinaHardwarový rozsah CCTChování mimo rozsah
Light Panels, Shapes, Canvas, Lines1200–6500 KOříznuto firmwarem
Elements Hexagons1500–4000 KOříznuto firmwarem
Matter WiFi Essentials2127–6535 KOří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í

Nanoleaf Modul
Vlastní proměnné
authToken (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx32znakový 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.

Nanoleaf

Čtení (modul)
#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

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

Nanoleaf RGB světlo

Čtení (modul)
var value := PARSEJSON(StatusJson, "state.on.value");
IF(ISNULL(value), NaN, IF(value, 1, 0));
Čtení jasu
var value := PARSEJSON(StatusJson, "state.brightness.value")/100;
IF(ISNULL(value), NaN, value);
Zápis jasu
var content:="{\"brightness\" : {\"value\":"+ROUND(Hb*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Čtení odstínu
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
var content:="{\"hue\" : {\"value\":"+ROUND(Hd)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Čtení saturace
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
var content:="{\"sat\" : {\"value\":"+ROUND(Sa*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Čtení barevné teploty
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
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.

Zdroje