Guide complet pour configurer MQTT et Zigbee2MQTT sur Home Assistant 2024

En bref

• MQTT sert de messagerie locale entre les équipements et Home Assistant, tandis que Zigbee2MQTT traduit les échanges du réseau Zigbee en messages exploitables.
• Une installation supervisée dans Home Assistant facilite les redémarrages automatiques, les sauvegardes et le suivi des journaux.
• Le choix du coordinateur, son port stable et son emplacement physique ont un effet direct sur la fiabilité du réseau zigbee.
• Un compte MQTT dédié, un mot de passe robuste et une sauvegarde externe évitent les erreurs les plus coûteuses à corriger.

Pourquoi associer MQTT et Zigbee2MQTT dans Home Assistant

Une installation domotique devient vite confuse lorsque chaque objet connecté dépend d’une application, d’un compte en ligne ou d’une passerelle différente. L’association de Home Assistant, MQTT et Zigbee2MQTT propose une autre approche : les appareils communiquent sur le réseau local et les données restent pilotables depuis une interface centrale.

MQTT est un protocole de messagerie léger. Il fonctionne selon un principe simple : un appareil publie une information sur un sujet, appelé « topic », et les services intéressés s’y abonnent. Un détecteur d’ouverture peut ainsi publier l’état « ouvert » ou « fermé ». Home Assistant reçoit l’information et peut déclencher une automatisation, par exemple allumer un éclairage d’entrée entre 18 h et 7 h.

Zigbee2MQTT joue le rôle d’interprète entre le réseau zigbee et le broker MQTT. Le coordinateur USB reçoit les messages radio des capteurs, prises, boutons ou ampoules. Zigbee2MQTT les convertit ensuite dans un format compris par Home Assistant. Cette architecture permet d’utiliser des équipements de fabricants différents sans dépendre de leur passerelle d’origine, sous réserve qu’ils soient compatibles.

Le bénéfice est concret pour un foyer comme celui de Claire et Malik, propriétaires d’une maison de 110 m². Ils disposent de 14 ampoules, 6 détecteurs d’ouverture, 3 capteurs de température et 2 prises commandées. Avec une application par marque, ils devraient gérer plusieurs interfaces. Avec une intégration locale, leurs scénarios se construisent au même endroit : baisse du chauffage si une fenêtre reste ouverte 10 minutes, éclairage du couloir au passage, alerte locale lorsque la porte du garage s’ouvre la nuit.

Cette méthode ne promet pas une maison autonome en toute circonstance. Une coupure électrique, un défaut de carte mémoire ou une panne matérielle restent possibles. Elle réduit toutefois les dépendances inutiles à Internet. Pour une commande locale, un capteur Zigbee et une automatisation Home Assistant peuvent continuer à fonctionner si la connexion internet tombe, tant que le serveur, le routeur local et les équipements sont alimentés.

Le recours à MQTT est aussi utile au-delà du Zigbee. Des objets Wi-Fi, des stations météo, certains systèmes d’alarme compatibles ou des microcontrôleurs peuvent publier des données sur le même broker. Il faut néanmoins séparer les usages sensibles. Une domotique qui pilote l’éclairage ou le chauffage n’a pas vocation à remplacer une alarme certifiée ou une télésurveillance. Les automatismes apportent du confort et des alertes complémentaires, pas une garantie de protection.

Pour comprendre la portée et les contraintes de cette technologie radio, le guide consacré au protocole Zigbee en domotique permet de distinguer les appareils sur piles des équipements qui renforcent le maillage radio. Cette différence explique de nombreux problèmes de portée.

À retenir : MQTT n’est pas un gadget supplémentaire. C’est la couche de communication qui rend possible une intégration locale, lisible et évolutive des protocoles IoT dans Home Assistant.

Préparer le matériel et sécuriser la configuration de Home Assistant

Avant d’installer un module complémentaire, il faut vérifier le socle technique. Home Assistant OS est le choix le plus direct pour une installation supervisée, car il donne accès à la boutique d’applications, aux sauvegardes et au système de surveillance intégré. Une installation en conteneur Docker reste possible, mais elle demande davantage de manipulation pour les volumes, les périphériques USB et les mises à jour.

