Installer MQTT et Zigbee2MQTT sur Home Assistant : guide Complet de Supervision Domotique

La domotique, ou l’art de rendre sa maison intelligente, repose sur une communication fluide et fiable entre une multitude d’appareils. Au cœur de cet écosystème, des protocoles et des logiciels open source émergent comme des standards de fait, offrant une alternative puissante et flexible aux solutions propriétaires souvent fermées et coûteuses. Parmi eux, l’association de Home Assistant, du protocole MQTT et du pont Zigbee2MQTT constitue une architecture de choix pour quiconque souhaite bâtir un système domotique centralisé, local et entièrement personnalisable. Ce guide se propose de détailler, étape par étape, le processus d’installation et de configuration de cette triade technologique, ouvrant la voie à une supervision complète et efficace de votre foyer connecté.

Introduction à la supervision domotique avec MQTT et Zigbee2MQTT

Qu’est-ce que le protocole MQTT ?

Le Message Queuing Telemetry Transport, plus connu sous l’acronyme MQTT, est un protocole de messagerie conçu pour être extrêmement léger. Il fonctionne sur un modèle de publication et d’abonnement, ce qui le rend particulièrement adapté à l’internet des objets (IoT) et aux environnements où la bande passante et les ressources des appareils sont limitées. Au sein d’une installation domotique, MQTT agit comme un véritable système nerveux central. Un composant central, appelé le « broker » (ou courtier), reçoit les messages publiés par les appareils (les « publishers ») et les distribue aux autres appareils qui se sont abonnés (« subscribers ») à ces messages spécifiques, appelés « topics ». Cette architecture découplée assure une communication efficace et instantanée entre, par exemple, un capteur de température et un thermostat, sans qu’ils aient besoin de se connaître directement.

Le rôle de Zigbee2MQTT dans l’écosystème

Zigbee est l’un des protocoles de communication sans fil les plus répandus dans le monde de la domotique, utilisé par d’innombrables capteurs, ampoules et interrupteurs. Cependant, chaque fabricant a souvent tendance à proposer sa propre passerelle (ou « hub ») pour faire communiquer ses appareils avec votre réseau. Zigbee2MQTT est un projet open source révolutionnaire qui vient briser ces silos. Il s’agit d’un logiciel qui, associé à un simple adaptateur USB Zigbee, agit comme un pont universel. Il écoute les communications des appareils Zigbee de n’importe quelle marque, les traduit en messages MQTT, et les publie sur le broker. Inversement, il écoute les messages MQTT destinés aux appareils et les traduit en commandes Zigbee. L’avantage est immense : vous n’avez plus besoin d’une passerelle par marque, un seul coordinateur suffit pour gérer l’ensemble de votre parc Zigbee.

Pourquoi associer ces technologies à Home Assistant ?

Home Assistant est une plateforme de domotique open source qui s’est imposée comme le cerveau de la maison connectée pour de nombreux passionnés. Son principal atout est sa capacité à intégrer des milliers d’appareils et de services de marques différentes au sein d’une interface unique. En associant MQTT et Zigbee2MQTT à Home Assistant, on crée une solution domotique puissante, locale et respectueuse de la vie privée. Home Assistant s’abonne aux messages MQTT publiés par Zigbee2MQTT pour connaître l’état de tous les capteurs et peut publier des messages pour commander les actionneurs. Cette synergie permet de créer des automatisations complexes, des scénarios personnalisés et des tableaux de bord de supervision détaillés, transformant une simple collection d’objets connectés en une véritable maison intelligente et réactive.

Maintenant que les concepts fondamentaux de cette architecture sont posés, il convient d’examiner les éléments concrets, matériels et logiciels, nécessaires pour mettre en œuvre cette solution de supervision domotique.

Prérequis pour l’installation de MQTT et Zigbee2MQTT sur Home Assistant

Le matériel indispensable

Avant de se lancer dans la configuration logicielle, il est crucial de s’assurer de disposer du bon équipement. Le socle de l’installation est la machine qui héberge votre instance de Home Assistant. Plusieurs options s’offrent à vous :

• Un mini-ordinateur comme le Raspberry Pi (modèle 4 ou 5 recommandé pour des performances optimales).
  • 
    Raspberry Pi Zero 2 W
    23,80 €

    22,79 €

    -4%
  • 
    Raspberry Pi 4 Modèle B (4 Go)
    72,95 €
  • 
    Raspberry Pi 5 8 GB Quad-Core ARMA76 (64 Bits - 2,4 GHz)
    119,77 €
