Mosquitto MQTT Broker: comandi utili

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.

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:

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

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.