> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-fr/kilo-iot-server/gateways/mqtt-edge-gateways/zigbee2mqtt-hubs.md).
# 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](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — 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](/kilo-docs-fr/kilo-iot-server/gateways/mqtt-edge-gateways.md) 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](https://www.zigbee2mqtt.io/supported-devices/) 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](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector.md) (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](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md), 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-fr/kilo-iot-server/gateways/mqtt-edge-gateways/zigbee2mqtt-hubs.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