• Un NUC (Next Unit of Computing) ou tout autre ordinateur compact à faible consommation.
• Un serveur domestique ou une machine virtuelle si vous disposez déjà d’une telle infrastructure.
• Une solution clé en main comme la box Home Assistant Green, conçue spécifiquement pour cet usage.
  • 
    Home Assistant Vert
    152,47 €
  • 
    Home Assistant Connect ZBT-2 | Connectez des appareils Zigbee, Thread ou Matter à l'assistant domestique | Matériel officiel
    77,00 €
  • 
    SONOFF ZBMINIL2 ZigBee Interrupteur Intelligent (Aucun Fil Neutre Requis), 6A/1440W, 2 Way Smart Switch, Compatible avec Alexa, Google Home, Home Assistant, SONOFF ZigBee Hub Requis (4 Pack)
    59,99 €

    56,00 €

    -7%

Le second élément matériel, tout aussi essentiel, est le coordinateur Zigbee. Il s’agit d’un dongle USB qui se branche sur votre machine Home Assistant et qui gère le réseau sans fil Zigbee. Le choix de ce dongle est important pour la stabilité et la portée de votre réseau. Des modèles comme ceux de la marque SMLIGHT, notamment le SLZB-06 ou le Sonoff Zigbee 3.0 USB Dongle Plus, sont largement plébiscités par la communauté pour leur fiabilité et leur compatibilité.

Les logiciels et connaissances de base

Sur le plan logiciel, le prérequis principal est d’avoir une instance de Home Assistant OS fonctionnelle et à jour. Ce guide se concentre sur l’utilisation des « Modules complémentaires » (Add-ons), qui est la méthode la plus simple et la plus intégrée pour installer des services comme MQTT et Zigbee2MQTT. Une connaissance basique de l’interface de Home Assistant est nécessaire, notamment savoir naviguer dans les menus « Paramètres » et accéder à la boutique des modules complémentaires. Aucune compétence en programmation n’est requise, mais une approche méthodique et une lecture attentive des journaux (logs) en cas de problème seront vos meilleurs atouts.

Tableau récapitulatif des prérequis

Pour une vision claire et synthétique, voici un tableau résumant les éléments nécessaires.

Catégorie	Élément	Description
Matériel	Serveur Home Assistant	Raspberry Pi, NUC, serveur, ou box dédiée (ex: Home Assistant Green).
Matériel	Coordinateur Zigbee	Dongle USB compatible (ex: SMLIGHT, Sonoff).
Logiciel	Home Assistant OS	Installation à jour et fonctionnelle.
Connaissances	Interface Home Assistant	Savoir naviguer dans les paramètres et la boutique des modules.

Une fois que tous ces prérequis sont validés, la première étape concrète de notre installation peut commencer : la mise en place du courtier MQTT, qui servira de tour de contrôle pour tous les messages de notre domotique.

Guide d’installation de Mosquitto MQTT sur Home Assistant

Accéder à la boutique des modules complémentaires

L’installation du broker MQTT se fait très simplement grâce au système de modules complémentaires de Home Assistant. Pour commencer, connectez-vous à votre interface Home Assistant. Dans le menu de gauche, cliquez sur « Paramètres », puis sur « Modules complémentaires ». Vous arriverez sur la page qui liste vos modules déjà installés. En bas à droite de l’écran, cliquez sur le bouton bleu « Boutique des modules complémentaires » pour accéder au catalogue de tous les services additionnels disponibles.

Installation de l’add-on Mosquitto Broker

Dans la boutique, utilisez la barre de recherche en haut à droite et tapez « Mosquitto ». Le module « Mosquitto broker » devrait apparaître dans les résultats. Il s’agit du module officiel et pleinement intégré, ce qui en fait le choix recommandé. Cliquez dessus pour ouvrir sa page de description. Vous y trouverez des informations sur le module et son fonctionnement. Cliquez sur le bouton « Installer » et patientez quelques instants pendant que Home Assistant télécharge et installe le service. Une fois l’installation terminée, activez les options « Démarrer au démarrage » et « Chien de garde » (Watchdog) pour garantir que le broker se lance automatiquement et redémarre en cas de problème.

Configuration initiale et création d’un utilisateur

Avant de démarrer le broker pour la première fois, une étape de configuration est indispensable pour la sécurité. Restez sur la page du module Mosquitto et allez dans l’onglet « Configuration ». La configuration par défaut est généralement suffisante, mais il nous faut créer un utilisateur dédié pour que les services (comme Zigbee2MQTT) puissent se connecter au broker de manière sécurisée. Pour cela, retournez dans le menu « Paramètres », puis sélectionnez « Personnes ». Cliquez sur l’onglet « Utilisateurs » en haut de la page, puis sur le bouton « Ajouter un utilisateur » en bas à droite. Créez un utilisateur avec un nom simple (par exemple, « mqtt_user ») et un mot de passe fort et unique. Cet utilisateur n’a pas besoin d’être administrateur. Une fois l’utilisateur créé, retournez au module Mosquitto et démarrez-le. Vérifiez l’onglet « Journal » pour vous assurer que tout se lance correctement. Une ligne indiquant « Successfully send service information to the Supervisor » confirme que le broker est opérationnel.

