community italiana di domotica personale
 
Integrare Shelly i3 a Home Assistant via MQTT
Guide

Integrare Shelly i3 a Home Assistant via MQTT

 , , , , ,
Scopi della guida:
  • Integrare il sensore Shelly i3 all’HUB di domotica personale Home Assistant e utilizzarlo per innescare eventuali automazioni
  • Livello di difficoltà: bassa
  • Categoria d’integrazione: Local Push
Concetti affrontati:
  • Configurazione software
Componenti software utilizzate:
Prerequisiti:
  • Home Assistant configurato e funzionante
  • Componente/i Shelly da integrare già configurato/i in Wi-Fi
Dispositivi fisici utilizzati:
GUIDA INDICATA A UTENTI CON ISTALLAZIONE:
Ambienti Home Assistant HassOS-Supervised-Core
NOTE E DISCLAIMER
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata e realizzata SOLO da personale qualificato;
  • qualsiasi modifica non prevista attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno infatti puro scopo didattico) e fa decadere garanzia, omologazioni e certificazioni di qualità; dei dispositivi interessati;
  • tutte le tecniche descritte si intendono applicate a software e firmware aggiornati alle ultime versioni disponibili;
  • questa pagina è materialmente scritta e manutenuta da più individui: non ci si aspetti né si pretenda un supporto personale. In caso di difficoltà, chiedere supporto alla community sul nostro forum o sulla nostra chat;
  • gli articoli di inDomus sono totalmente indipendenti e non sponsorizzati. Se mai questo cambiasse, verrà segnalato chiaramente sulle pagine oggetto di sponsorizzazione;
  • se hai bisogno di orientarti, c'è la mappa.
Revisione guida: 1.4

Shelly Button1 - Home Assistant

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 particolarmente 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.

Home Assistant è uno degli HUB personali con i quali è più semplice far dialogare i componenti Shelly sfruttando il protocollo MQTT: in questa guida vedremo come predisporre le funzionalità dello Shelly i3 e come configurare Home Assistant affinché lo integri in tutte le sue funzioni.

N.b. Sebbene esistano componenti specifici per integrare “facilmente” i device della linea Shelly (come per esempio quello nativo di Home Assistant), la metodologia MQTT qui descritta rimane quella più comprovatamente sicura, efficiente e dai risultati più certi nel tempo – nonché quella che consigliamo caldamente di adottare. In alternativa, è possibile utilizzare anche il componente ShellyForHASS (vedi guida) o altri.

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 del componente. 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 “Internet & Security“:

Shelly Cloud - Intenet e security

Entrare poi nella sezione “Advanced – Developer Settings“.
La schermata che segue consente di inserire username, password e indirizzo (e porta) del proprio broker MQTT:

Shelly - Configurazione MQTT

Per quanto riguarda l’indirizzo e porta del server, esso deve essere espresso in termini di IP:PORTA (eg. 192.168.1.100:1883). La porta standard del broker MQTT è 1883 (a meno che non l’abbiate modificata).

