Zigbee2mqtt : choisir, installer et configurer.

Zigbee est aujourd’hui un protocole incontournable dans tout système domotique, et bien entendu Home Assistant : offre pléthorique d’appareils connectés à bon prix, réseau maillé, fiabilité. Il a doucement supplanté ZWave, son concurrent historique.

Par défaut, pour supporter Zigbee, Home Assistant propose un contrôleur maison : ZHA. Mais une autre implémentation est très populaire et offre de nombreux avantages : Zigbee2MQTT (diminutif Z2M).

Dans cet article, nous allons essayer de répondre à plusieurs questions cruciales avant de démarrer :

• Avantages et inconvénients de Zigbee2MQTT par rapport à ZHA.
• Quelle clé Zigbee choisir.
• Comment fonctionne Zigbee2MQTT.
• Comment installer Mosquito MQTT et Zigbee2MQTT sur HAOS.
• Comment bien les configurer.

Ce guide s’adresse aux personnes débutantes avec Zigbee2MQTT comme aux personnes plus confirmées souhaitant tirer partie de leur installation.

Choisir Zigbee2MQTT ou ZHA ?

ZHA (Zigbee Home Automation) est le contrôleur développé par Nabu Casa et intégré à Home Assistant via une intégration. Il est très fiable et son avenir est assuré.

Son installation est simple, les appareils Zigbee sont très facilement reconnus. Donc ZHA sera un excellent choix pour qui ne veut pas passer trop de temps sur son installation ou est débutant, a des appareils très courants, et ne veut pas forcément en modifier les paramètres.

Zigbee2MQTT (Z2M) n’est lui PAS un développement spécifique à Home Assistant. D’autres systèmes domotiques l’utilisent comme JEEDom. Vous pourriez donc envisager de garder votre configuration Zigbee2MQTT et changer de système domotique.

Parmi les avantages de Z2M, nous pourrions citer :

• Un nombre très important d’appareils Zigbee supportés, plus important que ZHA
• Une très belle interface graphique, avec un graphe dynamique du réseau maillé
• Un système open source vraiment fiable et évolutif grâce à la communauté le supportant.
• Une documentation exhaustive des appareils supportés, avec leurs paramètres et éventuels bugs (voir supported devices).
• Des possibilités de paramétrage avancées des appareils, ainsi que leur mise à jour.
• Une interface MQTT permettant de connecter d’autres systèmes que Home Assistant (Node-Red ou Frigate par exemple).
• Il peut être installé sur une machine autre que Home Assistant
• Peut supporter un nombre plus important d’appareils connectés, avec une éventuelle répartition de charge sur plusieurs serveurs Z2M.

Le choix Zigbee2MQTT est lié au choix d’utiliser un broker MQTT. C’est un choix d’architecture qui permet de l’interopérabilité avec d’autres systèmes et vous ouvre la voie des intégrations futures.

Le revers de la médaille est un système qui demandera un plus d’effort lors de son installation.

Quelles clés Zigbee choisir

Bien entendu, il en existe pas mal, et nous présentons ici uniquement les plus populaires et réputées.

• Conbee II ou Conbee III : clés très fiables et choix historique de pas mal de personnes. C’est une valeur sûre.

• Sonoff ZBDongle-P ou ZBDongle-E : elles ont l’avantage d’être à la fois fiables et performantes, mais proposées à des prix bas. La ZBDongle-E a l’avantage de supporter Matter, le nouveau protocole qui intègre Zigbee 3.0 mais aussi d’autres protocoles comme Thread. Par contre, pour Z2M, il vous faudra la flasher (voir annexe) et vous ne pourrez pas utiliser Matter.

• Sky Connect ZBT-1 : il s’agit s’une clé récente développée par Nabu Casa. Cette clé a aussi l’avantage de supporter Matter, le nouveau protocole qui intègre Zigbee 3.0 mais aussi d’autres protocoles comme Thread. Par contre, pour Zigbee2MQTT, il vous faudra la flasher (voir annexe) et vous ne pourrez pas utiliser Matter.
• ZiGate : une excellente clé proposée par la marque du même nom, prête à l’emploi.
• SLZB-06, SLZB-06M, SLZB-06P7 et SLZB-06P10 : Il s'agit de clé Zigbee récente en Ethernet POE, ce qui facilite l'extension de la couverture à plusieurs zones ou bâtiments tout en restant connecté à une seule et même instance Home Assistant. Suivant le modèle, le chipset sera différent ( texas instruments ou silicon labs ).

Comprendre l'architecture Z2M

Voilà, vous avez choisi Zigbee2MQTT (Z2M), vous avez une clé Zigbee, et vous mourrez d’envie de l’installer. Avant, il est important de comprendre comment marche Z2M.
Promis, on va essayer d’être bref ;)

