TapHome

Yeelight

Packet Parser → TCP
Dodane przez
Ostatnia aktualizacja: 04. 2026
Yeelight

Yeelight to marka inteligentnego oświetlenia LED Wi-Fi — żarówek jednokolorowych, żarówek z regulowaną bielą i pełnokolorowych, taśm LED oraz lamp sufitowych — wydawanego przez Qingdao Yeelink (część ekosystemu Xiaomi). Każdy produkt Yeelight z obsługą LAN komunikuje się tym samym protokołem JSON-RPC Inter-Operation Protocol na porcie TCP 55443, dlatego jeden szablon TapHome obsługuje całą rodzinę produktów.

Szablon udostępnia urządzenie typu ściemniacz: jasność (0–100 %) oraz włączanie/wyłączanie z płynnymi przejściami. Aktualny tryb koloru i temperatura bieli są raportowane jako atrybuty serwisowe tylko do odczytu. TapHome komunikuje się z żarówką bezpośrednio w sieci lokalnej — po włączeniu LAN Control nie jest wymagane konto w chmurze Yeelight.

Połączenie sprzętowe

Żarówki Yeelight są zasilane ze standardowej sieci (zazwyczaj E27, E14, GU10 lub zasilacz 24 V do taśm LED — zależnie od produktu). Między TapHome a żarówką nie jest potrzebne żadne okablowanie — cała komunikacja odbywa się przez Wi-Fi. Żarówka musi znajdować się w tym samym LAN / VLAN co CCU TapHome, ponieważ protokół JSON-RPC nie używa uwierzytelniania ani szyfrowania, a ruch nigdy nie jest routowany przez chmurę Yeelight.

Protokół LAN Yeelight jest nieszyfrowany. Nie wystawiaj portu TCP 55443 do publicznego internetu i umieść żarówki w zaufanym segmencie sieci — każdy, kto ma dostęp do LAN, może wysyłać polecenia do żarówki.

Konfiguracja

Włączanie LAN Control

LAN Control (w niektórych regionach nazywany Developer Mode) jest domyślnie wyłączony w żarówce. Bez niego żarówka odrzuca połączenia TCP na porcie 55443.

  1. Otwórz aplikację mobilną Yeelight i sparuj żarówkę z lokalną siecią Wi-Fi procedurą SmartConfig / QuickConnect, jeśli jeszcze tego nie zrobiono.
  2. Wybierz docelową żarówkę w aplikacji.
  3. Dotknij ikony ustawień (prawy górny róg) i otwórz LAN Control (w niektórych wersjach firmware występuje pod nazwą Developer Mode).
  4. Przełącz LAN Control na ON.
  5. Zapisz adres IP żarówki — jest on widoczny w informacjach o urządzeniu w aplikacji Yeelight lub można go odczytać z tabeli dzierżaw DHCP routera.

Po włączeniu LAN Control żarówka nasłuchuje na porcie TCP 55443 i okresowo ogłasza się przez multicast UDP 239.255.255.250:1982.

Konfiguracja sieci
  • Adres IP — szablon TapHome nie wykrywa żarówek automatycznie. Przypisz żarówce statyczny IP lub rezerwację DHCP w routerze, aby adres nie zmienił się po odnowieniu dzierżawy.
  • Ten sam segment LAN — CCU TapHome i żarówka muszą być w tej samej domenie rozgłoszeniowej. Jeśli klienci Wi-Fi i przewodowi są w różnych VLAN-ach, dodaj regułę firewall zezwalającą na TCP 55443 między nimi.
Parametry importu

Podczas importu szablonu w TapHome użytkownik podaje trzy wartości:

ParametrOpisWartość domyślna
ipAddressAdres IP żarówki Yeelight w LAN192.168.0.1 (placeholder — zastąp rzeczywistym IP)
PortPort TCP sterowania żarówką55443
Internal poll intervalJak często szablon wysyła get_prop (w milisekundach)10000 (10 s)

Domyślny port 55443 jest standardowym portem LAN Control Yeelight i nie powinien być zmieniany, chyba że żarówka została skonfigurowana na niestandardowy port.

Między pollami szablon reaguje również na powiadomienia props, które żarówka wysyła sama przy każdej zmianie stanu. W praktyce oznacza to, że zmiany jasności lub włączenia/wyłączenia wykonane z aplikacji Yeelight, włącznika ściennego lub innej instancji Home Assistant pojawiają się w TapHome niemal natychmiast, bez czekania na kolejny poll.

Możliwości urządzenia

