Mosquitto MQTT Broker: comandi utili

6 minuti di lettura

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:

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:

Come configurare MQTT sui dispositivi della propria domotica

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 Raspbian è 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 HASSIO, è 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.

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

Se si utilizza Raspbian (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  “Strumenti per gli sviluppatori” > “MQTT” (la quale ovviamente appare solo e quando si sono correttamente configurati i servizi client MQTT sull’HUB).

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 Raspbian) è 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.


Telegram News Channel