TapHome

Yeelight

Packet Parser → TCP
Eingereicht von
Zuletzt aktualisiert: 04. 2026
Yeelight

Yeelight ist eine Marke für Wi-Fi Smart-LED-Beleuchtung — einfarbige Lampen, Tunable-White- und RGB-Lampen, LED-Streifen sowie Deckenleuchten — herausgegeben von Qingdao Yeelink (Teil des Xiaomi-Ökosystems). Jedes LAN-fähige Yeelight-Produkt spricht dasselbe JSON-RPC Inter-Operation Protocol auf TCP-Port 55443, daher deckt eine einzige TapHome-Vorlage die gesamte Produktfamilie ab.

Die Vorlage stellt ein Dimmer-Gerät bereit: Helligkeit (0–100 %) und Ein-/Aus-Steuerung mit weichen Übergängen. Der aktuelle Farbmodus und die Farbtemperatur werden als schreibgeschützte Service-Attribute gemeldet. TapHome kommuniziert direkt über das lokale Netzwerk mit der Lampe — sobald LAN Control aktiviert ist, wird kein Yeelight-Cloud-Konto benötigt.

Hardware-Anschluss

Yeelight-Lampen werden aus dem normalen Stromnetz versorgt (typischerweise E27, E14, GU10 oder 24-V-Netzteil für Streifen — je nach Produkt). Zwischen TapHome und Lampe ist keine Verkabelung erforderlich — die gesamte Kommunikation läuft über Wi-Fi. Die Lampe muss im selben LAN / VLAN wie die TapHome-CCU sein, da das JSON-RPC-Protokoll weder Authentifizierung noch Verschlüsselung verwendet und der Datenverkehr nie über die Yeelight-Cloud geroutet wird.

Das Yeelight-LAN-Protokoll ist unverschlüsselt. TCP-Port 55443 niemals ins öffentliche Internet exponieren und die Lampen in einem vertrauenswürdigen Netzsegment betreiben — jeder mit LAN-Zugang kann Befehle an die Lampe senden.

Konfiguration

LAN Control aktivieren

LAN Control (in manchen Regionen Developer Mode genannt) ist an der Lampe standardmäßig deaktiviert. Ohne diese Einstellung lehnt die Lampe alle TCP-Verbindungen auf Port 55443 ab.

  1. Öffne die Yeelight-App und koppele die Lampe per SmartConfig / QuickConnect mit dem lokalen Wi-Fi, falls dies noch nicht geschehen ist.
  2. Wähle in der App die Ziel-Lampe aus.
  3. Tippe auf das Einstellungssymbol (oben rechts) und öffne LAN Control (in einigen Firmware-Versionen Developer Mode).
  4. Schalte LAN Control auf EIN.
  5. Notiere die IP-Adresse der Lampe — sie wird in den Geräteinformationen der Yeelight-App angezeigt oder kann aus der DHCP-Lease-Tabelle des Routers abgelesen werden.

Sobald LAN Control aktiviert ist, lauscht die Lampe auf TCP-Port 55443 und kündigt sich periodisch per UDP-Multicast 239.255.255.250:1982 an.

Netzwerk-Konfiguration
  • IP-Adresse — die TapHome-Vorlage findet Lampen nicht automatisch. Weise der Lampe im Router eine statische IP oder eine DHCP-Reservierung zu, damit sich die Adresse nach einer Lease-Erneuerung nicht ändert.
  • Gleiches LAN-Segment — TapHome-CCU und Lampe müssen in derselben Broadcast-Domäne sein. Liegen Wi-Fi- und kabelgebundene Clients in verschiedenen VLANs, füge eine Firewall-Regel hinzu, die TCP 55443 zwischen ihnen erlaubt.
Import-Parameter

Beim Importieren der Vorlage in TapHome werden drei Werte abgefragt:

ParameterBeschreibungStandard
ipAddressIP-Adresse der Yeelight-Lampe im LAN192.168.0.1 (Platzhalter — durch echte IP ersetzen)
PortTCP-Steuerport der Lampe55443
Internal poll intervalWie oft die Vorlage get_prop sendet (in Millisekunden)10000 (10 s)

Der Standardport 55443 ist der übliche Yeelight-LAN-Control-Port und sollte nicht geändert werden, außer die Lampe wurde auf einen abweichenden Port konfiguriert.

