Il broker MQTT integrato
HyperVisu può eseguire un broker MQTT dedicato direttamente sul server. I dispositivi si collegano così direttamente a HyperVisu invece di richiedere una macchina broker separata da installare, proteggere e mantenere aggiornata, e i relativi topic si associano esattamente come su qualsiasi altro broker (vedere «Integrazione MQTT»). Lo stesso broker può anche trasmettere all'esterno i valori dell'impianto, consentendo a una dashboard, a un sistema di gestione dell'energia o a un altro controller di monitorare l'attività dell'edificio.
Utilizzalo quando sono presenti dispositivi MQTT ma non è ancora disponibile un broker. Se disponi già di un broker attivo — quello integrato in un'installazione Zigbee2MQTT, un Mosquitto su un server, un EMQX — mantienilo: HyperVisu funziona perfettamente come client e il broker integrato può rimanere disattivato.
Requisiti: il protocollo MQTT abilitato (vedere «Servizi e protocolli») per consentire l'associazione dei dispositivi, e un account per ciascun dispositivo che si collegherà.
Attivazione. Il broker è un servizio opzionale, richiede quindi un riavvio per essere visualizzato e viene configurato successivamente:
- Accedere a Servizi e attivare Broker MQTT nell'elenco dei servizi opzionali.
- Fare clic su Riavvia server e attendere la riconnessione della pagina.
- Tornare su Servizi, fare clic su Configura nella riga del Broker MQTT. Si apre la pagina Broker MQTT.
ℹ️ Nota: L'interruttore nella pagina Servizi avvia e arresta il broker; tutte le impostazioni nella pagina Broker MQTT ne definiscono il comportamento. Una modifica nella pagina Servizi richiede il riavvio del server; una modifica nella pagina Broker MQTT riavvia solo il broker stesso.
Salvataggio delle modifiche. Le modifiche vengono raggruppate fino alla loro applicazione: nella parte inferiore della pagina viene visualizzata una barra con Applica e Annulla. Applica scrive le impostazioni e riavvia il broker: i dispositivi collegati si riconnettono automaticamente entro pochi secondi. Riapplica, nella parte superiore del pannello Stato, riscrive la configurazione e riavvia il servizio anche in assenza di modifiche; utilizzarlo se il broker è stato arrestato manualmente o se la pagina segnala che i file su disco differiscono dalle impostazioni salvate.
Stato: verifica del funzionamento e raggiungibilità per i dispositivi
Il pannello Stato è la prima sezione da consultare.
- Una scheda per ciascun listener — MQTT e WebSockets — ciascuna indicante il rispettivo indirizzo e lo stato: In ascolto, Nessuna risposta o Disattivato.
- Indirizzo da inserire nel dispositivo — l'indirizzo da digitare nella configurazione di uno Shelly, un Tasmota o Zigbee2MQTT, completo di pulsante Copia. Corrisponde all'indirizzo del server e alla porta del listener standard.
- Connessione interna di HyperVisu — l'account e la connessione utilizzati da HyperVisu stessa per comunicare con il broker. Viene creata automaticamente al primo utilizzo del broker; Ripara la ricrea se la connessione è stata modificata o eliminata.
Se il broker non è mai stato avviato, il pannello segnala che il servizio non è in esecuzione e rimanda alla pagina Servizi.
Listener: su quali porte risponde il broker
Un listener è una porta su cui il broker accetta connessioni. Sono disponibili due listener, ciascuno con una Porta e un Indirizzo di binding:
| Listener | Predefinito | Finalità |
|---|---|---|
| MQTT | porta 1883, on | Il listener standard utilizzato dai dispositivi. L'autenticazione rimane attiva: non è crittografato, ma non è aperto. |
| WebSockets | porta 9001, off | Per i client MQTT eseguiti in un browser e per dashboard che comunicano tramite MQTT su websockets. |
L'Indirizzo di binding definisce chi può raggiungere il listener: 0.0.0.0 accetta connessioni dalla rete, 127.0.0.1 limita l'accesso al solo server.
Almeno un listener deve rimanere attivo: senza alcun listener abilitato nessun dispositivo potrebbe connettersi e la pagina rifiuta il salvataggio. Due listener non possono condividere la stessa porta, e le porte già utilizzate sul server (interfaccia web, database storico, dashboard, Node-RED, streaming telecamere, Home Assistant, API di HyperVisu) vengono rifiutate indicandone il nome.
⚠️ Attenzione: Nessuno dei listener cifra i dati trasmessi; mantenere pertanto il broker sulla rete locale. Effettuare il binding a
127.0.0.1se deve essere utilizzato esclusivamente dal server stesso, e non inoltrare mai la relativa porta da Internet.
Account e accessi: autorizzazioni di connessione
⚠️ Attenzione: Un broker senza restrizioni costituisce un punto di accesso all'impianto. Assegnare a ciascun dispositivo un account dedicato e mantenere disattivato l'accesso anonimo.
Account. Ogni dispositivo che si connette richiede un nome utente e una password. Fare clic su Aggiungi account, inserire un Nome utente (lettere, cifre e . _ @ -) e una Password, quindi applicare le modifiche. La password viene sottoposta a hash nel momento in cui viene salvata e non può più essere letta in chiaro, ma solo sostituita tramite il pulsante Password sulla riga dell'account. HyperVisu dispone di un proprio account dedicato, contrassegnato come tale; è gestito automaticamente e non può essere rimosso.
La pagina impedisce il salvataggio di una configurazione in cui l'accesso anonimo è disattivato e non è presente alcun account: in tale condizione nessun client potrebbe connettersi, compresa HyperVisu.
Connessioni anonime. L'opzione Consenti connessioni anonime permette a qualsiasi client di connettersi senza nome utente. È disattivata per impostazione predefinita. Se viene attivata mentre un listener è raggiungibile dalla rete, la pagina mostra un avviso — Questo broker risulterebbe aperto all'intera rete — e rifiuta il salvataggio finché non si spunta Comprendo e desidero consentirlo. Chiunque sulla rete potrebbe altrimenti leggere i dati dell'impianto e controllarlo.
Restrizioni sui topic. Senza regole, ogni account autenticato può pubblicare e sottoscrivere qualsiasi topic. Attivare Limita i topic per account e fare clic su Aggiungi regola. Ogni regola è composta da un Account (digitare il nome utente; lasciando il campo vuoto la regola si applica ai client anonimi), un'Autorizzazione (read, write, readwrite o deny) e un Filtro topic, dove + corrisponde a un singolo livello e # a tutti i livelli successivi.
Un insieme tipico: il gateway Zigbee ottiene readwrite su zigbee2mqtt/#, una dashboard ottiene read su hypervisu/#, e nessun altro accesso viene consentito.
ℹ️ Nota: Le regole costituiscono l'elenco completo dei permessi: un account senza una regola corrispondente per un determinato topic viene rifiutato su di esso. L'account interno di HyperVisu costituisce l'eccezione: mantiene sempre l'accesso completo, garantendo che l'attivazione delle restrizioni non possa mai isolare il server dai topic a cui sono associati i dispositivi. Un'eventuale regola assegnata a tale account viene ignorata.
Archiviazione e limiti
Queste impostazioni proteggono il server da eventuali anomalie dei dispositivi e stabiliscono quali dati vengono conservati dopo un riavvio.
| Impostazione | Predefinito | Funzione |
|---|---|---|
| Mantieni i messaggi retained dopo il riavvio | on | Scrive lo stato del broker su disco, in modo che i topic retained rimangano disponibili dopo un riavvio. Senza questa opzione, ogni valore retained viene perso all'arresto del broker e i widget attendono la pubblicazione successiva da parte del dispositivo. |
| Intervallo di salvataggio (s) | 1800 | Frequenza di scrittura dello stato. Un intervallo più lungo riduce i cicli di scrittura sulla scheda di memoria del server. |
| Connessioni massime | 200 | Numero massimo di client connessi simultaneamente. -1 per nessun limite. |
| Dimensione massima del pacchetto (byte) | 0 | Dimensione massima del messaggio accettata dal broker. 0 indica nessun limite. |
| Consenti messaggi retained | on | Consente ai dispositivi di richiedere al broker la memorizzazione dell'ultimo valore per i nuovi sottoscrittori. Disattivando l'opzione, ogni widget attenderà una nuova pubblicazione dopo la riconnessione. |
💡 Suggerimento: Mantenere attivi i messaggi retained. Consentono all'app di visualizzare immediatamente i valori reali al ripristino del server, evitando widget vuoti.
Pubblicazione dello stato dei widget su MQTT
HyperVisu può pubblicare i valori dei propri dispositivi sul broker, consentendo ad altri sistemi di leggere l'impianto senza interagire direttamente con HyperVisu: una dashboard Grafana, un sistema di gestione dell'energia, un controller di terze parti o un altro sistema di supervisione dell'edificio.
La funzione è disattivata per impostazione predefinita e, finché resta disattivata, non viene pubblicato alcun dato. Attivando Pubblica lo stato dei widget su MQTT, vengono visualizzate le impostazioni:
| Impostazione | Predefinito | Funzione |
|---|---|---|
| Prefisso topic | hypervisu | Il primo segmento di ogni topic. Solo segmenti di topic semplici, senza caratteri + o #. |
| Includi il seriale dell'unità nel topic | on | Aggiunge il numero di serie del server dopo il prefisso, consentendo a due impianti di condividere lo stesso broker senza collisioni. |
| Stile del topic | Identificatori | Identificatori (stabile) utilizza gli identificativi numerici interni dei dispositivi; Nomi (leggibile) utilizza i nomi delle stanze e dei dispositivi. I nomi sono più leggibili, ma la ridenominazione di una stanza sposta tutti i topic sottostanti interrompendo le sottoscrizioni esistenti. |
| Payload | Solo valore | Solo valore pubblica unicamente il valore puro; JSON con contesto pubblica il valore insieme al nome del dispositivo, alla stanza, all'unità di misura, all'identificativo e al timestamp, consentendo a un sottoscrittore di interpretare il messaggio senza conoscere preventivamente il significato di widget/42/1. |
| Intervallo minimo (ms) | 1000 | Limite di frequenza per oggetto. L'ultimo valore viene sempre trasmesso; impostando 0 viene pubblicata ogni singola variazione. |
| Mantieni l'ultimo valore (retain) | on | Un client che si connette successivamente visualizza immediatamente lo stato attuale senza attendere la variazione successiva. |
| Pubblica un topic di disponibilità | on | Pubblica online / offline come messaggio retained su <prefisso>/<seriale>/status, consentendo ai sottoscrittori di verificare se il valore letto è aggiornato o corrisponde all'ultimo stato prima della disconnessione. La disattivazione della pubblicazione lo rimuove. |
| Solo questi widget | off | Disattivato pubblica tutti i dispositivi. Attivato consente di selezionare esattamente i widget desiderati. |
| Accetta comandi via MQTT | off | Consente a un sottoscrittore di inviare valori in scrittura. Consultare l'avviso di seguito. |
La pagina mostra l'anteprima Un topic apparirà così con un esempio aggiornato in tempo reale durante la modifica delle impostazioni. Con i valori predefiniti, il valore di un dispositivo viene indirizzato su:
hypervisu/<seriale>/widget/42/1/state
e con l'opzione Nomi (leggibile):
hypervisu/<seriale>/soggiorno/lampada-a-soffitto/1/state
L'ultimo segmento prima di state è il numero dell'oggetto del dispositivo: viene generato un topic per ciascun oggetto di comunicazione, non un topic per dispositivo.
Con l'opzione JSON con contesto, il payload descrive esplicitamente i dati contenuti:
{"value":21.5,"unit":"°C","name":"Termostato corridoio","room":"Bagno","widget":46,"object":2,"type":"FLOAT","ts":"2026-09-09T07:51:22.436Z"}
Il nome e la stanza vengono acquisiti al momento della pubblicazione; la ridenominazione di un dispositivo aggiorna quindi il messaggio successivo senza modificare il percorso del topic. Questa è la differenza rispetto all'opzione Nomi (leggibile): i topic leggibili cambiano percorso in caso di ridenominazione, mentre un payload leggibile mantiene inalterato il percorso del topic.
Ricezione dei comandi. Attivando Accetta comandi via MQTT, la pubblicazione di un valore sul corrispondente topic …/set aziona il dispositivo, esattamente come avverrebbe dall'app.
⚠️ Attenzione: Questa configurazione consente a chiunque possa pubblicare sul broker di controllare l'edificio. Attivarla solo con l'accesso anonimo disattivato e con restrizioni sui topic configurate: la pagina rifiuta tassativamente la combinazione di comandi attivi e accesso anonimo.
I comandi vengono rifiutati, e conteggiati come tali, quando il topic appartiene a un oggetto in sola lettura o se il payload non è convertibile nel tipo di dati dell'oggetto. Il pannello mostra il conteggio dei messaggi pubblicati e scartati, oltre a un indicatore con il numero di oggetti attualmente pubblicati.
ℹ️ Nota: La pubblicazione richiede l'attivazione del protocollo MQTT e una connessione valida a un broker. Se abilitata in assenza di connessione, il pannello segnala lo stato corrispondente invece di simulare la pubblicazione.
Esplorazione dei topic sul broker
La sezione Topic sul broker, situata nella parte inferiore della pagina, mostra l'attività in corso sul broker in tempo reale: costituisce il metodo più rapido per verificare se un dispositivo appena configurato sta effettivamente trasmettendo.
- Opzionalmente, compilare Limita a un sottoalbero per restringere la scansione (ad esempio
zigbee2mqttscansiona esclusivamentezigbee2mqtt/#). - Selezionare la durata in Ascolta per — 3, 4, 10 o 30 secondi.
- Fare clic su Scansiona.
Il risultato è una visualizzazione ad albero strutturata secondo i livelli / dei topic, mantenendo agevole la navigazione anche su broker con centinaia di topic. Fare clic su un ramo per aprirlo — la riga indica quanti topic sono presenti al di sotto — e fare clic su un topic per visualizzarne l'ultimo payload. Per un payload JSON i singoli campi sono elencati sotto con il rispettivo tipo riconosciuto; per un payload semplice, viene mostrato il tipo di dato identificato. Il pulsante di copia sulla riga aperta copia l'intero topic. I comandi Espandi tutto e Comprimi tutto si trovano sopra l'albero; una scansione di dimensioni ridotte si apre già espansa.
Un livello contenente un solo elemento secondario viene raggruppato nel genitore (118/1/state su una sola riga anziché tre), semplificando la visualizzazione di prefissi profondi. I topic retained sono posizionati per primi a ogni livello.
I topic pubblicati da HyperVisu riportano, ove possibile, il nome associato: un topic come hypervisu/<seriale>/widget/42/1/state viene visualizzato con accanto il dispositivo corrispondente, evitando la ricerca manuale del numero.
I topic retained vengono riprodotti dal broker nel momento in cui la scansione effettua la sottoscrizione; pertanto, anche una scansione breve restituisce l'intero albero dei topic retained. Se la scansione non rileva alcun dato, significa che nessun dispositivo è ancora connesso oppure che i dispositivi pubblicano solo su variazione: impostare una finestra di ascolto più lunga.
ℹ️ Nota: La scansione legge lo stato effettivo del broker in esecuzione; le modifiche non salvate nella pagina non sono incluse nel report. Il pannello segnala la presenza di modifiche non salvate.
La scansione è in sola lettura: visualizza i dati presenti e non effettua pubblicazioni. Per associare uno di questi topic a un dispositivo, aprire l'oggetto del dispositivo e selezionare il topic nell'editor dell'oggetto (vedere «Integrazione MQTT»): la stessa funzione di scansione è disponibile direttamente all'interno dell'editor e compila automaticamente il tipo, il percorso JSON e i valori di stato ON/OFF.
Esempio pratico: presa Shelly sul broker integrato
Configurazione di una presa Shelly Plus controllata da HyperVisu in assenza di un broker preesistente sulla rete.
- Servizi → attivare Broker MQTT → fare clic su Riavvia server. Verificare che anche il protocollo MQTT sia attivo.
- Servizi → fare clic su Configura nella riga Broker MQTT. In Account e accessi, fare clic su Aggiungi account: inserire il nome utente
shellye una password a scelta. Fare clic su Applica. - Rilevare l'Indirizzo da inserire nel dispositivo dal pannello Stato, ad esempio
192.168.1.60:1883. - Nell'interfaccia web del dispositivo Shelly, abilitare MQTT, inserire tale indirizzo, il nome utente
shellye la relativa password, quindi salvare. La presa si riavvia e si connette. - Accedere a Connessioni. Un pannello propone l'opzione Usa il broker locale; fare clic per consentire a HyperVisu di creare la propria connessione verso il broker. Se l'operazione è già stata eseguita in precedenza, la connessione risulterà già presente: il browser dei topic la richiede, pertanto eseguire questo passaggio prima della scansione.
- Tornare nella pagina Broker MQTT, aprire Topic sul broker e fare clic su Scansiona. Vengono visualizzati i topic della presa —
shellyplus1pm-a8032ab1/status/switch:0e altri — con i rispettivi ultimi payload. - In Dispositivi, aggiungere un widget Interruttore luce denominato «Presa cucina», protocollo MQTT, associato a tale connessione, quindi collegare i relativi oggetti ai topic della presa tramite il pulsante Scansiona broker nell'editor dell'oggetto.
- Azionare la presa dall'applicazione. Il comando viene inviato tramite il broker integrato e il topic di stato della presa ne conferma l'esecuzione.