TapHome

Shelly DUO

Packet Parser → HTTP
Inviato da
Ultimo aggiornamento: 03. 2026
Shelly DUO

Lo Shelly DUO è una lampadina LED Wi-Fi con attacco E27 che supporta la regolazione della luminosità e la temperatura colore del bianco regolabile (CCT) nel range da 2700 K (bianco caldo) a 6500 K (luce diurna). TapHome si integra con la lampadina localmente via Wi-Fi utilizzando l’API REST HTTP o MQTT. Non è necessaria alcuna connessione cloud.

Sono disponibili due template TapHome: un template HTTP per una singola lampadina e un template MQTT che può controllare fino a 5 lampadine DUO tramite una singola connessione broker MQTT. Entrambi i template espongono gli stessi tipi di dispositivo per lampadina — un dispositivo luce con controllo luminosità e CCT e un contatore elettrico per il monitoraggio della potenza.

Configurazione

Template HTTP

Il template HTTP richiede l’indirizzo IP della lampadina (o l’hostname mDNS ShellyBulbDuo-{MAC}.local). TapHome interroga l’endpoint /status ogni 2,5 secondi e memorizza la risposta JSON nella variabile personalizzata jsonStatus. I singoli script dispositivo analizzano la risposta memorizzata senza effettuare chiamate HTTP ridondanti.

Il template accetta due parametri di importazione:

  • Indirizzo IP — l’IP locale della lampadina (predefinito 192.168.0.1)
  • Tempo di transizione — durata della transizione luminosa in millisecondi (predefinito 300 ms)
Template MQTT

Il template MQTT richiede l’IP del broker, la porta e il Device ID per ogni lampadina (formato: ShellyBulbDuo-DEVICEID). Il Device ID si trova nell’interfaccia web Shelly in Settings > Device Info, oppure tramite GET http://{bulb-ip}/settings nel campo mqtt.id.

Il template supporta fino a 5 lampadine DUO tramite un singolo modulo. Ogni lampadina è identificata dalla propria variabile topic (bulb1topic fino a bulb5topic). Gli slot lampadina non utilizzati possono essere lasciati al valore placeholder predefinito.

Il template accetta tre parametri di importazione:

  • MQTT Broker IP — l’indirizzo del broker (predefinito 192.168.0.1)
  • MQTT Broker port — la porta del broker (predefinita 1883)
  • Tempo di transizione — durata della transizione luminosa in millisecondi (predefinito 300 ms)

Sui dispositivi Shelly Gen1, l’abilitazione di MQTT disabilita Shelly Cloud. Entrambi non possono funzionare simultaneamente.

Funzionalità del dispositivo

Controllo luce

Il template espone il DUO come dispositivo luce bianca con due parametri controllabili:

  • Luminosità — letta da lights[0].brightness (0–100, convertita internamente in 0,0–1,0) e lights[0].ison; controllata tramite /light/0?turn=on|off&brightness=N (HTTP) o pubblicando JSON nel topic light/0/set (MQTT)
  • Temperatura colore — letta da lights[0].temp (2700–6500 K); controllata tramite /light/0?temp=K (HTTP) o il campo temp nel payload JSON (MQTT)

Entrambi i parametri vengono inviati insieme in un singolo comando di scrittura. Il parametro tempo di transizione controlla la durata della dissolvenza per tutte le modifiche.

Quando la luce viene spenta (luminosità impostata a 0), il template invia turn=off (HTTP) o pubblica off nel topic light/0/command (MQTT).

Meccanismo di debounce

Il template HTTP include una protezione debounce per prevenire letture obsolete durante le transizioni luminose. Dopo ogni comando di scrittura, il template ignora le letture /status per la durata del tempo di transizione più 500 ms. Durante questo periodo, gli script di lettura restituiscono gli ultimi valori noti invece di interrogare il dispositivo. Questo previene la breve visualizzazione di stati intermedi nell’interfaccia mentre la lampadina sta transitando.

Il template MQTT non necessita di debounce — riceve aggiornamenti di stato direttamente dalla lampadina quando si verificano.

Misurazione potenza

Il contatore energetico integrato legge due valori:

  • Potenza istantanea — meters[0].power in watt, convertita in kW (divisa per 1000)
  • Consumo totale — meters[0].total in watt-minuti, convertito in kWh (diviso per 60 000)

Il contatore è in sola lettura e si aggiorna automaticamente ad ogni ciclo di polling (HTTP) o ad ogni messaggio MQTT.

