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).
  • 
    db-tronic Raspberry Pi 5 8 Go Starter Kit | Édition 128 Go | Alimentation 27 W | Boîtier avec Ventilateur | Micro HDMI 4K | Dissipateur alu | idéal pour Home Assistant et Le Smart Home

    ✔ Raspberry Pi 5 avec 8 Go de RAM : ordinateur monocarte puissant pour des projets et applications polyvalents. ✔ Alimentation officielle 27W : Alimentation stable et fiable pour votre Raspberry Pi 5. ✔ Boîtier officiel avec ventilateur : Protège votre Raspberry Pi et assure un refroidissement optimal lors d'une utilisation intensive. ✔ Carte mémoire de 128 Go : offre un stockage généreux pour votre système d'exploitation, vos applications et vos fichiers. ✔ Lecteur de cartes USB pour cartes mémoire : configuration simple et rapide de votre système d'exploitation sur votre PC ou ordinateur portable. ✔ Dissipateur thermique en aluminium : refroidissement supplémentaire pour des performances et une durabilité fiables. ✔ Câble Micro HDMI 4K 1 mètre : parfait pour une sortie vidéo ultra-nette sur des moniteurs ou téléviseurs 4K compatibles. ✔ Emballage db-tronic de haute qualité : Emballage robuste et élégant, idéal pour une expédition en toute sécurité et comme cadeau.
    254,99 €
  • 
    db-tronic Raspberry Pi 5 4 Go Starter Kit | Édition 64 Go | Alimentation 27 W | Boîtier avec Ventilateur | Micro HDMI 4K | Dissipateur alu | idéal pour Home Assistant et Le Smart Home

    ✔ Raspberry Pi 5 avec 4 Go de RAM : ordinateur monocarte puissant pour des projets et applications polyvalents. ✔ Alimentation officielle 27W : Alimentation stable et fiable pour votre Raspberry Pi 5. ✔ Boîtier officiel avec ventilateur : Protège votre Raspberry Pi et assure un refroidissement optimal lors d'une utilisation intensive. ✔ Carte mémoire de 64 Go : offre un stockage généreux pour votre système d'exploitation, vos applications et vos fichiers. ✔ Lecteur de cartes USB pour cartes mémoire : configuration simple et rapide de votre système d'exploitation sur votre PC ou ordinateur portable. ✔ Dissipateur thermique en aluminium : refroidissement supplémentaire pour des performances et une durabilité fiables. ✔ Câble Micro HDMI 4K 1 mètre : parfait pour une sortie vidéo ultra-nette sur des moniteurs ou téléviseurs 4K compatibles. ✔ Emballage db-tronic de haute qualité : Emballage robuste et élégant, idéal pour une expédition en toute sécurité et comme cadeau.
    199,99 €
  • 
    db-tronic Raspberry Pi 5 8 Go NVMe Kit | Édition 64 Go | Alimentation 27 W | Boîtier métal | Refroidissement Actif | SSD M.2 NVMe PCIe | Micro HDMI 4K | idéal pour Home Assistant et Le Smart Home

    ✔ Raspberry Pi 5 avec 8 Go de RAM : conçu pour des performances maximales dans des applications telles que les solutions serveur, la domotique et le multimédia. ✔ Carte PCIe SSD M.2 NVMe : connectez et utilisez facilement le stockage NVMe pour un transfert de données rapide. ✔ Boîtier en métal : le boîtier robuste combine protection et refroidissement. Le refroidisseur actif et le capuchon NVMe s'intègrent parfaitement dans le boîtier. ✔ Refroidisseur actif officiel : ventilateur puissant spécialement conçu pour Raspberry Pi 5 pour dissiper efficacement la chaleur. ✔ Alimentation USB-C officielle 27 W : alimentation stable et sûre pour Raspberry Pi et périphériques. ✔ Carte mémoire 64 Go : Solution flexible pour installer le système d'exploitation de votre choix. ✔ Câble Micro HDMI 4K : prêt pour une sortie vidéo 4K nette vers des moniteurs ou téléviseurs compatibles. ✔ Matériel de fixation et câble ruban : Tout est inclus pour une installation fluide et sécurisée.
    259,99 €
