---
title: "Shelly DUO"
description: "Lampadina Shelly DUO E27 in TapHome via HTTP o MQTT, senza cloud: luminosità, temperatura colore 2700–6500 K e potenza. Con MQTT fino a 5 lampadine."
url: "https://taphome.com/it/compatibility/shelly-duo/"
language: it
lastmod: 2026-03-30
generator: hugo
ai:
  topics: ["http","mqtt","lighting","wifi","cct","power-metering","led-bulb"]
  questions: ["Come integrare lo Shelly DUO con TapHome?","Come controllare luminosità e temperatura colore dello Shelly DUO da TapHome?","Come collegare lo Shelly DUO via HTTP a TapHome?","Come collegare più lampadine Shelly DUO via MQTT a TapHome?","Perché lo Shelly DUO mostra potenza zero?","Cos'è il meccanismo di debounce nel template Shelly DUO?"]
---

# Shelly DUO

Comunicazione: Packet Parser → HTTP

- [Pagina prodotto Shelly DUO](https://www.shelly.com/en/products/shop/shelly-bulb-duo)
- [Documentazione API Shelly DUO](https://shelly-api-docs.shelly.cloud/gen1/#shelly-duo)

> Indirizzo di rete
> 
> TapHome raggiunge il dispositivo all'indirizzo inserito durante l'importazione. Assegna al dispositivo un indirizzo fisso — una prenotazione IP nel router, oppure il suo nome mDNS se lo supporta —, altrimenti l'integrazione smette di funzionare quando il router cambia l'indirizzo.
> 
> [Preparazione della rete](https://taphome.com/it/docs/setup/network-preparation/)

## Guida all'integrazione

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)

> [!WARNING]
> 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.

> [!NOTE]
> 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

> [!WARNING]
> 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](https://www.shelly.com/en/support/shelly-app) (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**

> [!NOTE]
> 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

> [!TIP]
> 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

> [!NOTE]
> 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 2

Questi dispositivi compaiono in TapHome dopo l'importazione.

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) = TransitionTime | Durata della transizione di luce in millisecondi (parametro di importazione, predefinito 300 ms) |

Lettura (modulo)

```taphome
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

```taphome
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

```taphome
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

```taphome
VAR signal := PARSEJSON(jsonStatus, "$.wifi_sta.rssi", 1);
IF (ISNULL(signal), "-", signal + "db");
```

Cloud enabled

```taphome
VAR value := PARSEJSON(jsonStatus, "$.cloud.enabled", 1);
IF (ISNULL(value), "-", value)
```

Cloud connected

```taphome
VAR value := PARSEJSON(jsonStatus, "$.cloud.connected", 1);
IF (ISNULL(value), "-", value)
```

MQTT connected

```taphome
VAR value := PARSEJSON(jsonStatus, "$.mqtt.connected", 1);
IF (ISNULL(value), "-", value)
```

Device time

```taphome
VAR value := PARSEJSON(jsonStatus, "$.time", 1);
IF (ISNULL(value), "-", value)
```

FW update available

```taphome
VAR value := PARSEJSON(jsonStatus, "$.has_update");
IF (ISNULL(value), "-", value)
```

Uptime

```taphome
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

```taphome
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)

```taphome
VAR response := SENDHTTPREQUEST("/settings/cloud?enabled=" + enable);
VAR contentJson := response.Content;
VAR wasEnabled := PARSEJSON(contentJson, "enabled");

IF(wasEnabled, "Cloud enabled", "Cloud disabled");
```

Reboot

```taphome
VAR response := SENDHTTPREQUEST("/reboot");
VAR contentJson := response.Content;
VAR wasRebooted := PARSEJSON(contentJson, "ok");

IF(wasRebooted, "Reboot successful", "Error");
```

Luce Luce bianca Lettura e scrittura

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

numeric Unità: %, K json\_path

Lettura luminosità

```taphome
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à

```taphome
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

```taphome
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

```taphome
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

Lettura consumo totale

```taphome
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

```taphome
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 • Hostname: `ShellyBulbDuo-{MAC}.local`

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.

## Parametri di importazione

Inserisci questi valori quando importi l'XML.

| Richiesto nell'app   | Predefinito   |
|----------------------|---------------|
| Indirizzo IP         | `192.168.0.1` |
| Transition time (ms) | `300`         |

## Fonti

- Shelly Gen1 API Reference
  
  [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen1/) 2026-03-12
- Home Assistant Shelly Integration
  
  [www.home-assistant.io](https://www.home-assistant.io/integrations/shelly/) 2026-03-12
- Shelly DUO — Device-Specific API
  
  [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen1/#shelly-duo) 2026-03-30
- Shelly DUO — Product Datasheet
  
  [shellystore.co.uk](https://shellystore.co.uk/wp-content/uploads/2021/05/Duo-specs.pdf) 2026-03-30
  
  [PDF](https://taphome.com/compatibility/devices/shelly-duo/manufacturer/duo-specs.pdf)

I documenti del produttore sono © dei rispettivi proprietari. Sono forniti così come pubblicati dal produttore, solo a titolo informativo.

## Documentazione correlata

- [Integrazione Packet Parser](https://taphome.com/it/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/it/docs/integration/packet-parser/)
- [Funzioni Packet parser](https://taphome.com/it/docs/script/packet-parser/)
- [Funzioni di parsing](https://taphome.com/it/docs/script/parsing-functions/)