Scopi della guida:
Concetti affrontati:
|
Componenti software utilizzate:
Prerequisiti:
Dispositivi fisici utilizzati:
|
GUIDA INDICATA A UTENTI CON ISTALLAZIONE: |
|
NOTE E DISCLAIMER
|
|
| Revisione guida: 1.2 | |
Abstract
Uno dei grandi vantaggi della linea Shelly (rispetto per esempio alla diretta rivale, la ITEAD Sonoff, o altre analoghe) è quella di installare sui propri componenti di firmware in grado di offrire supporto allo standard MQTT.
MQTT (Message Queue Telemetry Transport) è uno standard solitamente apprezzato in domotica personale per prestazioni e semplicità; la sua adozione consente di integrare con estrema facilità (e nel modo preferibile, il Local Push) qualunque componente che lo utilizzi con i più svariati ambienti operativi quali, in domotica, gli HUB personali.
Fino ad oggi abbiamo sempre consigliato e ritenuto migliore l’integrazione via MQTT per una questione di performance, di libertà nei confronti di integrazioni che prevedessero la presenza del cloud (vedi approfondimento). Con i nuovi device di seconda generazione abbiamo avuto modo di apprezzare l’introduzione dello standard RPC, evidenziando come sia ora possibile controllare e monitorare i nostri Shelly sempre nello stesso modo ma utilizzando, volendo, tecnologie e protocolli diversi, per lo più in modalità Local Push.
Vista questa uniformità, vista la maturità raggiunta dall’integrazione Shelly già inclusa in Home Assistant e viste le diversità a livello di API che rendono di fatto più contorta l’integrazione via MQTT, per questi device noi di inDomus consigliamo di utilizzare quindi l’integrazione nativa di Shelly su Home Assistant.
Nonostante ciò, ci teniamo a mostrarvi come integrare il device utilizzando MQTT (quindi, uno dei possibili RPC Channel previsti da questi nuovi componenti) sia per mostrarvi effettivamente di cosa stiamo parlando che per cercare di rendere più chiaro il da farsi nel caso in cui qualcuno volesse optare per questa soluzione.
Assunti
Per l’implementazione della presente guida è necessario che sulla propria rete sia presente un broker MQTT; in primis però è importante capire come MQTT funzioni: per far questo, è importante la lettura di questa scheda scritta appositamente per capire il ruolo del broker MQTT all’interno della propria rete – a prescindere dai componenti che supportino MQTT presenti nel proprio ambiente.
Per dotarsi di un broker e per attivare le funzioni client MQTT su Home Assistant si rimanda a questa guida.
Si assume inoltre che lo/gli Shelly in questione siano già stati configurati fornendogli accesso alla propria rete Wi-Fi, cosa che può essere fatta sia tramite l’app Shelly Cloud (per Android e iOS) sia attraverso l’access point da essi fornito a fronte di un reset alle impostazioni di fabbrica.
Si parte
Modalità LAN e MQTT
La prima cosa da fare è connettere il nostro Shelly al broker MQTT presente sulla nostra rete (must-have indicato negli assunti). Per farlo è necessario attivare la modalità LAN disponibile sul firmware dell’unità, fornire le coordinate del broker (e gli eventuali username e password di autenticazione).
Per effettuare la configurazione è necessario utilizzare un qualsiasi browser tramite il quale collegarsi all’interfaccia web offerta dall’attuatore. Non è possibile effettuare questa configurazione tramite app mobile, e il perché è semplice: alcune impostazioni (tipo questa) sull’app semplicemente non figurano.
Avremo dunque bisogno dell’indirizzo IP a cui collegarci: lo si potrà trovare facilmente tramite l’interfaccia web del proprio modem/router oppure con un qualsiasi tool di scansione reti (eg. Fing). Se l’IP assegnato sarà (per esempio) il 192.168.1.100, l’interfaccia web alla quale collegarsi sarà disponibile all’indirizzo http://192.168.1.100.
Una volta connessi apparirà un’interfaccia estremamente elementare. Tappare sulla voce “Network“:
Per quanto riguarda l’indirizzo e porta del server, esso deve essere espresso in termini di IP:PORTA (eg. 192.168.1.1:1883). La porta standard del broker MQTT è 1883 (a meno che non l’abbiate modificata). Per come abbiamo ideato questa integrazione lasciamo abilitata la sola voce relativa a “Generic status update over MQTT“: Ci servirà per definire lo state_topic dell’entità MQTT.
Nel campo sotto “Connection type” indicare il “nome” MQTT dell’attuatore. La scelta del nome è personale; si tratta di un passaggio cardine rispetto alla configurazione che effettueremo, successivamente, su Home Assistant.
Una volta completata la configurazione, cliccare su “SAVE“.
Modalità d’uso dello Shelly
Prima di passare a Home Assistant, alcune considerazioni lato Shelly sono doverose.
Trattandosi di un attuatore a singolo canale, esso viene tipicamente utilizzato per controllare un punto luce, una presa elettrica o comunque un carico generico: va da sé che l’integrazione da realizzare sia questa, ovvero dotarsi di uno “Switch” per attivare/disattivare tale interruttore.
Nei paragrafi che seguono scopriremo come integrare via MQTT queste funzionalità.
| N.b. A differenza del modello Shelly Plus 1PM, lo Shelly 1 non dispone di sensori rilevazione di assorbimento elettrico né sensori di temperatura e surriscaldamento, quindi alla fine l’integrazione risulta piuttosto basica. |
Home Assistant
Vediamo ora come provvedere all’integrazione dell’attuatore, ipotizzando l’uso come “Relay”, nonché come sensori di diversa natura sopra descritti.
Relè
Ipotizziamo di aver collegato un carico al singolo canale d’uscita dello Shelly 1 e un pulsante/interruttore murale per controllare il canale.
L’obiettivo dell’integrazione dev’essere dunque quello di dotarsi, presso Home Assistant, di uno “Switch” il quale non solo agisca sullo Shelly in modo da poter attivarne il relè, ma anche da visualizzarne lo stato operativo aggiornato in caso di variazione effettuata tramite i pulsanti/interruttori murali. Allo scopo utilizzeremo la piattaforma “MQTT Switch“.
In passato abbiamo già visto come creare entità di tipo Light o Switch utilizzando platform MQTT. Vediamo di seguito come configurare un’entità di tipo switch utilizzando anche l’availability_topic, importantissimo parametro che ci permette di conoscere se effettivamente il device sia connesso al nostro broker o meno.
Cominciamo a definire la nostra entità modificando, come sempre, il nostro file di configurazione YAML di Home Assistant:
mqtt:
switch:
- name: "Switch"
I parametri che ci interessa aggiungere ora sono sono i seguenti:
- command_topic per impartire il comando on/off al relè dell’attuatore;
- state_topic per il recupero dello stato dello stato del relè dell’attuatore;
- availability_topic per sapere se il device è connesso al broker.
Analizziamoli e capiamoli.
COMMAND TOPIC
Partiamo dal command_topic. Alla luce di quanto detto in precedenza in merito al nome MQTT dell’attuatore, ipotizziamo ora che il suo nome sia “nomedevice“. Tipicamente, per comandare via MQTT il nostro attuatore dovremmo pubblicare un topic di comando così composto:
NOME-SHELLY/rpc payload
dove NOME-SHELLY/rpc è il topic di comando e payload è il “carico utile” espresso in notazione JSON contenente ciò che l’attuatore, ricevendolo, debba fare.
| N.b. Si noti come il topic di comando (“NOME-SHELLY/rpc“) sia a sua volta composto da un prefisso contenente il nome device (“NOME-SHELLY“) e il suffisso prefissato “rpc“. Questo perché coi modelli “Plus” di Shelly i comandi (e le telemetrie) MQTT hanno nomi così specificamente concepiti. |
Per quanto riguarda il payload da affiancare al topic, i parametri da indicare sono svariati:
- id: in questo caso può assumere qualsiasi valore. Dato che stiamo configurando uno switch acceso/spento, in questo caso abbiamo usato “switch-on” oppure “switch-off” a seconda dell’operazione che andremo a fare);
- src: sarà la telemetria MQTT che verrà pubblicata dal device in risposta al comando (detta anche “response frame”). In questo caso useremo “NOME-SHELLY/status“;
- method: è il metodo da utilizzare per impostare lo stato dello switch;
- params: è il JSON con i parametri che verrà passato in input al metodo. In questo caso è composta da:
- id: è l’id del canale “0” (se per esempiio fossero stati due avremmo avuto switch 0 e switch 1);
- on: è un parametro booleano e serve per indicare lo stato acceso (true) o spento (false).
Il payload JSON per l’accensione quindi sarà:
{
"id":"switch-on",
"src":"NOME-SHELLY/status",
"method":"Switch.Set",
"params":{
"id":0,
"on":true
}
}
mentre il payload JSON per lo spegnimento quindi sarà:
{
"id":"switch-on",
"src":"NOME-SHELLY/status",
"method":"Switch.Set",
"params":{
"id":0,
"on":false
}
}
In buona sostanza per accendere via MQTT il nostro Shelly 1 Plus dovremo pubblicare sul broker MQTT il seguente topic di comando:
NOME-SHELLY/rpc {“id”:”switch-on”,”src”:”NOME-SHELLY/status”,”method”:”Switch.Set”,”params”: {“id”:0,”on”:true}}
mentre, per spegnerlo:
NOME-SHELLY/rpc {“id”:”switch-on”,”src”:”NOME-SHELLY/status”,”method”:”Switch.Set”,”params”: {“id”:0,”on”:false}}
Torniamo quindi alla configurazione YAML per l’integrazione su Home Assistant. Dovremo quindi aggiungere la seguente porzione di codice:
command_topic: "NOME-SHELLY/rpc"
payload_on: '{"id":"switch-on","src":"NOME-SHELLY/status","method":"Switch.Set","params": {"id":0,"on":true}}'
payload_off: '{"id":"switch-off","src":"NOME-SHELLY/status","method":"Switch.Set","params": {"id":0,"on":false}}'
Passiamo oltre.
STATE TOPIC
Ora abbiamo bisogno dello state_topic per recuperare lo stato istantaneo dello switch: per farlo utilizzeremo il “generic status update” per due motivi:
- la struttura del payload è molto semplice rispetto al “frame di notifica”;
- nel momento in cui si sollecita il relè con pulsante esterno, non viene pubblicato alcun “response frame”.
Andremo quindi ad indicare in configurazione a quale telemetria MQTT Home Assistant dovrà “dare ascolto” (ovvero “sottoscrivere”) per conoscere lo stato istantaneo dello Shelly. A fronte della pubblicazione di tale comando, infatti, lo Shelly provvederà a pubblicare una telemetria con topic “NOME-SHELLY/status/switch:0” associato a un payload JSON contenente lo stato:
{
"id":0,
"source":"WS_in",
"output":true,
"temperature":{
"tC":54.0,
"tF":129.2
}
}
Come possiamo vedere, lo stato dello switch viene restituito nella chiave “output” del blocco JSON. Andremo ad estrarre tale informazione tramite un template come indicato a seguire, andando così a comporre un altro piccolo pezzettino della nostra configurazione Home Assistant:
state_topic: "NOME-SHELLY/status/switch:0"
value_template: "{{ 'true' if value_json.output == true else 'false' }}"
state_on: 'true'
state_off: 'false'
Concludiamo ora la configurazione prendendo in analisi l’availability topic.
AVAILABILITY TOPIC
Tale telemetria MQTT è solitamente composta dalla parte topic (“NOMESHELLY/online”) e il payload, il quale può assumere valore true o false. Andiamo quindi ad aggiungere questa informazione alla nostra configurazione aggiungendo anche la forzatura a “false” per quanto riguarda il parametro optimistic_mode:
availability_topic: "NOME-SHELLY/online"
payload_available: 'true'
payload_not_available: 'false'
optimistic: false
Abbiamo praticamente finito.
Configurazione finale
mqtt:
switch:
- name: "Switch"
command_topic: "NOME-SHELLY/rpc"
payload_on: '{"id":"switch-on","src":"NOME-SHELLY/status","method":"Switch.Set","params": {"id":0,"on":true}}'
payload_off: '{"id":"switch-off","src":"NOME-SHELLY/status","method":"Switch.Set","params": {"id":0,"on":false}}'
state_topic: "NOME-SHELLY/status/switch:0"
value_template: "{{ 'true' if value_json.output == true else 'false' }}"
state_on: 'true'
state_off: 'false'
availability_topic: "NOME-SHELLY/online"
payload_available: 'true'
payload_not_available: 'false'
optimistic: false
La configurazione dell’entità switch termina in pratica qui.
Availability topic
Veniamo ora al punto critico…l’availability_topic.
Purtroppo, diversamente da quanto accadeva con i device di prima generazione non possiamo pubblicare un topic di “announce” per farci restituire lo stato di connessione dal broker. Questa cosa non va affatto bene perché, finché è il device a scollegarsi e ricollegarsi, il topic viene sì pubblicato regolarmente, ma se per caso riavviamo Home Assistant, allora ci perdiamo lo stato di connessione del device con conseguente “indisponibilità” dell’entità. Si potrebbe ovviare a questo forzando (sempre lato Home Assistant) la pubblicazione del topic con retain (diverso da quello standard per evitare un loop infinito), ma dovremmo comunque pubblicare un topic per recuperare lo stato reale dello switch.
Quindi, vista la situazione, abbiamo pensato fosse meglio evitare la retain e recuperare gli stati di cui abbiamo bisogno tramite una sorta di polling, simulando quanto avveniva con i vecchi device.
Vi mostriamo quindi di seguito come abbiamo pensato noi questa automazione. Innanzi tutto dobbiamo fare in modo che scatti all’avvio di Home Assistant e che poi giri ogni “tot” secondi per recuperare lo stato del device.
automation:
- id: shelly_ng_announce
alias: "Shelly-NG Announce"
trigger:
# Avvio di Home Assistant
- platform: homeassistant
event: start
# Polling ogni 30 secondi
- platform: time_pattern # Polling Status
seconds: "/30"
Ora abbiamo bisogno di indicare all’automazione cosa fare nelle sue action. In questo caso abbiamo pensato di introdurre una “choose”. Come azione di default facciamo pubblicare il metodo “Shelly.GetStatus” per recuperare lo stato del device pubblicando il solito topic…
NOME-SHELLY/rpc
…ma con payload diverso ovviamente:
{
"id":"NOME-SHELLY-status",
"src":"NOME-SHELLY/shellystatus",
"method":"Shelly.GetStatus"
}
Come si nota facilmente abbiamo impostato come “src” il valore “NOME-SHELLY/shellystatus“. Come già abbiamo visto prima, questo sta a significare che il topic di response sarà “NOME-SHELLY-shellystatus/rpc“. Useremo quindi questo topic come ulteriore trigger dell’automazione ed è qui che ci tornerà utile la choose: andremo infatti a definire un ramo di scelta utilizzando come condition proprio questo topic e dove potremo recuperare sia lo stato di connessione al broker MQTT che lo stato dello switch forzando la pubblicazione dei due topic così come definito nell’entità creata prima.
Ed ecco l’automazione “completa”:
automation:
- id: shelly_ng_announce
alias: "Shelly-NG Announce"
trigger:
# L'automazione scatta al termine dello start di Home Assistant
- platform: homeassistant
event: start
# Il secondo trigger occorre per fare un polling cadenzato ogni 30s
- platform: time_pattern # Polling Status
seconds: "/30"
# Il terzo trigger scatta quando viene pubblicato il topic di response dopo la chiamata...
# ...al metodo "Shelly.GetStatus" avente come src -> "NOME-SHELLY/shellystatus"
- platform: mqtt
topic: "NOME-SHELLYshellyplu/shellystatus/rpc"
action:
- choose:
- alias: "NOME-SHELLY Announce"
conditions:
- condition: template
value_template: "{{ trigger.topic == 'NOME-SHELLY/shellystatus/rpc' }}"
sequence:
# Pubblichiamo l'availability_topic così come lo pubblica il device quando si collega al broker
- service: mqtt.publish
data:
topic: "NOME-SHELLY/online"
# Viene pubblicato il payload true/false a seconda dello stato di connessione al broker MQTT
payload: >
{% if trigger.payload_json.result.mqtt.connected == true %}
true
{% else %}
false
{% endif %}
- service: mqtt.publish
# Pubblichiamo lo state_topic così come definito nell'entità MQTT
data:
topic: "NOME-SHELLY/status/switch:0"
# con parte del JSON che permetta di recuperare lo stato con il template definito nell'entità MQTT
payload: >
{% if trigger.payload_json.result['switch:0'].output == false %}
{"output":false}
{% else %}
{"output":true}
{% endif %}
# Nella default ci entra quando i trigger sono quelli dello start di HA e del polling
default:
- service: mqtt.publish
data:
topic: "NOME-SHELLY/rpc"
payload: '{"id":"NOME-SHELLY-status", "src":"NOME-SHELLY/shellystatus", "method":"Shelly.GetStatus"}'
# Definiamo mode "parallel" perché potrebbe scattare n volte mentre sta già girando
mode: parallel
Ovviamente, questa configurazione andrà adeguata in presenza di più elementi Shelly Plus/Pro da integrare, ricordandosi di:
- replicare il ramo “choose”;
- aggiungere la publish nel ramo default.
Le API Shelly di seconda generazione: una panoramica tecnica
|
⚠️ Se di Home Assistant ne sai poco ma sei interessato a capirne di più, ti suggeriamo di partire da qui. |
| Questa pagina è redatta, manutenuta e aggiornata dallo staff di inDomus, un gruppo di persone molto diverse tra loro che trovi, per domande e supporto, sul forum e sulla chat del sito. Se ti sei perso, a tua disposizione c'è la mappa. |