Il protocollo MQTT (Message Queue Telemetry Transport) è uno dei standard più apprezzati in domotica personale (e più genericamente nel mondo dell’IoT) per le sue caratteristiche di leggerezza, efficacia, semplicità d’uso e versatilità.
Sostanzialmente si basa su un modello di brokering, vale a dire l’esistenza di un soggetto (il broker) al quale tutti i client si registrano e verso il quale quest’ultimi inoltrano e ricevono messaggi per e da altri client anch’essi connessi. Per coloro che non avessero almeno un’infarinatura rispetto a questi meccanismi rimandiamo alla “metafora dei fari” descritta in questa nostra scheda.
Dando quindi per scontato un minimo di conoscenza dello standard MQTT, il tema che affrontiamo su questa scheda formativa è il troubleshooting, ovvero l’insieme di tecniche usate per risolvere problemi in questo ambito.
Per lo più MQTT si utilizza per far dialogare componenti dotati di tale client; se si immaginano gli HUB personali (Home Assistant, openHAB eccetera) come dei client essi stessi, è chiaro come MQTT diventi il canale ideale per l’integrazione locale dei più disparati componenti dotati di client MQTT (vedi per esempio quelli dotati di firmware Tasmota, oppure quelli nativamente dotati, come gli Shelly).
Talvolta però qualcosa va storto: effettuiamo per esempio una configurazione di integrazione via MQTT ma qualcosa non funziona. Come risolvere?
L’idea è quella di “mettersi in ascolto sul broker“, ovvero collegarsi al broker come ennesimo client MQTT e richiedere di poter leggere “qualsiasi cosa passi” – in termini di messaggi MQTT – in tempo reale. Questa scheda formativa assume che si stia utilizzando, come broker locale, il più noto tra essi: Eclipse Mosquitto, il quale può essere installato, come spiegato nella sua scheda, in molti, diversi ambiti operativi.
Per lo più quando le cose non funzionano nel 99% dei casi si tratta di una cattiva configurazione.
Troubleshooting
Installazione broker
L’installazione di Eclipse Mosquitto è abbastanza semplice; noi l’abbiamo documentata per:
- come container Docker su Linux Debian;
- come applicativo su Raspberry Pi dotato di sistema operativo Raspberry Pi OS (Raspbian);
- come container Docker su Raspberry Pi dotato di sistema operativo Raspberry Pi OS (Raspbian);
- Windows 10;
- Home Assistant OS (aka HassOS/HASSIO).
Più genericamente, gli utenti Home Assistant (qualsiasi tipo di installazione) possono beneficiare di quest’estesa guida dedicata al tema che illustra le varie tecniche di installazione di Eclipse Mosquito e, contestualmente, spiega come installare le funzionalità client MQTT utili all’HUB per comunicare tramite questo standard.
Configurazione componenti
Dopo essersi dotati di un broker MQTT (rappresentato dal suo indirizzo IP e da un’username e una password di accesso), ciò che è cruciale effettuare è la configurazione lato client dei vari dispostivi.
La configurazione ovviamente varia da dispositivo a dispositivo, quindi è impossibile documentare ogni singola realtà: come traccia “jolly”, abbiamo a disposizione una guida specifica che fornisce un’ulteriore infarinatura su questi concetti:
MQTT nella domotica personale: come configurare il broker e i vari client
Comandi utili
A questo punto abbiamo un broker, abbiamo dei client teoricamente connessi ad esso (teoricamente, perché non lo abbiamo ancora appurato): siamo pronti per incarnare noi stessi il ruolo di client utilizzando alcuni comandi pratici per metterci in ascolto dei messaggi in transito sul broker, pubblicarne di nostri e altro.
Per farlo utilizzeremo i cosiddetti “Mosquitto Client tools”, ovvero i tool da riga di comando di Mosquitto che vengono solitamente installati assieme al broker; l’esecuzione verrà effettuata tramite terminale, quindi se si utilizza Raspberry Pi OS è sufficiente collegarsi via SSH all’host che ospita il broker (oppure direttamente sul terminale del proprio computer, se si hanno localmente installati i tool); se si usa Home Assistant OS, è sufficiente collegarsi al terminale SSH.
Mettersi in ascolto
Per mettersi in ascolto sul broker si utilizza il comando mosquitto_sub. Tale comando prevede una grande quantità di possibili parametri; noi ne documenteremo una piccolissima parte utile alle funzioni base di troubleshooting.
Innanzitutto, mettiamoci d’accordo sui topic (se non si sa cosa siano si rimanda nuovamente alla scheda dedicata al componente MQTT): è possibile iscriversi richiedendo di mostrare tutto ciò che passa semplicemente indicando, come topic da sottoscrivere:
#
il quale appunto iscrive genericamente a tutto. Sempre usando il carattere jolly “#“, è possibile iscriversi a “radici” di topic; mettiamo di volere intercettare tutti i topic che inizino con “stat/” (tipicamente le telemetrie inviate da componenti dotati di firmware Tasmota), il topic da indicare sarà:
stat/#
mettiamo infine di voler iscriversi a un topic specifico, per esempio quello telemetrico che fornisce lo stato di un controller Shelly RGBW2:
shellies/shelly-rgbw2/color/0/status
e così via (n.b. il nome “shellyplug” ovviamente può variare in base alla configurazione MQTT del componente).
Capito questo, vediamo come si compone il comando base:
mosquitto_sub -v -h IP_DEL_BROKER -u USERNAME -P PASSWORD -t "TOPIC"
dove:
IP_DEL_BROKER | rappresenta l’indirizzo IP del Broker |
USERNAME | rappresenta il nome utente per accedere al broker |
PASSWORD | rappresenta la password dell’utente indicato |
TOPIC | rappresenta il topic al quale iscriversi. Attenzione: il topic va tra apici. |
Questo aprirà la console client MQTT e, man mano che i topic affluiranno sul broker, verranno visualizzati.
NOTA PER UTENTI HOME ASSISTANT: la pubblicazione di topic MQTT sul broker può essere effettuata in alternativa dall’interfaccia web dell’HUB presso la sezione “Configurazione” > “Dispositivi e servizi” > “MQTT” (la quale ovviamente appare solo e quando si sono correttamente configurati i servizi client MQTT sull’HUB), dopodiché cliccare su “Configura” per accedere all’interfaccia di ascolto. |
DATA E ORA
Se si vuole un’informazione un po’ più articolata, è possibile aggiungere data e ora della ricezione dei topic:
mosquitto_sub -v -h IP_DEL_BROKER -u USERNAME -P PASSWORD -t TOPIC -F '@Y-@m-@dT@H:@M:@S@z : %t : %x'
GREP
Mettiamo di voler intercettare una stringa specifica nel flusso massivo di messaggi che passano, diciamo “POWER“. Ci viene in aiuto il comando grep, il quale concatenato al comando di sottoscrizione filtra e quindi visualizza solo le righe contenenti la stringa indicata:
mosquitto_sub -v -h IP_DEL_BROKER -u USERNAME -P PASSWORD -t "#" | grep -a POWER
Il comando proposto si iscrive a tutti i messaggi che passano (grazie alla presenza di “-t +/#“), ma visualizza solo le righe contenenti la tringa “POWER“. Se avessi voluto visualizzare, diciamo, solo i messaggi contenenti “POWER” relativi ai messaggi con topic che inizia con “shellies“, avrei usato:
mosquitto_sub -v -h IP_DEL_BROKER -u USERNAME -P PASSWORD -t "shellies/#" | grep POWER
e così via.
COLORI (SU Raspberry Pi OS)
Se si utilizza Raspberry Pi OS (o genericamente Linux) è possibile anche aggiungere alle stringhe visualizzate dei colori automatici in modo da aumentare la leggibilità. Per farlo però prima è necessario installare una tantum l’applicativo ccze tramite il comando:
sudo apt-get install ccze
Installato l’applicativo ccze, il comando per iscriversi diventa:
mosquitto_sub -v -h IP_DEL_BROKER -u USERNAME -P PASSWORD -t TOPIC | xargs -d$'\n' -L1 sh -c 'date "+%d.%m.%Y %T $0"'| ccze -m ansi
Il comando proposto pubblica già data e ora; volendo, è possibile concatenare il comando di grep.
Pubblicare
Il controcampo di mosquitto_sub è mosquitto_pub, il comando utile alla pubblicazione di topic MQTT. È particolarmente utile, per esempio, per capire se un dispositivo stia funzionando o meno: se per esempio sappiamo che il topic MQTT di comando
shellies/NOME_SHELLY/relay/0/command ON
accende il relè di uno Shelly 1PM, a questo punto se pubblicassimo questo topic sul broker e il dispositivo fosse correttamente collegato ad esso, di conseguenza dovrebbe reagire accendendosi.
Capito questo, vediamo come si compone il comando:
mosquitto_pub -h IP_DEL_BROKER -u USERNAME -P PASSWORD -t TOPIC -m MESSAGE
dove:
IP_DEL_BROKER | rappresenta l’indirizzo IP del Broker |
USERNAME | rappresenta il nome utente per accedere al broker |
PASSWORD | rappresenta la password dell’utente indicato |
TOPIC | rappresenta il topic da pubblicare (eg. “shellies/NOME_SHELLY/relay/0/command“). Attenzione: talvolta i nomi sono case sentitive, quindi prestare attenzione a come è scritto il nome presso il dispositivo, affinché tutto funzioni correttamente. Il topic va tra apici. |
MESSAGE | rappresenta il payload (ovvero il “messaggio”) del topic di comando (eg. “ON“). Attenzione: il messaggio va tra apici. |
Ovviamente potrebbe essere comodo aprire due sessioni terminale: una dedicato ai comandi di ricezione dei topic (per vedere “cosa passa”) e uno per pubblicare i messaggi
NOTA PER UTENTI HOME ASSISTANT: la pubblicazione di topic MQTT sul broker può essere effettuata in alternativa dall’interfaccia web dell’HUB presso la sezione “Configurazione” > “Dispositivi e servizi” > “MQTT” (la quale ovviamente appare solo e quando si sono correttamente configurati i servizi client MQTT sull’HUB), dopodiché cliccare su “Configura” per accedere all’interfaccia di pubblicazione. |
Cancellare/pulire le retain
Come abbiamo spiegato sulla scheda che spiega cosa siano le retain MQTT, può essere talvolta un problema trovarsi con delle retain accumulate sul broker.
Per pulirle, il comando da terminale (il quale utilizza il comando mosquitto_sub) è il seguente:
mosquitto_sub -h IP_DEL_BROKER -u USERNAME -P PASSWORD -t '#' --remove-retained --retained-only
Il comando viene eseguito e ritorna poi al prompt dei comandi; in caso non ritorni automaticamente, interrompere con CTRL+X.
Un metodo più radicale per pulire le retain (su Raspberry Pi OS) è eseguire i seguenti comandi in sequenza:
sudo service mosquitto stop sudo rm /var/lib/mosquitto/mosquitto.db sudo service mosquitto start
Questo interrompe temporaneamente il servizio mosquitto, cancella il database e riavvia il servizio.
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. Alcuni link sono taggati in qualità di affiliati Amazon e riceviamo un compenso dagli acquisti idonei, utile al sostenimento del sito, ma le nostre recensioni sono tutte indipendenti e non sponsorizzate. Se ti sei perso, a tua disposizione c'è la mappa. |