Hubs Zigbee2MQTT

Exécutez un hub Zigbee2MQTT comme passerelle MQTT en périphérie — radio coordinateur, logiciel Z2M, flux de topics JSON plats.

Zigbee2MQTT (Z2M) est l’un des modèles de passerelle MQTT en périphérie disponibles pour les déploiements Kilo qui incluent du matériel de terrain Zigbee. Ce n’est pas le chemin d’ingestion par défaut, et ce n’est pas adapté à tous les déploiements — les ponts Modbus, BACnet, OPC-UA et Sparkplug B restent les choix conventionnels pour la télémétrie industrielle. Mais là où le matériel Zigbee s’inscrit réellement dans le tableau opérationnel — programmes pilotes, instrumentation de laboratoire et de bureau, capteurs environnementaux à l’échelle d’un site, détection de présence et comptage de personnes, télémétrie de prises connectées, éclairage et présence pour la gestion du bâtiment — Z2M fournit un pont open source bien pris en charge qui transforme un maillage Zigbee en publications MQTT que le connecteur de la plateforme peut consommer.

Cette page couvre Z2M en tant que modèle de passerelle. L’enregistrement côté MQTT des appareils résultants (Device ID Topic, onglet Mapping, clés du connecteur) est documenté dans Topics et routage des appareils — ce flux est identique, quelle que soit la passerelle MQTT en périphérie qui produit le flux de topics.

Ce qu'est un hub Z2M

Un hub Z2M, c’est trois éléments qui fonctionnent ensemble :

1. Une machine hôte en périphérie du réseau — généralement un petit appareil Linux (mini-PC industriel, NUC, Raspberry Pi, appliance du fournisseur) avec USB ou Ethernet vers le coordinateur et un chemin réseau stable vers le broker. Sur le plan opérationnel, il fonctionne comme un service système avec une sémantique de redémarrage en cas d’échec.

2. Un coordinateur Zigbee — une radio USB (par exemple, Sonoff ZBDongle-E avec EFR32MG24, une option couramment utilisée) ou un coordinateur raccordé au réseau (par exemple, SMLIGHT SLZB-06). Le coordinateur est le pont radio entre le maillage Zigbee et Z2M ; il n’exécute pas MQTT lui-même.

3. Le logiciel Zigbee2MQTT — ouvre le transport du coordinateur, connecte les appareils Zigbee au maillage et publie l’état et la télémétrie de chaque appareil sous forme de JSON plat sur zigbee2mqtt/{friendlyName}.

Du point de vue de la plateforme, le flux MQTT résultant ressemble à celui de n’importe quelle autre passerelle en périphérie à charge utile JSON.

Où Z2M s’insère dans les déploiements commerciaux

Z2M convient lorsque les périphériques Zigbee sont utiles sur le plan opérationnel et que l’échelle du déploiement correspond à ce pour quoi le projet open source Z2M a été conçu :

• Programmes pilotes évaluer les types de capteurs ou les mélanges de fournisseurs avant de s’engager dans une infrastructure radio dédiée.

• Instrumentation de bureau, de laboratoire et d’installations — capteurs de température, d’humidité, de CO₂, de présence, de niveau de lumière, prises connectées, compteurs d’occupation.

• Compléments de gestion du bâtiment — capteurs supplémentaires qui complètent un BMS existant plutôt que de le remplacer.

• Éclairage commercial ciblé scénarios où les ampoules et prises Zigbee sont le matériel retenu.

Z2M n’est pas le bon outil pour la télémétrie de processus à haut débit, l’automatisation de l’atelier, ou les scénarios où des garanties de temps réel strict, une latence déterministe ou des architectures formelles de redondance sont requises sur le plan opérationnel. Ces cas d’usage sont mieux servis par des ponts Modbus, OPC-UA, BACnet ou Sparkplug B — voir l’ Aperçu des passerelles MQTT en périphérie pour une vue d’ensemble de la catégorie plus large.

Capacité et reprise — validez, n’assumez pas

Z2M est le lien actif entre le maillage Zigbee et le broker. Si l’hôte ou le conteneur redémarre, le routage du maillage Zigbee est interrompu pendant cette période. La capacité du coordinateur, la gestion du trafic et le comportement de reprise doivent tous être validés par rapport au nombre d’appareils et au profil de trafic spécifiques de votre déploiement avant de figer la conception. Les fenêtres d’indisponibilité acceptables, la fréquence des redémarrages et la tolérance opérationnelle aux interruptions transitoires sont des décisions propres au déploiement, pas des recommandations génériques — confirmez-les au moyen d’un test de panne délibéré avant de vous fier à Z2M pour toute télémétrie pertinente sur le plan opérationnel.

Ce guide ne prescrit pas de schémas de redondance pour Z2M. La redondance Z2M n’est pas triviale et dépend d’hypothèses sur le fournisseur du coordinateur, la topologie du maillage et la manière dont les clients tolèrent de brèves perturbations ; considérez la redondance comme une question de conception du déploiement, pas comme un schéma documenté.

Avertissements sur les fournisseurs et le firmware

• L’interopérabilité Zigbee 3.0 est bonne, mais pas parfaite. Certains modèles d’appareils peuvent nécessiter une prise en charge spécifique à une version du firmware. Validez l’ensemble d’appareils prévu par rapport à la Liste des appareils pris en charge par Zigbee2MQTT avant l’achat.

• Sparkplug B n’est pas natif à Z2M. Z2M publie du JSON plat, pas du Sparkplug. Pour les déploiements standardisés sur Sparkplug, un pont supplémentaire d’encodage Sparkplug se place entre Z2M et le broker.

• Compatibilité du firmware du coordinateur. Le serial.adapter paramètre dans configuration.yaml doit correspondre à la famille de puces du coordinateur — ezsp pour EFR32MG (Sonoff ZBDongle-E et similaires), zstack pour CC2652P (Sonoff ZBDongle-P). Des valeurs incompatibles empêchent Z2M de démarrer.

Passage du routage au connecteur MQTT

Une fois Z2M en publication, chaque appareil Zigbee devient du point de vue de la plateforme un éditeur MQTT ordinaire. Le travail côté connecteur est le même que pour toute autre passerelle publiant en MQTT :

1. Configurez le connecteur MQTT (Cloud MQTT ou MQTT externe) et dirigez Z2M vers lui via mqtt.server et mqtt.base_topic dans configuration.yaml.

2. Pour chaque appareil Zigbee, enregistrez une fiche appareil avec ID de l’appareil égal au nom convivial Z2M (à l’identique ; les espaces blancs sont supprimés côté plateforme, donc utilisez des noms sans espaces comme LineA-Sensor-12 ou lab_temp_03).

3. Définissez la Topic ID de l’appareil vers zigbee2mqtt/{{deviceId}}.

4. Mappez les clés de la charge utile en suivant le schéma d’enregistrement en deux passes documenté dans Topics et routage des appareils, puis revenez de manière itérative à Mapping au fur et à mesure que des champs supplémentaires apparaissent dans les charges utiles en direct.

Pour une référence complète de configuration Z2M (docker-compose.yml, configuration.yaml modèle, sélection du coordinateur, choix du canal), consultez la documentation propre au projet Zigbee2MQTT. Le flux de topics publié par Z2M atteint le connecteur MQTT de la plateforme de la même manière que n’importe quelle autre passerelle MQTT en périphérie produisant du JSON plat sur le broker.