Shelly Home Assistant: guida completa integrazione nativa vs custom component

I dispositivi Shelly rappresentano una delle scelte più popolari per la domotica fai-da-te: relè WiFi compatti che si installano dietro interruttori esistenti, trasformando qualsiasi circuito elettrico in smart home senza sostituire placche o cablaggi. Con Home Assistant hai due strade per integrare i tuoi Shelly: l’integrazione nativa ufficiale (inclusa di default in HA) oppure i custom component come Shelly4HASS installabili via HACS.

La domanda che si pongono tutti: quale integrazione scegliere? La risposta dipende dalla generazione dei tuoi dispositivi (Gen1, Gen2, Gen3), dalle funzionalità avanzate che ti servono (energy monitoring, roller shutter, scripting) e dalla velocità di risposta desiderata. In questa guida analizzeremo pro/contro di entrambe le integrazioni, configurazione ottimale per local push CoIoT su Gen1, setup Shelly Plus/Pro Gen2/Gen3, differenze hardware tra modelli 1/1PM/2.5/Plus, energy dashboard e firmware updates.

---

Shelly Gen1 vs Gen2 vs Gen3: quale generazione hai?

Identificare la generazione

Shelly ha rilasciato 4 generazioni di dispositivi con protocolli e chip differenti:

Gen1 (2019-2021) – ESP8266 chip:

• Shelly 1, 1PM, 1L, 2.5, Dimmer, RGBW2, EM, Plug S

• Protocollo: CoIoT (CoAP-based) per comunicazione locale

• Firmware: basato su Mongoose OS

• WiFi: 2.4GHz solo b/g/n

Gen2 (2021-2023) – ESP32 chip “Plus” series:

• Shelly Plus 1, Plus 1PM, Plus 2PM, Plus i4, Plus Plug S/IT

• Protocollo: RPC over WebSocket (più veloce di CoIoT)

• Scripting: supporto JavaScript on-board

• Bluetooth: BLE per setup iniziale

• WiFi: 2.4GHz con migliore ricezione

Gen3 (2023-2024) – ESP32-C3 chip “Mini” series:

• Shelly 1 Mini Gen3, 1PM Mini Gen3, Plus PM Mini Gen3

• Ancora più compatti (dimensioni ridotte 30%)

• Stesse funzionalità Gen2 in formato ridotto

Gen4 (2024+) – Pro series con Ethernet:

• Shelly Pro 1, Pro 2, Pro 3, Pro 4PM, Pro 3EM

• Connessione: WiFi + Ethernet LAN simultanea

• DIN rail mounting per quadro elettrico

• Power monitoring professionale

Come capire quale hai? Guarda nome modello stampato sul dispositivo o app Shelly → Device Info → Generation.

---

Integrazione nativa Home Assistant: la scelta consigliata

Perché scegliere l’integrazione nativa

Dal 2021 Home Assistant include integrazione Shelly ufficiale ottimizzata, e nel 2025 Shelly è entrata nel programma “Works with Home Assistant”, garantendo compatibilità testata e supporto prioritario.

Vantaggi integrazione nativa:

• Zero configurazione YAML: setup completamente UI-based

• Auto-discovery: Shelly rilevati automaticamente in rete locale

• Aggiornamenti costanti: bug fix e supporto nuovi modelli integrati core HA

• Supporto Gen1/Gen2/Gen3/Gen4: tutti dispositivi compatibili

• Energy dashboard: entità energy automaticamente riconosciute

• Firmware updates da HA: aggiornamento OTA direttamente dall’interfaccia

• Repair issues: notifiche se CoIoT non configurato correttamente

Limitazioni:

• Meno entità esposte rispetto a custom component (alcuni sensori avanzati mancanti)

• Gen1 richiede configurazione manuale CoIoT peer per prestazioni ottimali

Setup integrazione nativa passo-passo

Prerequisiti:

• Shelly già connesso a rete WiFi (usa app Shelly per prima configurazione)

• Home Assistant sulla stessa rete locale/VLAN

• Porta 5683 UDP aperta firewall (per CoIoT Gen1)

Aggiungi dispositivo:

Impostazioni → Dispositivi e Servizi → + Aggiungi integrazione → cerca Shelly

Scenario A: Auto-discovery (più comune):

• Se Shelly già in rete, HA lo rileva automaticamente

• Appare notifica “Discovered” → clicca Configure

• Assegna area e conferma

Scenario B: Configurazione manuale:

• Clicca + Aggiungi integrazione → Shelly

• Inserisci indirizzo IP del dispositivo

• Username/password (se abilitata autenticazione su Shelly)

Entità create automaticamente (esempio Shelly 1PM):