Le courtier MQTT est maintenant en place, prêt à recevoir et à distribuer des messages. L’étape suivante consiste à installer et configurer le pont qui fera le lien entre nos appareils physiques Zigbee et ce système de messagerie central.

Méthode d’installation et configuration de Zigbee2MQTT

Ajout du dépôt officiel de Zigbee2MQTT

Contrairement à Mosquitto, le module Zigbee2MQTT ne fait pas partie des dépôts officiels de Home Assistant. Il est donc nécessaire d’ajouter manuellement le dépôt qui le contient. Pour ce faire, retournez dans la « Boutique des modules complémentaires ». Cliquez sur les trois points verticaux en haut à droite de l’écran et sélectionnez « Dépôts ». Dans le champ qui apparaît, collez l’URL du dépôt officiel de Zigbee2MQTT : https://github.com/zigbee2mqtt/hassio-zigbee2mqtt. Cliquez sur « Ajouter ». Le système va alors charger la liste des modules contenus dans ce nouveau dépôt.

Installation du module complémentaire

Après avoir ajouté le dépôt, vous pouvez utiliser la barre de recherche de la boutique pour trouver « Zigbee2MQTT ». Plusieurs versions peuvent apparaître (stable, de développement). Il est fortement recommandé de choisir la version stable pour garantir une fiabilité maximale. Cliquez sur le module Zigbee2MQTT (celui sans la mention « edge ») et procédez à son installation de la même manière que pour le broker Mosquitto. Là encore, pensez à activer les options « Démarrer au démarrage », « Chien de garde » et, très important pour ce module, « Afficher dans la barre latérale » afin d’accéder facilement à son interface web.

Configuration critique : port série et identifiants MQTT

C’est l’étape la plus technique mais aussi la plus cruciale. Avant de démarrer Zigbee2MQTT, rendez-vous dans son onglet « Configuration ». Vous y trouverez plusieurs sections à remplir. Les deux plus importantes sont « serial » et « mqtt ».

• Section « serial » : Vous devez indiquer ici le chemin d’accès à votre dongle USB Zigbee. Pour le trouver, allez dans « Paramètres », « Système », « Matériel », puis cliquez sur les trois points et « Tout le matériel ». Cherchez votre dongle (il apparaît souvent avec un nom comme « ttyUSB0 » ou « ttyACM0 »). Vous devez copier le chemin complet (par exemple /dev/ttyUSB0) et le coller dans le champ port de la configuration de Zigbee2MQTT.
• Section « mqtt » : Ici, vous devez renseigner les informations de connexion à votre broker Mosquitto. Entrez le nom d’utilisateur (« mqtt_user ») et le mot de passe que vous avez créés précédemment. L’adresse du serveur peut généralement être laissée par défaut (core-mosquitto) car les modules s’exécutent sur le même système.

Sauvegardez la configuration une fois ces informations renseignées.

Démarrage et vérification des journaux

Il est temps de démarrer le module Zigbee2MQTT. Une fois lancé, patientez une minute puis allez dans l’onglet « Journal ». C’est ici que vous pourrez vérifier si tout fonctionne. Cherchez des lignes confirmant la connexion au broker MQTT (« Connected to MQTT server ») et le démarrage réussi de l’adaptateur Zigbee (« Successfully started Zigbee2MQTT »). Si vous rencontrez des erreurs, elles sont le plus souvent liées à un mauvais chemin de port série ou à des identifiants MQTT incorrects. Prenez le temps de bien vérifier ces paramètres.

Avec le broker MQTT qui tourne et le pont Zigbee2MQTT qui communique avec succès, l’infrastructure de base est complète. Il faut maintenant lier officiellement ce système à Home Assistant pour que celui-ci puisse commencer à découvrir et utiliser les appareils.

Intégration et configuration de MQTT dans Home Assistant

Découverte automatique des appareils

L’un des grands avantages de cette configuration est la fonction de découverte automatique. Si le broker Mosquitto et Zigbee2MQTT sont correctement configurés, Home Assistant devrait détecter de lui-même la présence d’un service MQTT sur le réseau. Rendez-vous dans « Paramètres », puis « Appareils et services ». Une nouvelle carte intitulée « MQTT » devrait apparaître dans la section des intégrations découvertes, vous invitant à la configurer. Cliquez simplement sur « Configurer » et Home Assistant se chargera du reste, en utilisant les informations du broker qu’il a détectées.

Configuration manuelle de l’intégration MQTT

