Intégration MQTT

Intégration MQTT

MQTT connecte HyperVisu au monde du publish/subscribe : Zigbee2MQTT, Tasmota, Shelly (mode MQTT), ESPHome, passerelles d'énergie et tout firmware personnalisé communiquant avec un broker MQTT. HyperVisu agit en tant que client MQTT — il s'abonne aux topics sur lesquels les appareils publient leur état et publie des commandes sur les topics écoutés par les appareils. Il n'y a aucun polling : un appareil qui change d'état publie l'information, et le widget se met à jour instantanément.

Un broker fait office d'intermédiaire. Il peut s'agir d'un broker existant (Mosquitto, EMQX, celui inclus dans une installation Zigbee2MQTT, …) ou du broker intégré à HyperVisu, que le serveur peut exécuter directement afin que les appareils s'y connectent sans intermédiaire (voir « Le broker MQTT intégré »). L'ensemble de cet article s'applique dans les deux cas — le broker intégré fonctionne comme un broker ordinaire, accessible via une connexion standard.

Prérequis : l'adresse et le port du broker, ses identifiants le cas échéant, ainsi que les topics et le format de payload des appareils — issus de la documentation de l'appareil ou lus directement sur le broker via l'explorateur de topics (ci-dessous).

Connexions. Activez d'abord le Protocole MQTT sur la page Services (voir « Services & Protocoles ») ; il est désactivé par défaut sur un nouveau serveur. MQTT prend en charge plusieurs connexions : une connexion par broker (voir « Connexions »). Dans Ajouter une connexion, sélectionnez la carte MQTT : la boîte de dialogue demande un Nom de l'instance, l'Adresse du broker, le Port, le Client ID et les identifiants, et propose un bouton Tester. Le Certificat CA et les Options du broker (Keepalive, QoS par défaut, Topic de disponibilité, Clean session) ne figurent pas dans cette boîte de dialogue : configurez-les sur la connexion enregistrée, qui s'ouvre dans son éditeur dès que vous cliquez sur Créer la connexion. L'éditeur de connexion comprend :

Le bouton Tester sur une connexion MQTT effectue un test réel : le serveur se connecte au broker et attend son accusé de réception (délai de 10 s). Un résultat correct affiche Connexion réussie. Dans la boîte de dialogue Ajouter une connexion, Tester vérifie les valeurs saisies avant la création de la connexion. Sur une connexion existante, Tester vérifie les paramètres enregistrés et non les champs non sauvegardés : cliquez d'abord sur Enregistrer la connexion, puis sur Tester. Un test réussi confirme que l'adresse, le port, les identifiants et les paramètres TLS sont acceptés par le broker ; il ne garantit pas que les topics transmettent des données.

L'état de la connexion affiche Connecté tant que la liaison avec le broker est active. En cas d'interruption du broker, des tentatives de reconnexion s'effectuent toutes les quelques secondes, indéfiniment — aucun redémarrage du serveur n'est nécessaire.

📘 Note : Après avoir créé ou enregistré une connexion, le bouton Appliquer les modifications apparaît dans le menu latéral avec un compteur. La connexion fonctionne déjà sans cette étape ; l'application recharge la configuration du serveur et remet le compteur à zéro.

Liaison d'un objet (voir « Liaison MQTT » ci-dessous). Pour chaque objet, saisissez un Topic ; l'interface d'administration le stocke sous la forme <connexion>:<topic> afin que deux brokers puissent utiliser le même nom de topic. La direction de l'objet détermine son comportement :

Le codec de payload — la méthode de conversion du payload en valeur et inversement — correspond à la chaîne de type de données de l'objet, générée par l'éditeur à partir de ces champs :

La chaîne adopte la structure TYPE:param:param… — par exemple BOOL:PATH=state:ON=ON:OFF=OFF ou FLOAT:SCALE=0.3937:PUB={"brightness":{{value}}}. Une chaîne vide signifie « utiliser le payload brut selon le type de l'objet ». L'éditeur d'objet ne possède pas de champ de sélection de type de données : le type est celui affiché sur le champ sélectionné dans l'explorateur de topics (ci-dessous), et cliquer sur un champ adapte automatiquement le type de l'objet. Les objets de couleur (RVB) acceptent {"r","g","b"}, {"red","green","blue"}, [r,g,b], #RRGGBB et 255,128,0 en entrée, et publient {"r":…,"g":…,"b":…} sauf si un modèle en dispose autrement.

⚠️ Avertissement : Une commande conservée (retained) est réexécutée à chaque reconnexion de l'appareil au broker. Conservez les états, pas les commandes — l'éditeur affiche un avertissement lorsque vous activez l'option retain sur un objet sortant.

Explorateur de topics. MQTT est le seul protocole dont les adresses peuvent être directement scannées sur le réseau. Dans l'éditeur d'objet, sous Configuration du topic MQTT, cliquez sur Scanner le broker : le serveur écoute l'ensemble du broker pendant quatre secondes et indique le nombre de topics détectés (les topics avec messages conservés/retained apparaissent instantanément, un scan court affiche donc l'essentiel des données utiles ; pour un appareil ne conservant pas ses messages, déclenchez une émission puis scannez à nouveau). La liste est limitée à 500 topics. L'éditeur d'objet ne permet pas de scanner une section spécifique du broker : ouvrez Topic et saisissez du texte dans Rechercher des topics… pour filtrer les éléments détectés, ou saisissez manuellement le topic complet. Chaque ligne indique le topic et son dernier payload, accompagné du badge retained. Sélectionnez un topic et :