• 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 Green Smart Home Hub, 4 Go de RAM, 32 Go, Gigabit Ethernet

    Plug and Play : système d'exploitation Home Assistant préinstallé, bloc d'alimentation 12 V inclus dans la livraison, il suffit de brancher l'alimentation et le réseau Matériel puissant : Quad-Core Cortex-A55 jusqu'à 1,8 GHz, 4 Go de RAM, 32 Go eMMC, Gigabit Ethernet, refroidissement passif Extensible : prend en charge Zigbee 3.0, Thread, Matter via SkyConnect/ZWA-2, 2 ports USB 2.0, HDMI pour le diagnostic PRIVÉ : stockage de données local sans contrainte dans le cloud, mises à jour mensuelles open source Remarque importante : le Home Assistant Green ne dispose pas de modules radio Zigbee/Thread intégrés. Pour contrôler les appareils Zigbee/Thread/Matter, un adaptateur USB compatible tel que Home Assistant SkyConnect, Sonoff ZBDongle-E ou Aeotec Z-Stick, vendu séparément Design compact : le boîtier en aluminium de 111 x 111 x 33,6 mm assure un refroidissement passif sans ventilateur et permet un fonctionnement continu silencieux à des températures de fonctionnement de 0 à 40 °C Contenu de la livraison : Home Assistant Green Hub, bloc d'alimentation 12 V CC avec prise européenne, câble Ethernet et guide rapide pour une entrée rapide dans votre système Smart Home
    345,00 €
  • 
    SONOFF ZigBee 3.0 USB Dongle Plus, EFR32MG21 Coordinator, Universelle USB ZigBee Hub, Passerelle ZigBee pour Home Assistant

    Firmware du coordinateur Zigbee basé sur EZNet 6.10.3 prêt à l'emploi Prend en charge les plateformes Smart Home Assistant, openHAB, Zigbee2MQTT et ainsi de suite Basé sur EFR32MG21 + CH9102F/CP2102N, gain de sortie de +20dBm Le boîtier en aluminium réduit efficacement les interférences du signal par les périphériques Câble d'extension USB de 1,5 m en option pour une meilleure portée du signal SONOFF Zigbee 3.0 USB Dongle Plus kann mit den folgenden Geraten funktionieren : Routeur : ZBMINI Smart schalter, S26R2ZBTPF Zigbee Smart steckdose Endgerat : ZBMINI-L Smart Switch, SNZB-01 Switch, SNZB-02 Temperatur und Feuchtigkeitssensor. Bewegungssensor SNZB-03, Tur-Fenstersensor SNZB-04
    29,99 €

    19,90 €

    -34%
  • 
    Assistant domotique Connecter ZBT-2 | Connectez des appareils Zigbee, filaires ou Matter aux assistants domestiques | Matériel officiel

    Informations supplémentaires : Un système d'assistance domestique est nécessaire pour connecter et contrôler les appareils avec Connect ZBT-2** ANTENNE OPTIMISÉE - Fournit la meilleure connexion possible avec des appareils Zigbee ou filaires. Plus réactif : avec une amélioration de la vitesse de 4 × par rapport à l'adaptateur de première génération, il améliore constamment la réponse de l'appareil. Rendement pur – la puce Zigbee et Thread mise à jour (MG24) offre des performances de premier ordre tout en assurant une stabilité inébranlable. PLUG ET PLAY – lancez un nouveau réseau Zigbee ou Thread en quelques minutes ou migrez votre réseau existant de manière transparente avec l’assistant intégré de Home Assistant. Conçu pour être aminci – déverrouillé, source ouverte et facile à ouvrir (aucun clip ni colle), avec des coussinets et des goupilles accessibles. Clip Smart Home Hub Switch - Connectez directement vos appareils Zigbee, Matter ou Thread existants à l'assistant domestique. Compatibilité étendue – prend en charge ZHA, Zigbee2MQT et OpenThread Border Router. Fiable au cœur – conçu par l’équipe qui fait progresser l’Assistant domestique. Toute la puissance de l'assistant domestique – offre une compatibilité Zigbee et filaire de premier ordre, avec des mises à jour Over-the-Air (OTA) pour les grandes marques.
    59,99 €

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.

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.

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.