Un explorateur de topics MQTT affiche chaque topic qui transite par un broker sous la forme d'une arborescence dynamique et dépliable, avec le dernier payload à côté de chaque nœud. Dans ce tutoriel, vous allez générer une hiérarchie de topics réaliste, l'explorer dans l'explorateur de topics en direct de ConnectMQ et en ligne de commande, et apprendre à repérer en quelques secondes les erreurs de nommage, les retained messages obsolètes et les payloads mal formés.
Ce que fait un explorateur de topics MQTT
MQTT ne dispose d'aucune commande intégrée pour « lister les topics ». Les topics ne sont ni créés ni enregistrés : ils n'existent que parce que quelqu'un publie dessus. Un explorateur de topics contourne cela en s'abonnant à un wildcard large comme # (ou à la racine d'un projet comme factory1/#) et en construisant une arborescence à partir des noms de topics reçus. Chaque slash devient un niveau, chaque niveau devient un dossier, et le payload le plus récent s'affiche sur la feuille.
Cette idée simple est étonnamment puissante. Un flux plat de messages issu de mosquitto_sub devient difficile à lire au-delà d'une douzaine d'appareils. Une arborescence vous indique d'un coup d'œil :
- Quelles branches existent, et lesquelles ne devraient pas exister.
- Quelles feuilles se mettent à jour en ce moment, et lesquelles se sont arrêtées il y a des heures.
- Quelles valeurs sont retained, c'est-à-dire qu'un nouvel abonné les recevra immédiatement.
- La taille des payloads et leur bonne formation.
Si la structure des topics est nouvelle pour vous, il est utile de comprendre ce que fait un broker MQTT des topics et des abonnements avant de commencer.
Générer une arborescence de topics à explorer
Il vous faut du trafic à parcourir. Le script ci-dessous publie une petite hiérarchie d'usine sur le serveur MQTT public gratuit broker.connectmq.com, réservé aux tests. Il inclut volontairement trois erreurs courantes pour que vous puissiez les retrouver dans l'explorateur. Installez le client avec pip install "paho-mqtt>=2.0".
import json
import random
import time
import uuid
import paho.mqtt.client as mqtt
RUN_ID = uuid.uuid4().hex[:6]
ROOT = f"connectmq/demo/{RUN_ID}"
client = mqtt.Client(
mqtt.CallbackAPIVersion.VERSION2,
client_id=f"tree-gen-{RUN_ID}",
)
client.connect("broker.connectmq.com", 1883, keepalive=60)
client.loop_start()
print(f"Publishing under {ROOT}/ (subscribe to {ROOT}/#)")
# Métadonnées d'appareil en retained
for line in ("line1", "line2"):
for machine in ("cnc1", "cnc2"):
meta = {"vendor": "demo", "model": "X200", "line": line}
client.publish(f"{ROOT}/factory1/{line}/{machine}/meta",
json.dumps(meta), qos=1, retain=True)
# Erreur 1 : une casse incohérente crée une branche parallèle
client.publish(f"{ROOT}/factory1/Line1/cnc1/meta", "{}", qos=1, retain=True)
# Erreur 2 : un slash final crée un dernier niveau vide
client.publish(f"{ROOT}/factory1/line2/cnc2/telemetry/", "42", qos=0)
try:
while True:
for line in ("line1", "line2"):
for machine in ("cnc1", "cnc2"):
payload = {
"spindle_rpm": random.randint(9000, 12000),
"temperature": round(random.uniform(35, 60), 1),
"ts": int(time.time()),
}
client.publish(f"{ROOT}/factory1/{line}/{machine}/telemetry",
json.dumps(payload), qos=0)
# Erreur 3 : un payload qui n'est pas du JSON valide
client.publish(f"{ROOT}/factory1/line1/cnc2/telemetry",
"temp=48.2;rpm=10100", qos=0)
time.sleep(2)
except KeyboardInterrupt:
client.loop_stop()
client.disconnect()
Le script publie quatre messages par cycle plus le message mal formé, ce qui le maintient largement sous la limite du broker public de 10 messages par seconde et par client. Laissez-le tourner et notez la racine affichée.
Explorer l'arborescence dans l'explorateur de topics ConnectMQ
Sur votre propre broker, l'explorateur de topics en direct du portail ConnectMQ est l'explorateur intégré. Pour suivre le tutoriel, créez un broker gratuit dans le portail, puis pointez-y le script ci-dessus en passant au port 8883 avec TLS et en ajoutant les identifiants générés par le portail (YOUR_USERNAME, YOUR_PASSWORD, YOUR_CLIENT_ID). Pour jeter plutôt un coup d'œil au broker public, n'importe quel explorateur MQTT compatible WebSocket peut se connecter à wss://broker.connectmq.com:8084/mqtt et s'abonner à votre racine connectmq/demo/<run-id>/#.
À mesure que les messages arrivent, parcourez l'arborescence depuis le haut :
- Dépliez la racine. Vous devriez voir
factory1et, en dessous,line1,line2et unLine1inattendu. Les topics sont sensibles à la casse :Line1est donc une branche distincte qu'aucun abonné àline1/#ne recevra jamais. - Ouvrez
line2/cnc2. Soustelemetryse trouve un enfant au nom vide. C'est le slash final :telemetry/compte un niveau de plus quetelemetry, et un abonnement à.../cnc2/telemetryne le captera pas. - Ouvrez
line1/cnc2/telemetry. La valeur alterne entre du JSON ettemp=48.2;rpm=10100. Tout consommateur qui parse du JSON lèvera une erreur un message sur deux. - Regardez les feuilles
meta. Elles portent le flag retained. Déconnectez-vous puis reconnectez-vous : elles apparaissent immédiatement, tandis que la télémétrie n'apparaît qu'à l'arrivée du message suivant.
Le portail ConnectMQ propose aussi une vue des appareils organisée par niveaux ISA-95 (entreprise, site, zone, ligne, cellule). Si vos topics suivent une organisation Unified Namespace, cette vue regroupe les mêmes données selon la hiérarchie de l'usine plutôt que selon les chaînes brutes, ce qui fait ressortir les appareils mal placés. Notre article sur Sparkplug B et le Unified Namespace explique cette structure.
Parcourir les topics en ligne de commande
Un explorateur graphique n'est pas toujours disponible. mosquitto_sub avec l'option -v affiche le topic avant chaque payload, et quelques options supplémentaires en font un explorateur léger :
# Tous les topics sous votre racine, avec leurs noms
mosquitto_sub -h broker.connectmq.com -p 1883 -i browse-$RANDOM \
-t 'connectmq/demo/RUN_ID/#' -v
# Uniquement les retained messages : connexion, affichage des retained, sortie après 3 s
mosquitto_sub -h broker.connectmq.com -p 1883 -i retained-$RANDOM \
-t 'connectmq/demo/RUN_ID/#' -v --retained-only -W 3
# Noms de topics uniques vus en 30 secondes
timeout 30 mosquitto_sub -h broker.connectmq.com -p 1883 -i list-$RANDOM \
-t 'connectmq/demo/RUN_ID/#' -F '%t' | sort -u
Remplacez RUN_ID par la valeur affichée par le script. La dernière commande est ce qui se rapproche le plus d'un « lister les topics » en MQTT, et c'est un moyen rapide de comparer les topics attendus à ceux qui existent réellement. D'autres recettes figurent dans nos exemples mosquitto_pub et mosquitto_sub.
Les schémas de débogage révélés par un explorateur de topics
Une fois habitué à lire une arborescence, la plupart des problèmes de topics se ramènent à un petit nombre de schémas.
| Ce que vous voyez dans l'arborescence | Ce que cela signifie | Correction |
|---|---|---|
| Deux branches qui ne diffèrent que par la casse | Nommage incohérent dans le firmware ou la configuration | Standardisez en minuscules et imposez-le en revue de code |
| Une feuille au nom vide | Slash final dans le topic de publication | Supprimez les slashs finaux avant de publier |
| Un premier niveau au nom vide | Slash initial (/factory1/...) |
Supprimez le slash initial ; il ajoute un niveau inutile |
| Une feuille dont la valeur ne change jamais | L'appareil a cessé de publier, ou la valeur est une donnée retained obsolète | Vérifiez l'appareil ; effacez le retained message s'il est périmé |
| Des valeurs qui alternent entre plusieurs formats | Deux versions de firmware ou deux éditeurs sur un même topic | Versionnez le payload ou séparez les topics |
| Des centaines de feuilles sœurs avec des IDs dans le nom | IDs uniques placés trop haut dans la hiérarchie | Descendez les IDs au niveau de l'appareil |
| Des branches très profondes | Topics sur-structurés | Aplatissez ; le broker public autorise 8 niveaux |
Effacer les retained messages obsolètes
Les valeurs retained persistent sur le broker jusqu'à leur remplacement. Un appareil mis hors service peut donc continuer à afficher une valeur « actuelle » dans tous les tableaux de bord. Pour supprimer un retained message, publiez un payload retained vide sur le topic exact :
mosquitto_pub -h broker.connectmq.com -p 1883 -i clear-$RANDOM \
-t 'connectmq/demo/RUN_ID/factory1/Line1/cnc1/meta' -r -n
L'option -n envoie un payload de longueur nulle et -r active le flag retain. Rafraîchissez l'explorateur de topics : la branche Line1 disparaît dès qu'elle n'a plus d'autres enfants.
Bien utiliser un explorateur de topics en production
Un explorateur abonné à # sur un broker de production chargé reçoit chaque message, ce qui consomme de la bande passante et peut atteindre les quotas d'abonnements ou de connexions. Quelques habitudes le gardent utile :
- Abonnez-vous à la racine la plus étroite qui répond à votre question, comme
factory1/line2/#, plutôt qu'à#. - Utilisez un identifiant dédié aux outils de débogage, pour qu'une session d'exploration ne prenne jamais le client ID d'un appareil et ne le mette pas hors ligne.
- Vérifiez l'état de connexion autant que les données. Le topic
$SYS/broker/connection/{clientId}/statede votre broker ConnectMQ indique si un client donné est connecté, ce qui distingue « appareil hors ligne » de « appareil en ligne mais silencieux ». - Mettez par écrit vos règles de nommage et comparez-y l'arborescence après chaque version de firmware.
Pour les flux de travail centrés sur l'éditeur, l'extension VS Code de ConnectMQ et l'explorateur MQTT Desktop de ConnectMQ offrent la même navigation arborescente en dehors du portail. Si vous testez uniquement depuis un navigateur, notre guide d'utilisation d'un client web MQTT en ligne complète bien celui-ci, et la supervision d'un broker MQTT couvre les métriques qu'un explorateur de topics n'affiche pas.
Explorez vos propres topics sur ConnectMQ
Créez un broker gratuit sur app.connectmq.com avec le plan Serverless, sans carte bancaire. Le portail inclut l'explorateur de topics en direct, le client intégré au navigateur et la vue des appareils ISA-95 utilisés dans ce guide. Découvrez ConnectMQ en tant que broker MQTT managé, ou lisez le guide général pour choisir un broker MQTT cloud.
Questions fréquentes
Puis-je lister tous les topics d'un broker MQTT ?
Pas directement : MQTT n'a pas de registre de topics. Un explorateur de topics s'abonne à un wildcard et affiche les topics qui reçoivent des messages, ainsi que les topics retained, ce qui en est l'équivalent pratique.
Pourquoi mon explorateur de topics n'affiche-t-il pas un topic dont je sais qu'il existe ?
Soit rien n'y a été publié depuis votre abonnement et il ne contient aucun retained message, soit votre wildcard ne le couvre pas. Vérifiez la casse, les slashs initiaux ou finaux et la racine de l'abonnement.
S'abonner à # est-il sans risque sur un broker de production ?
Cela fonctionne, mais vous recevez chaque message, ce qui peut être lourd. Abonnez-vous à la racine la plus étroite qui répond à votre question et utilisez un identifiant dédié au débogage.
Comment supprimer un topic de l'arborescence ?
Les topics disparaissent lorsque plus rien ne les maintient. Effacez un retained message en publiant un payload retained vide sur ce topic exact, et arrêtez l'éditeur qui le crée.