Une petite machine suffit généralement pour un réseau domestique raisonnable. Pour 20 à 60 appareils connectés et quelques automatisations, un Raspberry Pi récent équipé d’un SSD, un mini-PC basse consommation ou une machine virtuelle correctement dimensionnée convient. Le point important n’est pas seulement la puissance. La stabilité du stockage compte davantage. Une carte microSD sollicitée en permanence finit souvent par devenir le maillon faible.

Un ancien Raspberry Pi peut servir de serveur secondaire pour MQTT et Zigbee2MQTT. Cette séparation a un intérêt : le serveur principal conserve les interfaces, les tableaux de bord et les scénarios, tandis qu’une seconde instance assure les services radio. Ce n’est pas obligatoire. Deux machines impliquent deux alimentations, deux sauvegardes et davantage de réglages réseau. Pour un premier déploiement, une seule instance bien sauvegardée est plus simple à administrer.

La configuration doit aussi tenir compte de l’emplacement. Un coordinateur branché directement derrière un mini-PC, collé à un disque USB 3 ou à un routeur Wi-Fi, peut subir des interférences sur la bande 2,4 GHz. Une rallonge USB de 50 cm à 1 m améliore souvent la qualité radio. L’antenne doit rester verticale, dégagée et placée si possible à plus de 1 m du routeur Wi-Fi.

Dans Home Assistant, commencer par créer un utilisateur non administrateur dédié à MQTT. Depuis le menu des personnes et utilisateurs, il faut autoriser sa connexion puis définir un mot de passe long et unique. Un minimum raisonnable est de 14 caractères, avec lettres, chiffres et caractères spéciaux. Ce compte ne sert pas à ouvrir l’interface Home Assistant chaque jour. Il sert à authentifier les échanges entre Zigbee2MQTT et Mosquitto.

Cette précaution paraît technique, mais elle évite un défaut fréquent : un broker laissé accessible sans identifiants sur le réseau domestique. Même sans ouverture volontaire vers Internet, une configuration négligée peut permettre à un appareil local compromis d’envoyer des commandes ou de lire des états sensibles. Le principe est simple : limiter les droits et ne pas exposer MQTT sur la box internet.

Choisir un coordinateur adapté au réseau zigbee

Le coordinateur est la pièce centrale du réseau zigbee. Les modèles USB reposent sur plusieurs familles de puces. Les versions actuelles utilisant Ember, Texas Instruments ou Silicon Labs sont courantes, mais leur paramétrage diffère. Les adaptateurs récents demandent fréquemment une déclaration de type ember et un débit de 115200 bauds dans Zigbee2MQTT.

Un dongle USB avec antenne externe offre souvent une meilleure marge radio qu’un petit adaptateur compact. Pour une installation éloignée du serveur, un contrôleur Ethernet ou PoE peut être pertinent. Il place l’antenne au centre du logement sans prolonger l’USB. Le fonctionnement et les critères de choix d’un contrôleur Zigbee compatible Matter méritent alors d’être examinés avant l’achat.

Le piège : ne pas confondre coordinateur et routeur Zigbee. Le premier crée le réseau. Une prise connectée alimentée en permanence peut ensuite étendre sa portée, mais elle ne remplace pas le coordinateur.

Une préparation sérieuse évite les démontages inutiles. Le matériel doit être fixé, le port identifié et le compte MQTT créé avant de lancer les services.

Installer Mosquitto Broker et connecter MQTT à Home Assistant

Le broker Mosquitto est le point de passage des messages MQTT. Dans Home Assistant OS, ouvrir Paramètres, puis Applications, et accéder à la boutique des applications. Une recherche sur « Mosquitto » fait apparaître le module officiel Mosquitto Broker. Il est préférable de choisir cette version maintenue dans l’écosystème Home Assistant plutôt qu’un composant dont la provenance est incertaine.

Après l’installation, deux options méritent d’être activées immédiatement : Lancer au démarrage et Chien de garde. La première relance automatiquement le service après un redémarrage de la machine. La seconde surveille le module et tente un redémarrage s’il cesse de répondre. Cette surveillance ne remplace pas un diagnostic, mais elle évite qu’un service bloqué reste hors ligne jusqu’à la prochaine vérification manuelle.

Avant de démarrer Mosquitto, renseigner l’utilisateur MQTT créé précédemment. Selon la version de l’interface, le module peut accepter une liste d’identifiants dans sa zone de configuration ou utiliser les utilisateurs Home Assistant autorisés. Le but est identique : Zigbee2MQTT doit se connecter au broker avec un compte dédié, et non avec un accès anonyme.