Ściemniacz (jasność i włącz/wyłącz)

Szablon udostępnia jedno urządzenie ściemniacza. Przy każdym pollu wysyła:

1

{"id":951,"method":"get_prop","params":["bright","power"]}

i parsuje odpowiedź result[0] (jasność 1–100, dzielona przez 100 na zakres TapHome 0.0–1.0) oraz result[1] ("on" / "off").

Zapisy są tłumaczone na dwa polecenia JSON-RPC:

  • Jeśli poziom docelowy jest większy od zera, szablon wysyła set_power ["on","smooth",300], a następnie set_bright [round(level*100),"smooth",500]. Przejście 300 ms dla zasilania i 500 ms dla jasności dają płynny fade zamiast twardego skoku.
  • Jeśli poziom docelowy wynosi zero, szablon wysyła set_power ["off","smooth",300].

Ściemniacz obsługuje również powiadomienia props wysyłane przez żarówkę (power / brightness), dlatego zewnętrzne zmiany stanu są odzwierciedlane w TapHome bez czekania na kolejny poll.

Tryb koloru i temperatura bieli (tylko do odczytu)

Dwa atrybuty serwisowe na poziomie modułu są odczytywane osobnym żądaniem get_prop (id=981):

  • Color mode — RGB, Temperature lub HSV, dekodowany z liczbowej właściwości color_mode (1 / 2 / 3) przez wyrażenie SWITCH w skrypcie listenera.
  • Color temperature — wartość w Kelvinach raportowana jako "{ct}K" (np. "4000K"). Ma sens tylko wtedy, gdy żarówka jest w trybie Temperature. Typowy, zależny od modelu zakres: 1700–6500 K dla żarówek i taśm kolorowych, 2700–6500 K dla lamp sufitowych (ceiling3 ograniczony do 6000 K).

Oba atrybuty mają charakter wyłącznie diagnostyczny — szablon nie przełącza trybu koloru i nie zapisuje nowej temperatury bieli.

Dodatkowe możliwości

Protokół LAN Yeelight oferuje również sterowanie kolorem RGB i HSV (set_rgb, set_hsv), ustawianie temperatury bieli (set_ct_abx), programy color flow (start_cf / stop_cf), predefiniowane sceny (set_scene), timery usypiania w żarówce (cron_add), sterowanie światłem tła w lampach dwuświatłowych (metody bg_*) oraz music mode (set_music, kanał reverse-TCP pomijający limit przepustowości). Żadna z tych funkcji nie jest implementowana przez obecny szablon ściemniacza TapHome — użytkownicy, którzy potrzebują pełnego koloru lub efektów, muszą rozszerzyć szablon albo równolegle korzystać z natywnej aplikacji Yeelight.

Kolor, temperaturę bieli oraz sceny można dodać w przyszłej aktualizacji szablonu na tym samym kanale TCP. Skrypty odczytu i zapisu PacketParser można rozszerzyć o set_ct_abx, set_rgb lub set_scene bez zmiany parametrów importu.

Rozwiązywanie problemów

Żarówka nie reaguje na polecenia

  1. Sprawdź, czy LAN Control jest włączony na żarówce (aplikacja Yeelight → ustawienia żarówki → LAN Control). Bez niego żarówka odrzuca wszystkie połączenia TCP na porcie 55443.

  2. Zweryfikuj adres IP żarówki w aplikacji Yeelight lub w tabeli dzierżaw DHCP routera i upewnij się, że zgadza się z parametrem importu ipAddress. Żarówki Yeelight nie utrzymują domyślnie stałego IP — dzierżawa mogła wygasnąć i adres mógł się zmienić.

  3. Przypisz żarówce statyczny IP lub rezerwację DHCP, aby adres się nie zmieniał.

  4. Sprawdź, że CCU TapHome i żarówka są w tym samym LAN / VLAN oraz że port TCP 55443 nie jest blokowany przez firewall między nimi.

  5. Przetestuj połączenie ręcznie: telnet {bulb-ip} 55443 i wyślij surowy request zakończony \r\n:

    1

    {"id":1,"method":"get_prop","params":["bright","power"]}

    Poprawnie działająca żarówka odpowie {"id":1,"result":["<bright>","<power>"]}.

Read error: client quota exceeded