Voilà un schéma qui résume le fonctionnement de Z2M :

Contrairement à ZHA qui est une intégration (une librairie Home Assistant), Z2M est un « module complémentaire », c'est-à-dire un programme qui tourne indépendamment de Home Assistant. Il pourrait donc même tourner sur une autre machine que HA.

Z2M permet de gérer la clé Zigbee connectée à un port UB de sa machine (en général) et acter comme un coordinateur Zigbee.

Ensuite, il sait envoyer ou recevoir des messages MQTT. Et cela tombe bien, Home Assistant également. Nous allons donc utiliser un broker MQTT, Mosquito, qui servira de relai entre les 2 systèmes.

Un broker MQTT agit donc comme un intermédiaire, recevant les messages de certains appareils et les redistribuant aux appareils abonnés à ces messages (« publish-subscribe »). Il fera le passe-plat entre Home Assistant et Zigbee2MQTT.

Nous devrons donc déja avoir ou installer un autre module complémentaire : Mosquito pour Home Assistant.

Pour activer la fonction MQTT dans Home Assistant, il faudra installer une intégration (librairie) MQTT. Et tous les appareils Zigbee seront vus à travers cette intégration.

Dernier point : Zigbee2MQTT propose une interface web permettant de voir tous les appareils connectés. On activera dans Home Assistant (option de module complémentaire) la visualisation de cette interface pour qu’elle soit visible dans le menu de gauche.

Une fois configurée, l’utilisation sera simple et l’intégration parfaite.

Installation

Pré-requis

La procédure d'installation qui suit suppose que vous avez une configuration dite "clé en main" de Home Assistant : HA-OS.

Pour commencer, il faut s'assurer d'avoir ignoré les intégrations ZHA (Zigbee Home automation) ou Deconz. Sinon Zigbee2MQTT ne pourra pas démarrer, car l'une de ces intégrations utilisera votre clé Zigbee.

Pour cela rendez-vous dans Paramètres / appareils et services et ignorer l'installation :

Créer un utilisateur MQTT

Il faudra créer un utilisateur, aller dans paramètres / personnes :

Puis ajouter une nouvelle personne :

Installer Mosquitto broker (broker MQTT)

Un broker MQTT est un agent qui reçoit les messages publiés par les clients MQTT et les transmet aux clients abonnés aux sujets correspondants. Il agit comme un serveur centralisé qui facilite la communication entre les clients MQTT.

Pour installer Mosquitto broker, aller dans Paramètres / modules complémentaires :

Puis aller dans la boutique des modules complémentaires :

et sélectionner le module complémentaire Mosquitto broker :

Installer Mosquitto broker :

À la fin de l'installation, démarrer le module :

Installation de Zigbee2mqtt

Il faut ajouter le dépôt de Zigbee2MQTT dans le module complémentaire pour pouvoir l'installer, aller sur les 3 points, puis dépôt :

Copier/coller le dépôt et ajouter le :

https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

Actualiser la page et retourner dans la boutique de module complémentaire, puis sélectionner Zigbee2MQTT :

Installez-le :

Configuration du port USB

Avant de démarrer Zigbee2MQTT, vous allez devoir le configurer. Il va falloir rechercher le chemin de votre clé Zigbee.
Pour cela, aller dans paramètres / système / matériel, puis cliquer sur tout le matériel :

Rechercher le port USB de votre clé et copier le ID:

De retour dans le module complémentaire Zigbee2MQTT, puis onglet Configuration, il vous faut coller le chemin de la clé dans la partie serial :

Suivant la clé Zigbee que vous allez utiliser, il va falloir utiliser l'option "adapter". Ce mot clé est à rajouter après la définition du port dans le champ serial...

Pour une ZBDongle-P (chipset TI CC2652P) :

port: >-
  /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXXXXX-if00-port0
adapter: zstack

Pour une ZBDongle-E (chipset EFR32MG21) :

port: >-
  /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_XXXXXXXXXXX-if00
adapter: ember

pour la ZBDongle-E, il faudra la flasher avec le firmware ember, version 7.4.4 ou supérieur. Disponible a cette adresse : silabs-firmware-builder

Pour une Skyconnect/ZBT-1 :

port: >-
  /dev/serial/by-id/usb-Nabu_Casa_SkyConnect_v1.0_XXXXXXXXXXXXXXXXXXXXXXX-if00-port0
adapter: ember

Pour la Skyconnect/ZBT-1, il faudra la flasher avec le firmware ember, version 7.4.4 ou supérieur. Disponible à cette adresse : firmware_builds/skyconnect

Pour une Zigate :

port: >-
  /dev/serial/by-id/usb-FTDI_ZiGate_ZIGATE+-if00-port0
adapter: zigate

Pour une ConbeeII :

