Yeelight Color

Packet Parser → TCP

Inviato da

Ultimo aggiornamento: 06. 2026

Il template Yeelight Color estende il template solo dimmer Yeelight con il controllo colore HSB completo e il bianco regolabile (temperatura colore). Si rivolge alla stessa famiglia di LED smart Wi-Fi — lampadine a colori, strisce e plafoniere — utilizzando l’identico Yeelight Inter-Operation Protocol sulla porta TCP 55443. La differenza principale è il modello dispositivo: anziché un semplice dimmer, il template espone un PacketParserHSBLight, che fornisce a TapHome proprietà native di tonalità, saturazione, luminosità e temperatura colore in un unico dispositivo.

TapHome comunica con la lampadina direttamente sulla rete locale tramite JSON-RPC — non è necessaria alcuna connessione cloud una volta abilitato il LAN Control sulla lampadina. Il template interroga tutte e sei le proprietà colore contemporaneamente e reagisce alle notifiche props inviate dalla lampadina, quindi le modifiche effettuate dall’app Yeelight o da un altro controller appaiono in TapHome quasi istantaneamente.

Collegamento hardware

Le lampadine Yeelight sono alimentate dalla rete standard (tipicamente E27, E14, GU10 o alimentatore 24 V per strisce LED a seconda del prodotto). Non è necessario alcun cablaggio tra TapHome e la lampadina — tutta la comunicazione avviene tramite Wi-Fi. La lampadina deve essere nella stessa LAN / VLAN del TapHome CCU, poiché il protocollo JSON-RPC non ha autenticazione né crittografia e il traffico non passa mai attraverso il cloud Yeelight.

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

Configurazione

Abilitazione LAN Control

Il LAN Control (in alcune regioni chiamato Developer Mode) �� disabilitato di default sulla lampadina. Senza di esso, le connessioni TCP sulla porta 55443 vengono rifiutate.

Aprire l’app mobile Yeelight e associare la lampadina alla rete Wi-Fi locale con la procedura SmartConfig / QuickConnect se non è ancora stata associata.
Selezionare la lampadina di destinazione nell’app.
Toccare l’icona impostazioni (in alto a destra) e aprire LAN Control (in alcune versioni firmware etichettato come Developer Mode).
Attivare LAN Control su ON.
Annotare l’indirizzo IP della lampadina — è mostrato nelle informazioni dispositivo dell’app Yeelight o può essere letto dalla tabella DHCP lease del router.

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

Configurazione di rete

Indirizzo IP — il template TapHome non rileva automaticamente le lampadine. Assegnare un IP statico o una prenotazione DHCP nel router affinché l’indirizzo della lampadina non cambi dopo il rinnovo del lease.
Stesso segmento LAN — il TapHome CCU e la lampadina devono essere nello stesso dominio broadcast. Se i client Wi-Fi e cablati sono in VLAN separate, aggiungere una regola firewall che consenta TCP 55443 tra di essi.

Parametri di importazione

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

Parametro	Descrizione	Predefinito
`ipAddress`	Indirizzo IP della lampadina Yeelight nella LAN	`192.168.0.1` (segnaposto — sostituire con IP reale)
`Port`	Porta TCP di controllo sulla lampadina	`55443`
`Internal poll interval`	Frequenza di invio `get_prop` (in millisecondi)	`10000` (10 s)

La porta predefinita 55443 è la porta standard Yeelight LAN Control e non dovrebbe essere modificata a meno che la lampadina non sia configurata su una porta non standard.

Tra un polling e l’altro, il template reagisce anche alle notifiche props che la lampadina invia quando cambia stato. In pratica questo significa che le modifiche di colore, luminosità e on/off effettuate dall’app Yeelight, da un adattatore interruttore a muro o da un altro controller appaiono in TapHome quasi istantaneamente, senza attendere il prossimo poll.

Capacità del dispositivo

Luce HSB a colori (tonalità, saturazione, luminosità e on/off)

Il template espone un singolo dispositivo luce HSB. Ad ogni ciclo di polling invia una richiesta get_prop per tutte e sei le proprietà contemporaneamente:

