---
title: "Shelly RGBW2"
description: "Shelly RGBW2 controller LED RGBW Wi-Fi con due modalità operative. Controlla strisce LED RGB a colori o quattro canali bianchi indipendenti via HTTP da TapHome."
url: "https://taphome.com/it/compatibility/shelly-rgbw2/"
language: it
lastmod: 2026-10-08
generator: hugo
ai:
  topics: ["http","lighting","wifi","rgbw","led-controller","dimmer"]
  questions: ["Come integrare lo Shelly RGBW2 con TapHome?","Qual è la differenza tra la modalità Color e White sullo Shelly RGBW2?","Come controllare le strisce LED RGB tramite TapHome?","Come regolare quattro canali bianchi indipendenti con lo Shelly RGBW2 in TapHome?","Perché il template Shelly RGBW2 mostra un errore di modalità in TapHome?","Come impostare il tempo di transizione per le variazioni di luce dello Shelly RGBW2?"]
---

# Shelly RGBW2

Comunicazione: Packet Parser → HTTP

- [Pagina prodotto Shelly RGBW2](https://www.shelly.com/en/products/shop/shelly-rgbw2)
- [Documentazione API Shelly RGBW2](https://shelly-api-docs.shelly.cloud/gen1/#shelly-rgbw2-color-mode)

> 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 RGBW2 è un controller per strisce LED RGBW Wi-Fi con quattro uscite PWM (12/24 V DC). Supporta due modalità operative mutuamente esclusive — Color e White — ciascuna con il proprio template TapHome. TapHome comunica con il dispositivo via HTTP sulla rete locale; non è necessaria alcuna connessione cloud.

In **modalità Color**, le quattro uscite controllano una striscia LED RGBW come singola luce colorata con tonalità, saturazione, luminosità e un canale bianco (CCT) opzionale. In **modalità White**, le quattro uscite funzionano come dimmer indipendenti, ciascuno controllando una striscia LED bianca o zona separata.

La modalità operativa deve essere scelta nell'interfaccia web Shelly (o tramite API) prima di importare il template corrispondente. Ogni template valida la modalità corrente ad ogni polling e mostra un errore se il dispositivo è impostato sulla modalità sbagliata.

## Configurazione

Entrambi i template si connettono via Wi-Fi. Durante l'importazione del template TapHome, inserire l'indirizzo IP del dispositivo (placeholder predefinito `192.168.0.1`) e un tempo di transizione opzionale in millisecondi (predefinito `300`).

Il parametro tempo di transizione controlla la velocità di dissolvenza della luce tra i livelli di luminosità. Si applica a tutti i comandi di scrittura (on/off, luminosità, cambi colore) e influenza la finestra di debounce — il template ignora i valori di polling per `transitionTime + 500 ms` dopo ogni scrittura per prevenire letture obsolete durante le transizioni.

## Template modalità Color

### Luce colorata

Il template espone la striscia RGBW come singola luce colorata HSB con due sotto-modalità:

- **Colore RGB** — tonalità e saturazione controllano il colore della striscia. Il template converte tra i valori RGB dell'API Shelly (rosso, verde, blu 0-255) e il modello HSB di TapHome. La luminosità è controllata tramite il parametro `gain` (0-100).
- **Bianco (CCT)** — quando viene impostata la temperatura di colore correlata, il template passa al controllo del canale bianco. L'intervallo CCT è 3000-6500 K. La luminosità è controllata tramite il parametro `white` (0-100).

Lo stato della luce viene letto dalla risposta `/status` (`lights[0]`) e controllato tramite l'endpoint `/light/0`. L'accensione invia `turn=on` con i valori correnti di colore o bianco; lo spegnimento invia `turn=off`. Tutti i comandi di scrittura includono il parametro tempo di transizione.

### Misurazione potenza (Color)

Il template Color include un contatore energetico che legge da `meters[0]`:

- **Potenza istantanea** — `meters[0].power` in watt, convertita in kW
- **Consumo totale** — `meters[0].total` in watt-minuti, convertito in kWh

Se la luce è accesa ma la potenza mostra zero, il template visualizza un avviso suggerendo di configurare il modello del dispositivo nelle impostazioni dell'app Shelly.

## Template modalità White

### Quattro dimmer indipendenti

Il template White espone quattro canali dimmer indipendenti, uno per uscita PWM:

| Canale | Uscita | Endpoint | Intervallo di polling |
|--------|--------|----------|----------------------|
| Ch1 | R (Red) | `/light/0` | 2,5 s |
| Ch2 | G (Green) | `/light/1` | 2,5 s |
| Ch3 | B (Blue) | `/light/2` | 2,5 s |
| Ch4 | W (White) | `/light/3` | 2,5 s |

Ogni dimmer legge `lights[N].ison` e `lights[N].brightness` (0-100, normalizzato a 0-1) dalla risposta `/status`. I comandi di scrittura usano `/light/N?turn=on|off&brightness=VALUE`. Tutti i canali usano lo stesso tempo di transizione e logica di debounce.

### Misurazione potenza (White)

Ogni canale ha il proprio contatore energetico, che legge da `meters[0]` a `meters[3]`. Il primo canale esegue il polling ogni 2,5 secondi; i canali 2-4 eseguono il polling a intervalli di 15 secondi. Ogni contatore fornisce potenza istantanea (W in kW) ed energia cumulativa (watt-minuti in kWh).

## Diagnostica di servizio

Entrambi i template espongono 10 attributi di servizio per il monitoraggio del dispositivo:

- **Info rete** — indirizzo IP, indirizzo MAC (formattato con 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

Entrambi i template condividono tre azioni di servizio:

- **Abilita cloud** — abilita o disabilita la connettività Shelly Cloud
- **Riavvio** — avvia un riavvio del dispositivo
- **Imposta modalità** — il template Color include "Set mode Color" (`/settings?mode=color`) e il template White include "Set mode White" (`/settings?mode=white`). Queste azioni cambiano la modalità operativa del dispositivo tramite API.

### Funzionalità aggiuntive

Lo Shelly RGBW2 espone anche effetti luce (modalità Color, indice effetto 0-3), stato dell'ingresso fisico, temperatura interna, flag di surriscaldamento e impostazioni di protezione potenza nella sua API. Queste funzionalità potranno essere aggiunte in un futuro aggiornamento del template.

## Risoluzione dei problemi

### Il dispositivo non risponde

1. Verificare che lo Shelly sia connesso al Wi-Fi e abbia un indirizzo IP valido
2. Provare a usare l'hostname mDNS (`shellyrgbw2-AABBCCDDEE.local`) invece dell'indirizzo IP — l'IP potrebbe essere cambiato dopo un rinnovo DHCP
3. Aprire `http://{device-ip}/shelly` nel browser — se risponde, il dispositivo è raggiungibile
4. Verificare che TapHome CCU e Shelly siano sulla stessa rete / VLAN

### Errore "Mode White/Color is not supported"

Questo errore significa che il dispositivo è impostato sulla modalità operativa sbagliata per il template importato. Per risolvere:

1. Aprire l'interfaccia web Shelly su `http://{device-ip}`
2. Cambiare la modalità operativa per corrispondere al template (Color o White)
3. In alternativa, usare l'azione di servizio "Set mode Color" o "Set mode White" dall'altro template per cambiare modalità via API, poi reimportare il template corretto

### La potenza mostra zero

1. Confermare che i LED sono collegati alle uscite dello Shelly RGBW2
2. Aprire l'app Shelly o l'interfaccia web e verificare che il modello del dispositivo sia configurato in Settings -> Device Model
3. Verificare che la luce sia accesa — il contatore misura solo quando scorre corrente attraverso le uscite
4. Interrogare `/status` manualmente e verificare che `meters[0].power` restituisca un valore diverso da zero

### La luce colorata non cambia

1. Verificare che il dispositivo sia in modalità Color (controllare la risposta `/status` — `mode` dovrebbe essere `"color"`)
2. Assicurarsi che la luce sia accesa prima di cambiare tonalità o saturazione
3. Se sia `gain` che `white` sono diversi da zero, il template li azzera automaticamente e spegne la luce — questo previene un comportamento indefinito dove i canali RGB e bianco competono

> [!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. Se anche un altro sistema interroga il dispositivo, aumentare gli intervalli di polling del template (per default 2,5 s per i canali luce) per ridurre la contesa delle connessioni.

## 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 RGBW2 Color 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                |
| Imposta modalità Color |

Variabili personalizzate

|                                             |                                                                                                   |
|---------------------------------------------|---------------------------------------------------------------------------------------------------|
| `transitionTime` (numeric) = TransitionTime | Durata della transizione luminosa 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;
    
    if PARSEJSON(jsonStatus, "$.mode", 1) = "white"
    adderror("Mode White is not supported");
    end
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");
```

Set mode Color

```taphome
VAR response := SENDHTTPREQUEST("/settings?mode=color");
IF(response.isSuccess, "Color mode is set", "Error");
```

Contatore elettrico Contatore elettrico Solo lettura

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

numeric Unità: W / kWh

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

Luce colorata Luce HSB Lettura e scrittura

Luce colorata RGBW con controllo HSB — tonalità, saturazione, luminosità e canale bianco CCT opzionale (3000–6500 K)

hsb

Lettura (modulo)

```taphome
if PARSEJSON(jsonStatus, "$.lights[0].white", 1) > 0 and PARSEJSON(jsonStatus, "$.lights[0].gain", 1)
    SENDHTTPREQUEST("light/0?gain=0&white=0");
    SENDHTTPREQUEST("light/0?turn=off");
end
```

Lettura luminosità

```taphome
VAR now := NOW();

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

INT value;
IF !ISNAN(Ct)
    value := PARSEJSON(jsonStatus, "$.lights[0].white", 1);
ELSE
    value := PARSEJSON(jsonStatus, "$.lights[0].gain", 1);
END

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
    IF !ISNAN(Ct)
    SENDHTTPREQUEST("light/0?turn=on&transition=" + transitionTime + "&gain=0&white=" + ROUND(Hb*100.0));
    ELSE
    SENDHTTPREQUEST("light/0?turn=on&transition=" + transitionTime + "&white=0&gain=" + ROUND(Hb*100.0));
    END
ELSE
    SENDHTTPREQUEST("light/0?turn=off&transition=" + transitionTime);
END

VAR now := NOW();
debounceTimestamp := now.Ticks + transitionTime + 500;
```

Lettura tonalità

```taphome
VAR now := NOW();

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

INT r := PARSEJSON(jsonStatus, "$.lights[0].red", 1);
INT g := PARSEJSON(jsonStatus, "$.lights[0].green", 1);
INT b := PARSEJSON(jsonStatus, "$.lights[0].blue", 1);

VAR HSVColor := RGBTOHSV(r, g, b);
ROUND(HSVColor.Hue);
```

Scrittura tonalità

```taphome
IF !ISNAN(Ct)
    RETURN(0);
END

VAR color := HSVTORGB(Hd, Sa, 1);

SENDHTTPREQUEST("light/0?mode=color&transition=" + transitionTime + "&gain=" + ROUND(Hb*100) + "&red=" + color.RED + "&green=" + color.GREEN + "&blue=" + color.BLUE + "&white=0");


VAR now := NOW();
debounceTimestamp := now.Ticks + transitionTime + 500;
```

Lettura saturazione

```taphome
VAR now := NOW();

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

INT r := PARSEJSON(jsonStatus, "$.lights[0].red", 1);
INT g := PARSEJSON(jsonStatus, "$.lights[0].green", 1);
INT b := PARSEJSON(jsonStatus, "$.lights[0].blue", 1);
 
VAR HSVColor := RGBTOHSV(r, g, b);
ROUND(HSVColor.Saturation * 100.0) / 100.0;
```

Scrittura saturazione

```taphome
IF !ISNAN(Ct)
    RETURN(0);
END

VAR color := HSVTORGB(Hd, Sa, 1);

SENDHTTPREQUEST("light/0?mode=color&transition=" + transitionTime + "&gain=" + ROUND(Hb*100) + "&red=" + color.RED + "&green=" + color.GREEN + "&blue=" + color.BLUE + "&white=0");


VAR now := NOW();
debounceTimestamp := now.Ticks + transitionTime + 500;
```

Lettura temperatura colore

```taphome
VAR now := NOW();

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

INT value := PARSEJSON(jsonStatus, "$.lights[0].temp", 1);
IF PARSEJSON(jsonStatus, "$.lights[0].white", 1) = 0
    RETURN(NaN);
END
 
Ct
```

Scrittura temperatura colore

```taphome
IF ISNAN(Ct)
    RETURN(0);
END

VAR temp := MIN(Ct, 6500);
temp := MAX(temp, 3000);

SENDHTTPREQUEST("light/0?transition=" + transitionTime + "&white=" + ROUND(Hb*100) + "&gain=0");

VAR now := NOW();
debounceTimestamp := now.Ticks + transitionTime + 500;
```

**Connessione:** Packet Parser → HTTP • Hostname: `shellyrgbw2-{MAC}.local`

Possibili miglioramenti (7)

- Light effect — Color mode: effect index (0=off, 1–3=predefined effects), settable via /light/0?effect=N
- Input State — Physical input state (0/1), available in /status response
- WiFi RSSI (numeric) — WiFi RSSI in dBm as numeric value — template reads it as string with 'db' suffix
- Power protection — Max power setting in Watts, available in /settings; read + write possible via /settings?max\_power=N
- OTA firmware update — Trigger OTA firmware update via /ota?update=true
- Internal device temperature — Internal temperature in C, available in /status response (Gen1 devices)
- Overheated — Overtemperature flag, boolean, available in /status response

## 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 RGBW2 API — Color & White Mode Endpoints
  
  [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen1/#shelly-rgbw2-color-mode) 2026-03-30
- Shelly RGBW2 Knowledge Base
  
  [kb.shelly.cloud](https://kb.shelly.cloud/knowledge-base/shelly-rgbw2) 2026-03-30

## 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/)