Structure des topics MQTT maison connectée : conseils

Une bonne structure des topics MQTT pour la maison connectée fait la différence entre des automatisations lisibles d'un coup d'œil et un enchevêtrement de topics sensor1/temp2 dont personne ne se souvient. Dans ce guide, vous obtiendrez une organisation pièce/appareil/propriété prête à l'emploi, vous comprendrez pourquoi les topics de commande et d'état doivent être séparés, et vous verrez comment retained messages, disponibilité et wildcards s'articulent sur un vrai broker.

Pourquoi la conception des topics compte avant le dixième appareil

Avec trois appareils, n'importe quel nommage fonctionne. Une fois arrivé à trente, les noms de topics déterminent la facilité avec laquelle vous pouvez :

vous abonner à « tout ce qui se trouve dans la cuisine » ou à « toutes les températures de la maison » avec un seul wildcard,
ajouter un nouvel appareil sans modifier chaque automatisation,
savoir si un message est une demande ou un fait,
voir dans un explorateur de topics ce qui se passe réellement.

MQTT n'impose aucune structure. Les topics sont de simples chaînes UTF-8 découpées par /, et le broker compare les abonnements à ces chaînes. C'est précisément cette liberté qui rend une convention nécessaire. Si le fonctionnement du routage des messages par le broker est nouveau pour vous, commencez par le rôle d'un broker MQTT.

L'organisation recommandée : maison, pièce, appareil, propriété

Une organisation qui passe bien à l'échelle pour la plupart des logements est :

<home>/<room>/<device>/<property>[/set]

Exemples :

home1/kitchen/ceiling-light/power            state: "ON" or "OFF" (retained)
home1/kitchen/ceiling-light/power/set        command: "ON", "OFF", "TOGGLE"
home1/kitchen/ceiling-light/brightness       state: 0-100 (retained)
home1/kitchen/ceiling-light/brightness/set   command: 0-100
home1/livingroom/climate/temperature         state: 21.6 (retained)
home1/livingroom/climate/humidity            state: 48 (retained)
home1/garage/door/state                      state: "open", "closed", "opening" (retained)
home1/garage/door/state/set                  command: "OPEN", "CLOSE"
home1/garage/door/availability               "online" or "offline" (retained, last will)

Pourquoi cet ordre fonctionne :

Niveau	Rôle	Exemple de wildcard
`home`	Sépare les sites (maison, appartement de vacances, maison des parents)	`home1/#`
`room`	Correspond à la façon dont les gens pensent et parlent	`home1/kitchen/#`
`device`	Un appareil physique ou logique	`home1/+/climate/#`
`property`	Une valeur ou une capacité	`home1/+/+/temperature`
Suffixe `set`	Marque une commande, pas un fait	`home1/+/+/+/set`

Limitez la profondeur à cinq niveaux au maximum. Les arborescences profondes sont plus pénibles à saisir, et le serveur MQTT public gratuit, réservé aux tests, limite de toute façon les topics à huit niveaux, ce qui constitue un plafond raisonnable pour une maison.

Topics de commande et d'état dans la structure des topics MQTT d'une maison connectée

La règle la plus importante : n'utilisez jamais le même topic pour les commandes et pour l'état.

Si une lampe écoute et rend compte sur home1/kitchen/ceiling-light/power, un tableau de bord qui publie ON verra son propre message lui revenir, ne pourra pas savoir si la lampe s'est réellement allumée, et une commande ON en retained message rallumera la lampe à chaque reconnexion de l'appareil, même après que quelqu'un l'a éteinte à l'interrupteur.

Avec des topics séparés, le flux est sans ambiguïté :

Le tableau de bord publie ON sur .../power/set (sans retain).
L'appareil commute le relais.
L'appareil publie ON sur .../power avec le flag retain.
Chaque abonné, tableau de bord compris, se met à jour à partir du topic d'état.

Le topic d'état devient la source de vérité unique. Les commandes sont des demandes qui peuvent échouer ; les états sont des faits confirmés par l'appareil.

Retenez l'état, jamais les commandes