1
{"id":951,"method":"get_prop","params":["hue","sat","bright","power","ct","color_mode"]}

Lo script listener analizza la risposta e la mappa sulle proprietà native TapHome:

Hue (Hd) — result[0], intero 0–359 gradi
Saturation (Sa) — result[1], percentuale 0–100, divisa per 100 nell’intervallo TapHome 0,0–1,0
Brightness (Hb) — result[2], percentuale 1–100, divisa per 100 nell’intervallo TapHome 0,0–1,0
Power (St) — result[3], "on" mappato a 1, "off" mappato a 0 (la luminosità è impostata a 0 anche quando spento)
Color temperature (Ct) — result[4], valore in Kelvin impostato solo quando color_mode = 2 (modalità bianca); impostato a NaN altrimenti
Color mode — result[5], determina se Ct viene scritto (1 = RGB, 2 = Temperature, 3 = HSV)

Commutazione modalità colore

Il template usa la proprietà Ct per determinare la modalità colore attiva:

Ct = NaN — la lampadina è in modalità colore HSV. Le scritture usano set_hsv per tonalità e saturazione.
Ct = numero — la lampadina è in modalità bianca (temperatura colore). Le scritture usano set_ct_abx.

TapHome non invia un comando esplicito di cambio modalità. Invece, l’utente imposta la temperatura colore su un valore numerico per entrare in modalità bianca, o la imposta su NaN (scegliendo un colore nel selettore HSB) per entrare in modalità HSV. Gli script di scrittura controllano Ct prima dell’invio e saltano il comando irrilevante — writesaturation ritorna immediatamente se Ct non è NaN, e writecct ritorna immediatamente se Ct è NaN.

Comandi di scrittura

Tre script di scrittura gestiscono diversi aspetti della luce:

Luminosità / alimentazione (writebrightness) — se luminosità > 0, invia set_power ["on","smooth",300] seguito da set_bright [livello,"smooth",300]. Se luminosità = 0, invia set_power ["off","smooth",300].
Tonalità e saturazione (writesaturation) — invia set_power ["on","smooth",300] seguito da set_hsv [tonalità, saturazione,"smooth",300]. Si esegue solo quando Ct = NaN (modalità HSV).
Temperatura colore (writecct) — invia set_power ["on","smooth",300] seguito da set_ct_abx [ct,"smooth",300]. Si esegue solo quando Ct è un numero (modalità bianca). Intervallo valido: 1700–6500 K (limiti esatti dipendono dal modello della lampadina).

Tutte le scritture usano una transizione smooth di 300 ms per una dissolvenza morbida anziché un salto netto. Dopo ogni scrittura, la variabile debounce è impostata a 1, causando il salto del ciclo di polling successivo — questo evita la lettura di stati obsoleti durante la transizione della lampadina.

Diagnostica dei servizi

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

Modalità colore — RGB, Temperature o HSV, decodificata dalla proprietà numerica color_mode (1 / 2 / 3) usando un’espressione SWITCH nello script listener del modulo.
Temperatura colore — valore in Kelvin riportato come "{ct}K" (ad esempio "4000K"). Significativo solo quando la lampadina è in modalità Temperature.

Questi attributi sono diagnostica di sola lettura — il controllo effettivo della temperatura colore avviene tramite la proprietà Ct a livello dispositivo e lo script writecct descritto sopra.

Risoluzione dei problemi

La lampadina non risponde ai comandi

Verificare che il LAN Control sia abilitato sulla lampadina (app Yeelight → impostazioni lampadina → LAN Control). Senza di esso, la lampadina rifiuta tutte le connessioni TCP sulla porta 55443.
Confermare l’IP della lampadina nell’app Yeelight o nella tabella DHCP lease del router, e assicurarsi che corrisponda al parametro di importazione ipAddress. Le lampadine Yeelight non mantengono un IP fisso di default — il lease potrebbe essere scaduto e l’IP cambiato.
Assegnare alla lampadina un IP statico o una prenotazione DHCP per evitare il cambio di indirizzo.
Verificare che TapHome CCU e la lampadina siano nella stessa LAN / VLAN e che TCP 55443 non sia bloccato da un firewall tra di essi.
Testare la connettività manualmente: telnet {bulb-ip} 55443 e inviare una richiesta raw seguita da \r\n:
1
{"id":1,"method":"get_prop","params":["hue","sat","bright","power","ct","color_mode"]}
Una lampadina funzionante risponde con {"id":1,"result":["<hue>","<sat>","<bright>","<power>","<ct>","<color_mode>"]}.

