Abstract violet and amber illustration representing Zigbee2MQTT, a bridge that converts Zigbee mesh network traffic into MQTT messages

Zigbee2MQTT

Zigbee2MQTT

Zigbee2MQTT est un pont, pas un hub. Il capte le trafic radio de vos appareils Zigbee (ampoules, capteurs, prises, boutons) et le transforme en messages MQTT que n’importe quelle plateforme domotique peut écouter. Il remplace la passerelle Zigbee propriétaire du fabricant (le hub Tradfri d’Ikea, le bridge Hue de Philips, le hub Aqara) par un seul logiciel que vous contrôlez, sur du matériel qui vous appartient.

Cette distinction compte, parce que zigbee2mqtt est souvent rangé à côté de Home Assistant dans la case « plateforme domotique », et ce n’est pas vraiment le cas. Il n’a ni moteur d’automatisation ni tableau de bord digne de ce nom, en dehors de l’appairage et de la configuration des appareils. Ce qu’il propose, c’est une interface web pour appairer le matériel, et une connexion MQTT qui publie chaque changement d’état vers tout ce qui écoute : Home Assistant, openHAB, Node-RED, ou un script maison.

Ce que fait réellement Zigbee2MQTT

Chaque réseau Zigbee a besoin d’un coordinateur, une radio qui communique directement avec vos ampoules et capteurs via le protocole 802.15.4. Les hubs des fabricants associent ce coordinateur à une application connectée au cloud. Zigbee2mqtt fait le même travail, mais en local. Il pilote un coordinateur Zigbee USB (souvent basé sur une puce Texas Instruments CC2652, comme le dongle Sonoff Zigbee 3.0 USB Dongle Plus, ou un ConBee II/III de Phoscon), tient à jour une carte en direct de chaque appareil appairé, et republie les changements d’état sous forme de topics MQTT, du type zigbee2mqtt/living-room-motion/state.

Le projet répartit son fonctionnement interne sur trois dépôts GitHub distincts, d’après sa propre documentation. zigbee-herdsman gère la communication radio bas niveau avec le matériel du coordinateur, zigbee-herdsman-converters fait correspondre des centaines de particularités propres à chaque fabricant à un modèle de données commun, et Zigbee2MQTT lui-même pilote l’ensemble et sert l’interface web. Cette bibliothèque de convertisseurs explique en bonne partie pourquoi zigbee2mqtt prend en charge les nouveaux appareils plus vite que les hubs fermés des fabricants : le support est ajouté par la communauté, en public, sans attendre une mise à jour du firmware constructeur.

Zigbee2MQTT face au ZHA intégré de Home Assistant

Home Assistant embarque sa propre intégration Zigbee, ZHA (Zigbee Home Automation), qui parle directement au même matériel de coordinateur, sans broker MQTT ni service intermédiaire. C’est la comparaison que les gens cherchent réellement, et la réponse honnête est que les deux fonctionnent très bien. La différence est architecturale, pas un écart de fonctionnalités.

ZHA est plus simple si Home Assistant est le seul système qui consommera jamais vos données Zigbee : un service de moins à faire tourner, une chose de moins à maintenir. Zigbee2mqtt devient le meilleur choix dès qu’un deuxième système a besoin des mêmes données Zigbee. Il s’intègre nativement avec openHAB, Domoticz, Gladys Assistant, Homey et ioBroker, et continue de fonctionner même si vous migrez plus tard hors de Home Assistant, parce que vos appareils parlent un protocole neutre au lieu d’être enfermés dans la couche d’intégration d’une seule plateforme.

Installer Zigbee2MQTT avec Docker

L’image Docker officielle est le chemin le plus rapide vers une installation fonctionnelle. Montez un répertoire de données pour la base d’appareils et le fichier de configuration, passez le coordinateur USB, et pointez le conteneur vers un broker MQTT :

docker run -d --name zigbee2mqtt \
  --device=/dev/ttyUSB0 \
  -v /path/to/zigbee2mqtt/data:/app/data \
  -p 8080:8080 \
  -e TZ=Europe/Paris \
  koenkk/zigbee2mqtt

Ce dernier point n’est pas optionnel. Zigbee2mqtt ne parle ni à Home Assistant ni à rien d’autre directement, il ne parle que MQTT. Ce qui veut dire qu’il a besoin d’un broker comme Mosquitto qui tourne déjà avant d’avoir un endroit où publier. Cette association est assez courante pour que la plupart des installations Zigbee auto-hébergées fassent tourner les deux conteneurs côte à côte sur le même réseau Docker.

Problèmes de configuration courants

Quelques soucis reviennent assez souvent pour être mentionnés. Le coordinateur USB doit être passé explicitement au conteneur, et un chemin stable du type /dev/serial/by-id/... survit mieux aux redémarrages qu’un numéro brut /dev/ttyUSB0 qui peut changer d’une fois sur l’autre. Les erreurs de permission sur ce périphérique sont presque toujours un décalage utilisateur/groupe Docker, pas une panne matérielle. L’interface web embarquée tourne sur le port 8080 par défaut et n’est pas exposée hors du conteneur tant que vous ne la publiez pas explicitement. Et un coordinateur avec un firmware obsolète est l’une des causes les plus courantes d’un réseau qui appaire les appareils sans problème mais les perd de façon intermittente ensuite. Vérifier la version de firmware recommandée pour votre dongle avant la première session d’appairage évite pas mal de dépannage plus tard.

Licence et gouvernance

Zigbee2mqtt est publié sous licence GPL-3.0, confirmée directement dans le fichier LICENSE du dépôt GitHub Koenkk/zigbee2mqtt. Contrairement à Mosquitto ou openHAB, il n’est rattaché à aucune fondation. Il est maintenu par Koenraad Vandenborne (Koenkk) et une large communauté de contributeurs sur le support des appareils, financé par GitHub Sponsors et des dons directs plutôt que par un soutien d’entreprise. Cette indépendance explique en partie pourquoi le projet avance vite : le support de nouveaux appareils arrive sous forme de pull requests communautaires, pas d’éléments de feuille de route.

Si vous construisez une maison connectée auto-hébergée autour de Home Assistant, zigbee2mqtt associé à Mosquitto comme broker reste la manière la plus courante d’obtenir un support Zigbee indépendant des fabricants, sans dépendre de l’intégration propriétaire d’un seul hub. Pour la vue d’ensemble de la façon dont les pièces s’assemblent, notre guide sur la pile domotique auto-hébergée détaille le reste de la chaîne.