Les retained messages permettent à un client nouvellement connecté de voir immédiatement l'état actuel. C'est exactement ce que vous voulez pour les états et la disponibilité, et exactement ce que vous ne voulez pas pour les commandes. Un OPEN en retained message sur le topic de commande d'une porte de garage, c'est une porte qui s'ouvre toute seule après chaque coupure de courant. Notre tutoriel sur l'ouvre-porte de garage MQTT illustre ce pattern dans un projet où une erreur a de réelles conséquences.

Choisissez la QoS selon le type de topic

Les états des capteurs se contentent de QoS 0 ou 1 ; une température manquée est remplacée par la suivante. Les commandes doivent utiliser la QoS 1 pour être livrées au moins une fois, et les appareils doivent traiter les commandes répétées de façon idempotente (ON deux fois reste allumé). Pour les compromis, consultez les niveaux de QoS MQTT expliqués.

Disponibilité et last will

Chaque appareil doit publier un topic availability. Passez-le à online (en retained message) après la connexion et configurez un message last will offline (en retained message) sur le même topic. Si l'appareil perd l'alimentation ou le Wi-Fi, le broker publie le will à sa place, et les tableaux de bord peuvent griser l'appareil au lieu d'afficher une valeur périmée comme si elle était actuelle.

// ESP32 with PubSubClient: last will on connect, then announce online
const char* AVAIL = "home1/garage/door/availability";
if (mqtt.connect(clientId, user, pass, AVAIL, 1, true, "offline")) {
  mqtt.publish(AVAIL, "online", true);
  mqtt.subscribe("home1/garage/door/state/set", 1);
}

Conventions de payload

Structure des topics et format des payloads vont de pair. Choisissez une approche et utilisez-la partout :

Une valeur par topic (.../temperature = 21.6) est simple, fonctionne avec tous les outils et rend les wildcards très puissants.
Un JSON par appareil (.../climate = {"temperature":21.6,"humidity":48}) réduit le nombre de messages et garde la cohérence entre valeurs liées.

Beaucoup de foyers utilisent les deux : du JSON pour les appareils multicapteurs issus de Zigbee2MQTT ou d'ESPHome, des valeurs simples pour les appareils faits maison. Si vous utilisez du JSON, documentez les clés et indiquez les unités soit dans le nom de la clé (temp_c), soit dans une note de schéma. Évitez de mélanger 21.6, "21.6" et "21.6 C" d'un appareil à l'autre.

Des règles de nommage qui évitent les ennuis

Utilisez des noms en minuscules séparés par des tirets : ceiling-light, et non Ceiling Light.
Pas d'espaces, pas de # ni de + dans les noms, pas de / initial (il crée un premier niveau vide).
Nommez les pièces comme le font les occupants, mais évitez les noms susceptibles de changer (chambre-de-tom devient gênant quand Tom déménage ; chambre-2 dure).
Nommez les appareils selon leur fonction, pas selon leur marque ou leur modèle, pour pouvoir remplacer le matériel sans tout renommer.
Réservez un préfixe de premier niveau aux topics système, comme home1/system/backup-status.
Ne mettez jamais de secrets, de codes de porte ou de données personnelles dans les noms de topics ; les topics sont visibles par tout abonné dont les wildcards correspondent.

Intégrer les topics des écosystèmes

Vous ne maîtriserez pas tous les noms de topics. Zigbee2MQTT publie sous zigbee2mqtt/<friendly_name>, Tasmota utilise les préfixes stat/, tele/ et cmnd/, et la découverte Home Assistant utilise homeassistant/<component>/<id>/config. Ne luttez pas contre ces conventions. À la place :

Donnez aux appareils des noms conviviaux qui suivent votre schéma pièce/appareil, par exemple kitchen/ceiling-light dans Zigbee2MQTT, afin que leurs topics deviennent zigbee2mqtt/kitchen/ceiling-light.
Gardez vos propres appareils faits maison sous votre racine home1/.
Laissez Home Assistant transformer le tout en entités grâce à la découverte MQTT. Jeedom et Domoticz savent aussi communiquer en MQTT et peuvent exploiter la même arborescence.

