Registrati 
Accedi 
- Introduzione al controllo dei dispositivi Shelly tramite API
- Come trovare l’indirizzo IP del tuo dispositivo Shelly
- Struttura delle API REST di Shelly
- Autenticazione e sicurezza
- Lettura dello stato dei dispositivi
- Controllo dei relay e degli switch
- Lettura dei dati energetici
- Configurazione remota del dispositivo
- Integrazione con Home Assistant
- Webhook e eventi in tempo reale
- WebSocket per aggiornamenti in tempo reale
- Errori comuni e risoluzione dei problemi
- Conclusione
Introduzione al controllo dei dispositivi Shelly tramite API
I dispositivi Shelly rappresentano una delle soluzioni più diffuse e affidabili per la domotica fai-da-te. Prodotti dall’azienda bulgara Allterco Robotics, questi smart relay, plug, dimmer e sensori si distinguono per la facilità di installazione, la stabilità della connettività Wi-Fi e, soprattutto, per la ricchezza delle interfacce di controllo disponibili. Sebbene l’app ufficiale e il cloud Shelly siano strumenti validi per la gestione quotidiana dei dispositivi, le API REST offerte da ogni unità Shelly aprono un mondo di possibilità per chi desidera integrare questi componenti in sistemi più complessi, dashboard personalizzate o automazioni avanzate.
Questo articolo ti guiderà attraverso tutti gli aspetti necessari per controllare i tuoi dispositivi Shelly utilizzando le loro API native. Scopriremo come accedere ai dati dei sensori, inviare comandi di accensione e spegnimento, configurare le impostazioni del dispositivo e integrare tutto ciò in progetti personali o professionali.
Come trovare l’indirizzo IP del tuo dispositivo Shelly
Il primo passo per comunicare con un dispositivo Shelly tramite API è conoscerne l’indirizzo IP sulla tua rete locale. Ogni dispositivo Shelly, una volta connesso alla tua rete Wi-Fi, ottiene un indirizzo IP assegnato dal router. Esistono diversi metodi per individuarlo.
Il metodo più immediato consiste nell’utilizzare l’app Shelly o il pannello web integrato nel dispositivo. Accedi all’interfaccia web digitando l’indirizzo IP che hai impostato manualmente durante la configurazione iniziale, oppure scopri l’IP assegnato dinamicamente dal router. La maggior parte dei router moderni offre una pagina dedicata dove è possibile visualizzare tutti i dispositivi connessi alla rete, con nome host e indirizzo IP.
In alternativa, puoi utilizzare strumenti di scansione della rete come Fing, disponibile per smartphone e computer, che rileva automaticamente tutti i dispositivi presenti sulla tua rete LAN. Cerca tra i risultati il nome del produttore “Allterco” o “Shelly” per identificare correttamente il tuo dispositivo.
Struttura delle API REST di Shelly
Le API Shelly sono basate sul protocollo HTTP e seguono lo stile RESTful. Questo significa che ogni risorsa del dispositivo (stato, impostazioni, sensori) è accessibile tramite URL specifici. La struttura base di qualsiasi chiamata API a un dispositivo Shelly è la seguente:
- Protocollo: HTTP o HTTPS (se il dispositivo supporta le connessioni sicure)
- Indirizzo IP: l’indirizzo del tuo dispositivo Shelly sulla rete locale
- Porta: di default la 80 per HTTP e la 443 per HTTPS
- Endpoint: il percorso specifico che identifica la risorsa desiderata
Ad esempio, per ottenere lo stato attuale di un relay Shelly, la chiamata base sarà una richiesta GET all’indirizzo http://INDIRIZZO_IP/relay/0. Ogni dispositivo ha i propri endpoint specifici a seconda del modello e delle funzionalità disponibili.
Endpoint principali
Gli endpoint più utilizzati per il controllo dei dispositivi Shelly sono:
- /relay/0 o /switch/0: controlla lo stato del primo relay o switch. Utilizza GET per leggere lo stato e POST con parametri specifici per cambiarlo.
- /input/0: legge lo stato di un ingresso fisico collegato al dispositivo.
- /emeter/0: fornisce i dati energetici del dispositivo, tra cui tensione, corrente, potenza attiva e energia totale consumata.
- /settings: restituisce tutte le impostazioni correnti del dispositivo in formato JSON.
- /config: utilizzato per modificare le impostazioni del dispositivo. Richiede una richiesta POST con il corpo contenente i nuovi valori in formato JSON.
- /wifi: gestisce le impostazioni della connettività Wi-Fi del dispositivo.
- /device/uptime: fornisce informazioni sul tempo di attività del dispositivo.
Autenticazione e sicurezza
Per motivi di sicurezza, molte chiamate API ai dispositivi Shelly richiedono un’autenticazione. Questo è particolarmente vero per le operazioni di scrittura (modificare impostazioni, accendere o spegnere relay). Esistono due metodi principali di autenticazione supportati dalle API Shelly.
Il primo metodo utilizza l’autenticazione HTTP Basic. In questo caso, devi includere le credenziali dell’utente Shelly nell’intestazione della richiesta HTTP. Le credenziali predefinite sono impostate durante la configurazione iniziale del dispositivo tramite l’app o il pannello web. Per inviare una richiesta autenticata con questo metodo, devi codificare username e password in formato Base64 e inserirli nell’intestazione Authorization.
Il secondo metodo, disponibile sui firmware più recenti, utilizza token di accesso generati dinamicamente. Questo approccio è più sicuro perché il token ha una durata limitata e può essere rigenerato senza modificare la password del dispositivo. Per ottenere un token, devi prima inviare una richiesta POST all’endpoint /login con le tue credenziali nel corpo della richiesta.
Come configurare le credenziali
Se non hai ancora impostato username e password sul tuo dispositivo Shelly, procedi come segue:
- Accedi al pannello web del dispositivo digitando il suo indirizzo IP nel browser.
- Naviga fino alla sezione Impostazioni o Security.
- Inserisci un nome utente e una password forti e univoche.
- Salva le modifiche. Da questo momento, tutte le chiamate API che richiedono autenticazione dovranno includere queste credenziali.
Lettura dello stato dei dispositivi
La lettura dello stato è l’operazione più semplice e comune da eseguire tramite le API Shelly. Non richiede generalmente autenticazione, il che la rende ideale per monitoraggi in tempo reale o integrazioni con dashboard.
Per ottenere lo stato attuale del primo relay di un dispositivo Shelly 2PM, ad esempio, invia una richiesta GET all’endpoint /relay/0. Il dispositivo risponderà con un oggetto JSON contenente informazioni dettagliate:
- ison: valore booleano che indica se il relay è acceso (true) o spento (false).
- has_timer: indica se il relay supporta timer.
- timer_started: timestamp di inizio timer, se attivo.
- timer_duration: durata impostata per il timer.
- timer_remaining: tempo restante al timer.
Per leggere i dati energetici, utilizza l’endpoint /emeter/0. La risposta includerà valori come tensione (voltage), corrente (current), potenza attiva (power), potenza apparente e fattore di potenza. Questi dati vengono aggiornati in tempo reale dal dispositivo e possono essere interrogati ogni volta che necessario.
Per ottenere lo stato di tutti i sensori e relay contemporaneamente, puoi utilizzare l’endpoint /status. Questo restituisce un JSON completo con tutte le informazioni disponibili del dispositivo in un’unica chiamata, riducendo il numero di richieste HTTP necessarie.
Controllo dei relay e degli switch
L’operazione più pratica che potrai eseguire tramite le API Shelly è il controllo on/off dei relay. Questo si ottiene inviando una richiesta POST all’endpoint appropriato con un parametro specifico nel corpo della richiesta.
Per accendere o spegnere il primo relay, invia una richiesta POST a /relay/0?turn=on oppure a /relay/0?turn=off. Il dispositivo elaborerà la richiesta e cambierà lo stato del relay di conseguenza. La risposta confermerà l’avvenuta esecuzione dell’operazione.
Se il tuo dispositivo è un Shelly Plug S o un modello con multiple uscite, dovrai specificare l’indice corretto: /relay/1 per il secondo relay, /relay/2 per il terzo, e così via. Ogni indice corrisponde a un circuito fisico diverso sul dispositivo.
Per i dispositivi di tipo dimmer, come lo Shelly Dimmer 2, il controllo della luminosità segue una logica simile ma utilizza parametri diversi. L’endpoint /roller/0 o /dimmer/0 accetta un parametro di livello (da 0 a 100) per impostare la luminosità desiderata.
Esempio di accensione tramite riga di comando
Se desideri testare il controllo del relay direttamente dal terminale del tuo computer, puoi utilizzare curl. Apri il terminale e digita:
- Per accendere un relay: curl http://INDIRIZZO_IP/relay/0?turn=on
- Per spegnere un relay: curl http://INDIRIZZO_IP/relay/0?turn=off
- Per commutare lo stato (toggle): curl http://INDIRIZZO_IP/relay/0?toggle=true
Sostituisci INDIRIZZO_IP con l’effettivo indirizzo IP del tuo dispositivo. Se hai impostato un’autenticazione, aggiungi le credenziali all’intestazione della richiesta.
Lettura dei dati energetici
I dispositivi Shelly dotati di misurazione energetica (come lo Shelly 2PM, lo Shelly Pro 2 o lo Shelly EM) offrono dati dettagliati sul consumo elettrico. Questi dati sono fondamentali per monitoraggio energetico, analisi dei costi e automazioni basate sul consumo.
L’endpoint /emeter/0 restituisce un JSON con i seguenti campi principali:
- voltage: la tensione in volt del circuito monitorato.
- current: la corrente in ampere assorbita dal carico collegato.
- power: la potenza attiva in watt in tempo reale.
- total: l’energia totale consumata dall’accensione del dispositivo, espressa in kilowattora.
Per dispositivi a doppio canale come lo Shelly 2PM, esistono due endpoint separati: /emeter/0 per il primo canale e /emeter/1 per il secondo. Ogni canale fornisce dati indipendenti, permettendo un monitoraggio dettagliato di carichi diversi.
I dati energetici possono essere interrogati a intervalli regolari per costruire grafici storici del consumo. Molti utenti integrano questi dati con strumenti come InfluxDB e Grafana per creare dashboard di monitoraggio professionali.
Configurazione remota del dispositivo
Oltre alla lettura dello stato e al controllo dei relay, le API Shelly permettono di modificare le impostazioni del dispositivo in modo remoto. Questa funzionalità è potente ma richiede cautela, poiché modifiche errate possono rendere il dispositivo inaccessibile.
Per ottenere tutte le impostazioni correnti, invia una richiesta GET a /settings. La risposta contiene un JSON con ogni parametro configurabile: nome del dispositivo, impostazioni Wi-Fi, modalità di funzionamento dei relay, impostazioni di input, automazioni, e molto altro.
Per modificare le impostazioni, invia una richiesta POST a /config con il corpo della richiesta contenente solo i parametri che desideri cambiare. Non è necessario includere tutti i campi: solo quelli specificati verranno aggiornati. Ad esempio, per rinominare un dispositivo:
- Invia una richiesta POST a /config
- Nel corpo della richiesta, inserisci il JSON {“device”:{“name”:”NuovoNome”}}
- Il dispositivo applicherà la modifica e risponderà con conferma.
Altre impostazioni comuni modificabili tramite API includono:
- input_filter: attiva o disattiva il filtro anti-rebounce per gli ingressi fisici.
- rfid_enabled: abilita la funzione RFID se supportata dal modello.
- metered: configura se un relay deve essere considerato come carico misurato.
- max_return_power: imposta il limite di potenza per carichi induttivi.
Integrazione con Home Assistant
Uno dei modi più popolari per sfruttare le API Shelly è attraverso l’integrazione con Home Assistant, la piattaforma open source di domotica. Home Assistant supporta nativamente i dispositivi Shelly tramite il componente “Shelly for Home Assistant”, che utilizza le API REST per comunicare con ogni dispositivo.
Per configurare l’integrazione:
- Assicurati che Home Assistant e i dispositivi Shelly siano sulla stessa rete LAN.
- Nel pannello di configurazione di Home Assistant, vai su Integrations e aggiungi una nuova integrazione Shelly.
- Inserisci l’indirizzo IP del dispositivo o utilizza la scoperta automatica (mDNS) per trovare tutti i dispositivi Shelly sulla rete.
- Se richiesto, inserisci username e password configurati sul dispositivo.
- Home Assistant rileverà automaticamente relay, sensori di temperatura, contatori energetici e altri componenti disponibili.
Una volta integrata, ogni entità Shelly diventa controllabile direttamente dall’interfaccia di Home Assistant, automatizzabile con le automazioni native e visualizzabile nelle dashboard personalizzate.
Webhook e eventi in tempo reale
I dispositivi Shelly supportano i webhook, una funzionalità che permette di inviare notifiche HTTP a un server esterno quando si verificano eventi specifici. Questo è particolarmente utile per integrare i dispositivi Shelly con servizi come Node-RED, OpenHAB o server personalizzati.
Gli eventi che possono attivare un webhook includono:
- Cambio di stato del relay (da acceso a spento e viceversa).
- Azione su un ingresso fisico (premuto, rilasciato, toggle).
- Superamento di una soglia di potenza o corrente.
- Variazione della temperatura per i dispositivi con sensore integrato.
Per configurare un webhook, accedi al pannello web del dispositivo e naviga alla sezione Webhook. Inserisci l’URL del tuo server ricevente, il metodo HTTP (GET o POST) e, se necessario, i parametri da inviare nel corpo della richiesta. Il dispositivo Shelly invierà automaticamente una richiesta HTTP ogni volta che si verifica l’evento configurato.
WebSocket per aggiornamenti in tempo reale
Oltre alle chiamate API tradizionali basate su richieste HTTP, i dispositivi Shelly supportano le WebSocket. Questa funzionalità permette di ricevere aggiornamenti in tempo reale senza dover effettuare polling continuo. Una volta stabilita la connessione WebSocket al dispositivo, ogni cambiamento di stato viene inviato automaticamente al client connesso.
L’endpoint per la WebSocket è ws://INDIRIZZO_IP/shelly?events=1. Sostituisci INDIRIZZO_IP con l’indirizzo del tuo dispositivo. Una volta connesso, riceverai messaggi JSON ogni volta che un parametro del dispositivo cambia. Questo approccio è molto più efficiente rispetto al polling periodico e riduce il carico sulla rete.
I client WebSocket sono particolarmente indicati per dashboard in tempo reale, notifiche immediate e sistemi di automazione che reagiscono istantaneamente ai cambiamenti dello stato dei dispositivi.
Errori comuni e risoluzione dei problemi
Nell’utilizzo delle API Shelly potresti incontrare alcuni problemi ricorrenti. Ecco i più comuni e come risolverli.
Impossibilità di raggiungere il dispositivo: verifica che il dispositivo sia ancora connesso alla rete Wi-Fi e che l’indirizzo IP non sia cambiato. Se il router assegna indirizzi IP dinamici, configura un reservation DHCP per garantire che il dispositivo mantenga sempre lo stesso IP.
Errori di autenticazione: se ricevi un errore 401 Unauthorized, verifica username e password. Ricorda che le credenziali sono case-sensitive. Se hai dimenticato la password, dovrai resettare il dispositivo alle impostazioni di fabbrica premendo il pulsante fisico per circa dieci secondi.
Risposte vuote o incomplete: assicurati di utilizzare l’endpoint corretto per il tuo modello specifico. Non tutti i dispositivi supportano tutte le funzionalità. Controlla la documentazione ufficiale del tuo modello su shelly.com per verificare quali endpoint sono disponibili.
Latenza elevata: se le risposte API sono lente, verifica la qualità del segnale Wi-Fi del dispositivo. Un segnale debole può causare ritardi significativi nelle comunicazioni. Considera l’uso di un ripetitore Wi-Fi o il posizionamento di un access point più vicino al dispositivo.
Conclusione
Le API REST dei dispositivi Shelly rappresentano uno strumento potente per chi desidera andare oltre il controllo base e integrare la domotica in progetti personalizzati. Dalla semplice lettura dello stato al controllo remoto, dal monitoraggio energetico all’integrazione con piattaforme di automazione come Home Assistant, le possibilità sono vaste e flessibili.
La chiave per un utilizzo efficace delle API Shelly risiede nella comprensione della struttura degli endpoint, nella corretta gestione dell’autenticazione e nella scelta del metodo di comunicazione più adatto alle proprie esigenze. Sia che tu preferisca chiamate HTTP tradizionali, WebSocket in tempo reale o webhook reattivi, i dispositivi Shelly offrono la flessibilità necessaria per adattarsi a qualsiasi scenario domotico.
Per approfondimenti tecnici dettagliati, consulta la documentazione ufficiale disponibile sul sito Shelly e la community attiva su Shelly Community, dove migliaia di utenti condividono progetti, script e soluzioni creative per sfruttare al massimo questi dispositivi.