• switch.shelly_1pm_xxxxx – controllo relay on/off

• sensor.shelly_1pm_xxxxx_power – potenza istantanea (W)

• sensor.shelly_1pm_xxxxx_energy – energia cumulativa (kWh)

• sensor.shelly_1pm_xxxxx_temperature – temperatura interna dispositivo

• binary_sensor.shelly_1pm_xxxxx_overpowering – protezione sovraccarico

• update.shelly_1pm_xxxxx_firmware – aggiornamenti firmware disponibili

---

Configurazione CoIoT per Gen1: eliminare ritardi 10+ secondi

Il problema: polling lento

Per default, integrazione nativa su dispositivi Gen1 usa polling HTTP ogni 60 secondi: quando accendi fisicamente l’interruttore, Home Assistant aggiorna stato dopo 10-60 secondi ritardo inaccettabile.

Soluzione: abilitare CoIoT unicast per push updates istantanei (< 1 secondo).

Configurare CoIoT peer su Shelly Gen1

Step-by-step:

1. Accedi interfaccia web Shelly via browser: http://[IP_SHELLY]

2. Internet & Security → ADVANCED – DEVELOPER SETTINGS

3. Trova sezione CoIoT:

   • ☑️ Enable CoIoT (spunta checkbox)

   • CoIoT peer: inserisci [IP_HOME_ASSISTANT]:5683
     Esempio: 192.168.1.100:5683

4. Clicca SAVE

5. Riavvia manualmente Shelly: Settings → Device → Reboot

Verifica funzionamento:

• Accendi/spegni fisicamente interruttore collegato

• Stato in HA si aggiorna immediatamente (1-2 secondi max)

• Se ritardo persiste, controlla firewall porta 5683 UDP

Nota critica per dispositivi battery-powered (Shelly Button, Door/Window, Motion): CoIoT unicast obbligatorio anche se alimentati via USB, altrimenti aggiornamenti possono impiegare ore​.

Troubleshooting: Repair issue “CoIoT peer not configured”

Se HA mostra riparazione richiesta per Shelly Gen1:

Cause comuni:

• CoIoT peer non impostato o errato

• Firewall blocca porta 5683 UDP

• Firmware Shelly obsoleto (pre-1.10) senza opzione CoIoT

Soluzioni:

1. Verifica CoIoT peer nell’interfaccia Shelly (deve puntare a IP corretto HA)

2. Testa porta: nc -u -l 5683 su server HA, poi trigger evento Shelly (se non ricevi pacchetti → firewall problema)

3. Aggiorna firmware: se non vedi opzione CoIoT, firmware troppo vecchio → aggiorna a ultima versione stable

---

Shelly Gen2/Gen3: configurazione semplificata

RPC over WebSocket: nessuna configurazione extra

Dispositivi Plus (Gen2) e Mini (Gen3) usano protocollo RPC più moderno che non richiede configurazione CoIoT peer:

Vantaggi Gen2/Gen3:

• Push updates nativi senza setup manuale

• Velocità: WebSocket mantiene connessione persistente, latenza <500ms

• Scripting JavaScript: automazioni on-device (riduce carico HA)

• Bluetooth setup: configurazione WiFi via BLE se necessario

Setup Gen2/Gen3:

1. Connetti Shelly a WiFi (app Shelly o BLE)

2. HA rileva automaticamente via mDNS

3. Aggiungi integrazione → tutto funziona immediatamente

Nessun firewall config necessario, comunicazione avviene su porta 80 HTTP standard WebSocket.

---

Custom component Shelly4HASS: quando serve?

Cos’è Shelly4HASS

Shelly4HASS (ora deprecato, fork attivo: ShellyForHASS) è custom component HACS che offriva funzionalità avanzate prima che integrazione nativa maturasse.​

Nel 2025, integrazione nativa ha raggiunto parità funzionale, quindi custom component raccomandato solo per:

Caso d’uso 1: Entità extra avanzate:

• Custom component espone più sensori (es. RSSI WiFi dettagliato, uptime, stato cloud)

• Configurazioni granulari via YAML (decimali power, polling custom)

Caso d’uso 2: Automazioni legacy YAML complesse:

• Se hai già 50+ automazioni scritte per custom component con entity_id custom

• Migrazione a integrazione nativa richiederebbe riscrittura

Caso d’uso 3: Funzionalità experimental non ancora in core:

• Beta firmware support

• Device-specific tweaks

Pro/contro custom component

Pro:

• Più entità esposte

• Configurazione YAML fine-tuning

• Aggiornamenti frequenti community

Contro:

• Installazione manuale via HACS

• Breaking changes possibili con aggiornamenti HA core

• Supporto dipende da maintainer volontari