Il resto va impostato come da configurazione (raccomandiamo la retain non abilitata e la QoS a 0 oppure a 1 (addirittura 2, in caso di specifiche necessità).

Cliccare poi su “Use Custom MQTT Prefix” per definire il “nome” MQTT del componente:

Shelly - MQTT - Custom MQTT Prefix

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“.

N.b. Attivare MQTT – quindi la cosiddetta modalità “LAN” di fatto disconnette il componente dal cloud Shelly, il che non consentirà più di controllare l’unità via app (da remoto, perché localmente continuerà a funzionare). Tale comportamento è più normale: il controllo remoto sarà garantito attraverso Home Assistant e non più dall’app Shelly Cloud.

Modalità d’uso dello Shelly

Prima di passare a Home Assistant, alcune considerazioni lato Shelly sono doverose.

Shelly i3Come noto, Shelly i3 serve per domotizzare pulsanti e interruttori (tipicamente murali) allo scopo di veicolarne le gesture in domotica, le quali possono essere (per ognuno dei tre diversi input):

  • interruttore acceso;
  • interruttore spento;
  • pulsante pressione singola breve;
  • pulsante pressione singola lunga;
  • pulsante doppia pressione breve;
  • pulsante tripla pressione breve;
  • pulsante pressione breve seguita da pressione lunga;
  • pulsante pressione lunga seguita da pressione breve.

Tali eventi vengono pubblicati sotto forma di topic MQTT con relativi payload:

shellies/NOME_SHELLY/input/x 0
shellies/NOME_SHELLY/input/x 1
shellies/NOME_SHELLY/input_event/x {"event":"S","event_cnt":1}
shellies/NOME_SHELLY/input_event/x {"event":"L","event_cnt":1}
shellies/NOME_SHELLY/input_event/x {"event":"SS","event_cnt":1}
shellies/NOME_SHELLY/input_event/x {"event":"SSS","event_cnt":1}
shellies/NOME_SHELLY/input_event/x {"event":"SL","event_cnt":1}
shellies/NOME_SHELLY/input_event/x {"event":"LS","event_cnt":1}

Si noti come la x indicherà il canale:

  • assumerà valore 0 se la gesture è intercettata sul canale 1;
  • assumerà valore 1 se la gesture è intercettata sul canale 2;
  • assumerà valore 2 se la gesture è intercettata sul canale 3.

Va da sé che Home Assistant (o comunque qualunque HUB personale dotato di client MQTT) possa, per ognuno dei vari binomi topic+payload gestire delle automazioni tramite essi innescate.

Vetrina - Offerte del giorno

Mettiamo per esempio di voler invertire lo stato di un punto luce (spegnerlo se è acceso / accenderlo se spento) tramite la singola rapida pressione di un pulsante collegato a uno dei tre input dello Shelly i3: basterà utilizzare il terzo binomio di cui sopra come trigger e innescare il servizio light.toggle puntando all’entità luce che ci interessa. Facilissimo,

Home Assistant

Vediamo ora come provvedere all’integrazione del sensore.

Questa guida, a differenza di quasi tutte le altre dedicate all’integrazione di componenti Shelly via MQTT, non genererà alcuna entità di tipo “Switch” o “Binary Sensor” (come si potrebbe immaginare) – si andrà, infatti, ad integrare direttamente la(e) funzionalità del sensore, intese come la possibilità di innescare automazioni.

L’approccio che descriveremo sarà duplice: la definizione di tante automazioni quante sono le gesture inviabili dal sensore, oppure una singola automazione (per canale) che, in base alla gesture, effettui determinate azioni.

Il primo scenario viene utile quando per esempio si voglia maggiore leggibilità oppure si voglia la possibilità di disattivare, selettivamente (sia in modo manuale che programmatico), una o più delle singole automazioni; il secondo, invece, riduce a una singola automazione che, per alcuni, può sembrare il modo più corretto e pulito di agire.

Entrambi li scenari saranno calati rispetto all’uso di interruttori o di pulsanti.

Interruttori

Nel caso di un interruttore gli stati possibili sono solo due: acceso o spento. Tali stati inviano su MQTT due possibili topic, rispettivamente:

shellies/NOME_SHELLY/input/x 1

shellies/NOME_SHELLY/input/x 0

dove il valore NOME_SHELLY è ovviamente da personalizzare: tale nome viene impostato nella fase di configurazione MQTT già effettuata in precedenza. Stesso discorso per la x, che indica il canale come sopra spiegato.

A fare la differenza sarà pertanto il payload, il quale verrà analizzato nel blocco condition.
Ecco le risultanti automazioni:

automation:
  - alias: "Shelly i3 - Canale 1 Acceso"
    trigger:
      platform: mqtt
      topic: "shellies/NOME_SHELLY/input/0"
    condition:
      condition: template
      value_template: "{{ trigger.payload == '1' }}"
    action: []

  - alias: "Shelly i3 - Canale 1 Spento"
    trigger:
      platform: mqtt
      topic: "shellies/NOME_SHELLY/input/0"
    condition:
      condition: template
      value_template: "{{ trigger.payload == '0' }}"
    action: []

Ovviamente sarà poi il blocco action di ogni automazione a terminare “cosa fare” a fronte della ricezione della gesture.

Le due automazioni proposte sono relative al canale 1; volendo implementarle anche sul canale 2 e 3 sarà sufficiente correggere il topic indicando, come suffisso, il numero corretto (1 per il canale 2, 2 per il canale 3).

Singola automazione

Vediamo ora come risolvere la questione con un’unica automazione:

automation:
  - alias: "Shelly i3 - Canale 1"
      trigger:
        platform: mqtt
        topic: "shellies/NOME_SHELLY/input/0"
      condition: []
      action:
      - service: script.turn_on
        data:
          entity_id:
            {% if trigger.payload == "1" %}
              script.shelly_i3_accensione
            {% elif trigger.payload == "0" %}
              script.shelly_i3_spegnimento
            {% endif %}

Questa automazione approccia in modo diverso: viene sempre eseguita quando viene ricevuto il topic telemetrico dallo Shelly i3, ma è nel blocco action a decidersi “cosa fare”: in base al payload, viene eseguito uno script (da definirsi) piuttosto che un altro.

L’automazione proposta è relativa al canale 1; volendo implementarla anche sul canale 2 e 3 sarà sufficiente correggere il topic indicando, come suffisso, il numero corretto (1 per il canale 2, 2 per il canale 3).

Pulsanti

Per scrivere quattro automazioni è necessario capire che il trigger sarà sempre lo stesso, ovvero la ricezione da parte del client MQTT di Home Assistant del topic MQTT

shellies/NOME_SHELLY/input_event/x

dove il valore NOME_SHELLY è ovviamente da personalizzare: tale nome viene impostato nella fase di configurazione MQTT già effettuata in precedenza. Stesso discorso per la x, che indica il canale come sopra spiegato.

A fare la differenza sarà pertanto il payload, il quale verrà analizzato nel blocco condition.
Ecco le risultanti automazioni:

automation:
  - alias: "Shelly i3 - Canale 1 - pressione corta"
    trigger:
      platform: mqtt
      topic: "shellies/NOME_SHELLY/input_event/0"
    condition:
      condition: template
      value_template: "{{ trigger.payload_json.event == 'S' }}"
    action: []

  - alias: "Shelly i3 - Canale 1 - pressione lunga"
    trigger:
      platform: mqtt
      topic: "shellies/NOME_SHELLY/input_event/0"
    condition:
      condition: template
      value_template: "{{ trigger.payload_json.event == 'L' }}"
    action: []

  - alias: "Shelly i3 - Canale 1 - pressione corta, doppia"
    trigger:
      platform: mqtt
      topic: "shellies/NOME_SHELLY/input_event/0"
    condition:
      condition: template
      value_template: "{{ trigger.payload_json.event == 'SS' }}"
    action: []

  - alias: "Shelly i3 - Canale 1 - pressione corta, tripla"
    trigger:
      platform: mqtt
      topic: "shellies/NOME_SHELLY/input_event/0"
    condition:
      condition: template
      value_template: "{{ trigger.payload_json.event == 'SSS' }}"
    action: []

  - alias: "Shelly i3 - Canale 1 - pressione corta, poi lunga"
    trigger:
      platform: mqtt
      topic: "shellies/NOME_SHELLY/input_event/0"
    condition:
      condition: template
      value_template: "{{ trigger.payload_json.event == 'LS' }}"
    action: []

  - alias: "Shelly i3 - Canale 1 - pressione lunga, poi corta"
    trigger:
      platform: mqtt
      topic: "shellies/NOME_SHELLY/input_event/0"
    condition:
      condition: template
      value_template: "{{ trigger.payload_json.event == 'LS' }}"
    action: []

Ovviamente sarà poi il blocco action di ogni automazione a terminare “cosa fare” a fronte della ricezione della gesture.

Le automazioni proposte sono relative al canale 1; volendo implementarle anche sul canale 2 e 3 sarà sufficiente correggere il topic indicando, come suffisso, il numero corretto (1 per il canale 2, 2 per il canale 3).

Singola automazione

Vediamo ora come risolvere la questione con un’unica automazione:

automation:
  - alias: "Shelly i3"
      trigger:
        platform: mqtt
        topic: "shellies/NOME_SHELLY/input_event/0"
      condition: []
      action:
      - service: script.turn_on
        data:
          entity_id:
            {% if trigger.payload_json.event == "S" %}
              script.shelly_i3_pressione_corta
            {% elif trigger.payload_json.event == "L" %}
              script.shelly_i3_pressione_lunga
            {% elif trigger.payload_json.event == "SS" %}
              script.shelly_i3_pressione_corta_doppia
            {% elif trigger.payload_json.event == "SSS" %}
              script.shelly_i3_pressione_corta_tripla
            {% elif trigger.payload_json.event == "SL" %}
              script.shelly_i3_pressione_corta_poi_lunga
            {% elif trigger.payload_json.event == "LS" %}
              script.shelly_i3_pressione_lunga_poi_corta
            {% endif %}

Questa automazione approccia in modo diverso: viene sempre eseguita quando viene ricevuto il topic telemetrico dallo Shelly Button1, ma è nel blocco action a decidersi “cosa fare”: in base al payload, viene eseguito uno script piuttosto che un altro.

L’automazione proposta è relativa al canale 1; volendo implementarla anche sul canale 2 e 3 sarà sufficiente correggere il topic indicando, come suffisso, il numero corretto (1 per il canale 2, 2 per il canale 3).

Comandi speciali

La presenza dello standard MQTT consente agli Shelly di essere configurati e interrogati tramite comandi diretti MQTT (nonché API REST via HTTP). A tale aspetto abbiamo dedicato la scheda che segue:

Shelly (1st gen), MQTT e HTTP: comandi utili


⚠️ 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.