Każde połączenie TCP do żarówki Yeelight jest ograniczone do 60 poleceń na minutę, a żarówka przyjmuje maksymalnie 4 jednoczesne połączenia (łącznie 144 polecenia/minutę w całej sieci LAN). Jeśli inny system odpytuje żarówkę równolegle — Home Assistant, sesja chmurowa Yeelight, własny skrypt — połączony ruch może wywołać błędy rate-limit, które TapHome zgłasza jako Read error: client quota exceeded.

  1. Wyłącz lub zwolnij inne integracje, które korzystają z tej samej żarówki.
  2. Pozostaw interwał pollingu w TapHome na domyślnej wartości 10000 ms lub wyższej. Jeden get_prop plus dwa zapisy set_* na zmianę bezpiecznie mieszczą się w limicie 60 poleceń/minutę.
  3. Zamknij nieużywane sesje debugowe telnet — liczą się one do limitu 4 połączeń.
Atrybut serwisowy Color temperature pokazuje “error”

Atrybuty Color mode i Color temperature odczytują color_mode i ct z żarówki. Jeśli jest to model mono (tylko biel), który nie obsługuje regulowanej bieli, albo żarówka jest właśnie w trybie RGB lub HSV, wartość ct nie jest sensowna i skrypt listenera raportuje Color temperature jako "error". Jest to zachowanie oczekiwane, a nie usterka.

Zmiany wprowadzone w aplikacji Yeelight nie są odzwierciedlane

Szablon reaguje na powiadomienia props wysyłane przez żarówkę, więc zmiany zewnętrzne zwykle pojawiają się w ciągu sekundy. Jeśli nie:

  1. Powiadomienie mogło dotrzeć w momencie ponownego nawiązywania połączenia TCP — kolejny poll (domyślnie 10 s) zresynchronizuje stan.
  2. Niektóre starsze wersje firmware wysyłają powiadomienia tylko po wysłaniu aktywnego polecenia. Zaktualizuj firmware żarówki z aplikacji Yeelight.
  3. Żarówka mogła osiągnąć limit 4 połączeń — zmniejsz liczbę jednoczesnych klientów w LAN.

Dostępne urządzenia

Moduł Yeelight Moduł
Atrybuty serwisowe
Tryb koloruAktywny tryb koloru raportowany przez żarówkę — RGB, Temperature (regulowana biel) lub HSV. Tylko do odczytu — szablon nie przełącza trybu koloru.
Temperatura bieliAktualny punkt bieli w Kelvinach (ważny tylko w trybie Temperature). Tylko do odczytu — szablon nie zapisuje temperatury bieli. Zakres zależny od modelu: 1700–6500 K dla kolorowych żarówek i taśm, 2700–6500 K dla lamp sufitowych.
Zmienne niestandardowe

Yeelight module

Nasłuchiwanie
VAR jsonResponse := TOSTRING(RECEIVEDBYTES);
VAR id := PARSEJSON(jsonResponse, "id", 1);

IF(id = 981)
   VAR error := PARSEJSON(jsonResponse, "error.message", 1);
   
   IF(!ISNULL(error))
      COMPLETESERVICEATTRIBUTE("Color mode", "", "error");
      COMPLETESERVICEATTRIBUTE("Color temperature", "", "error");
   ELSE
      VAR colorMode := PARSEJSON(jsonResponse, "result[0]", 1);
      VAR colorTemp := PARSEJSON(jsonResponse, "result[1]", 1);
      
      IF(!ISNULL(colorMode))
      VAR colorModeValue := SWITCH(TODOUBLE(colorMode), 1, "RGB", 2, "Temperature", 3, "HSV", "Unknown");
         COMPLETESERVICEATTRIBUTE("Color mode", colorModeValue, "");
      ELSE
         COMPLETESERVICEATTRIBUTE("Color mode", "", "error");
      END
      
      IF(!ISNULL(colorTemp))
         COMPLETESERVICEATTRIBUTE("Color temperature", colorTemp + "K", "");
      ELSE
         COMPLETESERVICEATTRIBUTE("Color temperature", "", "error");
      END
   END
END
Atrybuty serwisowe
Color mode
VAR json := "{\"id\":981, \"method\":\"get_prop\", \"params\":[\"color_mode\", \"ct\"]}";
SENDDATA(json);
Color temperature
Ściemniacz Yeelight Ściemniacz

Jasność (0–100 %) oraz włączanie/wyłączanie z płynnymi przejściami 300–500 ms. Kolor, temperatura bieli i efekty nie są udostępniane przez ten szablon.

numeric Jednostka: brightness 0–100 %
Zmienna: receiveError, Zmienna: notificationError, Zmienna: sendError

Ściemniacz Yeelight