• Possibile conflitto se usi entrambe integrazioni simultanee

Raccomandazione 2025: Usa integrazione nativa salvo necessità specifiche documentate sopra. Custom component ha senso solo per utenti avanzati con esigenze particolari.

---

Modelli Shelly: quale scegliere?

Shelly 1 vs 1PM: power monitoring vale la pena?

Quando scegliere Shelly 1:

• Controllo luci/carichi senza interesse monitoraggio consumi

• Applicazioni bassa tensione (12V/24V) → dry contact essenziale

• Budget limitato (differenza minima però)

Quando scegliere Shelly 1PM:​

• Energy dashboard Home Assistant → tracciare consumi singolo circuito

• Protezione sovraccarico automatica → sicurezza extra

• Carichi variabili (lavatrice, scaldabagno) → capire consumi reali

• Differenza prezzo minima ($2) → conviene sempre 1PM

Shelly 2.5 vs Shelly Plus 2PM

Quando scegliere Shelly 2.5:​

• Prezzo: più economico Gen1 (spesso in offerta)

• Carico totale 20A se due circuiti pesanti simultanei

• Già abituato a configurare CoIoT

Quando scegliere Plus 2PM:

• Power monitoring separato per canale → energy dashboard preciso

• Scripting on-device → automazioni locali senza dipendenza HA

• Setup zero-config → nessun CoIoT peer manuale

• Futuro-proof: Gen2 riceve aggiornamenti firmware prioritari

Shelly Pro series: installazione quadro elettrico

Shelly Pro 4PM esempio professionale:

• 4 canali relay 16A ciascuno con power monitoring separato

• Montaggio DIN rail su guida quadro

• Ethernet + WiFi simultanei (ridondanza connessione)

• Display LCD integrato stato dispositivo

• Ideale per: quadri elettrici, impianti commerciali, monitoraggio trifase

Shelly Pro 3EM: energy meter trifase 3x120A senza relay, solo monitoraggio consumi.

---

Energy monitoring e dashboard Home Assistant

Configurare energy dashboard con Shelly

Dispositivi con power monitoring (1PM, 2.5, Plus 2PM, Pro 4PM) espongono automaticamente entità energy riconosciute da HA energy dashboard.

Setup step-by-step:

1. Verifica entità energy create:

   • Strumenti Sviluppatore → Stati

   • Cerca sensor.[nome_shelly]_energy

   • device_class: energy e state_class: total_increasing

2. Aggiungi a Energy Dashboard:

   • Impostazioni → Dashboard → Energy

   • Electricity grid → Add Consumption

   • Seleziona sensor.shelly_1pm_xxxxx_energy

   • Imposta costo kWh (opzionale)

3. Crea grafici personalizzati:

   type: energy-date-selection

   type: energy-usage-graph

Monitorare consumi real-time

Card Lovelace potenza istantanea:

type: entities
title: Consumi Real-Time
entities:
  - entity: sensor.shelly_1pm_lavatrice_power
    name: Lavatrice
    icon: mdi:washing-machine
  - entity: sensor.shelly_1pm_frigo_power
    name: Frigorifero
    icon: mdi:fridge
  - entity: sensor.shelly_2pm_luci_soggiorno_channel_1_power
    name: Luci Soggiorno
  - type: divider
  - entity: sensor.shelly_pro_4pm_total_power
    name: Consumo Totale Casa
    icon: mdi:home-lightning-bolt

Automazione alert consumo anomalo:

automation:
  - alias: "Alert Consumo Anomalo Frigo"
    description: "Notifica se frigo consuma >200W (possibile guasto)"
    trigger:
      - platform: numeric_state
        entity_id: sensor.shelly_1pm_frigo_power
        above: 200
        for:
          minutes: 10
    action:
      - service: notify.mobile_app
        data:
          message: "⚠️ Frigo consuma {{ states('sensor.shelly_1pm_frigo_power') }}W - verifica guasto!"
          data:
            priority: high

Firmware updates: OTA da Home Assistant

Aggiornamento automatico integrazione nativa

Dal 2024, integrazione nativa supporta firmware OTA direttamente da HA UI:

Procedura:

1. Notifica aggiornamento disponibile:

   • HA mostra badge su update.shelly_xxxxx_firmware

   • Oppure manualmente: Dispositivi e Servizi → Shelly → Device → Firmware

2. Installa aggiornamento:

   • Clicca entità update.shelly_xxxxx_firmware

   • Install → conferma

   • Shelly scarica firmware, riavvia automaticamente (2-3 minuti)

   • HA riconnette automaticamente

Importante:

• Non spegnere Shelly durante update (rischio brick)

• Aggiorna 1 dispositivo per volta se rete WiFi debole