Le port MQTT standard est 1883. Sur une installation supervisée, Zigbee2MQTT communique habituellement avec le broker interne via l’adresse mqtt://core-mosquitto:1883. Dans certains environnements, notamment après une migration ou une installation particulière, mqtt://localhost:1883 peut être nécessaire. Il ne faut pas changer cette valeur au hasard. Les journaux de Zigbee2MQTT indiqueront clairement une erreur de connexion, d’authentification ou de résolution de nom.

Une fois Mosquitto lancé, Home Assistant doit reconnaître l’intégration MQTT. Aller dans Paramètres, puis Appareils et services. Si MQTT est détecté, cliquer sur « Configurer » puis terminer l’assistant. Cette étape active l’intégration côté Home Assistant. Sans elle, le broker peut fonctionner mais les entités publiées par Zigbee2MQTT ne seront pas exploitées correctement dans les tableaux de bord.

Lire les journaux plutôt que recommencer toute l’installation

Les journaux sont le premier outil de dépannage. Un message « connection refused » renvoie souvent à un identifiant, un mot de passe ou une adresse de broker incorrecte. Une erreur liée au port 1883 peut signaler qu’un autre service utilise déjà ce port. Un module qui redémarre en boucle peut avoir une configuration YAML mal indentée ou une valeur placée dans la mauvaise rubrique.

Claire et Malik ont rencontré un cas classique : Mosquitto était installé, mais l’intégration MQTT restait en attente dans Home Assistant. Leur réseau Zigbee n’était pas en cause. Après l’activation de l’intégration dans « Appareils et services », les appareils publiés sont apparus normalement. Cette vérification prend moins de 2 minutes et évite de réinitialiser les équipements radio.

Il est prudent de ne pas exposer le port 1883 vers Internet. L’accès distant à Home Assistant doit passer par une solution sécurisée, avec authentification forte et mises à jour suivies. MQTT est conçu pour le transport de messages. Il n’est pas un portail public à ouvrir par défaut.

À retenir : un broker bien configuré est discret. Il doit démarrer seul, accepter uniquement les comptes prévus et laisser des journaux suffisamment clairs pour diagnostiquer un incident.

Installer Zigbee2MQTT et déclarer le port du coordinateur Zigbee

Zigbee2MQTT n’apparaît pas toujours dans les applications officielles de Home Assistant. Il faut alors ajouter son dépôt maintenu par le projet. Dans Paramètres, puis Applications, ouvrir la boutique, utiliser le menu à trois points et sélectionner les dépôts. Ajouter l’adresse https://github.com/zigbee2mqtt/hassio-zigbee2mqtt, puis actualiser la page si le nouveau catalogue n’est pas visible immédiatement.

Deux éditions peuvent être proposées : la version stable et l’édition Edge. La version Edge sert à tester des évolutions récentes. Elle peut résoudre un souci de compatibilité très précis, mais elle n’est pas le bon choix pour un logement où l’on attend des automatismes réguliers. La version stable est préférable dans la majorité des cas.

Installer Zigbee2MQTT, puis activer trois options : lancement au démarrage, chien de garde et affichage dans la barre latérale. La dernière n’influe pas sur la fiabilité technique. Elle rend simplement l’interface de gestion accessible sans chercher le module dans les menus. Ne pas démarrer tout de suite. Il faut d’abord renseigner le broker et le coordinateur.

Dans la partie MQTT de la configuration, indiquer l’adresse du serveur, le nom d’utilisateur, le mot de passe et un topic de base, par exemple zigbee2mqtt. Ce topic est le préfixe sous lequel les états des appareils seront publiés. Il est préférable de conserver un nom court et explicite. Éviter les espaces, les accents et les noms imprécis tels que « test ».

La seconde donnée essentielle est le chemin du périphérique série. Dans Home Assistant, ouvrir Paramètres, Système, puis Matériel. Le coordinateur doit être branché avant cette opération. La liste affiche souvent un chemin tel que /dev/ttyUSB0 ou /dev/ttyACM0. Ce chemin peut changer si plusieurs périphériques USB sont débranchés, ajoutés ou redémarrés.

La pratique la plus sûre consiste à utiliser, quand il est disponible, un chemin stable dans /dev/serial/by-id/. Il identifie le matériel plutôt que sa position temporaire. C’est un détail important : un port qui passe de ttyUSB0 à ttyUSB1 peut empêcher Zigbee2MQTT de redémarrer après une maintenance pourtant banale.

