Le broker MQTT intégré
HyperVisu peut faire tourner son propre broker MQTT, sur le serveur. Les appareils se connectent alors directement à HyperVisu, et non à une machine broker distincte que vous devriez installer, sécuriser et maintenir à jour, et vous associez leurs topics exactement comme sur n'importe quel autre broker (voir « MQTT Integration »). Le même broker peut aussi diffuser les valeurs de l'installation vers l'extérieur, de sorte qu'un tableau de bord, un système de gestion de l'énergie ou un autre contrôleur puisse lire ce que fait le bâtiment.
Utilisez-le lorsque vous avez des appareils MQTT et pas encore de broker. Si vous exploitez déjà un broker — celui d'une installation Zigbee2MQTT, un Mosquitto sur un serveur, un EMQX — conservez-le : HyperVisu est un client tout à fait adapté, et le broker intégré peut rester désactivé.
Prérequis : le protocole MQTT activé (voir « Services & Protocols ») pour pouvoir associer les appareils, et un compte par appareil qui se connectera.
Activation. Le broker est un service optionnel : il faut un redémarrage pour qu'il apparaisse, puis on le configure :
- Allez dans Services et activez MQTT Broker dans la liste des services optionnels.
- Cliquez sur Restart Server et attendez que la page se reconnecte.
- De retour dans Services, cliquez sur Configure sur la ligne MQTT Broker. La page MQTT Broker s'ouvre.
ℹ️ Remarque : Le commutateur de la page Services démarre et arrête le broker ; tout ce qui figure sur la page MQTT Broker décrit son comportement. Une modification sur la page Services nécessite un redémarrage du serveur ; une modification sur la page MQTT Broker ne redémarre que le broker.
Enregistrement des modifications. Les modifications sont mises en attente jusqu'à ce que vous les appliquiez : une barre apparaît en bas de la page avec Apply et Discard. Apply écrit les paramètres et redémarre le broker — les appareils connectés se reconnectent d'eux-mêmes en quelques secondes. Re-apply, en haut du panneau Status, réécrit et redémarre même si rien n'a changé ; utilisez-le si le broker a été arrêté manuellement ou si la page signale que les fichiers sur disque diffèrent des paramètres enregistrés.
Status — est-il en marche, et comment les appareils l'atteignent-ils
Le panneau Status est le premier endroit à consulter.
- Une carte par listener — MQTT et WebSockets — indiquant son adresse et s'il est Listening, sans réponse (No answer) ou désactivé (Off).
- Address to enter in a device — l'adresse à saisir dans la configuration d'un Shelly, d'un Tasmota ou de Zigbee2MQTT, avec un bouton Copy. C'est l'adresse propre du serveur et le port du listener non chiffré.
- HyperVisu's own connection — le compte et la connexion qu'HyperVisu utilise lui-même pour joindre le broker. Elle est créée automatiquement lors de la première utilisation du broker ; Repair la recrée si la connexion a été modifiée ou supprimée.
Si le broker n'a jamais été démarré, le panneau indique que le service ne tourne pas et renvoie vers la page Services.
Listeners — sur quels ports le broker répond-il
Un listener est un port sur lequel le broker accepte les connexions. Deux sont disponibles, chacun avec un Port et une Bind address :
| Listener | Par défaut | Utilité |
|---|---|---|
| MQTT | port 1883, activé | Le listener que les appareils utilisent normalement. L'authentification s'applique toujours — ce listener est non chiffré, pas ouvert. |
| WebSockets | port 9001, désactivé | Pour les clients MQTT exécutés dans un navigateur et pour les tableaux de bord qui parlent MQTT sur websockets. |
La Bind address détermine qui peut atteindre le listener : 0.0.0.0 accepte les connexions depuis le réseau, 127.0.0.1 les limite au serveur lui-même.
Au moins un listener doit rester activé — sans listener, rien ne pourrait se connecter, et la page refuse d'enregistrer. Deux listeners ne peuvent pas partager un port, et les ports déjà utilisés sur le serveur (l'interface web, la base de données d'historique, les tableaux de bord, Node-RED, le streaming des caméras, Home Assistant, l'API HyperVisu) sont refusés par leur nom.
⚠️ Avertissement : Aucun des deux listeners ne chiffre ce qu'il transporte ; gardez donc le broker sur le réseau local. Associez-le à
127.0.0.1si seul le serveur lui-même en a besoin, et ne redirigez jamais son port depuis Internet.
Comptes et accès — qui peut se connecter
⚠️ Avertissement : Un broker sans restrictions est une porte d'entrée vers l'installation. Donnez à chaque appareil son propre compte et laissez l'accès anonyme désactivé.
Comptes. Chaque appareil qui se connecte a besoin d'un nom d'utilisateur et d'un mot de passe. Cliquez sur Add account, saisissez un Username (lettres, chiffres et . _ @ -) et un Password, puis appliquez. Le mot de passe est haché dès son enregistrement et ne peut jamais être relu — seulement remplacé, avec le bouton Password sur la ligne du compte. HyperVisu dispose d'un compte propre, signalé comme tel ; il est géré pour vous et ne peut pas être supprimé.
La page refuse d'enregistrer une configuration dans laquelle l'accès anonyme est désactivé et où aucun compte n'existe — rien ne pourrait se connecter, pas même HyperVisu.
Connexions anonymes. Allow anonymous connections permet à n'importe quel client de se connecter sans nom d'utilisateur. Cette option est désactivée par défaut. Si vous l'activez alors qu'un listener est accessible depuis le réseau, la page affiche un avertissement — This broker would be open to the whole network — et refuse d'enregistrer tant que vous n'avez pas coché I understand and want to allow this. Sinon, n'importe qui sur le réseau pourrait lire les données de l'installation et la commander.
Restrictions de topics. Sans règles, chaque compte authentifié peut publier et s'abonner à tout. Activez Restrict topics per account et cliquez sur Add rule. Chaque règle comprend un Account (saisissez le nom d'utilisateur ; laissé vide, la règle s'applique aux clients anonymes), une Permission (read, write, readwrite ou deny) et un Topic filter, où + correspond à un niveau et # au reste.
Un jeu typique : la passerelle Zigbee reçoit readwrite sur zigbee2mqtt/#, un tableau de bord reçoit read sur hypervisu/#, et rien d'autre n'est autorisé nulle part.
ℹ️ Remarque : Les règles constituent la liste complète — un compte sans règle correspondant à un topic est refusé sur celui-ci. Le compte propre d'HyperVisu fait exception : il conserve toujours un accès complet, de sorte qu'activer les restrictions ne peut jamais couper le serveur des topics auxquels ses appareils sont associés. Une règle désignant ce compte est ignorée.
Stockage et limites
Ces paramètres protègent le serveur contre un appareil défaillant et déterminent ce qui survit à un redémarrage.
| Paramètre | Par défaut | Fonction |
|---|---|---|
| Keep retained messages across restarts | activé | Écrit l'état du broker sur disque, de sorte que les topics retenus sont toujours présents après un redémarrage. Sans cela, chaque valeur retenue est perdue à l'arrêt du broker et les widgets attendent la prochaine publication de l'appareil. |
| Save interval (s) | 1800 | Fréquence d'écriture de cet état. Plus l'intervalle est long, moins il y a d'écritures sur la carte mémoire du serveur. |
| Maximum connections | 200 | Nombre de clients pouvant être connectés simultanément. -1 pour illimité. |
| Maximum packet size (bytes) | 0 | Le plus grand message accepté par le broker. 0 signifie illimité. |
| Allow retained messages | activé | Détermine si les appareils peuvent demander au broker de mémoriser leur dernière valeur pour les nouveaux abonnés. Le désactiver oblige chaque widget à attendre une nouvelle publication après une reconnexion. |
💡 Astuce : Laissez les messages retenus activés. Ils permettent à l'application d'afficher des valeurs réelles dès que le serveur revient, au lieu de widgets vides.
Publication des états des widgets vers MQTT
HyperVisu peut publier les valeurs de ses propres appareils sur le broker, afin que d'autres systèmes lisent l'installation sans passer par HyperVisu : un tableau de bord Grafana, un gestionnaire d'énergie, un contrôleur tiers, un autre système du bâtiment.
Cette fonction est désactivée par défaut, et tant qu'elle l'est, rien n'est publié. Activez Publish widget states to MQTT et les paramètres apparaissent :
| Paramètre | Par défaut | Fonction |
|---|---|---|
| Topic prefix | hypervisu | Le premier segment de chaque topic. Segments de topic simples uniquement — ni + ni #. |
| Include the appliance serial in the topic | activé | Ajoute le numéro de série du serveur après le préfixe, de sorte que deux installations peuvent partager un broker sans collision. |
| Topic style | Identifiers | Identifiers (stable) utilise les numéros internes des appareils ; Names (readable) utilise les noms des pièces et des appareils. Les noms sont plus lisibles, mais renommer une pièce déplace tous les topics qu'elle contient et casse l'abonnement de ceux qui s'y étaient abonnés. |
| Payload | Value only | Value only publie la valeur seule ; JSON with context publie la valeur avec le nom et la pièce de l'appareil, son unité, son identité et un horodatage — de sorte qu'un abonné peut lire un message sans savoir ce qu'est widget/42/1. |
| Minimum interval (ms) | 1000 | Limitation de fréquence par objet. La dernière valeur arrive toujours ; 0 publie chaque changement. |
| Retain the last value | activé | Un client qui se connecte plus tard voit immédiatement l'état actuel au lieu d'attendre le prochain changement. |
| Publish an availability topic | activé | Publie online / offline, retenu, sur <prefix>/<serial>/status, afin que les abonnés sachent si ce qu'ils lisent est en direct ou le dernier message avant une déconnexion. Désactiver la publication le retire. |
| Only these widgets | désactivé | Désactivé, tous les appareils sont publiés. Activé, vous choisissez précisément lesquels. |
| Accept commands over MQTT | désactivé | Permet à un abonné de réécrire des valeurs. Voir l'avertissement ci-dessous. |
La page affiche A topic will look like avec un exemple en direct lorsque vous modifiez les paramètres. Avec les valeurs par défaut, la valeur d'un appareil arrive sur :
hypervisu/<serial>/widget/42/1/state
et avec Names (readable) :
hypervisu/<serial>/living-room/ceiling-lamp/1/state
Le dernier segment avant state est le numéro d'objet de l'appareil — un topic par objet de communication, et non un par appareil.
Avec JSON with context, le message dit lui-même ce qu'il est :
{"value":21.5,"unit":"°C","name":"Hall thermostat","room":"Bathroom","widget":46,"object":2,"type":"FLOAT","ts":"2026-09-09T07:51:22.436Z"}
Le nom et la pièce sont lus au moment de la publication ; renommer un appareil modifie donc le message suivant sans déplacer aucun topic. C'est la différence avec Names (readable) : les topics lisibles bougent lorsque vous renommez, une charge utile lisible non.
Acceptation des commandes. Avec Accept commands over MQTT activé, publier une valeur sur le topic …/set correspondant modifie l'appareil, exactement comme si l'application l'avait fait.
⚠️ Avertissement : Cela permet à toute personne pouvant publier sur le broker de piloter le bâtiment. N'activez cette option qu'avec l'accès anonyme désactivé et des restrictions de topics en place — la page refuse catégoriquement la combinaison de commandes et d'accès anonyme.
Les commandes sont refusées, et comptées comme refusées, lorsque le topic appartient à un objet en lecture seule ou lorsque la charge utile ne peut pas être lue comme le type de l'objet. Le panneau indique combien de messages ont été publiés et abandonnés, ainsi qu'un badge avec le nombre d'objets actuellement publiés.
ℹ️ Remarque : La publication nécessite que le protocole MQTT soit activé et une connexion à un broker. Activée sans cela, le panneau l'indique au lieu de faire semblant de publier.
Parcourir les topics du broker
Topics on the broker, en bas de la page, montre ce qui se passe réellement sur le broker à l'instant — le moyen le plus rapide de savoir si un appareil que vous venez de configurer communique vraiment.
- Remplissez éventuellement Limit to a subtree pour restreindre l'analyse (
zigbee2mqttn'analyse quezigbee2mqtt/#). - Choisissez la durée d'écoute avec Listen for — 3, 4, 10 ou 30 secondes.
- Cliquez sur Scan.
Le résultat est une arborescence qui suit les niveaux / des topics eux-mêmes, de sorte qu'un broker transportant des centaines de topics reste navigable. Cliquez sur une branche pour l'ouvrir — la ligne indique combien de topics se trouvent en dessous — et cliquez sur un topic pour voir sa dernière charge utile. Pour une charge utile JSON, les champs sont listés en dessous avec le type que chacun représente ; pour une charge utile simple, le type reconnu. Le bouton de copie sur la ligne ouverte copie le topic complet. Expand all et Collapse all se trouvent au-dessus de l'arborescence, et une petite analyse s'ouvre déployée.
Un niveau n'ayant qu'un seul enfant est fusionné avec son parent (118/1/state sur une ligne plutôt que trois), de sorte qu'un long préfixe ne coûte aucun clic. Les topics retenus viennent en premier à chaque niveau.
Les topics publiés par HyperVisu sont nommés lorsque c'est possible : un topic tel que hypervisu/<serial>/widget/42/1/state est affiché avec l'appareil auquel il appartient à côté, pour que vous n'ayez pas à chercher le numéro.
Les topics retenus sont rejoués par le broker dès que l'analyse s'abonne ; même une analyse courte montre donc toute l'arborescence retenue. Si une analyse ne trouve rien, soit aucun appareil n'est encore connecté, soit les appareils ne publient qu'en cas de changement — essayez une fenêtre plus longue.
ℹ️ Remarque : L'analyse lit le broker tel qu'il tourne maintenant ; les modifications non enregistrées plus haut dans la page ne sont donc pas prises en compte. Le panneau l'indique tant qu'il y a des modifications non enregistrées.
L'analyse est en lecture seule : elle montre ce qui existe et ne publie jamais. Pour associer l'un de ces topics à un appareil, ouvrez l'objet de l'appareil et choisissez le topic dans l'éditeur d'objet (voir « MQTT Integration ») — la même analyse y est disponible, et elle renseigne pour vous le type, le chemin JSON et les jetons ON/OFF.
Exemple concret — une prise Shelly sur le broker intégré
Une prise Shelly Plus doit être pilotée par HyperVisu, sans aucun broker sur le réseau pour l'instant.
- Services → activez MQTT Broker → Restart Server. Assurez-vous que le protocole MQTT est également activé.
- Services → Configure sur la ligne MQTT Broker. Dans Accounts and access, cliquez sur Add account : nom d'utilisateur
shelly, un mot de passe de votre choix. Cliquez sur Apply. - Notez l'Address to enter in a device dans le panneau Status — par exemple
192.168.1.60:1883. - Dans l'interface web propre au Shelly, activez MQTT, saisissez cette adresse, le nom d'utilisateur
shellyet son mot de passe, puis enregistrez. La prise redémarre et se connecte. - Allez dans Connections. Un panneau propose Use the local broker ; cliquez dessus, et HyperVisu crée sa propre connexion au broker. Si vous l'avez déjà fait une fois, la connexion existe — le navigateur de topics en a besoin, faites donc cette étape avant d'analyser.
- De retour sur la page MQTT Broker, ouvrez Topics on the broker et cliquez sur Scan. Les topics de la prise apparaissent —
shellyplus1pm-a8032ab1/status/switch:0et d'autres — avec leurs dernières charges utiles. - Dans Devices, ajoutez un widget Light switch « Kitchen plug », protocole MQTT, sur cette connexion, et associez ses objets aux topics de la prise avec Scan broker dans l'éditeur d'objet.
- Commutez la prise dans l'application. La commande part via le broker intégré, et le topic d'état de la prise la confirme.