Per abilitare il monitoraggio della potenza, il modello del dispositivo deve essere configurato nell’app Shelly o nel browser web in Settings > Device Model. Se la lampadina è accesa ma la potenza mostra zero, il template visualizza un avviso su questo passaggio di configurazione.

Diagnostica di servizio (template HTTP)

Il template HTTP espone 10 attributi di servizio:

  • Info rete — indirizzo IP, indirizzo MAC (formattato con separatori a due punti), intensità segnale Wi-Fi (dB)
  • Connettività — cloud abilitato/connesso, MQTT connesso
  • Info dispositivo — ora dispositivo, tempo di attività (formattato come giorni/ore/minuti), utilizzo RAM
  • Firmware — aggiornamento firmware disponibile
Azioni di servizio (template HTTP)

Sono disponibili due azioni di servizio:

  • Abilita cloud — abilita o disabilita la connettività Shelly Cloud
  • Riavvio — avvia un riavvio del dispositivo
Funzionalità aggiuntive

Lo Shelly DUO espone anche un timer luce (flag attivo e secondi rimanenti), un timer di spegnimento automatico sull’endpoint luce, temperatura interna del dispositivo, intensità del segnale Wi-Fi come dispositivo sensore autonomo e un topic MQTT online/offline LWT per il rilevamento dello stato di connessione. Queste funzionalità potranno essere aggiunte in un futuro aggiornamento del template.

Risoluzione dei problemi

La lampadina non risponde (HTTP)
  1. Verificare che il DUO sia connesso al Wi-Fi e abbia un indirizzo IP valido
  2. Provare a usare l’hostname mDNS (ShellyBulbDuo-AABBCCDDEE.local) invece dell’indirizzo IP — l’IP potrebbe essere cambiato dopo un rinnovo DHCP
  3. Aprire http://{bulb-ip}/shelly nel browser — se risponde con un JSON contenente "type":"SHBDUO-1", la lampadina è raggiungibile
  4. Verificare che TapHome CCU e DUO siano sulla stessa rete / VLAN
La potenza mostra zero
  1. Confermare che il modello dispositivo è configurato nell’app Shelly (Settings > Device Model)
  2. Verificare che la lampadina sia accesa — il contatore misura solo quando scorre corrente
  3. Interrogare /status manualmente e verificare che meters[0].power restituisca un valore diverso da zero
La lampadina MQTT non risponde
  1. Verificare che MQTT sia abilitato nell’interfaccia web Shelly (Internet & Security > Advanced — MQTT)
  2. Confermare che indirizzo broker e porta siano corretti sia nel dispositivo Shelly che nelle impostazioni modulo TapHome
  3. Verificare che la variabile personalizzata bulbNtopic corrisponda esattamente al Device ID della lampadina (es. ShellyBulbDuo-B929CC)
  4. Utilizzare un client MQTT (es. MQTT Explorer) per iscriversi a shellies/# e verificare che la lampadina pubblichi messaggi
Le transizioni luminose appaiono a scatti
  1. Aumentare il parametro tempo di transizione — i 300 ms predefiniti potrebbero essere troppo brevi per grandi variazioni di luminosità
  2. Se si usa HTTP, assicurarsi che nessun altro sistema interroghi la lampadina contemporaneamente — i dispositivi Gen1 supportano solo 2 connessioni simultanee

I dispositivi Shelly Gen1 supportano solo 2 connessioni HTTP simultanee. Se TapHome e un altro sistema (es. Home Assistant) interrogano lo stesso dispositivo contemporaneamente, la comunicazione potrebbe diventare inaffidabile. Considerare il passaggio al template MQTT per ambienti con più sistemi.

Come installare in TapHome

Prerequisiti

  • Dispositivo Shelly installato e acceso
  • Rete Wi-Fi locale (2,4 GHz)
  • TapHome CCU sulla stessa rete

Passaggio 1 — Collegare Shelly al Wi-Fi

Opzione A — App Shelly (consigliata):

  1. Scarica l’app Shelly (iOS / Android)
  2. Tocca + → Add Device e segui la procedura guidata di associazione Bluetooth
  3. Inserisci le credenziali Wi-Fi quando richiesto

Opzione B — Modalità AP (senza app):

  1. Al primo avvio il dispositivo crea un hotspot: ShellyXXX-AABBCCDDEE
  2. Collega il tuo telefono/PC a questo hotspot
  3. Apri http://192.168.33.1 → Internet & Security → Wi-Fi Mode - Client
  4. Inserisci SSID e password → Save