Dans le cas où la découverte automatique ne fonctionnerait pas, l’ajout manuel est tout aussi simple. Sur la page « Appareils et services », cliquez sur le bouton « + Ajouter l’intégration » en bas à droite. Recherchez « MQTT » dans la liste et sélectionnez-le. Une fenêtre de dialogue vous demandera les informations du broker. L’adresse du broker sera localhost (ou l’adresse IP de votre machine Home Assistant si vous l’avez installé différemment), le port par défaut est 1883. Saisissez ensuite le nom d’utilisateur (« mqtt_user ») et le mot de passe que vous avez créés. Validez, et l’intégration sera ajoutée à votre système.

Vérification du bon fonctionnement

Une fois l’intégration MQTT configurée, vous pouvez vérifier qu’elle fonctionne correctement. Sur la carte de l’intégration MQTT, vous devriez voir un message indiquant qu’elle écoute les messages. Pour un test plus approfondi, vous pouvez utiliser les outils de développement. Allez dans « Outils de développement », onglet « MQTT ». Dans la section « Publier un paquet », vous pouvez publier un message de test sur un topic. Dans la section « Écouter un topic », vous pouvez vous abonner à ce même topic pour voir si le message est bien reçu. Cependant, la meilleure vérification viendra lorsque vous ajouterez votre premier appareil Zigbee, qui devrait apparaître automatiquement comme un nouvel appareil dans Home Assistant.

L’ensemble de l’infrastructure logicielle est désormais en place et interconnecté. Home Assistant est à l’écoute, prêt à intégrer les capteurs et actionneurs qui constituent le cœur de la maison connectée. Il est temps de peupler notre réseau.

Ajout et gestion des appareils Zigbee avec Zigbee2MQTT

Activer le mode appairage dans Zigbee2MQTT

Pour ajouter un nouvel appareil Zigbee à votre réseau, vous devez d’abord mettre le coordinateur en mode « appairage ». C’est lui qui autorisera de nouveaux appareils à rejoindre le réseau. Pour ce faire, accédez à l’interface web de Zigbee2MQTT. Si vous avez activé l’option « Afficher dans la barre latérale », un lien « Zigbee2MQTT » est désormais présent dans le menu de gauche de Home Assistant. Cliquez dessus pour ouvrir l’interface. En haut à droite de cette interface, vous trouverez un bouton « Permit join (All) ». Cliquez sur ce bouton. Il deviendra vert et un compte à rebours s’affichera, indiquant que le réseau est ouvert aux nouveaux appareils pour une durée limitée.

Procédure d’appairage d’un nouvel appareil

Pendant que le mode appairage est actif, prenez votre nouvel appareil Zigbee (un capteur d’ouverture, une ampoule connectée, une prise intelligente, etc.) et suivez la procédure du fabricant pour le mettre en mode appairage.

Généralement, cela implique d’appuyer sur un bouton pendant plusieurs secondes ou d’allumer et éteindre l’appareil plusieurs fois. L’appareil va alors chercher un réseau à rejoindre. Après quelques instants, il devrait apparaître dans la liste des appareils de l’interface Zigbee2MQTT. Il sera initialement identifié par son nom technique, mais vous pourrez le renommer avec un nom plus explicite (par exemple, « Capteur porte d’entrée »). Simultanément, grâce à l’intégration MQTT, l’appareil et ses entités (batterie, état, température…) apparaîtront automatiquement dans Home Assistant, prêts à être utilisés dans vos tableaux de bord et vos automatisations.

Gestion des appareils et mises à jour

L’interface de Zigbee2MQTT offre bien plus que le simple ajout d’appareils. C’est un véritable centre de contrôle pour votre réseau Zigbee. Pour chaque appareil, vous pouvez :

• Renommer l’appareil pour une identification facile.
• Consulter la qualité du signal (LQI), une information cruciale pour diagnostiquer des problèmes de connexion.
• Accéder aux commandes spécifiques de l’appareil pour des tests.
• Visualiser une carte du réseau montrant comment les appareils communiquent entre eux et avec le coordinateur.
• Effectuer des mises à jour de firmware (OTA – Over-The-Air) pour les appareils compatibles, directement depuis l’interface.

Cette gestion centralisée est l’un des atouts majeurs de Zigbee2MQTT, vous donnant un contrôle total et une vision claire de la santé de votre réseau domotique sans fil.

La mise en place d’un broker Mosquitto, couplée au pont Zigbee2MQTT et intégrée dans Home Assistant, constitue une base extraordinairement solide et évolutive pour la domotique. Ce guide a couvert les étapes essentielles, de la sélection du matériel à l’ajout des appareils. Le résultat est un système de supervision local, indépendant des fabricants et des services cloud, qui place l’utilisateur au centre du contrôle de sa maison connectée. La puissance de cette architecture réside dans sa flexibilité, permettant des automatisations fines et une gestion unifiée d’un parc d’appareils hétérogènes, pour une maison véritablement intelligente.