Les conventions de nommage des topics MQTT déterminent si votre système reste simple à s'abonner, à sécuriser et à déboguer à mesure qu'il passe de cinq appareils à cinq mille. Ce guide vous donne 12 règles concrètes avec de bons et de mauvais exemples, un modèle réutilisable et une liste de vérification à appliquer avant la livraison du premier appareil.
Pourquoi les noms de topics méritent une convention
Les topics MQTT sont des chaînes UTF-8 libres séparées par des /. Le broker n'impose aucune structure, et les topics sont créés à la volée dès que quelqu'un publie. Cette liberté est pratique le premier jour et pénible le trois-centième, lorsque les abonnés dépendent de dizaines d'orthographes légèrement différentes, que les wildcards capturent les mauvaises données et que personne n'ose plus rien renommer de peur de casser des consommateurs inconnus.
Les noms de topics sont de fait l'API publique de votre système. Chaque abonné, tableau de bord, flux Node-RED et règle d'accès en dépend. S'accorder tôt sur une convention est l'une des améliorations de fiabilité les moins coûteuses qui soient.
Les 12 conventions de nommage des topics MQTT
1. Ne pas commencer par une barre oblique
Une barre / initiale crée un premier niveau vide. /factory/line1 et factory/line1 sont deux topics différents, et ce niveau vide n'apporte que de la confusion.
- Mauvais :
/factory/line1/temp - Bon :
factory/line1/temp
2. N'utiliser que des minuscules
Les topics sont sensibles à la casse. Line1/Temp et line1/temp sont deux topics différents, et le mélange de casses garantit que quelqu'un s'abonnera au mauvais. Choisissez les minuscules et tenez-vous-y.
3. Éviter les espaces et les caractères spéciaux
Les espaces, les accents et les symboles sont autorisés, mais posent des problèmes d'échappement dans les shells, les URL, les journaux et les fichiers de configuration. Utilisez a-z, 0-9, - et _. N'utilisez jamais + ni # dans les noms : ce sont des caractères wildcard dans les abonnements.
- Mauvais :
Plant A/Pump #3/Pressure (bar) - Bon :
plant-a/pump-3/pressure
4. Aller du général au particulier
Ordonnez les niveaux du périmètre le plus large au plus étroit, afin que les wildcards puissent sélectionner des branches entières. Une forme courante est :
<namespace>/<site>/<area>/<line-or-group>/<device>/<category>/<measurement>
Avec cet ordre, acme/berlin/# sélectionne un site et acme/+/+/+/+/telemetry/temperature sélectionne toutes les mesures de température. L'ordre inverse rend ces abonnements impossibles. Consultez les wildcards MQTT pour savoir comment + et # fonctionnent.
5. Commencer par un espace de noms
Un premier niveau comme le nom de votre entreprise, de votre produit ou de votre application sépare votre trafic des autres systèmes qui partagent le même broker et facilite ultérieurement les ponts ou les migrations. Sur le serveur MQTT public gratuit, un préfixe unique comme connectmq/demo/<random-id>/ évite que vos expériences ne gênent les autres.
6. Placer les ID d'appareil après l'emplacement, pas avant
Les identifiants se placent au niveau qui représente l'appareil, après les niveaux de regroupement qui décrivent où il se trouve. Vous pouvez ainsi vous abonner à un emplacement sans connaître chaque ID d'appareil, et à un appareil précis avec un seul topic exact.
- Mauvais :
esp32-a4cf12/berlin/hall2/temperature - Bon :
acme/berlin/hall2/esp32-a4cf12/telemetry/temperature
7. Séparer les catégories de messages
Gardez la télémétrie, l'état, les commandes et les événements dans des branches différentes. Les abonnés et les règles d'accès peuvent alors cibler exactement ce dont ils ont besoin.
| Catégorie | Exemple de topic | QoS / retain habituels |
|---|---|---|
| Télémétrie | acme/berlin/hall2/pump-3/telemetry/pressure |
QoS 0, non retenu |
| État | acme/berlin/hall2/pump-3/state/running |
QoS 1, retenu |
| Statut | acme/berlin/hall2/pump-3/status |
QoS 1, retenu, défini par le Last Will |
| Commandes | acme/berlin/hall2/pump-3/cmd/set-speed |
QoS 1, non retenu |
| Événements / alarmes | acme/berlin/hall2/pump-3/event/overpressure |
QoS 1, non retenu |
8. Versionner le contrat de payload
Lorsque le format des payloads change, les consommateurs cassent. Placez une version là où il est facile de router dessus, soit comme niveau de topic (acme/v2/...), soit comme champ dans chaque payload. Une version dans le topic permet aux anciens et aux nouveaux consommateurs de cohabiter pendant la migration.
9. Rester suffisamment peu profond
Chaque niveau doit avoir un sens. Sept ou huit niveaux suffisent largement pour la plupart des systèmes, et certains brokers imposent une limite ; le serveur MQTT public gratuit de ConnectMQ autorise jusqu'à 8 niveaux. Les arborescences profondes coûtent aussi de la bande passante, car la chaîne de topic complète est envoyée avec chaque message (les alias de topic de MQTT 5 aident, mais ne corrigent pas une mauvaise conception).
10. Ne pas mettre de données ni de secrets dans le topic
Les valeurs, horodatages, jetons et données personnelles ont leur place dans le payload. Un topic comme acme/pump-3/pressure/4.2 crée un nouveau topic à chaque mesure et casse les retained messages et les abonnements. Les noms de topics apparaissent aussi dans les journaux et les outils de supervision : n'y incluez jamais d'identifiants de connexion ni d'informations personnelles.
11. Utiliser des noms singuliers et stables
Choisissez un mot par concept et documentez-le : temperature, et non temp à un endroit et Temperature_C à un autre. Les unités ont leur place dans le payload ou la documentation plutôt que dans le nom du topic, sauf si la même mesure est réellement publiée dans plusieurs unités.
12. Réserver $ au broker
Les topics commençant par $ sont réservés à l'usage interne du broker, comme les statistiques $SYS/..., et ne sont pas capturés par un simple abonnement #. Ne créez pas vos propres topics $. Découvrez ce que votre broker y publie dans les topics $SYS MQTT.
Bonnes et mauvaises arborescences côte à côte
# Difficile à utiliser
/Factory1/Line 1/CNC#1/Temp
cnc1/factory1/temperature/71.3
Factory1/line1/CNC1/TEMP_C
# Facile à utiliser
acme/factory1/machining/line1/cnc1/telemetry/spindle-temperature
acme/factory1/machining/line1/cnc1/state/mode
acme/factory1/machining/line1/cnc1/status
acme/factory1/machining/line1/cnc1/cmd/start
La seconde arborescence suit la hiérarchie de style ISA-95 (entreprise, site, zone, ligne et cellule) souvent utilisée pour un Unified Namespace. Si vous travaillez dans l'industrie, le guide Sparkplug B et Unified Namespace explique comment ces hiérarchies sont standardisées. Pour d'autres arborescences prêtes à l'emploi, parcourez nos exemples de hiérarchie de topics MQTT.
Tester votre convention sur un broker réel
Publiez quelques messages avec la structure envisagée sur le serveur MQTT public gratuit et vérifiez que les abonnements avec wildcards sélectionnent exactement ce que vous attendez. Remplacez n8x4 par votre propre chaîne aléatoire ; l'espace public est lisible par tous et réservé aux tests et aux prototypes. La démonstration supprime le niveau de zone pour que le topic complet reste dans la limite de 8 niveaux du serveur public.
P="connectmq/demo/n8x4/factory1/line1"
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-t "$P/cnc1/telemetry/spindle-temperature" -m '{"v":71.3,"unit":"C"}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-t "$P/cnc2/telemetry/spindle-temperature" -m '{"v":68.9,"unit":"C"}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-r -q 1 -t "$P/cnc1/status" -m 'online'
# Toute la télémétrie de line1, rien d'autre
mosquitto_sub -h broker.connectmq.com -p 1883 -i naming-sub-n8x4 -v \
-t "connectmq/demo/n8x4/factory1/line1/+/telemetry/#"
Seul le message status retenu aurait été livré immédiatement à un nouvel abonné ; la télémétrie ci-dessus a été publiée avant la connexion de l'abonné et n'était pas retenue. Publiez à nouveau pendant que l'abonné tourne pour la voir arriver.
Liste de vérification de votre convention
- Un document écrit liste chaque niveau, sa signification et ses valeurs autorisées.
- Tous les topics sont en minuscules, sans barre oblique initiale, espaces ni caractères wildcard.
- Un espace de noms constitue le premier niveau.
- Les niveaux vont du général au particulier, avec l'ID d'appareil après son emplacement.
- La télémétrie, l'état, le statut, les commandes et les événements ont des branches séparées.
- Une stratégie de versionnage existe.
- Aucune valeur, aucun horodatage ni aucun secret n'apparaît dans les topics.
- La profondeur reste dans les limites du broker.
- Les abonnements avec wildcards de chaque consommateur connu ont été testés.
- L'arborescence a été examinée dans un explorateur de topics avec des données réalistes.
Si vous êtes tout au début, le tutoriel MQTT aborde ensemble les topics, les abonnements et la QoS.
Visualiser votre arborescence dans ConnectMQ
ConnectMQ fournit à chaque broker un explorateur de topics en direct : vous voyez votre hiérarchie grandir en temps réel et repérez immédiatement les orthographes égarées. Il reconnaît aussi les topics de style ISA-95 et Unified Namespace et affiche les appareils par niveau ISA-95, ce qui récompense une convention rigoureuse. En tant que broker MQTT managé, il prend en charge MQTT 3.1.1 et 5.0 sur TCP, TLS et WebSockets. Créez un broker Serverless (Free), sans carte bancaire, et testez votre convention de topics avec de vrais appareils.
Questions fréquentes
Les topics MQTT doivent-ils commencer par une barre oblique ?
Non. Une barre oblique initiale crée un premier niveau vide, ce qui rend les topics plus difficiles à lire et facilite les fautes de frappe. Commencez directement par votre espace de noms, par exemple acme/....
Les topics MQTT sont-ils sensibles à la casse ?
Oui. Sensor/Temp et sensor/temp sont deux topics complètement différents. Utiliser les minuscules partout évite les erreurs de correspondance accidentelles.
Combien de niveaux un topic MQTT doit-il comporter ?
Autant qu'il en faut pour porter du sens, et pas davantage ; la plupart des systèmes ont besoin de quatre à huit niveaux. Vérifiez aussi les limites du broker : le serveur MQTT public gratuit de ConnectMQ autorise jusqu'à 8 niveaux.
Où placer l'ID de l'appareil dans un topic MQTT ?
Après les niveaux qui décrivent l'emplacement ou le regroupement, et avant la catégorie de message et la mesure. Cet ordre permet aux wildcards de sélectionner proprement un site, une ligne ou un seul appareil.