Adapter la configuration au modèle de clé radio

Le bloc série doit correspondre au matériel. Beaucoup de clés modernes utilisent l’adaptateur ember avec baudrate: 115200. Certains anciens modèles nécessitent un autre adaptateur. Il faut consulter la documentation propre au coordinateur avant de modifier ces lignes. Copier une configuration destinée à une autre puce est une source fréquente d’échec au démarrage.

Un exemple de logique de configuration comprend l’adresse MQTT, les identifiants, le topic et le bloc série avec le port stable. Les mots de passe ne doivent jamais être copiés dans une capture publiée sur un forum ou envoyée sans précaution à un tiers. Une capture des journaux doit masquer les données sensibles.

Le choix du matériel mérite également une vérification de compatibilité. Le dossier sur le dongle Zigbee Sonoff et Matter aide à distinguer les usages Zigbee, Thread et les limites d’un même adaptateur lorsqu’il faut choisir un rôle radio unique.

Après l’enregistrement, démarrer Mosquitto en premier, puis Zigbee2MQTT. Ouvrir le journal de ce dernier. Si le coordinateur est détecté et que la connexion MQTT est validée, l’interface Zigbee2MQTT devient accessible dans la barre latérale de Home Assistant.

Le bon ordre réduit les erreurs : broker opérationnel, intégration MQTT active, port radio stable, puis démarrage de Zigbee2MQTT.

Appairer les appareils et construire une automatisation domotique fiable

Lorsque Zigbee2MQTT est fonctionnel, l’appairage devient la phase visible de l’installation. Dans son interface, activer l’autorisation d’association pendant une durée limitée, par exemple 2 à 5 minutes. Mettre ensuite le capteur, la prise ou l’ampoule en mode appairage selon la procédure du fabricant. En quelques secondes, l’équipement doit apparaître avec un nom et plusieurs états exploitables.

Il est recommandé de renommer chaque appareil immédiatement. « Capteur porte entrée », « prise salon » ou « température chambre Lina » sont plus utiles que les identifiants techniques générés automatiquement. Une maison équipée de 30 objets devient difficile à maintenir si les noms sont incompréhensibles. Le nommage facilite aussi les recherches lors d’une panne ou d’une modification de scénario.

Le réseau zigbee repose sur un maillage. Les appareils alimentés en permanence, comme les prises et ampoules compatibles routeur, relaient les messages. Les capteurs sur piles sont généralement des terminaux : ils transmettent, mais ne renforcent pas la couverture. Dans une maison à étage, placer deux ou trois routeurs répartis entre le coordinateur et les zones éloignées est souvent plus efficace qu’acheter une antenne plus puissante.

Pour intégrer un appareil éloigné, Zigbee2MQTT permet dans certains cas de choisir un routeur précis pendant l’association. Cette fonction est utile dans un garage, une dépendance attenante ou une pièce située derrière plusieurs murs porteurs. Elle ne contourne pas les limites physiques. Un mur en béton armé, une baie métallique ou un tableau électrique peut réduire fortement la portée.

Construire des scénarios utiles sans multiplier les alertes

Une automatisation doit répondre à une situation réelle. Prenons un détecteur d’ouverture posé sur une fenêtre de cuisine. Une règle simple peut couper le chauffage de cette pièce après 10 minutes d’ouverture, puis le rétablir à la fermeture. Cette logique limite le gaspillage sans déclencher de notifications inutiles.

Autre exemple : une prise routeur Zigbee dans le couloir alimente une veilleuse. Entre 22 h et 6 h, le mouvement détecté dans le passage lance l’éclairage à 20 % durant 90 secondes. La luminosité modérée évite l’éblouissement et la consommation reste faible. Si le capteur ne répond plus, l’automatisation doit échouer sans bloquer d’autres fonctions de la maison.

Pour les équipements liés à la sécurité domestique, la prudence est nécessaire. Un capteur d’ouverture peut compléter un système d’alarme en envoyant une information vers Home Assistant. Il ne doit pas être présenté comme une alarme certifiée. Les détecteurs destinés à une protection contre l’intrusion doivent respecter les exigences du système auquel ils sont rattachés, notamment lorsqu’un assureur ou un contrat professionnel impose une certification spécifique.

