Integrazione MQTT

Integrazione MQTT

MQTT collega HyperVisu al mondo publish/subscribe: Zigbee2MQTT, Tasmota, Shelly (modalità MQTT), ESPHome, gateway energetici e qualsiasi firmware personalizzato che comunica con un broker MQTT. HyperVisu è un client MQTT: sottoscrive i topic su cui i dispositivi pubblicano il proprio stato e pubblica i comandi sui topic ascoltati dai dispositivi. Non c'è polling: un dispositivo che cambia stato esegue la pubblicazione e il widget si aggiorna immediatamente.

Al centro c'è un broker. Può essere un broker già attivo (Mosquitto, EMQX, quello integrato in un'installazione Zigbee2MQTT, …) oppure il broker integrato in HyperVisu, eseguibile direttamente dal server per consentire ai dispositivi di collegarsi senza intermediari (vedere "The Built-in MQTT Broker"). Tutto quanto descritto in questo articolo si applica a entrambi i casi: il broker integrato è un normale broker, accessibile tramite una comune connessione.

Cosa serve: l'indirizzo e la porta del broker, le sue credenziali di accesso se richieste, nonché i topic e il formato del payload del dispositivo (ricavabili dalla documentazione tecnica del dispositivo o letti direttamente dal broker con il topic browser descritto di seguito).

Connessioni. Attiva prima MQTT Protocol nella pagina Services (vedere "Services & Protocols"); su un server nuovo è disattivato. MQTT supporta connessioni multiple: una connessione per ciascun broker (vedere "Connections"). In Add connection, seleziona la scheda MQTT: la finestra di dialogo richiede Instance Name, Broker address, Port, Client ID e le credenziali, oltre a presentare il pulsante Test. Il CA certificate e le Broker options (Keepalive, Default QoS, Availability topic, Clean session) non compaiono in questa finestra: vanno impostati sulla connessione salvata, che si apre nel rispettivo editor appena si fa clic su Create connection. L'editor della connessione comprende:

Il pulsante Test su una connessione MQTT esegue una verifica reale: il server si collega al broker e attende la risposta (entro 10 s). Un esito positivo mostra Connection succeeded. Nella finestra di dialogo Add connection, Test prova i valori digitati prima di creare la connessione. Su una connessione salvata, Test verifica i parametri salvati, non i campi non ancora memorizzati: fare prima clic su Save connection, poi su Test. L'esito positivo del test conferma che indirizzo, porta, credenziali e impostazioni TLS sono accettati dal broker; non certifica la presenza di dati sui topic.

Lo stato della connessione indica Connected finché il collegamento con il broker è attivo. Se il broker si disconnette, il tentativo di riconnessione si ripete ogni pochi secondi senza limiti: non è mai necessario riavviare il server.

📘 Nota: Dopo aver creato o salvato una connessione, compare Apply changes nella barra laterale con un contatore. La connessione è già operativa senza applicare; l'applicazione ricarica la configurazione del server e azzera il contatore.

Associazione di un oggetto (vedere "Binding MQTT" di seguito). Per ogni oggetto si inserisce un Topic; l'amministrazione lo memorizza come <connection>:<topic>, consentendo a due broker di gestire lo stesso nome topic. La direzione dell'oggetto determina il comportamento:

Il codec del payload — la modalità di conversione del payload in valore e viceversa — è la stringa del tipo di dati dell'oggetto, composta dall'editor a partire da questi campi:

La stringa ha il formato TYPE:param:param… — ad esempio BOOL:PATH=state:ON=ON:OFF=OFF oppure FLOAT:SCALE=0.3937:PUB={"brightness":{{value}}}. Una stringa vuota indica di "trattare il payload grezzo secondo il tipo dell'oggetto". L'editor dell'oggetto non contiene un campo per il tipo di dati: il tipo corrisponde a quello visualizzato sul campo selezionato nel topic browser (descritto di seguito), e la selezione di un campo aggiorna automaticamente il tipo dell'oggetto. Gli oggetti colore (RGB) accettano {"r","g","b"}, {"red","green","blue"}, [r,g,b], #RRGGBB e 255,128,0 in ingresso, e pubblicano {"r":…,"g":…,"b":…} a meno di impostare un template differente.

⚠️ Attenzione: Un comando inviato con flag retained viene rieseguito a ogni riconnessione del dispositivo al broker. Mantieni come retained lo stato, non i comandi: l'editor segnala un avviso quando si attiva il flag retain su un oggetto in uscita.

Topic browser. MQTT è l'unico protocollo i cui indirizzi possono essere rilevati direttamente dalla rete. Nell'editor dell'oggetto, alla sezione MQTT topic configuration, fare clic su Scan broker: il server resta in ascolto sull'intero broker per quattro secondi e segnala il numero di topic rilevati (i topic con flag retained arrivano subito, quindi una scansione breve mostra già la maggior parte dei punti utili; per un dispositivo senza retained, inviare una lettura e ripetere la scansione). L'elenco è limitato a 500 topic. L'editor non consente la scansione parziale del broker: aprire Topic e digitare in Search topics… per filtrare i risultati, oppure inserire il topic manualmente. Ogni riga mostra il topic e il rispettivo last payload, accompagnato dall'etichetta retained. Seleziona un topic e:

• per un payload JSON, ogni parametro è elencato sotto Pick the value this object should follow: un clic imposta il percorso JSON, il tipo di oggetto e, per i booleani, i token ON/OFF con la sintassi specifica del dispositivo;
• per un payload semplice, Use the raw payload as assegna il tipo.

Seleziona il topic prima di fare clic su un parametro: la scelta di un altro topic reimposta il formato del payload, il percorso JSON e i token. Il clic non compila i campi Scale e Offset.

È comunque possibile inserire manualmente un topic non rilevato dalla scansione: un topic di comando potrebbe non essere mai stato pubblicato, oppure un oggetto in ingresso potrebbe richiedere un carattere jolly. Digitalo nel campo Topic e fai clic su Use "…" nell'elenco.

Caratteristiche di funzionamento utili

• Stato immediato al riavvio. I messaggi retained vengono ritrasmessi dal broker a ogni connessione o riconnessione: i widget mostrano i valori senza attendere la successiva pubblicazione del dispositivo.
• Nessun feedback fittizio. Un comando viene confermato solo quando il dispositivo pubblica il proprio topic di stato (o il broker lo ritrasmette), esattamente come per gli oggetti di stato KNX. Se il dispositivo non risponde, il widget non simula lo stato.
• Comandi durante una disconnessione. I comandi con QoS 1 o 2 vengono accodati se il broker non è raggiungibile e recapitati al ripristino della connessione; i comandi con QoS 0 verso un broker non raggiungibile non vanno a buon fine e vengono registrati nei log.
• Protezione. I payload superiori a 64 KB vengono scartati con un avviso; viene aperta una sola sottoscrizione per ciascun filtro di topic distinto, indipendentemente dal numero di oggetti associati.

Esempio pratico: lampada dimmerabile Zigbee2MQTT

Zigbee2MQTT pubblica lo stato della lampada in formato JSON su zigbee2mqtt/lamp ({"state":"ON","brightness":178}) e accetta comandi su zigbee2mqtt/lamp/set. La luminosità varia da 0 a 254.

1. Crea una connessione MQTT per il broker (vedere "Connections"): indirizzo broker 192.168.1.10, porta 1883, credenziali del broker Zigbee2MQTT se presenti. Fai clic su Test: deve confermare l'esito positivo.
2. In Devices, aggiungi un widget Dimmer denominato "Luce ufficio". In Protocol, seleziona la connessione del broker identificata dal nome assegnato. Il dispositivo viene creato con quattro oggetti: Switch ON/OFF, Switch Feedback, Dimming setpoint e Dimming feedback.
3. Su Switch ON/OFF (comando on/off): digita zigbee2mqtt/lamp/set in Topic e fai clic su Use "…" nell'elenco. Imposta ON token su ON, OFF token su OFF e Payload template su {"state":"{{value}}"}. Digita manualmente i token: le voci ON e OFF in grigio sono solo indicazioni d'esempio; senza token l'interruttore pubblica true o false.
4. Su Switch Feedback (stato on/off): fai clic su Scan broker, seleziona zigbee2mqtt/lamp, quindi fai clic sul campo state: l'editor imposta il percorso JSON state e i token ON/OFF.
5. Su Dimming setpoint (comando luminosità): topic zigbee2mqtt/lamp/set, Payload template {"brightness":{{value}}}, Scale 0.3937, Offset 0.
6. Su Dimming feedback (stato luminosità): topic zigbee2mqtt/lamp, fai clic sul campo brightness e imposta la stessa Scale 0.3937. Questo valore corrisponde a circa 100/254: i valori in ingresso vengono moltiplicati per tale fattore (la scala Zigbee 0–254 diventa 0–100 %), mentre i valori in uscita vengono divisi (0–100 % diventa 0–254).
7. Fai clic su Save object per ciascun oggetto, quindi fai clic su Apply changes nella barra laterale e conferma.
8. Imposta la luminosità al 50 % nell'app. La lampada riceve circa 127 e il suo feedback restituisce circa 50 %. Il cursore conferma il valore dal topic di stato, e anche regolando la lampada dal telecomando fisico l'app si aggiorna di conseguenza.

📘 Nota: Il valore trasmesso non è arrotondato: 50 % viene pubblicato come 127.000254. L'editor dell'oggetto non include un campo per il tipo di dati, pertanto non è possibile forzare un oggetto di comando a inviare un numero intero. Verifica che la lampada supporti valori decimali di luminosità.

Binding MQTT

Gli oggetti MQTT si configurano nella finestra delle impostazioni dell'oggetto (aprire l'oggetto con Edit, vedere "Object Settings, Logging & Notifications"). La sezione dedicata al protocollo è suddivisa in tre schede:

MQTT topic configuration

Publishing (oggetti in uscita)

Subscribing (oggetti in ingresso)

I campi vengono memorizzati come stringa del tipo di dati dell'oggetto (es. BOOL:PATH=state:ON=ON:OFF=OFF): la sintassi, il topic browser e un esempio pratico sono descritti nel capitolo MQTT sopra.