Zwischen den Polls reagiert die Vorlage auch auf props-Notifications, die die Lampe bei jeder Zustandsänderung selbständig aussendet. Praktisch bedeutet das: Änderungen an Helligkeit oder Ein/Aus über die Yeelight-App, einen Wandschalter oder eine andere Home-Assistant-Instanz erscheinen in TapHome nahezu sofort, ohne den nächsten Poll abzuwarten.

Gerätefunktionen

Dimmer (Helligkeit und Ein/Aus)

Die Vorlage stellt ein einzelnes Dimmer-Gerät bereit. Bei jedem Poll sendet sie:

1

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

und wertet result[0] (Helligkeit 1–100, geteilt durch 100 in den TapHome-Bereich 0.0–1.0) sowie result[1] ("on" / "off") aus.

Schreibvorgänge werden in zwei JSON-RPC-Befehle übersetzt:

  • Ist der Zielwert größer als null, sendet die Vorlage set_power ["on","smooth",300] gefolgt von set_bright [round(level*100),"smooth",500]. Der 300-ms-Einschaltübergang und der 500-ms-Helligkeitsübergang erzeugen einen weichen Fade statt eines harten Sprungs.
  • Ist der Zielwert null, sendet die Vorlage set_power ["off","smooth",300].

Der Dimmer verarbeitet außerdem die von der Lampe gesendeten props-Notifications (Power / Brightness), so dass externe Zustandsänderungen ohne Warten auf den nächsten Poll in TapHome erscheinen.

Farbmodus und Farbtemperatur (nur Lesen)

Zwei Service-Attribute auf Modulebene werden über einen separaten get_prop-Request (id=981) gelesen:

  • Color mode — RGB, Temperature oder HSV, dekodiert aus der numerischen Eigenschaft color_mode (1 / 2 / 3) per SWITCH-Ausdruck im Listener-Skript.
  • Color temperature — Kelvin-Wert im Format "{ct}K" (zum Beispiel "4000K"). Nur aussagekräftig, wenn die Lampe im Temperature-Modus arbeitet. Typischer modellabhängiger Bereich: 1700–6500 K für Farblampen und -streifen, 2700–6500 K für Deckenleuchten (ceiling3 ist auf 6000 K begrenzt).

Beide Attribute sind rein diagnostisch — die Vorlage schaltet den Farbmodus nicht um und schreibt keine neue Farbtemperatur.

Weitere Funktionen

Das Yeelight-LAN-Protokoll bietet außerdem RGB- und HSV-Farbsteuerung (set_rgb, set_hsv), Farbtemperatur-Steuerung (set_ct_abx), Color-Flow-Programme (start_cf / stop_cf), vordefinierte Szenen (set_scene), geräteinterne Sleep-Timer (cron_add), Hintergrundlicht-Steuerung bei Doppelleuchten (bg_*-Methoden) sowie Music Mode (set_music, ein Reverse-TCP-Kanal, der das Rate-Limit umgeht). Keine dieser Funktionen ist in der aktuellen TapHome-Dimmer-Vorlage implementiert — wer volle Farbe oder Effekte benötigt, muss die Vorlage erweitern oder parallel die native Yeelight-App nutzen.

Farbe, Farbtemperatur und Szenen lassen sich in einer künftigen Vorlagen-Aktualisierung über denselben TCP-Kanal ergänzen. Die PacketParser Read-/Write-Skripte lassen sich um set_ct_abx, set_rgb oder set_scene erweitern, ohne die Import-Parameter zu verändern.

Fehlerbehebung

Lampe reagiert nicht auf Befehle

  1. Prüfe, ob LAN Control an der Lampe aktiviert ist (Yeelight-App → Lampeneinstellungen → LAN Control). Ohne diese Einstellung lehnt die Lampe alle TCP-Verbindungen auf Port 55443 ab.

  2. Kontrolliere die IP-Adresse der Lampe in der Yeelight-App oder in der DHCP-Lease-Tabelle des Routers und stelle sicher, dass sie mit dem Import-Parameter ipAddress übereinstimmt. Yeelight-Lampen haben standardmäßig keine feste IP — der Lease kann abgelaufen und die Adresse gewechselt sein.

  3. Vergib der Lampe eine statische IP oder eine DHCP-Reservierung, damit die Adresse stabil bleibt.

  4. Prüfe, dass TapHome-CCU und Lampe im selben LAN / VLAN sind und TCP 55443 dazwischen nicht durch eine Firewall blockiert wird.

  5. Teste die Verbindung manuell: telnet {bulb-ip} 55443 und sende einen rohen Request mit \r\n als Abschluss:

    1

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

    Eine funktionsfähige Lampe antwortet mit {"id":1,"result":["<bright>","<power>"]}.