La domotique peut aussi simplifier le quotidien des proches âgés : une lumière de circulation, une alerte de température anormale ou un rappel discret. Elle ne se substitue pas à un dispositif de téléassistance adapté lorsque l’état de santé l’exige. L’intérêt est d’ajouter des repères pratiques, pas de confier à une automatisation une responsabilité qu’elle ne peut garantir.

À retenir : un bon scénario est compréhensible en une phrase, utile chaque semaine et désactivable facilement si les habitudes du foyer changent.

Sauvegarder MQTT et Zigbee2MQTT pour éviter de reconstruire le réseau

La sauvegarde est souvent oubliée jusqu’au premier incident. Or, le réseau zigbee possède une clé de sécurité et une base d’appareils qui ne se recréent pas automatiquement après un changement de serveur. Sans copie fiable, remplacer un disque, restaurer une machine ou migrer vers un mini-PC peut imposer de réappairer chaque module. Avec 25 appareils, cette opération peut représenter 1 à 3 heures, parfois davantage si certains capteurs sont difficiles d’accès.

Home Assistant propose des sauvegardes complètes et partielles. Une sauvegarde complète inclut la configuration, les modules, les données et les réglages nécessaires à une restauration cohérente. Elle doit être réalisée avant toute mise à jour importante de Home Assistant, de Mosquitto ou de Zigbee2MQTT. Une fréquence hebdomadaire convient à un système stable. Après l’ajout de plusieurs appareils ou la création d’automatismes importants, une sauvegarde manuelle supplémentaire est justifiée.

Conserver la sauvegarde sur la même carte SD ou le même SSD ne suffit pas. En cas de panne matérielle, le fichier disparaît avec le système. Une copie vers un NAS, un espace chiffré ou un support USB débranché après usage offre une meilleure protection. La règle pratique est de disposer d’au moins deux copies, dont une hors de la machine Home Assistant.

Les mises à jour doivent être préparées. Lire les notes de version de Zigbee2MQTT avant une évolution majeure. Certaines modifications touchent les adaptateurs radio, les conventions de configuration ou la compatibilité d’appareils. Attendre quelques jours avant d’installer une version importante est raisonnable pour un système domestique stable. Il n’y a aucun bénéfice à appliquer une mise à jour le jour même si l’installation fonctionne correctement.

Un contrôle mensuel prend moins de 15 minutes : consulter les journaux, vérifier les appareils indisponibles, tester un capteur sur piles, examiner l’état des sauvegardes et s’assurer que la rallonge USB est bien fixée. Ce contrôle préventif est plus utile qu’une accumulation d’automatisations complexes jamais relues.

La disponibilité locale reste un avantage, mais elle implique une responsabilité simple : maintenir le serveur. Les utilisateurs qui préfèrent une approche progressive peuvent commencer par les bases grâce au guide d’initiation à Home Assistant, puis ajouter MQTT et Zigbee2MQTT lorsque les sauvegardes et la structure de la domotique sont comprises.

Le bon réflexe : créer maintenant une sauvegarde complète de Home Assistant, la copier hors de la machine, puis noter le chemin stable du coordinateur Zigbee dans un document conservé avec les identifiants de récupération.

Faut-il une connexion internet pour utiliser Zigbee2MQTT ?

Non. Les échanges entre le coordinateur, Zigbee2MQTT, MQTT et Home Assistant peuvent rester locaux. Internet est surtout utile pour les mises à jour, l’accès distant choisi par le foyer et certaines intégrations externes.

Pourquoi Zigbee2MQTT ne démarre-t-il pas après une mise à jour ?

Les causes les plus courantes sont un port USB modifié, un adaptateur mal déclaré, des identifiants MQTT incorrects ou une évolution de configuration. Le journal du module donne généralement l’indication utile avant toute réinstallation.

Peut-on utiliser plusieurs coordinateurs Zigbee avec la même installation ?

Oui, mais chaque coordinateur gère son propre réseau Zigbee et demande une instance adaptée de Zigbee2MQTT. Pour un logement classique, un seul coordinateur correctement placé et quelques routeurs suffisent généralement.

Le chien de garde Home Assistant remplace-t-il une sauvegarde ?

Non. Le chien de garde tente de relancer un service bloqué. Il ne restaure ni les appareils, ni la clé réseau, ni les automatisations après une panne de stockage ou une erreur de configuration.