Notre guide d'installation de Zigbee2MQTT montre comment les noms conviviaux se traduisent en topics.

Essayer l'organisation sur un broker public

Vous pouvez tester la structure sans matériel. Utilisez un préfixe aléatoire pour que vos topics n'entrent pas en collision avec ceux des autres :

# Terminal 1: watch the whole house
mosquitto_sub -h broker.connectmq.com -p 1883 -i watch-h7q2 -t "connectmq/demo/h7q2/home1/#" -v

# Terminal 2: a light reports retained state, then a dashboard sends a command
mosquitto_pub -h broker.connectmq.com -p 1883 -i light-h7q2 -r -q 1 \
  -t connectmq/demo/h7q2/home1/kitchen/ceiling-light/power -m ON
mosquitto_pub -h broker.connectmq.com -p 1883 -i dash-h7q2 -q 1 \
  -t connectmq/demo/h7q2/home1/kitchen/ceiling-light/power/set -m OFF

# Every temperature in the house, any room, any device
mosquitto_sub -h broker.connectmq.com -p 1883 -i temps-h7q2 -t "connectmq/demo/h7q2/home1/+/+/temperature" -v

Le préfixe de démo ajoute trois niveaux, une raison de plus pour garder votre propre arborescence peu profonde. La zone publique est lisible par tous : réservez-la aux expériences de structure, pas à votre vraie maison. En passant à un broker privé, vous pourrez supprimer le préfixe de démo et commencer directement à home1/.

Check-list de la structure des topics de la maison connectée

Chaque appareil suit <home>/<room>/<device>/<property>.
Les commandes utilisent un suffixe /set et ne sont jamais retenues.
Les états sont retenus et publiés par l'appareil après qu'il a agi.
Chaque appareil dispose d'un topic availability avec un last will.
Les noms sont en minuscules, avec tirets, et fondés sur la fonction.
Le format des payloads est documenté et cohérent.
La profondeur des topics reste de cinq niveaux au maximum.

Faire tourner votre maison sur un broker privé

Une structure de topics ne reste propre que si le broker qui l'héberge est sûr et fiable. ConnectMQ propose un broker MQTT managé avec TLS sur le port 8883, des identifiants générés et un explorateur de topics en direct où votre arborescence pièce/appareil se parcourt facilement. Si vous hésitez entre l'auto-hébergement et un broker MQTT cloud, pensez à l'accès à distance, aux certificats et aux mises à jour. Pour d'autres projets dans la maison et le bâtiment, consultez le guide de l'automatisation IoT.

Démarrer avec ConnectMQ

Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire, copiez vos identifiants générés et publiez vos premiers topics home1/. L'explorateur de topics en direct de ConnectMQ affiche toute votre maison sous forme d'arborescence en quelques secondes.

Questions fréquentes

Les topics doivent-ils commencer par une barre oblique ?

Non. Une barre oblique initiale crée un premier niveau vide, ce qui est autorisé mais déroutant et source de fautes de frappe. Commencez par le nom de votre maison ou de votre site.

Vaut-il mieux un topic JSON par appareil ou un topic par valeur ?

Les deux fonctionnent. Une valeur par topic est le plus simple pour les wildcards et les appareils faits maison ; un JSON par appareil convient aux appareils multicapteurs. Choisissez une approche par type d'appareil et documentez-la.

Pourquoi ma lampe s'allume-t-elle toute seule après un redémarrage ?

Vous avez probablement retenu un message de commande. Effacez-le en publiant un retained message vide sur le topic de commande, et ne retenez désormais que les topics d'état.

Combien de niveaux de topics une maison connectée doit-elle utiliser ?

Quatre ou cinq suffisent largement : maison, pièce, appareil, propriété et un suffixe set facultatif. Des arborescences plus profondes ajoutent de la saisie pour peu de valeur.

Structure des topics MQTT pour la maison connectée : bonnes pratiques pour pièces, appareils et commandes