Shelly, MQTT e HTTP: comandi utili

4 minuti di lettura
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

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):

POSTMAN - Shelly polling time

Al termine della procedura sarà possibile, tramite una nuova GET (come sopra spiegato), verificare che l’impostazione sia stata effettivamente attuata.


Shelly 1PM 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.


Telegram News Channel