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.
    244,99 €
  • 
    Raspberry Pi 3 modèle B+

    Raspberry Pi 3B+ 1 Go
    52,89 €
  • 
    db-tronic Raspberry Pi 5 2 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 2 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.
    128,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 Vert

    💡 LE MOYEN LE PLUS FACILE DE COMMENCER AVEC HOME ASSISTANT - Avec Home Assistant déjà installé, il suffit de brancher l'alimentation électrique et le câble Ethernet inclus pour commencer. ✅ OFFICIEL - Ce matériel officiel Home Assistant est conçu et pris en charge par Nabu Casa, l’équipe qui pilote le développement de Home Assistant. Conçu pour la maison : le design petit, sans ventilateur et silencieux contient un processeur quad-core, 32 Go de stockage et 4 Go de RAM. 📱 UN HUB POUR CONTRÔLER TOUTE LA MAISON - Réduisez l'encombrement des hubs et des applications et contrôlez toute votre maison à partir de Home Assistant Green. 🤖 AUTOMATISEZ TOUT - Faites fonctionner tous les appareils de votre maison en harmonie - faites diminuer l'éclairage lorsque vous commencez à regarder un film, ou éteignez votre chauffage lorsque vous êtes absent de chez vous. 🔒 VOTRE MAISON, VOS DONNÉES - Les données de votre maison seront conservées à la maison sur votre Green. Vous pouvez facilement afficher, partager et exporter ces données où vous le souhaitez. 🌿 Économe en énergie : en utilisant seulement quelques watts de puissance, c'est la façon écologique de faire fonctionner Home Assistant. 🔗 EXPANSION DE LA CONNECTIVITÉ USB - Si vous avez besoin de plus de connectivité, étendez votre Home Assistant Green avec des périphériques USB Z-Wave, Zigbee et Thread.
    196,00 €
  • 
    Home Assistant Connect ZBT-2 | Connectez des appareils Zigbee, Thread ou Matter à l'assistant domestique | Matériel officiel

    **Remarque : un système Home Assistant est nécessaire pour connecter et contrôler les appareils avec Connect ZBT-2** Antenne optimisée : fournit la meilleure connexion possible aux appareils Zigbee ou Thread. Plus réactif – avec une amélioration de la vitesse de 4 fois par rapport à l'adaptateur de première génération, il améliore constamment la réactivité de l'appareil. Performance pure : la puce Zigbee et Thread (MG24) mise à jour offre des performances supérieures tout en offrant une stabilité solide comme le roc. Prêt à l'emploi : démarrez un nouveau réseau Zigbee ou Thread en quelques minutes, ou migrez de manière transparente votre réseau existant avec l'assistant intégré de Home Assistant. Construit pour être bricolé : déverrouillé, open source, et facile à ouvrir (pas de clips ou de colle), avec tampons et broches accessibles. Coupez l'encombrement du hub Smart Home : connectez directement vos appareils Zigbee, Matter ou Thread existants à Home Assistant. Large compatibilité : prend en charge le routeur ZHA, Zigbee2MQTT et OpenThread. Fiable au cœur : construit par l'équipe qui fait avancer le développement de Home Assistant. Toute la puissance de l'assistant domestique : offre la plus haute compatibilité Zigbee et Thread, avec des mises à jour en direct (OTA) pour les grandes marques.
    65,49 €

    62,74 €

    -4%
  • 
    Aqara WiFi Détecteur de Présence FP2, Radar mmWave, Filaire, Positionnement de Zone, Détection Multi-Personnes et Chute, Compatible avec HomeKit, Alexa, Google Home et Home Assistant

    Positionnement par zone : Le FP2 (Wi-Fi 2,4 GHz REQUIS) offre des avantages significatifs par rapport aux capteurs de mouvement à infrarouge PIR en utilisant un seul capteur radar pour surveiller des pièces allant jusqu'à 40 m². Vous pouvez le diviser en 30 zones maximum et configurer des automatisations individuelles pour chaque zone. C'est comme si vous aviez plusieurs capteurs en même temps dans un même FP2. * Veuillez noter que FP2 est un détecteur filaire qui doit être constamment alimenté Détection de Plusieurs Personnes et de Chutes : Le FP2 peut détecter simultanément jusqu'à 5 personnes et déclencher différents scénarios et automatisations. Vous pouvez également installer le FP2 au plafond et choisir le mode Détection des chutes, qui détectera et vous avertira via l'application en cas de chute. (Remarque : Le FP2 n'est pas un dispositif médical et ne peut être utilisé qu'à des fins de notification). Compatible avec Plusieurs Ecosystèmes : Le Détecteur de Présence FP2 est compatible sous forme de capteurs multiples avec HomeKit, Alexa, Google Home et Home Assistant. (Remarque : L'appareil peut être ajouté directement à Home Assistant par intégration avec le contrôleur HomeKit). Vous pouvez intégrer le détecteur facilement sans avoir besoin d'un hub Aqara, ce qui constitue une excellente solution pour les passionnés de maison connectée. Ultra-haute précision avec plus de confidentialité: Grâce à la technologie radar à ondes millimétriques, le détecteur de présence FP2 permet une détection précise des mouvements sans produire de faux négatifs, même en cas de légers mouvements. De plus, la détection ne nécessite aucun système de surveillance par caméra, maximisant ainsi l’intimité des utilisateurs. De plus, grâce à son indice IPX5, le FP2 peut également être installé dans des environnements humides tels que les salles de bains. Détecteur de lumière intégré et automatisations locales : Le FP2 est en outre doté d'un détecteur de lumière intégré, qui offre plus de souplesse et de libertés pour créer des automatisations d'éclairage (uniquement disponible avec Aqara Home, HomeKit et IFTTT). Enfin, les automatisations du FP2 sont exécutées sans envoi vers le cloud et continueront de fonctionner même sans connexion Internet.
    82,99 €

    66,39 €

    -20%

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.