port: >-
  /dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_XXXXXX-if00
adapter: deconz

Pour une ConbeeIII :

port: >- 
  /dev/serial/by-id/usb-dresden_elektronik_ConBee_III_xxxxxxxxxx-if00-port0
adapter: deconz
baudrate: 115200

Pour une SLZB-06 :

port: tcp://192.168.1.xx:6638
adapter: zstack
baudrate: 115200

Pour une SLZB-06M :

port: tcp://192.168.1.xx:6638
adapter: ember
baudrate: 115200

Pour la SLZB-06M, il faudra la flasher avec le firmware ember, version 7.4.4 ou supérieur. Disponible à cette adresse : firmware_builds/slzb-06m

Configuration de l'URL d'accés et du login (section MQTT)

Ensuite, on va configurer la partie MQTT, deux choix s'offre à vous.
Soit vous utiliser l'utilisateur MQTT créer auparavant, soit vous laisser la case vide et Zigbee2mqtt s'occupera de créer un compte MQTT automatiquement.

Option 1
Avec le compte utilisateur MQTT créé auparavant, indiquer dans la partie MQTT :

server: mqtt://core-mosquitto:1883
user: mqtt
password: mqtt

Option 2
laisser la case MQTT vide.

Puis enregistrer votre configuration.

Tout est fini, vous pouvez maintenant démarrer Zigbee2MQTT.

Si tout s'est bien passé, Zigbee2MQTT a démarré. À vous les joies du Zigbee !
Vous aurez une icône dans la barre latérale pour accéder au menu de Zigbee2MQTT.

Ajouter l'intégration MQTT

Pour remonter les informations du broker MQTT sur Home assistant, il faut installer l'intégration MQTT. Normalement, vous devriez avoir une proposition d'installation de l'intégration MQTT qui est détectée automatiquement.

Aller dans paramètres / appareils et services, et installer l'intégration MQTT en appuyant sur configurer :

Maintenant, vous retrouvez tous les appareils appairés sur Zigbee2MQTT dans l'intégration MQTT. Vous y retrouverez toutes les entités des appareils, pour pouvoir les piloter dans Home assistant.

Utilisation de Zigbee2MQTT

Nous vous présentons ici quelques subtilités de l'outil. Rendez-vous sur l'interface.

Appairage / choix d'un routeur

En haut à droite du menu de l'écran d'accueil se trouve une combo qui permet de mettre Z2M en appairage Z2M.

Pour appairer un nouvel appareil, cliquer sur "Activer l'appairage", puis faire la procédure d'appairage sur votre appareil (3 clics sur un bouton, appui long... suivant l'appareil). Le nouvel appareil devrait apparaitre dans la liste des appareils. Après un peu de temps, les informations de l'appareil (marque, modèle... apparaitront).

Une fois les appairages terminés, pensez à désactiver l'appairage.

Vous pouvez également choisir sur quel routeur doit être utilisé pour appairer un appareil.

Liste des appareils

L'onglet Appareils liste l'ensemble des appareils et leur état.

Renommer un appareil
Pour renommer un appareil, utiliser l'icône renommer !

Puis saisissez le nouveau nom.

Détail d'un appareil

Si vous cliquez sur un des appareils dans la liste, vous obtenez le détail d'un appareil.

Sur la page principale, vous aurez accès à la documentation de l'appareil en cliquant sur le modèle (voir ci-dessous). Vous y trouverez une foule d'information sur le paramétrage de votre appareil, les problèmes connus, etc.