I comandi colore vengono ignorati (tonalità/saturazione non cambiano)

Lo script writesaturation controlla Ct prima di inviare set_hsv. Se Ct è impostato su un valore numerico (modalità bianca), lo script ritorna senza inviare alcun comando. Per controllare il colore HSV, impostare prima la temperatura colore su NaN selezionando un colore nel selettore HSB di TapHome.

Analogamente, writecct ritorna senza inviare se Ct = NaN (modalità HSV). Per scrivere una temperatura colore, la lampadina deve già essere in modalità bianca.

Errore di lettura: client quota exceeded

Ogni connessione TCP a una lampadina Yeelight è limitata a 60 comandi al minuto, e la lampadina accetta al massimo 4 connessioni simultanee in totale. Se un altro sistema interroga la lampadina contemporaneamente — Home Assistant, una sessione cloud Yeelight, uno script personalizzato — il traffico combinato può attivare errori di rate limit.

Disattivare o rallentare le altre integrazioni che condividono la lampadina.
Mantenere l’intervallo di polling TapHome ai 10000 ms predefiniti o superiori. Il template colore invia un get_prop per poll più fino a tre scritture set_* per modifica, restando ben sotto la quota di 60 cmd/min.
Chiudere le sessioni debug telnet inutilizzate — contano nel limite di 4 connessioni.

Errore di scrittura HueSat o temperatura colore

Lo script listener traccia gli errori di scrittura separatamente per ogni tipo di comando — writeErrorBrightness per le scritture di alimentazione/luminosità, writeErrorHueSat per le scritture set_hsv e writeErrorCt per le scritture set_ct_abx. Se appare un errore:

Confermare che la lampadina è accesa — tutti i comandi set_* tranne set_power sono accettati solo quando la lampadina è nello stato on.
Verificare che il valore della temperatura colore sia nell’intervallo specifico del modello (tipicamente 1700–6500 K per lampadine a colori, 2700–6500 K per plafoniere, 2700–6000 K per ceiling3).
Controllare il messaggio di errore raw nella diagnostica servizi TapHome per il codice di errore specifico restituito dalla lampadina.

Le modifiche nell’app Yeelight non si riflettono

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

La notifica potrebbe essere arrivata durante il ristabilimento del socket TCP — il prossimo poll (predefinito 10 s) risincronizzerà lo stato.
Alcune versioni firmware meno recenti inviano notifiche solo quando un comando viene attivamente inviato. Aggiornare il firmware della lampadina dall’app Yeelight.
La lampadina potrebbe aver raggiunto il limite di 4 connessioni — ridurre il numero di client simultanei nella LAN.

I dispositivi Yeelight supportano solo 4 connessioni TCP simultanee e 60 comandi al minuto per connessione. Se TapHome e un altro sistema (es. Home Assistant) interrogano la stessa lampadina contemporaneamente, la comunicazione potrebbe diventare inaffidabile. Utilizzare un intervallo di polling di 10 secondi o superiore.

Dispositivi disponibili

Modulo Yeelight color Modulo

Attributi di servizio

Modalità colore	Modalità colore corrente della lampadina — RGB, Temperature o HSV — decodificata dalla proprietà color_mode
Temperatura colore	Temperatura colore in Kelvin, riportata solo quando la lampadina è in modalità Temperature (color_mode=2)

Yeelight color 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);

RETURN(NULL);

Color temperature

Luce HSB Luce HSB

