TapHome

Yeelight

Packet Parser → TCP
Inviato da
Ultimo aggiornamento: 04. 2026
Yeelight

Yeelight è un marchio di illuminazione LED Wi-Fi smart — lampadine a colore singolo, a bianco regolabile e a colori completi, strisce LED e plafoniere — prodotto da Qingdao Yeelink (parte dell’ecosistema Xiaomi). Ogni prodotto Yeelight compatibile con LAN usa lo stesso protocollo JSON-RPC Inter-Operation Protocol sulla porta TCP 55443, quindi un unico template TapHome copre l’intera famiglia di prodotti.

Il template espone un dispositivo dimmer: luminosità (0–100 %) e controllo on/off con transizioni smooth. La modalità colore e la temperatura colore correnti vengono riportate come attributi di servizio in sola lettura. TapHome comunica con la lampadina direttamente sulla rete locale — una volta abilitato LAN Control sulla lampadina, non serve alcun account cloud Yeelight.

Collegamento hardware

Le lampadine Yeelight sono alimentate dalla rete elettrica standard (tipicamente E27, E14, GU10 o alimentatore 24 V per le strisce, a seconda del prodotto). Tra TapHome e la lampadina non serve alcun cablaggio — tutta la comunicazione passa via Wi-Fi. La lampadina deve trovarsi sulla stessa LAN / VLAN della CCU TapHome, perché il protocollo JSON-RPC non usa autenticazione né cifratura e il traffico non viene mai instradato attraverso il cloud Yeelight.

Il protocollo LAN di Yeelight non è cifrato. Non esporre la porta TCP 55443 a internet pubblico e posiziona le lampadine su un segmento di rete affidabile — chiunque abbia accesso alla LAN può inviare comandi alla lampadina.

Configurazione

Abilitare LAN Control

LAN Control (in alcune regioni chiamato Developer Mode) è disabilitato di default sulla lampadina. Senza di esso la lampadina rifiuta le connessioni TCP sulla porta 55443.

  1. Apri l’app Yeelight e accoppia la lampadina alla rete Wi-Fi locale tramite la procedura SmartConfig / QuickConnect, se non è ancora accoppiata.
  2. Seleziona la lampadina di destinazione nell’app.
  3. Tocca l’icona delle impostazioni (in alto a destra) e apri LAN Control (in alcune versioni firmware chiamato Developer Mode).
  4. Imposta LAN Control su ON.
  5. Annota l’indirizzo IP della lampadina — è visibile nelle informazioni dispositivo dell’app Yeelight o può essere letto dalla tabella lease DHCP del router.

Una volta abilitato LAN Control, la lampadina ascolta sulla porta TCP 55443 e si annuncia periodicamente via UDP multicast 239.255.255.250:1982.

Configurazione di rete
  • Indirizzo IP — il template TapHome non individua automaticamente le lampadine. Assegna alla lampadina un IP statico o una riservazione DHCP nel router, in modo che l’indirizzo non cambi dopo il rinnovo del lease.
  • Stesso segmento LAN — la CCU TapHome e la lampadina devono trovarsi nello stesso dominio broadcast. Se i client Wi-Fi e cablati sono su VLAN separate, aggiungi una regola firewall che permetta TCP 55443 tra le due.
Parametri di import

Durante l’import del template in TapHome l’utente inserisce tre valori:

ParametroDescrizioneDefault
ipAddressIndirizzo IP della lampadina Yeelight sulla LAN192.168.0.1 (placeholder — sostituisci con l’IP reale)
PortPorta TCP di controllo della lampadina55443
Internal poll intervalOgni quanto il template invia get_prop (in millisecondi)10000 (10 s)

La porta di default 55443 è la porta standard LAN Control di Yeelight e non va cambiata, salvo che la lampadina sia configurata su una porta non standard.

Tra un poll e l’altro il template reagisce anche alle notifiche props che la lampadina invia spontaneamente a ogni cambio di stato. In pratica significa che le modifiche a luminosità o on/off fatte dall’app Yeelight, da un interruttore fisico o da un’altra istanza Home Assistant compaiono in TapHome quasi istantaneamente, senza attendere il poll successivo.

Capacità del dispositivo

Dimmer (luminosità e on/off)

Il template espone un singolo dispositivo dimmer. A ogni poll invia:

1

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

e interpreta la risposta result[0] (luminosità 1–100, divisa per 100 per l’intervallo TapHome 0.0–1.0) e result[1] ("on" / "off").

Le scritture vengono tradotte in due comandi JSON-RPC:

  • Se il livello target è maggiore di zero, il template invia set_power ["on","smooth",300] seguito da set_bright [round(level*100),"smooth",500]. La transizione di 300 ms per l’accensione e di 500 ms per la luminosità dà un fade morbido al posto di un salto brusco.
  • Se il livello target è zero, il template invia set_power ["off","smooth",300].

Il dimmer consuma anche le notifiche props inviate dalla lampadina (power / brightness), così i cambi di stato esterni vengono riflessi in TapHome senza attendere il poll successivo.

Modalità colore e temperatura colore (sola lettura)

Due attributi di servizio a livello modulo vengono letti con una richiesta get_prop separata (id=981):

  • Color mode — RGB, Temperature o HSV, decodificato dalla proprietà numerica color_mode (1 / 2 / 3) tramite un’espressione SWITCH nel listener script.
  • Color temperature — valore in Kelvin riportato come "{ct}K" (ad esempio "4000K"). Significativo solo quando la lampadina è in modalità Temperature. Intervallo tipico in base al modello: 1700–6500 K per lampadine a colori e strisce, 2700–6500 K per plafoniere (ceiling3 arriva fino a 6000 K).

