TapHome

Nanoleaf RGB lámpa

Packet Parser → HTTP
Beküldő
Utoljára frissítve: 04. 2026
Nanoleaf RGB lámpa

A Nanoleaf egy Wi-Fi LED világítástermék-család — moduláris fali panelek, LED szalagok, izzók, állólámpák és ünnepi fényfüzérek — amelyek mindegyike ugyanazt a helyi REST API-t használja a TCP 16021 porton. Egyetlen TapHome sablon lefedi minden WiFi-n elérhető Nanoleaf terméket: a TapHome HTTP-n keresztül lekérdezi a vezérlőt a LAN-on, és az egész elrendezést egyetlen HSB lámpaként teszi elérhetővé színhőmérséklettel.

Támogatott modellek

TermékModellkódMegjegyzések
Light Panels (korábban Aurora)NL22Érintés nélkül
Shapes HexagonsNL42Érintésérzékeny
Shapes TrianglesNL47Érintésérzékeny
Shapes Mini TrianglesNL48Érintésérzékeny
Canvas (négyzetek)NL29Érintésérzékeny
Elements Hexagons (fa hatású)NL52Szűkebb CCT tartomány (1500–4000 K)
LinesNL59Érintésérzékeny
Matter WiFi Essentials (izzók, LED szalagok, ünnepi fényfüzérek, állólámpa, A19)—Csak 3.0.10+ firmware; szigorúbb fényerő alsó határ és szűkebb CCT tartomány (2127–6535 K)

A kizárólag Thread protokollos Nanoleaf Essentials változatok és a Nanoleaf Skylight nem támogatottak — a sablon olyan WiFi-n elérhető vezérlőt igényel, amely az Open API-t a 16021 porton beszéli.

Eszközfunkciók

Lámpa (HSB + színhőmérséklet)

A sablon egyetlen HSB lámpát tesz elérhetővé be/ki kapcsolás, fényerő, színárnyalat, telítettség és színhőmérséklet funkciókkal. Minden lekérdezési ciklusban (500 ms) a modul a következőt küldi:

1

GET /api/v1/{authToken}/

és a teljes eszköz-JSON-t a StatusJson egyéni változóban tárolja. Az egyes tulajdonságokhoz tartozó olvasási szkriptek ezután a gyorsítótárazott objektumból olvassák ki a mezőket:

  • Be/ki — state.on.value
  • Fényerő — state.brightness.value (0–100), a TapHome 0,0–1,0 tartományára normalizálva
  • Színárnyalat — state.hue.value (0–360°) — csak akkor olvasható, ha state.colorMode == "hs"
  • Telítettség — state.sat.value (0–100) — csak akkor olvasható, ha state.colorMode == "hs"
  • Színhőmérséklet — state.ct.value (Kelvinben) — csak akkor olvasható, ha state.colorMode == "ct"

Minden írás a PUT /api/v1/{authToken}/state végpontra megy, tulajdonságonkénti JSON törzzsel:

1
2
3
4

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

A sablon 1800–6500 K tartományt deklarál a színhőmérsékletre — ez gyakorlati részhalmaza annak, amit a hardver valóban támogat. Az eszköz fizikai tartományán kívüli értékeket a Nanoleaf firmware csendben levágja (lásd Megjegyzések és korlátozások).

Színmód-kapuzás

A Nanoleaf vezérlők mindig pontosan a három színmód egyikében vannak:

colorModeJelentés
hsSzínárnyalat/telítettség mód — a színárnyalat és telítettség értékek aktívak
ctSzínhőmérséklet mód — a CCT érték aktív
effectDinamikus jelenet fut

A TapHome olvasási szkriptjei figyelembe veszik ezt: a színárnyalat és telítettség olvasások NULL értéket adnak vissza, ha a vezérlő ct vagy effect módban van, a színhőmérséklet olvasás pedig NaN értéket ad vissza, ha hs vagy effect módban van. Ez megakadályozza, hogy elavult, más módból származó értékek kerüljenek a dashboard-ra. Bármely színárnyalat vagy telítettség érték írása a vezérlőt hs módba kapcsolja, CCT érték írása pedig ct módba — mindkettő leállítja a futó effektet.

Konfiguráció

1. A vezérlő párosítása a Nanoleaf alkalmazásban

Szerelje fel a paneleket / izzót / szalagot, telepítse a Nanoleaf mobilalkalmazást, és csatlakoztassa a vezérlőt a helyi Wi-Fi hálózathoz az alkalmazás párosítási folyamatán keresztül. Jegyezze fel a vezérlő IPv4 címét — az alkalmazás az eszközbeállítások → Info alatt mutatja, vagy kiolvasható a router DHCP bérleti tábláján.

Rendeljen a Nanoleaf vezérlőhöz DHCP foglalást (vagy statikus IP-t), hogy a cím ne változzon a bérlet megújítása után. A TapHome sablon az IP-t az importparaméterekben tárolja, és nem fedezi fel automatikusan.

2. Open API token generálása