Read error: client quota exceeded

Jede TCP-Verbindung zu einer Yeelight-Lampe ist auf 60 Befehle pro Minute begrenzt, und die Lampe akzeptiert insgesamt maximal 4 gleichzeitige Verbindungen (144 Befehle/Minute im gesamten LAN). Wenn ein weiteres System die Lampe zeitgleich pollt — Home Assistant, eine Yeelight-Cloud-Session, ein eigenes Skript — kann der kombinierte Verkehr Rate-Limit-Fehler auslösen, die in TapHome als Read error: client quota exceeded gemeldet werden.

  1. Deaktiviere oder verlangsame andere Integrationen, die dieselbe Lampe verwenden.
  2. Belasse das Poll-Intervall in TapHome auf dem Standardwert von 10000 ms oder höher. Ein get_prop plus zwei set_*-Schreibvorgänge pro Änderung bleiben zuverlässig unter dem 60-Befehle/Minute-Kontingent.
  3. Schließe ungenutzte telnet-Debug-Sessions — sie zählen zum Limit von 4 Verbindungen.
Service-Attribut Color temperature zeigt “error”

Die Service-Attribute Color mode und Color temperature lesen color_mode und ct aus der Lampe. Handelt es sich um ein Mono-Modell (nur Weiß) ohne Tunable-White, oder arbeitet die Lampe im RGB- oder HSV-Modus, ist der ct-Wert nicht aussagekräftig und das Listener-Skript meldet Color temperature als "error". Das ist erwartetes Verhalten und kein Fehler.

Änderungen in der Yeelight-App werden nicht reflektiert

Die Vorlage reagiert auf von der Lampe gesendete props-Notifications, externe Änderungen erscheinen daher normalerweise innerhalb einer Sekunde. Falls nicht:

  1. Die Notification kann eingetroffen sein, während der TCP-Socket neu aufgebaut wurde — der nächste Poll (Standard 10 s) synchronisiert wieder.
  2. Einige ältere Firmware-Versionen senden Notifications nur, wenn aktiv ein Befehl abgesetzt wurde. Aktualisiere die Lampen-Firmware über die Yeelight-App.
  3. Die Lampe kann das 4-Verbindungen-Limit erreicht haben — reduziere die Anzahl gleichzeitiger Clients im LAN.

Verfügbare Geräte

Yeelight-Modul Modul
Serviceattribute
FarbmodusAktiver Farbmodus, den die Lampe meldet — RGB, Temperature (Tunable White) oder HSV. Nur lesend — die Vorlage wechselt den Farbmodus nicht.
FarbtemperaturAktueller Weißpunkt in Kelvin (nur im Temperature-Modus gültig). Nur lesend — die Vorlage schreibt keine Farbtemperatur. Modellabhängiger Bereich: 1700–6500 K für Farblampen und Streifen, 2700–6500 K für Deckenleuchten.
Benutzerdefinierte Variablen

Yeelight module

Listener
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
Serviceattribute
Color mode
VAR json := "{\"id\":981, \"method\":\"get_prop\", \"params\":[\"color_mode\", \"ct\"]}";
SENDDATA(json);
Color temperature
Yeelight-Dimmer Dimmer

Helligkeit (0–100 %) und Ein/Aus mit weichen Übergängen von 300–500 ms. Farbe, Farbtemperatur und Effekte werden von dieser Vorlage nicht bereitgestellt.

numeric Einheit: brightness 0–100 %
Variable: receiveError, Variable: notificationError, Variable: sendError

Yeelight-Dimmer

Level lesen
VAR json := "{\"id\":951, \"method\":\"get_prop\", \"params\":[\"bright\", \"power\"]}";
SENDDATA(json);
Level schreiben
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
Listener
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
Verbindung: Packet Parser → TCP
Mögliche Verbesserungen (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.

Quellen