Ces exemples de hiérarchie de topics MQTT vous offrent des arborescences prêtes à l'emploi pour quatre types de projets courants : une maison connectée, une flotte de véhicules, une usine et un système de supervision énergétique. Pour chacun, vous verrez l'arborescence, les abonnements qu'elle doit servir et les décisions qui la sous-tendent, afin de pouvoir l'adapter au lieu de partir d'une page blanche.
Les principes d'une bonne hiérarchie de topics MQTT
Toutes les arborescences ci-dessous suivent la même poignée de règles. Les connaître permet d'adapter plus facilement les exemples à votre propre projet.
- Du général au particulier. Placez le niveau le plus général en premier (site, maison, flotte) et le plus spécifique en dernier (une mesure ou une commande précise).
- Profondeur fixe par type de données. Si la télémétrie de chaque appareil se trouve au même niveau, un seul motif
+les retrouve toutes. - Séparer les données selon leur sens. La télémétrie remonte, les commandes descendent. Donnez-leur des branches différentes pour que les appareils ne s'abonnent qu'à ce dont ils ont besoin.
- Minuscules, pas d'espaces, pas de barre oblique initiale.
home/kitchen/tempetHome/Kitchen/Tempsont deux topics différents ; une/initiale crée un premier niveau vide. - Des identifiants qui résistent aux changements. Utilisez des étiquettes d'actif ou des numéros de série, pas des libellés humains qui seront renommés.
- Concevoir pour les abonnements, pas pour l'éditeur. Notez les requêtes wildcard que les consommateurs exécuteront avant de figer l'arborescence.
Le raisonnement détaillé est présenté dans les conventions de nommage des topics MQTT. Ici, nous nous concentrons sur des arborescences concrètes.
Exemple de hiérarchie de topics pour une maison connectée
Une maison a une structure naturelle : les pièces contiennent des appareils, et les appareils exposent un état et acceptent des commandes.
home/<room>/<device>/state # état courant, retenu
home/<room>/<device>/set # commande envoyée à l'appareil
home/<room>/<device>/availability # online/offline (Last Will)
home/<room>/<sensor>/<measurement> # mesures numériques
home/livingroom/lamp/state -> {"on": true, "brightness": 70}
home/livingroom/lamp/set -> {"on": false}
home/kitchen/climate/temperature -> 21.4
home/kitchen/climate/humidity -> 48
home/garage/door/state -> "closed"
home/garage/door/availability -> "online"
| Besoin du consommateur | Abonnement |
|---|---|
| Tout ce qui concerne la cuisine | home/kitchen/# |
| L'état de chaque appareil | home/+/+/state |
| Chaque mesure de température | home/+/+/temperature |
| Les appareils hors ligne | home/+/+/availability |
Publiez state et availability sous forme de retained messages, afin qu'un tableau de bord lancé plus tard connaisse immédiatement la situation actuelle. Les commandes ne doivent pas être retenues, sinon un appareil qui redémarre rejouera le « ouvre la porte du garage » de la veille. Pour un traitement plus approfondi des pièces, des intégrations et de la découverte Home Assistant, consultez le guide sur la structure des topics MQTT pour la maison connectée. Jeedom et Domoticz savent aussi communiquer en MQTT : une arborescence propre sert donc toute la maison connectée, quelle que soit la box domotique.
Exemple de hiérarchie de topics pour une flotte de véhicules
Les données de flotte s'organisent autour des véhicules, et les consommateurs veulent généralement soit la vue complète d'un véhicule, soit un type de données sur toute la flotte.
fleet/<region>/<vehicleId>/telemetry/<stream>
fleet/<region>/<vehicleId>/events/<eventType>
fleet/<region>/<vehicleId>/cmd/<command>
fleet/<region>/<vehicleId>/status
fleet/eu-west/van-0142/telemetry/gps -> {"lat": 51.51, "lon": -0.12, "spd": 34}
fleet/eu-west/van-0142/telemetry/engine -> {"rpm": 1800, "coolant": 88}
fleet/eu-west/van-0142/events/harsh-brake -> {"ts": 1792130400, "g": 0.52}
fleet/eu-west/van-0142/cmd/locate -> {}
fleet/eu-west/van-0142/status -> "online"
| Besoin du consommateur | Abonnement |
|---|---|
| Carte en direct de tous les véhicules | fleet/+/+/telemetry/gps |
| Tout ce qui provient d'une camionnette | fleet/+/van-0142/# |
| Événements de conduite dans une région | fleet/eu-west/+/events/# |
Les décisions à reprendre :
- La région avant le véhicule. Cela permet de répartir ultérieurement le traitement par région, par exemple avec des abonnements partagés par groupe de workers régional.
- Des flux plutôt qu'un payload géant. Le GPS à une seconde d'intervalle et les données moteur toutes les trente secondes ne doivent pas être forcés dans le même message.
- Des commandes par véhicule. Chaque véhicule s'abonne à
fleet/<region>/<its id>/cmd/#et à rien d'autre.
Exemple de hiérarchie de topics pour une usine
Dans l'industrie, la hiérarchie des équipements existe déjà dans la documentation de l'usine : l'arborescence doit la refléter. Une version simplifiée :
<site>/<area>/<line>/<machine>/<namespace>/<detail>
plant1/assembly/line1/robot2/telemetry/joint-temps
plant1/assembly/line1/robot2/state
plant1/assembly/line1/robot2/alarms/overtemp
plant1/machining/line3/cnc1/telemetry/spindle
plant1/machining/line3/cnc1/cmd/stop
| Besoin du consommateur | Abonnement |
|---|---|
| Service TRS (OEE) pour une ligne | plant1/machining/line3/+/state |
| Vue maintenance de toutes les alarmes | plant1/+/+/+/alarms/# |
| Historian pour l'ensemble du site | plant1/# |
Gardez un vocabulaire d'espaces de noms restreint et fixe : telemetry, state, alarms, events, cmd. Lorsqu'un intégrateur invente data, values et measurements pour désigner la même chose, chaque consommateur doit apprendre trois motifs.
Exemple de hiérarchie de topics pour la supervision énergétique
Les projets énergétiques mélangent compteurs, onduleurs et batteries répartis sur plusieurs bâtiments. L'arborescence sépare l'emplacement physique de la grandeur énergétique mesurée.
energy/<site>/<building>/<meterId>/<quantity>
energy/campus-a/building-3/main-meter/power -> 42.7 (kW)
energy/campus-a/building-3/main-meter/energy -> 18233.4 (kWh)
energy/campus-a/building-3/pv-inverter-1/power -> 12.1
energy/campus-a/building-3/battery-1/soc -> 76
energy/campus-a/building-3/battery-1/cmd/mode -> "discharge"
Indiquez les unités dans la documentation ou dans le payload, jamais dans le topic lui-même. Un topic comme .../power_kw devient faux le jour où quelqu'un publie des watts. Un payload JSON tel que {"v": 42.7, "unit": "kW", "ts": 1792130400} garde le topic stable et la mesure autodescriptive.
Pour finir : une arborescence de style ISA-95
Lorsqu'un projet dépasse un seul site ou commence à alimenter un Unified Namespace, il converge généralement vers une arborescence de style ISA-95 : entreprise, site, zone, ligne, cellule ou machine, puis un espace de noms de données. C'est aussi la forme qu'utilise ConnectMQ lorsqu'il republie des données Sparkplug B sous forme de topics lisibles. Un message Sparkplug sur
spBv1.0/factory1/DDATA/line1/cnc1
est décodé et republié sur
connectmq/factory1/production/line1/cnc1/telemetry
Ce qui donne un exemple complet de la structure cible :
<enterprise>/<site>/<area>/<line>/<machine>/<namespace>
connectmq/factory1/production/line1/cnc1/telemetry
connectmq/factory1/production/line1/cnc1/state
connectmq/factory1/production/line2/press4/telemetry
connectmq/factory1/quality/lab/cmm1/events
Le portail ConnectMQ reconnaît les topics ISA-95 et Unified Namespace et affiche les appareils regroupés selon ces niveaux : une arborescence rigoureuse porte donc directement ses fruits dans la vue des appareils. L'article sur les topics MQTT ISA-95 explique chaque niveau et ses pièges, et le guide Sparkplug B et Unified Namespace montre comment les deux s'articulent.
Comparaison des quatre arborescences
| Projet | Niveau supérieur | Niveau d'identité | Données réparties par | Profondeur type |
|---|---|---|---|---|
| Maison connectée | home |
appareil dans une pièce | state / set / mesure | 4 |
| Flotte | fleet |
véhicule dans une région | telemetry / events / cmd | 4–5 |
| Usine | site | machine sur une ligne | espace de noms | 5–6 |
| Énergie | energy |
compteur dans un bâtiment | grandeur | 5 |
La profondeur compte sur les brokers réels. Certains brokers limitent le nombre de niveaux de topic, et chaque niveau supplémentaire coûte des octets dans chaque message. Le serveur MQTT public gratuit broker.connectmq.com, par exemple, autorise jusqu'à 8 niveaux de topic : un préfixe de démonstration comme connectmq/demo/<id> laisse donc cinq niveaux pour votre propre arborescence.
Tester une arborescence sur le broker public
Vous pouvez prototyper n'importe laquelle de ces hiérarchies sur le serveur MQTT public gratuit avant de vous engager. Utilisez un préfixe unique, car l'espace public est lisible par tous, et gardez des données non sensibles.
# Abonné : tous les états d'appareils de votre maison de démonstration
mosquitto_sub -h broker.connectmq.com -p 1883 -i tree-sub-a91c \
-t 'connectmq/demo/a91c/home/+/+/state' -v
# Éditeur : un état de lampe retenu
mosquitto_pub -h broker.connectmq.com -p 1883 -i tree-pub-a91c -r \
-t 'connectmq/demo/a91c/home/livingroom/lamp/state' \
-m '{"on": true, "brightness": 70}'
Cet exemple utilise sept niveaux, ce qui respecte la limite du broker public. Si l'abonné voit l'état de la lampe, votre plan de wildcards fonctionne. Essayez ensuite connectmq/demo/a91c/home/livingroom/# et vérifiez qu'il ne renvoie que le salon. Si l'arborescence est nouvelle pour vous, le guide des wildcards MQTT explique précisément comment + et # correspondent à chaque niveau, et le tutoriel MQTT couvre les bases du publish/subscribe.
Erreurs courantes dans les hiérarchies de topics
- Placer le type de données en premier.
temperature/kitchendisperse chaque appareil sur de nombreuses branches et complique les abonnements par appareil. - Encoder des valeurs dans les topics. Avoir
home/lamp/onethome/lamp/offcomme topics oblige les consommateurs à s'abonner aux deux ; publiez la valeur dans le payload. - Un topic par identifiant de message ou par horodatage. Les topics sont des adresses, pas des enregistrements. Des topics uniques par message gonflent le stockage des retained messages et les listes de topics.
- Des séparateurs mélangés.
line-1,line_1etLine1dans la même arborescence finiront par casser le wildcard de quelqu'un. Choisissez un seul style. - Pas de branche de commandes. Si les commandes partagent un topic avec la télémétrie, les appareils reçoivent leurs propres données en retour et doivent filtrer davantage.
Démarrer avec ConnectMQ
Lorsque votre arborescence est prête pour de vrais appareils, exécutez-la sur un broker MQTT cloud avec TLS et des identifiants privés, par exemple un broker MQTT managé comme ConnectMQ. Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire, et regardez votre hiérarchie se remplir grâce à l'explorateur de topics en direct et à la vue des appareils ISA-95.
Questions fréquentes
Quelle profondeur doit avoir une hiérarchie de topics MQTT ?
Suffisamment pour identifier la source et le type de données, généralement quatre à six niveaux. Des niveaux supplémentaires ajoutent des octets à chaque message et peuvent atteindre les limites du broker sans apporter de structure utile.
Faut-il placer l'ID de l'appareil ou le type de données en premier ?
Placez d'abord l'emplacement et l'identité de l'appareil, puis le type de données. Ainsi, toutes les données d'un appareil restent sous une même branche, tout en permettant aux wildcards + de sélectionner un type de données sur l'ensemble des appareils.
Puis-je modifier ma hiérarchie de topics plus tard ?
Oui, mais chaque éditeur et chaque abonné doit évoluer avec elle. Une stratégie de migration courante consiste à publier à la fois sur l'ancienne et la nouvelle arborescence pendant une période de transition, puis à retirer l'ancienne une fois les consommateurs migrés.
Ai-je besoin d'ISA-95 pour un petit projet ?
Non. Une arborescence simple comme celle de l'exemple de maison connectée convient parfaitement aux petits projets. Les arborescences de style ISA-95 deviennent rentables dès que plusieurs sites, équipes ou systèmes partagent un même espace de noms.