A Nanoleaf Open API egyszeri párosítást igényel a TapHome és a vezérlő között. A párosítás létrehoz egy állandó 32 karakteres auth_token-t, amely túléli az újraindításokat és firmware frissítéseket.

  1. A Nanoleaf vezérlőn (a panelek esetén a kis inline egység, izzók / szalagok esetén maga az eszköz) tartsa lenyomva a be-/kikapcsoló gombot 5–7 másodpercig, amíg a fehér LED mintázatban villogni nem kezd. Az eszköz 30 másodpercig párosítási módban van.

  2. A 30 másodperces ablakon belül küldjön egy üres POST kérést a párosítási végpontra — például curl, PowerShell vagy Postman segítségével:

    1

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

    A vezérlő így válaszol:

    1

    { "auth_token": "xxxKJISJCjY2hfAyilpyIOfGixxxx" }

  3. Másolja ki a 32 karakteres auth_token karakterláncot.

Ha az ablak a POST megérkezése előtt lejár, a végpont 403 Forbidden választ ad — tartsa lenyomva újra a be-/kikapcsoló gombot, és próbálja meg ismét.

Egyes Essentials kivitelek (izzók, szalagok) nem rendelkeznek fizikai gombbal. Ebben az esetben indítsa el a párosítást a Nanoleaf alkalmazás eszközbeállításaiból — az alkalmazás aktiválja a 30 másodperces ablakot Ön helyett.

3. A sablon importálása a TapHome-ba
  1. A TapHome-ban hozzon létre egy új PacketParser eszközt a Nanoleaf RGB light sablonból.
  2. Adja meg a vezérlő IPv4 címét az ipAddress importparaméterként. A port rögzítve 16021, nem kell módosítani.
  3. Nyissa meg az eszköz tulajdonságait, keresse meg az authToken egyéni változót, és illessze be a 2. lépésben generált 32 karakteres tokent.
  4. Mentés. A modul 500 ms-onként lekérdezi a /api/v1/{authToken}/ végpontot, és feltölti a HSB lámpát az aktuális állapottal.

Ha a token hibás vagy lejárt, minden olvasás 401 Unauthorized hibával végződik a TapHome naplóban.

Hálózati követelmények
  • Csak kimenő TCP 16021 a TapHome CCU-tól a Nanoleaf vezérlőig. Nincsenek felhőhívások, MQTT bróker, HTTPS tanúsítványok.
  • A CCU-nak és a vezérlőnek ugyanazon a LAN / VLAN hálózaton kell lennie. Ha a Wi-Fi és a vezetékes hálózat szegregált, adjon hozzá tűzfalszabályt, amely engedélyezi a TCP 16021-et közöttük.
  • A Nanoleaf vezérlők a _nanoleafapi._tcp szolgáltatást hirdetik mDNS-en keresztül. A sablon közvetlen IP-t igényel, de az mDNS felderítésre használható az avahi-browse -r _nanoleafapi._tcp (Linux) vagy dns-sd -B _nanoleafapi._tcp (macOS) paranccsal.

A Nanoleaf Open API csak HTTP — nincs HTTPS és nincs átviteli titkosítás. LAN-on belül biztonságos, de soha nem szabad kitenni a nyilvános internetre. Ne továbbítsa a 16021 portot a routeren keresztül.

Megjegyzések és korlátozások

A színhőmérséklet tartománya a modellcsaládtól függ

A TapHome sablon 1800–6500 K értéket deklarál írható CCT tartományként. A mögöttes hardveres sáv családonként eltérő:

CsaládHardveres CCT tartományViselkedés a tartományon kívül
Light Panels, Shapes, Canvas, Lines1200–6500 KFirmware által levágva
Elements Hexagons1500–4000 KFirmware által levágva
Matter WiFi Essentials2127–6535 KFirmware által levágva; 1800 K az alsó 2127 K határ alatt van, tehát az Essentials 2127 K-ra vág

Az eszköz fizikai sávján kívüli érték írása nem okoz hibát — a vezérlő csendben a saját határértékét használja. Az Essentials-t célzó dashboard-ok tervezésekor részesítse előnyben a közös 2127–6500 K ablakba eső CCT értékeket.

Az Essentials elutasítja a fényerő = 0 értéket

A klasszikus vezérlők (Light Panels, Shapes, Canvas, Elements, Lines) elfogadják a brightness: 0 értéket. A Matter WiFi Essentials minimum 1 értéket vár el, és a 0-t HTTP 400-zal utasítja el. Egy Essentials izzó vagy szalag kikapcsolásához használja a be/ki csatornát ahelyett, hogy a fényerőt nullára állítaná.

A színárnyalat / telítettség / CCT olvasások NULL vagy NaN értéket adhatnak vissza

Mivel a hs és ct módok kölcsönösen kizárják egymást, és mindkettő inaktív futó effekt alatt, a rossz módból történő olvasások szándékosan NULL (színárnyalat / telítettség) vagy NaN (ct) értéket adnak vissza. Ez várt viselkedés, nem hiba. A színárnyalat / telítettség / ct írása visszaállítja a vezérlőt hs vagy ct módba, és az olvasások folytatódnak.