Attention, certains paramètres sont pour une utilisation avancée (voir la documentation de l'appareil).

L'onglet Expose vous permettra de voir les informations remontées par votre appareil, mais aussi de directement le contrôler pour test (ci-dessous l'exemple d'une prise).

Schéma de maillage

L'onglet Schéma depuis l'écran principal est le plus impressionnant : après un temps plus ou moins long, il affiche un graphe avec le réseau maillé.

Vous pouvez vérifier si tous les appareils sont connectés, par quel chemin, et avec quel signal.
On rappelle que seuls les appareils branchés au secteur font relai. Ce peut être l'occasion de rajouter par exemple une prise connectée si certains capteurs ont un signal trop faible.

Grouper des appareils

L'onglet Groupes permet de coupler des appareils. Un groupe permet de contrôler plusieurs appareils simultanément avec une seule commande. Cela est particulièrement utile pour des scénarios comme allumer ou éteindre plusieurs lumières en même temps, ou ajuster la température sur plusieurs thermostats.

Mise à jour OTA

Vous avez la possibilité de mettre à jour le firmware d'un équipement en OTA (Over The Air), s'il dispose de l'option. Pour cela, accèder l'onglet MAJ OTA.

Il vous suffit de lancer la mise à jour sur le bouton MAJ du firmware de l'appareil. Il faut compter en moyen 30 min, pour une mise à jour par OTA.

Touchlink

L'onglet Touchlink permet de scanner et identifier les appareils compatibles. Touchlink est une fonctionnalité de Zigbee qui permet aux appareils physiquement proches de communiquer entre eux sans être sur le même réseau. Cela est particulièrement utile pour connecter des appareils comme les ampoules Philips Hue ou IKEA sans passer par un réseau existant.

Nous ne détaillerons pas plus cela ici.

Journaux (log)

L'onglet Journaux permet de voir les différents événements et erreur. En cas de problème, il est important de le consulter.

Rappelez-vous : Z2M est un programme (module complémentaire) qui tourne en dehors de Home Assistant. En cas de problème avec un appareil, vous n'aurez pas accès au problème depuis les LOG de Home Assistant et il faut consulter ces logs.

Outils, backup de votre config

Pour redémarrer Z2M, cliquer sur la roue crantée et accédez aux outils. Vous pouvez forcer le redémarrage de Z2M.

Z2M propose un outil de backup : cliquez sur download_Z2M_backup. Si vous avez une grosse configuration, cela a du sens de le faire de temps en temps.

Éviter les interférences WiFi - Zigbee

Par défaut dans Zigbee2MQTT le zigbee est sur le canal 11, ce qui peut provoquer des interférences avec votre wifi si vous êtes sur le canal 1 par exemple (ou celui de vos voisins).

Les canaux conseillés sont le 15 / 20 / 25 et aussi le 26, mais attention, sachez que certains équipements zigbee ne seront pas compatibles avec certains canaux de zigbee (rare, mais cela peut arriver). Plus le canal est haut, plus la couverture sera moindre que les autres. Utiliser le canal le plus bas, pour une meilleure couverture ( 15 ).

Pour changer de canal Zigbee, dans le menu de Zigbee2MQTT aller dans paramètres (roue crantée) puis onglet avancés et modifier Zigbee channel.
Puis cliquer sur submit en bas de la page, pour enregistrer le paramètre.
Il faudra redémarrer Zigbee2MQTT pour le changement de canal.

Pour vous aider à trouver le meilleur signal pour votre zigbee et éviter des interférences avec votre wifi, je vous conseille de vous servir de Wifi Analyzer sur mobile que l’on trouve sur le google play (gratuit).

WiFi Analyzer - Apps on Google Play

Optimize your WiFi network using WiFi Analyzer, Get the most out of your WiFi.

Apps on Google Play

Conclusion

Vous disposez maintenant d'un puissant contrôleur Zigbee et d'un serveur MQTT.

Il ne vous reste plus qu'à choisir des appareils dans un catalogue très fourni de près de 4000 appareils compatibles.

Zigbee2MQTT

Zigbee to MQTT bridge, get rid of your proprietary Zigbee bridges

Enfin, n'hésitez pas à consulter cet article HACF qui présente comment bien gérer les indisponibilités de vos entités.

Zigbee2MQTT : bien gérer les disponibilités de ses devices

L’indisponibilité non détectée d’un périphérique Zigbee peut avoir de graves conséquences pour nos systèmes domotiques. Cet article vous explique comment fiabiliser Zigbee2MQTT en gérant correctement la surveillance des objets connectés.

Home Assistant Communauté FrancophoneArgonaute

ANNEXE - Flasher certaines clés USB Zigbee

Flasher la clé Skyconnect/ZBT-1

Pour flasher la clé Skyconnect/ZBT-1, vous pouvez utiliser le module complémentaire Silicon Labs Flasher. Vous l'installez et vous pouvez vous en servir pour flasher la clé Zigbee.

Attention, avant de le démarrer, assurez-vous d'avoir arrêté Zigbee2MQTT pour qu'il n'utilise pas la clé Zigbee et empêcher le flashage.

Après avoir flashé la clé, il faut arrêter Silicon Labs Flasher et redémarrer Zigbee2MQTT.

Flasher la clé Sonoff ZBDongle-P ou ZBDongle-E

Vous pouvez utiliser le module complémentaire ZigStar.

Ajouter le dépôt dans le module complémentaire :

https://github.com/mercenaruss/zigstar_addons

Pour la ZBDongle-E, installer ZigStar Silicon Labs FW Flsher.
Pour la ZBDongle-P, installer ZigStar TI CC2652P/P7 FW Flasher.

Attention, avant de le démarrer, assurez-vous d'avoir arrêté Zigbee2MQTT pour qu'il n'utilise pas la clé Zigbee et empêcher le flash.

Après avoir flashé la clé, il faut arrêter ZigStar Silicon Labs FW Flsher ou ZigStar TI CC2652P/P7 FW Flasher et redémarrer Zigbee2MQTT.