• pour un payload JSON, l'ensemble des champs apparaît sous Sélectionnez la valeur suivie par cet objet — un clic configure le chemin JSON, le type d'objet et, pour les booléens, les tokens ON/OFF selon la syntaxe propre à l'appareil ;
• pour un payload simple, Utiliser le payload brut comme définit le type.

Sélectionnez le topic avant de cliquer sur un champ : choisir un autre topic réinitialise le format de payload, le chemin JSON et les tokens. Ce clic ne renseigne pas le Facteur d'échelle ni l'Offset.

Vous pouvez également saisir un topic non détecté lors du scan — un topic de commande peut ne jamais avoir été publié, et un objet entrant peut nécessiter un caractère générique. Saisissez-le dans Topic et cliquez sur Utiliser « … » dans la liste.

Comportements à retenir

• État immédiat après redémarrage. Les messages conservés (retained) sont renvoyés par le broker à chaque connexion ou reconnexion, permettant aux widgets d'afficher leurs valeurs sans attendre la publication suivante de l'appareil.
• Aucun retour d'état simulé. Une commande n'est confirmée que lorsque l'appareil publie sur son topic d'état (ou lorsque le broker le renvoie) — exactement comme les objets d'état KNX. Si l'appareil est hors ligne, le widget ne simule aucun changement.
• Commandes pendant une coupure. Les commandes avec QoS 1 ou 2 sont mises en file d'attente lorsque le broker est inaccessible et transmises lors de la reconnexion ; les commandes QoS 0 vers un broker inaccessible échouent et sont consignées dans les logs.
• Sécurité. Les payloads supérieurs à 64 Ko sont ignorés avec un avertissement ; un seul abonnement est ouvert par filtre de topic distinct, quel que soit le nombre d'objets associés.

Exemple pratique — une lampe variable Zigbee2MQTT

Zigbee2MQTT publie l'état de la lampe en JSON sur zigbee2mqtt/lamp ({"state":"ON","brightness":178}) et reçoit les commandes sur zigbee2mqtt/lamp/set. La luminosité s'échelonne de 0 à 254.

1. Créez une connexion MQTT pour le broker (voir « Connexions ») : adresse du broker 192.168.1.10, port 1883, identifiants du broker Zigbee2MQTT si nécessaire. Cliquez sur Tester — la réussite doit être confirmée.
2. Dans Appareils, ajoutez un widget Variateur « Lampe bureau ». Sous Protocole, sélectionnez votre connexion broker selon le nom défini. L'appareil est créé avec quatre objets : Commutation ON/OFF, Retour commutation, Consigne de variation et Retour variation.
3. Sur Commutation ON/OFF (commande marche/arrêt) : saisissez zigbee2mqtt/lamp/set dans Topic et cliquez sur Utiliser « … » dans la liste. Définissez Token ON sur ON, Token OFF sur OFF et Modèle de payload sur {"state":"{{value}}"}. Saisissez explicitement les tokens : les mentions grisées ON et OFF ne sont que des indications ; sans saisie, l'interrupteur publie true ou false.
4. Sur Retour commutation (état marche/arrêt) : cliquez sur Scanner le broker, sélectionnez zigbee2mqtt/lamp, puis cliquez sur le champ state — l'éditeur applique le chemin JSON state et les tokens ON/OFF.
5. Sur Consigne de variation (commande de luminosité) : topic zigbee2mqtt/lamp/set, Modèle de payload {"brightness":{{value}}}, Facteur d'échelle 0.3937, Offset 0.
6. Sur Retour variation (état de luminosité) : topic zigbee2mqtt/lamp, cliquez sur le champ brightness, et appliquez le même Facteur d'échelle 0.3937. Cela équivaut approximativement à 100/254 : les valeurs entrantes sont multipliées par ce facteur (Zigbee 0–254 devient 0–100 %), les valeurs sortantes sont divisées par celui-ci (0–100 % devient 0–254).
7. Cliquez sur Enregistrer l'objet pour chaque objet, puis cliquez sur Appliquer les modifications dans le menu latéral et confirmez.
8. Réglez la luminosité sur 50 % dans l'application. La lampe reçoit environ 127, et son retour d'état renvoie environ 50 %. Le curseur se positionne d'après le topic d'état, et toute action physique sur la télécommande de la lampe met également l'application à jour.

📘 Note : La valeur transmise n'est pas arrondie : 50 % est publié sous la forme 127.000254. L'éditeur d'objet ne comportant pas de champ de sélection de type de données, il n'est pas possible d'imposer un nombre entier sur un objet de commande. Assurez-vous que votre lampe accepte les valeurs décimales de luminosité.

Liaison MQTT

Les objets MQTT se configurent dans la boîte de dialogue des paramètres d'objet (ouvrez l'objet via Modifier, voir « Paramètres d'objet, journalisation & notifications »). La section propre au protocole se compose de trois cartes :

Configuration du topic MQTT

Publication (objets sortants)

Abonnement (objets entrants)

Ces paramètres sont stockés sous forme de chaîne de type de données de l'objet (ex. BOOL:PATH=state:ON=ON:OFF=OFF) — la structure, l'explorateur de topics et un exemple détaillé sont présentés dans la section MQTT ci-dessus.