| N.b. Le considerazioni e le spiegazioni presenti su questa scheda sono applicabili solo ai componenti della linea Shelly “Home Automation Systems” che montino una versione firmware uguale o superiore alla 1.4.3. Se non si ha dimestichezza con lo standard MQTT si consiglia, prima, una lettura attenta di questa scheda. |
La linea di componenti domotici Shelly “Home Automation Systems” è dotata di supporto nativo per lo standard MQTT (Message Queue Telemetry Transport) nonché per lo standard API Rest via HTTP. Si tratta di capacità tali da consentire a questi componenti una piena integrazione con i maggiori HUB personali in modalità Local (sia push che polling).
Al di là della possibilità di essere integrati, i loro comportamenti possono essere influenzati non solo dalla loro configurazione (solitamente attuata tramite l’app “Shelly Cloud” disponibile per iOS e Android) ma anche tramite comandi diretti instradati, appunto via MQTT o via HTTP.
- MQTT
- API REST (HTTP)
MQTT
| N.b. Coloro che utilizzino un broker MQTT Eclipse Mosquitto possono beneficiare, per la pubblicazione dei comandi che seguono (e non solo), delle spiegazioni di questa nostra guida. |
I topic di comando Shelly possono essere di gruppo oppure diretti destinati a uno specifico device. Il topic di comando di gruppo solitamente è dato da:
shellies/command + payload
mentre quello diretto:
shellies/nome-mqtt-dello-shelly/command + payload
Il PAYLOAD può essere una comunque stringa come un contenuto scritto in notazione JSON.
ANNOUNCE
Uno dei payload più noti da associare a command è ANNOUNCE. Il binomio così composto permette di richiedere forzosamente a tutti i componenti Shelly (che ovviamente abbiano MQTT attivo e siano collegati al proprio Broker di rete) il proprio stato, il quale viene fornito come telemetria MQTT di risposta.
Tutti i componenti Shelly possono essere configurati con un nome MQTT specifico (vedi esempio di configurazione), ma comunque tutti, quando si registrano al Broker, si iscrivono al topic di comando “shellies/command announce“. Questo significa che quando tale topic di comando viene pubblicato da un qualunque client presso il Broker, qualunque Shelly collegato ad esso risponderà con una telemetria.
Poniamo di avere sulla nostra rete uno Shelly di nome MQTT “shelly1-98F4ABF298AD” regolarmente registrato sul Broker. Pubblicando il topic di comando “shellies/command announce” presso il broker, lo Shelly risponderà (e con lui tutti gli altri eventualmente presenti) con due topic telemetrici di questo tipo:
shellies/shelly1-98F4ABF298AD/online true
shellies/announce {“id”:”shelly1-98F4ABF298AD”,”mac”:”98F4ABF298AD”,”ip”:”192.168.1.81″,”new_fw”:false, “fw_ver”:”20200206-083100/v1.5.10@e6a4205e”}
La prima telemetria (shellies/shelly1-98F4ABF298AD/online) semplicemente fornisce lo stato operativo dello Shelly. Il suo payload (una semplice stringa) valorizzato a TRUE indica infatti la presenza online dello Shelly. In caso invece sia down, interverrà l’LWT, fornendo un valore false (leggi di più relativamente all’LWT).
La seconda telemetria (shellies/announce) invece è più completa. Il suo payload è scritto in JSON e contiene le seguenti informazioni:
- id (nome MQTT identificativo dello shelly);
- mac (MAC address del dispositivo);
- ip (indirizzo IP attualmente assegnato al dispositivo);
- new_fw (di default riporta false; diventa true se è disponibile un nuovo aggiornamento firmware);
- fw_ver (indica la versione firmware a bordo del dispositivo.
La prima telemetria è particolarmente utile quando si integra un componente Shelly al proprio HUB personale: all’avvio di quest’ultimo, infatti, è possibile pubblicare un comando “shellies/command announce” e ottenere così lo stato istantaneo di tutti i componenti integrati (vedi esempio Home Assistant).
È altresì possibile inviare un comando ANNOUNCE diretto (e quindi non “di gruppo”) al componente – a patto di conoscerne il nome MQTT. Il comando è il seguente
shellies/nome-mqtt-dello-shelly/command announce
Rimanendo nel solco dell’esempio di cui sopra, il comando sarebbe:
shellies/shelly1-98F4ABF298AD/command announce
Le telemetrie di risposta saranno le stesse sopra descritte.
STATUS
Gli Shelly che utilizzano MQTT inviano ciclicamente e prescindere (o comunque ad ogni cambio di stato), un topic telemetrico di stato. Tale topic telemetrico termina sempre con “status” e varia da modello a modello. Per esempio, il modello Shelly RGBW2 eroga topic di questo tipo:
shellies/nome-mqtt-dello_shelly/color/o/status {“ison”:false,”mode”:”color”,”red”:255,”green”:63,”blue”:0,”white”:255,”gain”:100,”effect”:0,”power”:0.00,”overpower”:false}
Il payload contiene lo stato completo del dispositivo; la lista dei topic telemetrici di status specifici modello per modello è disponibile qui.
UPDATE FIRMWARE
Un comando utile per far sì che i dispositivi provvedano – se disponibile – ad aggiornare il proprio firmware in autonomia è UPDATE_FW.
Comando di gruppo:
shellies/command update_fw
mentre quello diretto:
shellies/nome-mqtt-dello-shelly/command update_fw
API REST (HTTP)
Oltre a precedentemente citato MQTT, esiste anche la possibilità di sfruttare le API REST via HTTP messe a disposizione anche localmente da Shelly, ampiamente documentate sul sito Shelly Cloud.
POLLING TIME
Particolarmente utile potrebbe essere la possibilità di cambiare l’intervallo di tempo in cui Shelly invia le proprie telemetrie cicliche MQTT (detto anche polling time). Di default, gli Shelly inviano il proprio stato ogni 30 secondi.
E’ possibile verificarlo andando a fare una richiesta di tipo GET (quindi anche da una semplice finestra del browser) utilizzando l’IP dello Shelly:
http://192.168.1.100/settings
La risposta (response) è sempre un payload JSON:
"mqtt":{
"enable":true,
"server":"192.168.1.10:1883",
"user":"",
"id":"shellyswitch25-B8ABAC",
"reconnect_timeout_max":60.000000,
"reconnect_timeout_min":2.000000,
"clean_session":true,
"keep_alive":60,
"max_qos":0,
"retain":false,
"update_period":30
},
Come si intuisce facilmente, il campo “update_period” comunica l’impostazione in essere.
Per variare l’impostazione (o altre) è necessario pubblicare una request di tipo POST (tramite un’app come POSTMAN o analoghe):
Al termine della procedura sarà possibile, tramite una nuova GET (come sopra spiegato), verificare che l’impostazione sia stata effettivamente attuata.
 |
ATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica agli Shelly (e più generalmente ai dispositivi ESP8266), per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti. |