Odczyt poziomu
VAR json := "{\"id\":951, \"method\":\"get_prop\", \"params\":[\"bright\", \"power\"]}";
SENDDATA(json);
Zapis poziomu
IF(Le > 0)
    VAR jsonPowerOn := "{\"id\":952,\"method\":\"set_power\",\"params\":[\"on\", \"smooth\", 300]}";
    SENDDATA(jsonPowerOn);

    VAR jsonBrightness := "{\"id\":953,\"method\":\"set_bright\",\"params\":[" + ROUND(Le*100) + ",\"smooth\", 500]}";
    SENDDATA(jsonBrightness);
ELSE
    VAR jsonPowerOff := "{\"id\":954,\"method\":\"set_power\",\"params\":[\"off\", \"smooth\", 300]}";
    SENDDATA(jsonPowerOff);
END
Nasłuchiwanie
VAR jsonResponse := TOSTRING(RECEIVEDBYTES);
VAR method := PARSEJSON(jsonResponse, "method", 1);
VAR id := PARSEJSON(jsonResponse, "id", 1);
STRING onOff;

IF(id = 951)
   receiveError := PARSEJSON(jsonResponse, "error.message", 1);
   
   IF(LENGTH(receiveError) = 0)
      VAR brightnessStr := PARSEJSON(jsonResponse, "result[0]", 1);
      onOff := PARSEJSON(jsonResponse, "result[1]", 1);
   
      IF(!ISNULL(brightnessStr))
         Le := TODOUBLE(brightnessStr) / 100.0;
      END
   
      IF(onOff = "on")
         St := 1;
      ELSEIF(onOff = "off")
         Le := 0;
         St := 0;
      END
   END
END

IF(id > 951 AND id < 955)
   sendError := PARSEJSON(jsonResponse, "error.message", 1);
END

IF(method = "props")
   notificationError := PARSEJSON(jsonResponse, "error.message", 1);
   
   IF(LENGTH(notificationError) = 0)
      VAR brightness := PARSEJSON(jsonResponse, "params.bright", 1);
      onOff := PARSEJSON(jsonResponse, "params.power", 1);
   
      IF(!ISNULL(brightness))
         Le := brightness / 100.0;
      END
   
      IF(onOff = "on")
         St := 1;
         IF(ISNULL(brightness))
            SENDDATA("{\"id\":951, \"method\":\"get_prop\", \"params\":[\"bright\", \"power\"]}");
         END
      ELSEIF(onOff = "off")
         Le := 0;
         St := 0;
      END
   END
END

IF(LENGTH(receiveError) > 0)
   ADDERROR("Read error: " + receiveError);
END

IF(LENGTH(sendError) > 0)
   ADDERROR("Write error: " + sendError);
END

IF(LENGTH(notificationError) > 0)
   ADDERROR(notificationError);
END
Połączenie: Packet Parser → TCP
Możliwe ulepszenia (13)
  • Set color temperature — Write color temperature (1700–6500 K, model-dependent). Color temperature is exposed as a read-only service attribute but cannot be changed from TapHome.
  • Set RGB color — Write full RGB color (0–16777215). TapHome dimmer template exposes brightness + on/off only — no color control.
  • Set HSV color — Write hue (0–359) + saturation (0–100). Not exposed by dimmer template.
  • Color flow — Scripted sequences of brightness / color / CT changes (sunrise effect, strobe, ambient cycles). Not exposed by dimmer template.
  • Set scene — Jump directly to a predefined state (color, hsv, ct, cf, auto_delay_off). Not exposed by dimmer template.
  • Toggle power — Single-parameter power toggle. Not exposed — TapHome writes explicit on/off via set_power instead.
  • Sleep timer (cron) — On-device auto-off timer in minutes. Not exposed — TapHome uses its own Smart Rules for scheduling instead.
  • Music mode — Reverse-TCP channel bypassing the 60 cmd/min rate limit. Not used by TapHome.
  • Relative adjustments — Relative +/- changes without knowing the current value. Not exposed — TapHome always writes absolute brightness.
  • Save current state as power-on default — Persist current brightness/color to flash so it survives a hard power cut. Not exposed by dimmer template.
  • Background light control — Secondary light channel on dual-light fixtures (e.g., some ceiling lights). Not exposed by dimmer template.
  • Extended state properties — Additional properties pushed via props notifications (rgb, hue, sat, flowing, delayoff, music_on, name). Template only consumes bright and power.
  • LAN auto-discovery — User must enter the bulb IP manually during import — template does not perform SSDP discovery. A static DHCP lease is strongly recommended.

Źródła