Entrambi gli attributi sono puramente diagnostici — il template non cambia la modalità colore e non scrive una nuova temperatura colore.

Capacità aggiuntive

Il protocollo LAN di Yeelight offre anche il controllo del colore RGB e HSV (set_rgb, set_hsv), l’impostazione della temperatura colore (set_ct_abx), i programmi di color flow (start_cf / stop_cf), scene predefinite (set_scene), timer di spegnimento sulla lampadina (cron_add), controllo della luce di sfondo sui corpi a doppia luce (metodi bg_*) e music mode (set_music, un canale TCP inverso che aggira il rate limit). Nessuna di queste funzioni è implementata dal template dimmer TapHome attuale — chi desidera il colore completo o gli effetti deve estendere il template o usare in parallelo l’app Yeelight nativa.

Colore, temperatura colore e scene possono essere aggiunti in un futuro aggiornamento del template sullo stesso canale TCP. Gli script di lettura e scrittura PacketParser possono essere estesi con set_ct_abx, set_rgb o set_scene senza modificare i parametri di import.

Risoluzione dei problemi

La lampadina non risponde ai comandi

  1. Verifica che LAN Control sia abilitato sulla lampadina (app Yeelight → impostazioni lampadina → LAN Control). Senza questa impostazione la lampadina rifiuta tutte le connessioni TCP sulla porta 55443.

  2. Conferma l’IP della lampadina nell’app Yeelight o nella tabella lease DHCP del router e assicurati che corrisponda al parametro di import ipAddress. Le lampadine Yeelight non mantengono un IP fisso di default — il lease può essere scaduto e l’indirizzo potrebbe essere cambiato.

  3. Assegna alla lampadina un IP statico o una riservazione DHCP per evitare che l’indirizzo vari.

  4. Controlla che la CCU TapHome e la lampadina siano sulla stessa LAN / VLAN e che la porta TCP 55443 non sia bloccata da un firewall tra le due.

  5. Prova la connessione manualmente: telnet {bulb-ip} 55443 e invia una richiesta grezza terminata con \r\n:

    1

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

    Una lampadina valida risponde con {"id":1,"result":["<bright>","<power>"]}.

Read error: client quota exceeded

Ogni connessione TCP verso una lampadina Yeelight è limitata a 60 comandi al minuto, e la lampadina accetta al massimo 4 connessioni simultanee in totale (144 comandi/minuto sull’intera LAN). Se un altro sistema interroga la lampadina nello stesso tempo — Home Assistant, una sessione cloud Yeelight, uno script personalizzato — il traffico combinato può innescare errori di rate limit segnalati in TapHome come Read error: client quota exceeded.

  1. Disattiva o rallenta le altre integrazioni che usano la stessa lampadina.
  2. Mantieni l’intervallo di poll di TapHome al valore di default di 10000 ms o superiore. Un get_prop più due scritture set_* per ogni cambio restano ampiamente sotto la quota di 60 comandi/minuto.
  3. Chiudi le sessioni telnet di debug inutilizzate — contano anch’esse sul limite di 4 connessioni.
L’attributo di servizio Color temperature mostra “error”

Gli attributi Color mode e Color temperature leggono color_mode e ct dalla lampadina. Se si tratta di un modello mono (solo bianco) che non supporta il bianco regolabile, o se la lampadina è in modalità RGB o HSV, il valore ct non è significativo e il listener script riporta Color temperature come "error". È un comportamento atteso, non un malfunzionamento.

Le modifiche fatte nell’app Yeelight non si riflettono

Il template reagisce alle notifiche props inviate dalla lampadina, quindi le modifiche esterne compaiono normalmente entro un secondo. Se non accade:

  1. La notifica potrebbe essere arrivata mentre il socket TCP veniva ricreato — il poll successivo (default 10 s) risincronizza lo stato.
  2. Alcune versioni firmware più vecchie inviano notifiche solo quando viene inviato un comando attivo. Aggiorna il firmware della lampadina tramite l’app Yeelight.
  3. La lampadina potrebbe aver raggiunto il limite di 4 connessioni — riduci il numero di client simultanei sulla LAN.

Dispositivi disponibili

Modulo Yeelight Modulo
Attributi di servizio
Modalità coloreModalità colore attiva riportata dalla lampadina — RGB, Temperature (bianco regolabile) o HSV. Sola lettura — il template non cambia la modalità colore.
Temperatura colorePunto di bianco corrente in Kelvin (valido solo in modalità Temperature). Sola lettura — il template non scrive la temperatura colore. Intervallo dipendente dal modello: 1700–6500 K per lampadine e strisce a colori, 2700–6500 K per plafoniere.
Variabili personalizzate

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

Luminosità (0–100 %) e controllo on/off con transizioni smooth 300–500 ms. Colore, temperatura colore ed effetti non sono esposti da questo template.

numeric Unità: brightness 0–100 %
Variabile: receiveError, Variabile: notificationError, Variabile: sendError

Dimmer Yeelight

Lettura livello
VAR json := "{\"id\":951, \"method\":\"get_prop\", \"params\":[\"bright\", \"power\"]}";
SENDDATA(json);
Scrittura livello
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
Connessione: Packet Parser → TCP
Possibili miglioramenti (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.

Fonti