TapHome

Nanoleaf RGB svetlo

Packet Parser → HTTP
Pridal
Posledná aktualizácia: 04. 2026
Nanoleaf RGB svetlo

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

ProduktKód modeluPoznámky
Light Panels (pôvodne Aurora)NL22Bez dotyku
Shapes HexagonsNL42S dotykom
Shapes TrianglesNL47S dotykom
Shapes Mini TrianglesNL48S dotykom
Canvas (štvorce)NL29S dotykom
Elements Hexagons (drevený dizajn)NL52Užší rozsah CCT (1500–4000 K)
LinesNL59S 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)

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

1

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

1
2
3
4

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

Rozlišovanie farebných režimov

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

colorModeVýznam
hsRežim odtieňa/sýtosti — hodnoty odtieňa a sýtosti sú aktívne
ctRežim farebnej teploty — hodnota CCT je aktívna
effectBeží 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.

Priraďte ovládaču Nanoleaf DHCP rezerváciu (alebo statickú IP), aby sa adresa po obnovení nájmu nemenila. TapHome šablóna ukladá IP v parametroch importu a neaktualizuje ju automaticky.

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:

    1

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

    Ovládač odpovie:

    1

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

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

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:

RodinaHardvérový rozsah CCTSprávanie mimo rozsahu
Light Panels, Shapes, Canvas, Lines1200–6500 KOrezané firmvérom
Elements Hexagons1500–4000 KOrezané firmvérom
Matter WiFi Essentials2127–6535 KOrezané 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

Nanoleaf Modul
Vlastné premenné
authToken (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx32-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.

Nanoleaf

Čítanie (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 svetlo HSB svetlo

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

Nanoleaf RGB svetlo

Čítanie (modul)
var value := PARSEJSON(StatusJson, "state.on.value");
IF(ISNULL(value), NaN, IF(value, 1, 0));
Čítanie 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);
Čítanie odtieňa
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
var content:="{\"hue\" : {\"value\":"+ROUND(Hd)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Čítanie saturácie
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
var content:="{\"sat\" : {\"value\":"+ROUND(Sa*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Čítanie farebnej 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 farebnej teploty
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.

Zdroje