Shelly supporta solo reti a 2,4 GHz. Le reti a 5 GHz non appariranno nella scansione.

Passaggio 2 — Trovare l’indirizzo IP

Dopo la connessione al Wi-Fi, trova l’indirizzo IP assegnato tramite uno di questi metodi:

  • App Shelly: Dettaglio dispositivo → Device info → Indirizzo IP
  • Interfaccia web Shelly: Connettiti all’AP del dispositivo prima della configurazione Wi-Fi — l’IP viene mostrato dopo il salvataggio
  • Tabella DHCP del router: Cerca un hostname come shelly1pm-AABBCCDDEE
  • mDNS: Esegui il ping di shelly<model>-<mac>.local (es. shelly1pm-AABBCCDDEE.local) dalla stessa rete

Assegna un IP statico (prenotazione DHCP) nel tuo router per il dispositivo Shelly per evitare che l’indirizzo cambi dopo un riavvio del router.

Passaggio 3 — Configurazione in TapHome

  1. In TapHome, aggiungi un nuovo modulo Packet Parser (HTTP)
  2. IP Address: inserisci l’IP dal passaggio 2 (es. 192.168.1.50)
  3. Port: 80 (predefinito, nessuna modifica necessaria)
  4. Importa il template — TapHome interrogherà periodicamente /status per leggere lo stato del dispositivo

L’autenticazione HTTP è disabilitata per impostazione predefinita sui dispositivi Shelly. Se hai abilitato la protezione con accesso, TapHome attualmente non supporta HTTP Basic Auth — mantieni l’autenticazione disabilitata per l’integrazione con TapHome.

Dispositivi disponibili

Shelly DUO Modulo
Attributi di servizio
Indirizzo IP
Indirizzo MAC
Segnale WiFi
Cloud abilitato
Cloud connesso
MQTT connesso
Ora del dispositivo
Aggiornamento FW disponibile
Tempo di attività
RAM
Azioni di servizio
Abilita cloud
Riavvio
Variabili personalizzate
transitionTime (numeric) = TransitionTimeLight transition duration in milliseconds (import parameter, default 300 ms)

Shelly DUO Module

Lettura (modulo)
VAR now := NOW();

IF now.Ticks < debounceTimestamp
    RETURN(0);
END

VAR response := SENDHTTPREQUEST("/status");

IF response.IsSuccess
    jsonStatus := response.Content;
ELSE
    jsonStatus := NULL;
END
Attributi di servizio
IP Address
VAR response := SENDHTTPREQUEST("/status");

IF response.IsSuccess
    jsonStatus := response.Content;
ELSE
    jsonStatus := NULL;
END

VAR address := PARSEJSON(jsonStatus, "$.wifi_sta.ip", 1);
IF (ISNULL(address), "-", address)
MAC Address
VAR value := PARSEJSON(jsonStatus, "$.mac", 1);
IF ISNULL(value)
    RETURN("-");
END;

STRING mac;
INT i := 0;
INT len := LENGTH(value);

WHILE i < len
    mac += GETAT(value, i);
    i += 1;
    
    IF MOD(i, 2) = 0 AND i < len
        mac += ":";
    END
LOOP

mac
WIFI signal
VAR signal := PARSEJSON(jsonStatus, "$.wifi_sta.rssi", 1);
IF (ISNULL(signal), "-", signal + "db");
Cloud enabled
VAR value := PARSEJSON(jsonStatus, "$.cloud.enabled", 1);
IF (ISNULL(value), "-", value)
Cloud connected
VAR value := PARSEJSON(jsonStatus, "$.cloud.connected", 1);
IF (ISNULL(value), "-", value)
MQTT connected
VAR value := PARSEJSON(jsonStatus, "$.mqtt.connected", 1);
IF (ISNULL(value), "-", value)
Device time
VAR value := PARSEJSON(jsonStatus, "$.time", 1);
IF (ISNULL(value), "-", value)
FW update available
VAR value := PARSEJSON(jsonStatus, "$.has_update");
IF (ISNULL(value), "-", value)
Uptime
VAR value := PARSEJSON(jsonStatus, "$.uptime", 1);
IF ISNULL(value)
    RETURN("-");
END

VAR days := FLOOR(value/86400, 1);
value := MOD(value, 86400);
VAR hours := FLOOR(value/3600, 1);
value := MOD(value, 3600);
VAR minutes := FLOOR(value/60, 1);

