Zigbee2MQTT dans Home Assistant sans conflit

MQTT est un bus de messages : Zigbee2MQTT y publie l'état de chaque objet, et Home Assistant s'y abonne via son intégration MQTT.

Zigbee est la radio qui relie vos objets au coordinateur branché en USB. MQTT, lui, est le bus logiciel par lequel Zigbee2MQTT transmet l'état de chaque objet. Deux couches, deux rôles : la radio porte les trames, le bus les diffuse. Home Assistant n'écoute pas le Zigbee ; il s'abonne aux topics MQTT via son intégration MQTT, et c'est Zigbee2MQTT qui les publie.

Zigbee2MQTT s'installe donc comme un add-on séparé, pas dans le menu Intégrations. Vous le lancez, il pilote le coordinateur, publie sur le broker, et Home Assistant consomme. Ça tient si le broker tourne ; sinon les entités restent muettes.

Quand l'installation fonctionne, le journal du broker montre les messages de Zigbee2MQTT et Home Assistant découvre les entités automatiquement.

Le journal de l'add-on doit vous montrer deux choses : la connexion au broker, puis l'ouverture du coordinateur. S'il répète un message d'erreur, la chaîne est cassée quelque part, donc inutile d'aller plus loin.

Pour valider l'ensemble, faites un appairage test avec un seul objet : il apparaît d'abord dans Zigbee2MQTT, puis comme entité dans Home Assistant. Ça tient la charge si ce trajet va au bout ; ça décroche si une étape manque. Testez ainsi avant de migrer tous vos appareils d'un coup.

Avant d'installer Zigbee2MQTT, vérifiez qu'aucun autre logiciel ne prend déjà le contrôle du dongle.

ZHA et Zigbee2MQTT ne peuvent pas se partager le même dongle : pendant que l'un parle au coordinateur, l'autre est aveugle. Donc, avant d'installer Zigbee2MQTT, désactivez ZHA. Dans Paramètres puis Appareils et services, cherchez une entrée Zigbee Home Automation ; si elle existe, désactivez-la. Le symptôme d'un conflit ressemble à une panne : ça ne se connecte pas, sans message clair.

Le piège ne vient pas toujours de ZHA. Une seconde instance Zigbee2MQTT, ou une version Edge oubliée qui tourne encore, produit exactement les mêmes erreurs. Et si le port USB change de nom après un redémarrage, la configuration casse alors que vous n'avez rien touché. Identifiez le port une fois pour toutes et gardez-le stable. Ça tient la charge si le dongle reste le même, ça décroche dès qu'il bouge.

Installez d'abord le broker MQTT, démarrez-le, puis installez Zigbee2MQTT et connectez-le à ce broker.

Montez d'abord le broker MQTT, puisque Zigbee2MQTT ne démarre pas correctement s'il ne trouve pas de broker joignable. Ajoutez-le depuis le magasin d'add-ons, démarrez-le, puis activez l'intégration MQTT dans Home Assistant pour que les entités remontent.

Ensuite seulement, installez Zigbee2MQTT. Dans son écran de configuration, choisissez le port du coordinateur et l'emplacement du broker. Le dongle doit être branché avant de lancer l'add-on.

Trois réglages suffisent au départ, à savoir le chemin stable du coordinateur, les identifiants du broker et la base topic.

Le port du coordinateur ne se donne pas par numéro, puisque ce numéro peut changer après un redémarrage. Renseignez plutôt le chemin par identifiant matériel, car il reste le même d'un démarrage à l'autre. C'est ce qui évite de retrouver Zigbee2MQTT pointé vers le mauvais port. Les identifiants du broker et la base topic se configurent dans le même fichier. La base topic est le préfixe commun des messages. Gardez celle par défaut, sauf si vous faites tourner plusieurs installations sur le même broker. Vérifiez aussi que l'adaptateur correspond à la puce du dongle, sinon la communication radio ne s'ouvre pas. Ça tient la charge si ces trois points sont justes, ça décroche si l'un d'eux est approximatif.

Dans la majorité des cas, un autre logiciel occupe déjà le dongle ou bien deux instances Zigbee2MQTT tournent en même temps.

Un journal qui affiche une erreur d'ouverture du port signifie presque toujours que le dongle est déjà pris ailleurs, par ZHA ou par une seconde instance. Repérez la ligne qui nomme le port, filtrez le journal sur cette ouverture, et vous verrez qui tient le coordinateur.

Deux instances Zigbee2MQTT sur le même coordinateur se disputent les objets. Les états deviennent incohérents et l'appairage échoue, puisque chacune croit piloter le réseau. Et si la base topic de Zigbee2MQTT diffère de celle de l'intégration MQTT, Home Assistant reste silencieux alors que tout paraît démarré.

Vous arrêtez Zigbee2MQTT, vous désactivez proprement son côté Home Assistant, puis vous réactivez ZHA sur le même coordinateur.

Vous voulez revenir en arrière ? Aucune conversion automatique n'existe entre les deux bases, et il faut d'abord le savoir. D'après la documentation officielle, ZHA ne sait pas importer une base Zigbee2MQTT. Vos objets devront donc être réappairés un par un, même s'ils restent physiquement à leur place. Avant de toucher aux intégrations, exportez une sauvegarde complète de Home Assistant. Elle seule fait la différence entre une reprise propre et une réinstallation à l'aveugle.

Vous arrêtez Zigbee2MQTT, vous désactivez proprement son côté Home Assistant, puis vous réactivez ZHA sur le même coordinateur. Si vous repartez d'une base vide, supprimez d'abord l'ancienne base Zigbee2MQTT. Sans cela, les objets fantômes réapparaissent et polluent vos tableaux de bord. La marche arrière demande une soirée, pas un week-end, à condition de sauvegarder avant.

Zigbee2MQTT apporte plus de réglages et une compatibilité plus large ; ZHA reste plus simple à maintenir au quotidien.

Si votre réseau Zigbee tient avec ZHA et que vous n'avez aucun besoin de réglage fin, la migration vous coûte du temps pour un gain mince. Ça tient la charge tant que vos objets sont reconnus et que le comportement par défaut vous suffit : vous n'avez alors rien à gagner à tout réinstaller.

Zigbee2MQTT devient intéressant dès qu'un objet n'est pas reconnu, que vous voulez régler la puissance radio, ou que vous préférez gérer votre configuration dans un fichier lisible plutôt que dans une interface. Dans les deux cas, votre coordinateur doit être compatible avec le logiciel choisi. Vérifiez ce point avant de trancher, puisque c'est lui qui décide si le passage est possible.

Zigbee2MQTT se monte proprement à condition de préparer le broker MQTT, de libérer le coordinateur et de sauvegarder avant toute bascule.

Zigbee2MQTT publie ses données sur un bus MQTT auquel Home Assistant s'abonne, au lieu de fonctionner comme une intégration cloisonnée. Le broker MQTT est donc le premier maillon à installer et démarrer avant même de penser au dongle. Une fois ce socle en place, Zigbee2MQTT s'y connecte et Home Assistant découvre les entités automatiquement. Si ce mécanisme est compris, la plupart des blocages se lisent facilement dans le journal du broker.

Le vrai piège n'est pas l'installation mais la concurrence sur le coordinateur. Un seul logiciel doit contrôler le dongle à la fois, sinon Zigbee2MQTT démarre mal ou perd ses objets. Vérifiez donc qu'aucune autre instance ni ZHA ne l'occupe, puis renseignez le chemin stable, les identifiants du broker et la base topic. Un retour à ZHA implique de réappairer les objets. Exportez une sauvegarde complète avant toute manipulation.