Luce HSB a colori con supporto temperatura colore — controlla tonalità, saturazione, luminosità e on/off tramite set_hsv, set_ct_abx e set_bright con transizioni smooth

numeric Unità: hue 0-359, sat/bright 0-100 %, CCT 2700-6500 K

Luce HSB

Lettura (modulo)

IF(debounce > 0)
    debounce := 0;
ELSE
    VAR json := "{\"id\":951, \"method\":\"get_prop\", \"params\":[\"hue\", \"sat\", \"bright\", \"power\", \"ct\", \"color_mode\"]}";
    SENDDATA(json);
END

Listener

VAR jsonResponse := TOSTRING(RECEIVEDBYTES);
VAR method := PARSEJSON(jsonResponse, "method", 1);
VAR id := PARSEJSON(jsonResponse, "id", 1);
VAR error := PARSEJSON(jsonResponse, "error.message", 1);

#response to ReadScript
IF(id = 951)
   receiveError1 := error;
   
   IF(LENGTH(receiveError1) = 0)
      VAR hueStr := PARSEJSON(jsonResponse, "result[0]", 1);
      VAR satStr := PARSEJSON(jsonResponse, "result[1]", 1);
      VAR brightnessStr := PARSEJSON(jsonResponse, "result[2]", 1);
      VAR onOffStr := PARSEJSON(jsonResponse, "result[3]", 1);
      VAR ctStr := PARSEJSON(jsonResponse, "result[4]", 1);
      VAR colorModeStr := PARSEJSON(jsonResponse, "result[5]", 1);
      
      IF(!ISNULL(hueStr))
         Hd := TODOUBLE(hueStr);
      END

      IF(!ISNULL(satStr))
        Sa := TODOUBLE(satStr) / 100.0;
      END
      
      IF(!ISNULL(brightnessStr))
        Hb := TODOUBLE(brightnessStr) / 100.0;
      END
   
      VAR cm := TODOUBLE(colorModeStr);
      IF(!ISNULL(ctStr) AND cm = 2)
        Ct := TODOUBLE(ctStr);
      ELSE
        Ct := NaN;
      END
      
      IF(onOffStr = "on")
         St := 1;
      ELSEIF(onOffStr = "off")
         Hb := 0;
         St := 0;
      END
   END
ELSEIF(id = 952)
   receiveError2 := error;
   
   IF(LENGTH(receiveError2) = 0)
      brightnessStr := PARSEJSON(jsonResponse, "result[0]", 1);
      
      IF(!ISNULL(brightnessStr))
        Hb := TODOUBLE(brightnessStr) / 100.0;
      END
   END
END

IF(id >= 941 AND id <= 942)
   writeErrorBrightness := error;
ELSEIF(id = 943)
   writeErrorHueSat := error;
ELSEIF(id = 944)
   writeErrorCt := error;
END

#general notification
IF(method = "props")
   notificationError := error;
   
   IF(LENGTH(notificationError) = 0)
      VAR brightJson := PARSEJSON(jsonResponse, "params.bright", 1);
      VAR onOffJson := PARSEJSON(jsonResponse, "params.power", 1);
      VAR hue := PARSEJSON(jsonResponse, "params.hue", 1);
      VAR sat := PARSEJSON(jsonResponse, "params.sat", 1);
      VAR colorMode := PARSEJSON(jsonResponse, "params.color_mode", 1);
      VAR ctJson := PARSEJSON(jsonResponse, "params.ct", 1);
      
      IF(!ISNULL(brightJson))
         Hb := brightJson / 100.0;
      END
      
      IF(!ISNULL(hue))
         Hd := hue;
         Ct := NaN;
      END      

      IF(!ISNULL(sat))
        Sa := sat / 100;
        Ct := NaN;
      END 
      
      IF(!ISNULL(ctJson))
        Ct := ctJson;
      END 
      
      IF(onOffJson = "on")
         St := 1;
         IF(ISNULL(brightJson))
            SENDDATA("{\"id\":952, \"method\":\"get_prop\", \"params\":[\"bright\"]}");
         END
      ELSEIF(onOffJson = "off")
         Hb := 0;
         St := 0;
      END
   END