• Backup configurazione Shelly prima major upgrade (Settings → Backup)

Update manuale via HTTP (troubleshooting)

Se update da HA fallisce, usa HTTP OTA request diretto:

Gen1 metodo:

curl "http://[IP_SHELLY]/ota?url=http://archive.shelly-tools.com/version/v1.14.0/SHXXX.zip"

Sostituisci SHXXX.zip con modello specifico (es. SHSW-1.zip per Shelly 1).

Gen2/Gen3 metodo:

curl -X POST "http://[IP_SHELLY]/rpc/Shelly.Update" -d '{"stage":"stable"}'

MQTT come alternativa (opzionale)

Quando usare MQTT invece CoIoT/RPC

MQTT offre alternativa standardizzata per comunicazione Shelly ↔ HA:

Vantaggi MQTT:

• Broker centralizzato: tutti dispositivi smart passano attraverso Mosquitto

• Affidabilità: MQTT gestisce riconnessioni automatiche meglio di CoIoT

• Interoperabilità: altri sistemi possono leggere stati Shelly

Svantaggi:

• Setup più complesso (Mosquitto broker necessario)

• Latenza leggermente superiore rispetto RPC Gen2

• Configurazione manuale ogni dispositivo

Setup MQTT su Shelly Gen1

Prerequisiti: Mosquitto broker installato su HA (Supervisor → Add-on Store → Mosquitto).

Configurazione Shelly:

1. Interfaccia web Shelly → Internet & Security → ADVANCED – DEVELOPER SETTINGS

2. Sezione MQTT:

   • Enable MQTT

   • Server: [IP_HOME_ASSISTANT]:1883

   • Username/Password: credenziali Mosquitto

   • Client ID: shelly-xxxxx (auto-generato)

3. Save e riavvia

HA configurazione:

• Integrazione Shelly rileva automaticamente dispositivi MQTT-enabled

• Entity ID includono mqtt nel nome

---

Confronto finale: quale integrazione scegliere?

Matrice decisionale

Best practices

Configurazione ottimale Gen1:

• CoIoT peer configurato correttamente

• Firmware aggiornato (almeno 1.10+)

• IP statico DHCP reservation per ogni Shelly

• VLAN isolata IoT (sicurezza)

Configurazione ottimale Gen2/Gen3:

• Integrazione nativa default

• Scripting JavaScript per automazioni time-critical

• Bluetooth abilitato per troubleshooting

---

Troubleshooting problemi comuni

Shelly non rilevato da HA

Causa: mDNS bloccato, firewall, VLAN isolata
Soluzione:

• Verifica ping: ping [IP_SHELLY] da server HA

• Aggiungi manualmente via IP invece discovery

• Abilita mDNS reflector se Shelly su VLAN diversa da HA

• Porta 80 HTTP accessibile

Ritardo 10+ secondi Gen1

Causa: CoIoT peer non configurato, polling fallback
Soluzione: Segui configurazione CoIoT peer sezione specifica sopra

Energy entities non appaiono dashboard

Causa: device_class o state_class mancanti
Soluzione:

• Controlla attributi entità: deve avere device_class: energy e state_class: total_increasing

• Se mancanti, rimuovi/riaggiunge integrazione Shelly

• Verifica firmware Shelly aggiornato (bug risolti versioni recenti)

Shelly Plus disconnessioni frequenti

Causa: WiFi 2.4GHz congestionato, interferenze
Soluzione:

• Cambia canale WiFi router (usa 1, 6, 11 non overlapping)

• Avvicina access point o installa repeater

• Verifica alimentazione stabile (drop tensione causa reboot)

---

Shelly offre il miglior rapporto qualità/prezzo per retrofit domotico di impianti esistenti, e Home Assistant li supporta eccellentemente tramite integrazione nativa che nel 2025 ha raggiunto piena maturità. Per la stragrande maggioranza degli utenti, integrazione nativa è la scelta corretta: auto-discovery, energy dashboard, firmware OTA, supporto ufficiale e zero manutenzione YAML.

Dispositivi Gen2/Gen3 (Plus/Mini) funzionano out-of-the-box senza configurazioni speciali, mentre Gen1 richiede 5 minuti setup CoIoT peer una tantum per prestazioni ottimali. Custom component Shelly4HASS rimane opzione per utenti avanzati con esigenze particolari, ma non è più necessario per funzionalità base o energy monitoring.

Consiglio finale: inizia con integrazione nativa, configura CoIoT peer su Gen1, abilita energy dashboard e goditi controllo locale veloce senza abbonamenti cloud. Se specifiche esigenze emergono, puoi sempre aggiungere custom component o MQTT in seguito senza riconfigurare da zero.