Egy token vezérlőnként, nem panelként

Egy többpaneles Shapes vagy Canvas elrendezés egyetlen TapHome eszköz. Az auth token vezérlő szinten kerül kiadásra, és lefedi az ahhoz csatlakoztatott minden panelt.

IPv6 mDNS instabilitás 8.5.2+ firmware-en

Az openHAB közösség jelentette, hogy az IPv6 mDNS rekordok ONLINE és OFFLINE állapotok között váltakoznak egyes 8.5.2+ firmware-ű vezérlőkön. Ha az mDNS felderítés instabil, állítson be fix IPv4 DHCP foglalást, és használja közvetlenül az IP-t — a TapHome sablon amúgy sem támaszkodik mDNS-re.

Hibaelhárítás

401 Unauthorized minden olvasásnál

Az authToken hibás, lejárt vagy visszavonásra került. Hozzon létre új tokent (tartsa lenyomva a be-/kikapcsoló gombot 5–7 másodpercig, és küldjön POST kérést a /api/v1/new végpontra), és illessze be az authToken egyéni változóba.

403 Forbidden token generálásakor

A 30 másodperces párosítási ablak bezárult. Tartsa lenyomva újra a be-/kikapcsoló gombot, amíg a LED mintázatban villogni nem kezd, majd azonnal küldjön POST /api/v1/new kérést.

A színárnyalat / telítettség NULL értéket mutat a dashboard-on

A vezérlő ct módban van, vagy effekt fut. Írjon be bármilyen színárnyalat vagy telítettség értéket, hogy a vezérlő visszaváltson hs módba, vagy állítsa be a színt a HSB választóval. A sablon nem tud színárnyalat / telítettség értéket leolvasni, ha az eszköz nem állít elő ilyet.

A színhőmérséklet NaN értéket olvas

A vezérlő hs módban van, vagy effekt fut. Írjon be CCT értéket a ct módra váltáshoz, vagy állítson be színhőmérsékletet a dashboard-ról. Ha effekt fut, állítsa le a Nanoleaf alkalmazásból (vagy írjon be bármilyen HSB / CCT értéket — ez is leállítja az effektet).

A fényerő-írás meghiúsul az Essentials-en

A Matter WiFi Essentials elutasítja a brightness: 0 értéket. Kikapcsoláshoz vezérelje a be/ki csatornát, ne a fényerőt írja 0-ra. Az 1–100 értékek minden modellen elfogadottak.

A vezérlő lekapcsolódik a 8.5.2+ firmware-en

Ha a TapHome CCU ismételten elveszíti a vezérlőt, rendeljen statikus IPv4 DHCP foglalást, és használja az IP-t az ipAddress importparaméterben — az IPv6 mDNS réteg instabil lehet ezen a firmware-ágon.

Elérhető eszközök

Nanoleaf Modul
Egyéni változók
authToken (string) = xxxKJISJCjY2hfAyilpyIOfGixxxx32 karakteres Nanoleaf Open API párosítási token. Generálja egyszer a vezérlő be-/kikapcsoló gombjának 5–7 másodpercig történő nyomva tartásával, és küldjön POST http://{ip}:16021/api/v1/new kérést 30 másodpercen belül — a visszakapott auth_token értéket illessze be ide. A token túléli az újraindításokat és a firmware-frissítéseket.
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

Olvasás (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 lámpa HSB lámpa

HSB lámpa kettős színmóddal — színárnyalat és telítettség (0–360° / 0–100 %), vagy színhőmérséklet (deklarált 1800–6500 K, a hardveres tartomány modellfüggő). Fényerő 0–100 %. A színárnyalat / telítettség olvasások csak hs módban aktívak; a CCT olvasások csak ct módban aktívak; mindkettő inaktív futó effekt alatt.

HSBLight json

Nanoleaf RGB lámpa

Olvasás (modul)
var value := PARSEJSON(StatusJson, "state.on.value");
IF(ISNULL(value), NaN, IF(value, 1, 0));
Fényerő olvasása
var value := PARSEJSON(StatusJson, "state.brightness.value")/100;
IF(ISNULL(value), NaN, value);
Fényerő írása
var content:="{\"brightness\" : {\"value\":"+ROUND(Hb*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Színárnyalat olvasása
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
Színárnyalat írása
var content:="{\"hue\" : {\"value\":"+ROUND(Hd)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Telítettség olvasása
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
Telítettség írása
var content:="{\"sat\" : {\"value\":"+ROUND(Sa*100)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Színhőmérséklet olvasása
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
Színhőmérséklet írása
var content:="{\"ct\" : {\"value\":"+ROUND(Ct)+"}}";
var response := SENDHTTPREQUEST("/api/v1/"+authToken+"/state", "PUT", content);
Kapcsolat: Packet Parser → HTTP
Lehetséges fejlesztések (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.

Források