END

IF(LENGTH(receiveError1) > 0)
   ADDERROR(951, "Read error: " + receiveError1);
END

IF(LENGTH(receiveError2) > 0)
   ADDERROR(952, "Read error: " + receiveError2);
END

IF(LENGTH(writeErrorBrightness) > 0)
   ADDERROR(941, "Brightness write error: " + writeErrorBrightness);
END

IF(LENGTH(writeErrorHueSat) > 0)
   ADDERROR(943, "HueSat write error: " + writeErrorHueSat);
END

IF(LENGTH(writeErrorCt) > 0)
   ADDERROR(944, "Color temperature write error: " + writeErrorCt);
END

IF(LENGTH(notificationError) > 0)
   ADDERROR(1, notificationError);
END

Scrittura luminosità

IF(Hb > 0)
    VAR jsonBrightness := "{\"id\":941,\"method\":\"set_power\",\"params\":[\"on\", \"smooth\", 300]}\r\n{\"id\":942,\"method\":\"set_bright\",\"params\":[" + ROUND(Hb*100) + ",\"smooth\", 300]}";
    SENDDATA(jsonBrightness);
ELSE
    VAR jsonPowerOff := "{\"id\":942,\"method\":\"set_power\",\"params\":[\"off\", \"smooth\", 300]}";
    SENDDATA(jsonPowerOff);
END

debounce := 1;

Scrittura saturazione

#do not send HUESAT when COLOR mode is active
IF !ISNAN(Ct)
    RETURN(0);
END

VAR hueSatJson := "{\"id\":941,\"method\":\"set_power\",\"params\":[\"on\", \"smooth\", 300]}\r\n{\"id\":943,\"method\":\"set_hsv\",\"params\":[" + ROUND(MOD(Hd, 360)) + ", " + ROUND(Sa*100) + ", \"smooth\", 300]}";

SENDDATA(hueSatJson);
debounce := 1;

Scrittura temperatura colore

#do not set CT in COLOR mode
IF ISNAN(Ct)
    RETURN(0);
END

VAR ctJson := "{\"id\":941,\"method\":\"set_power\",\"params\":[\"on\", \"smooth\", 300]}\r\n{\"id\":944,\"method\":\"set_ct_abx\",\"params\":[" + Ct + ", \"smooth\", 300]}";
SENDDATA(ctJson);

debounce := 1;

Connessione: Packet Parser → TCP

Possibili miglioramenti (12)

Set RGB color — Write full RGB color (0-16777215). Template uses set_hsv instead, which maps naturally to the HSBLight device model.
Color flow — Scripted sequences of brightness / color / CT changes (sunrise effect, strobe, ambient cycles). Not exposed by this template.
Set scene — Jump directly to a predefined state (color, hsv, ct, cf, auto_delay_off). Not exposed by this 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 values.
Save current state as power-on default — Persist current brightness/color to flash so it survives a hard power cut. Not exposed by this template.
Set device name — Set device name (max 64 bytes). Not exposed by this template.
Background light control — Secondary light channel on dual-light fixtures (e.g., some ceiling lights). Not exposed by this template.
Extended notification properties — Additional properties pushed via props notifications. Template consumes hue, sat, bright, power, color_mode and ct — remaining properties (rgb, flowing, delayoff, music_on, name) are ignored.
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.

Scarica template

Fonti

Yeelight WiFi Light Inter-Operation Specification
www.yeelight.com 2026-04-15
Yeelight Developer — Third-party Control Protocol
www.yeelight.com 2026-04-15
python-yeelight library documentation
yeelight.readthedocs.io 2026-04-15

Hai trovato un problema con questo template?

Dicci cosa non funziona, cosa manca o come dovrebbe comportarsi il template. Il tuo feedback ci aiuta a mantenere il catalogo accurato.

Verificato da TapHome

Vuoi usarlo nel tuo TapHome Core?

Apri questo template nel Customer Portal per applicarlo a una delle tue case, o crea una proposta di modifica e inviala al catalogo.

Apri nel portale