days + "day(s) " + hours + "h " + minutes + "m"
RAM
VAR ramFree := PARSEJSON(jsonStatus, "$.ram_free", 1);
VAR ramTotal := PARSEJSON(jsonStatus, "$.ram_total", 1);

IF ISNULL(ramFree) OR ISNULL(ramTotal)
    RETURN("-");
END

ramFree + " bytes free of " + ramTotal
Azioni di servizio
Enable cloud
Parametri: Enable (Enable / Disable)
VAR response := SENDHTTPREQUEST("/settings/cloud?enabled=" + enable);
VAR contentJson := response.Content;
VAR wasEnabled := PARSEJSON(contentJson, "enabled");

IF(wasEnabled, "Cloud enabled", "Cloud disabled");
Reboot
VAR response := SENDHTTPREQUEST("/reboot");
VAR contentJson := response.Content;
VAR wasRebooted := PARSEJSON(contentJson, "ok");

IF(wasRebooted, "Reboot successful", "Error");
Luce Luce bianca

Luce bianca CCT (2700–6500 K) — regolazione luminosità e controllo temperatura colore

numeric Unità: %, K json_path

Luce

Lettura luminosità
VAR now := NOW();

IF now.Ticks < debounceTimestamp
    RETURN(Hb);
END

VAR value := PARSEJSON(jsonStatus, "$.lights[0].brightness", 1);

IF ISNULL(value)
    RETURN(NaN);
END

BOOL isOn := PARSEJSON(jsonStatus, "$.lights[0].ison", 1);

IF ISNULL(isOn)
    RETURN(NaN);
END

IF(isOn, value/100.0, 0);
Scrittura luminosità
IF St > 0.5
    SENDHTTPREQUEST("light/0?turn=on&transition=" + transitionTime + "&brightness=" + ROUND(Hb*100.0));
ELSE
    SENDHTTPREQUEST("light/0?turn=off&transition=" + transitionTime);
END

VAR now := NOW();
debounceTimestamp := now.Ticks + transitionTime + 500;
Lettura temperatura colore
VAR now := NOW();

IF now.Ticks < debounceTimestamp
    RETURN(Ct);
END

VAR value := PARSEJSON(jsonStatus, "$.lights[0].temp", 1);

IF ISNULL(value)
    RETURN(NaN);
END
 
value
Scrittura temperatura colore
SENDHTTPREQUEST("light/0?transition=" + transitionTime + "&brightness=" + ROUND(Hb*100) + "&temp=" + Ct);

VAR now := NOW();
debounceTimestamp := now.Ticks + transitionTime + 500;
Contatore elettrico Contatore elettrico Solo lettura

Misurazione consumo energetico — potenza istantanea (kW) ed energia cumulativa (kWh)

numeric Unità: W / kWh json_path

Contatore elettrico

Lettura consumo totale
IF LENGTH(jsonStatus) = 0
    RETURN(NaN);
END

VAR power := PARSEJSON(jsonStatus, "$.meters[0].power");
VAR total := PARSEJSON(jsonStatus, "$.meters[0].total");
BOOL isOn := PARSEJSON(jsonStatus, "$.lights[0].ison");

IF ISNULL(power) OR ISNULL(total) OR (ison AND power=0)
	ADDWARNING("To enable power monitoring, open device settings in Shelly app or web browser and configure device model in Settings->Device Model");
	
    RETURN(NaN);
END

total / 60000.0
Lettura domanda
IF LENGTH(jsonStatus) = 0
    RETURN(NaN);
END

VAR power := PARSEJSON(jsonStatus, "$.meters[0].power", 1);

IF ISNULL(power)
    RETURN(NaN);
END

power / 1000.0
Connessione: Packet Parser → HTTP
Possibili miglioramenti (7)
  • Light Timer Active — Boolean — whether a countdown timer is currently active on the light output.
  • Timer Remaining — Seconds remaining on active timer. Available in /status response.
  • Auto-off Timer — Auto-off timer in seconds, could be added as service action or light parameter.
  • WiFi Signal Strength (as device) — WiFi RSSI in dBm. HTTP template exposes it as service attribute but not as a standalone sensor device.
  • Internal Device Temperature — Internal temperature in celsius. Available in /status for Gen1 devices. Not exposed in DUO template.
  • MQTT Real-time Power (as device attribute) — MQTT template reads power in electric meter device but does not expose it as a service attribute on the light device.
  • Connection Status — LWT topic — true on connect, false on disconnect. Could detect offline bulbs.

Fonti