Zigbee MQTT : comprendre la chaîne avant de l'installer

Zigbee MQTT fonctionne avec quatre rôles distincts : les appareils Zigbee communiquent avec un coordinateur, Zigbee2MQTT traduit leurs états, un broker MQTT distribue les messages et Home Assistant les transforme en entités ou automatisations. Si le premier H2 doit retenir une seule idée, c’est celle-ci : MQTT transporte les données, mais ne remplace pas le réseau radio Zigbee.

Cette séparation explique les pannes. Un capteur peut être correctement appairé au réseau Zigbee, tandis que Home Assistant ne reçoit rien parce que le broker est arrêté. À l’inverse, MQTT peut fonctionner alors qu’un coordinateur mal placé perd les appareils radio.

Le coordinateur Zigbee est l’adaptateur radio qui pilote un réseau Zigbee. Il peut prendre la forme d’une clé USB ou d’un module compatible. Une installation ne doit pas laisser deux logiciels piloter le même coordinateur en parallèle : cette exclusivité évite des conflits difficiles à diagnostiquer.

Zigbee2MQTT sert de passerelle. Il dialogue avec le coordinateur, connaît les appareils compatibles et publie leurs états sous des topics MQTT. Son interface permet souvent d’appairer, nommer et surveiller les appareils, mais le service reste dépendant de la qualité de la liaison radio.

Le broker MQTT, souvent Mosquitto, reçoit et distribue les messages. Zigbee2MQTT s’y connecte avec une adresse de serveur, un port et éventuellement des identifiants. Home Assistant se connecte au même broker pour consommer ces messages. Une erreur d’utilisateur, de mot de passe ou de réseau peut donc ressembler à une panne Zigbee.

Oui, Zigbee2MQTT nécessite une connexion à un serveur MQTT pour fonctionner. Le broker peut tourner sur la même machine que Home Assistant, dans un conteneur séparé, sur un NAS ou sur un autre serveur local. Le choix importe moins que sa disponibilité et sa configuration cohérente.

Le point à vérifier n’est pas seulement l’installation de Mosquitto. Zigbee2MQTT doit atteindre le serveur, utiliser le bon port et s’authentifier si le broker l’exige. Home Assistant doit ensuite se connecter au même broker. Deux services configurés sur deux adresses différentes ne partagent pas les mêmes messages.

Pour un premier montage, gardez les briques proches : broker et Zigbee2MQTT sur le même hôte, réseau local simple, sauvegarde de la configuration. Vous pourrez séparer les services plus tard si le besoin est réel.

Home Assistant peut découvrir automatiquement les appareils exposés par Zigbee2MQTT grâce à MQTT discovery. Une lampe, un capteur de température ou un contact de porte apparaît alors comme une entité exploitable dans les tableaux de bord et automatisations.

La découverte ne corrige pas une chaîne cassée. Si le broker ne reçoit aucun message, si le préfixe MQTT est incohérent ou si l’intégration Home Assistant est mal connectée, les appareils resteront absents. Vérifiez dans cet ordre : le service Zigbee2MQTT démarre-t-il, le broker reçoit-il les messages, Home Assistant est-il abonné ?

Ne réappairez pas immédiatement tous les capteurs. Commencez par lire les journaux et testez un topic MQTT avec un outil adapté. Vous éviterez de transformer un problème de connexion en problème de migration.

Une clé Zigbee branchée directement derrière un mini-PC, près d’un port USB 3, d’une box Wi-Fi ou d’un boîtier métallique peut subir des interférences. Les symptômes sont connus : appairage qui échoue, capteurs intermittents, délais irréguliers ou appareils qui passent hors ligne.

Utilisez une rallonge USB et placez le coordinateur dans une zone dégagée, à distance de la machine hôte et des sources radio. Cette précaution paraît secondaire, mais elle améliore souvent davantage la stabilité qu’un changement de réglage logiciel. Pour les capteurs de sécurité, c’est un choix de fiabilité.

Le réseau Zigbee distingue généralement un coordinateur, des routeurs et des appareils finaux. Les prises et modules alimentés en continu peuvent relayer le trafic ; les capteurs sur pile dorment souvent pour économiser leur batterie et ne jouent pas ce rôle.

Dans une maison à étage ou avec une dépendance, ajoutez d’abord quelques routeurs Zigbee bien placés, puis appairez les capteurs à leur emplacement définitif. Un capteur qui fonctionne sur la table n’offre aucune garantie une fois installé derrière un mur épais ou au fond d’un garage.

Observez les délais, les pertes et la stabilité sur plusieurs jours. Une seule valeur de qualité radio ne suffit pas pour juger un réseau domestique.

1. Choisir un adaptateur non supporté ou négliger son firmware coordinateur.
2. Brancher le dongle sans rallonge contre le serveur ou près des perturbations USB.
3. Confondre MQTT et Zigbee alors que les deux couches peuvent tomber séparément.
4. Appairer tous les capteurs d’un coup avant d’avoir validé un premier appareil.
5. Faire piloter le coordinateur par deux logiciels concurrents.
6. Changer plusieurs composants à la fois et perdre la cause de la panne.

La méthode la plus efficace est progressive : une brique, un test, une sauvegarde, puis seulement l’étape suivante.

Conservez une copie de la configuration Zigbee2MQTT, notez le modèle du coordinateur et documentez l’adresse du broker. Avant un changement de firmware, une migration ou une mise à jour importante, faites une sauvegarde et lisez la documentation correspondante.

Évitez d’empiler les changements. Remplacer le coordinateur, déplacer le serveur et mettre à jour Zigbee2MQTT le même soir rend le retour arrière beaucoup plus difficile. Une modification à la fois donne un diagnostic exploitable.

Zigbee2MQTT convient aux personnes qui veulent une installation ouverte, multi-marques et contrôlable localement. Si vous cherchez une solution totalement invisible, sans maintenance ni diagnostic, un pont propriétaire ou une alarme dédiée peut être plus adapté.

Le meilleur choix n’est pas celui qui offre le plus de réglages, mais celui que vous pourrez comprendre et maintenir dans six mois. Pour une maison connectée, la lisibilité de l’architecture vaut souvent plus qu’une compatibilité théorique.

Zigbee MQTT désigne une architecture : les appareils communiquent en Zigbee, le coordinateur pilote le réseau, Zigbee2MQTT fait la passerelle et le broker MQTT transporte les messages vers Home Assistant ou un autre logiciel.

Commencez par un coordinateur documenté, un broker stable, une rallonge USB et un seul appareil de test. Cette base vous permettra d’ajouter progressivement le maillage et les scénarios sans transformer chaque panne en migration complète.