> 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-de/kilo-iot-server/gateways/mqtt-edge-gateways/zigbee2mqtt-hubs.md).
# Zigbee2MQTT-Hubs
Betreiben Sie einen Zigbee2MQTT-Hub als MQTT-Edge-Gateway — Koordinator-Funkmodul, Z2M-Software, flacher JSON-Topic-Stream.
Zigbee2MQTT (Z2M) ist ein MQTT-Edge-Gateway-Muster, das für Kilo-Deployments mit Zigbee-Feldhardware verfügbar ist. Es ist nicht der Standardpfad für die Datenaufnahme und nicht für jede Bereitstellung geeignet — Modbus-, BACnet-, OPC-UA- und Sparkplug-B-Bridges bleiben weiterhin die konventionellen Optionen für industrielle Telemetrie. Aber dort, wo Zigbee-Hardware tatsächlich ins Betriebskonzept passt — Pilotprojekte, Messgeräte in Laboren und Büros, standortweite Umweltsensoren, Belegungs- und Personenanzahlsensoren, Smart-Plug-Telemetrie, Beleuchtungs- und Präsenzsysteme im Gebäudemanagement — bietet Z2M eine gut unterstützte Open-Source-Bridge, die ein Zigbee-Mesh in MQTT-Publishes umwandelt, die der Connector der Plattform verarbeiten kann.
Diese Seite behandelt Z2M als Gateway-Muster. Die MQTT-seitige Registrierung der resultierenden Geräte (Device ID Topic, Mapping-Tab, Connector-Schlüssel) ist dokumentiert in [Topics und Geräte-Routing](/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — dieser Ablauf ist identisch, unabhängig davon, welches MQTT-Edge-Gateway den Topic-Stream erzeugt.
## Was ein Z2M-Hub ist
Ein Z2M-Hub besteht aus drei zusammenarbeitenden Teilen:
1. **Ein Host-Rechner** am Netzwerkrand — typischerweise ein kleines Linux-Gerät (Industrie-Mini-PC, NUC, Raspberry Pi, Hersteller-Appliance) mit USB oder Ethernet zum Koordinator und einem stabilen Netzwerkpfad zum Broker. Betrieblich läuft es als Systemdienst mit Neustart-bei-Fehler-Verhalten.
2. **Ein Zigbee-Koordinator** — ein USB-Funkmodul (zum Beispiel Sonoff ZBDongle-E mit EFR32MG24, eine häufig verwendete Option) oder ein netzwerkgebundener Koordinator (zum Beispiel SMLIGHT SLZB-06). Der Koordinator ist die Funkbrücke zwischen dem Zigbee-Mesh und Z2M; er selbst betreibt kein MQTT.
3. **Die Zigbee2MQTT-Software** — öffnet den Transport des Koordinators, bindet Zigbee-Geräte in das Mesh ein und veröffentlicht den Zustand sowie die Telemetrie jedes Geräts als flaches JSON auf `zigbee2mqtt/{friendlyName}`.
Aus Sicht der Plattform sieht der resultierende MQTT-Stream aus wie jeder andere Edge-Gateway-Stream mit JSON-Nutzdaten.
## Wo Z2M in kommerziellen Deployments passt
Z2M ist geeignet, wenn Zigbee-Endgeräte betrieblich sinnvoll sind und der Umfang des Deployments zu dem passt, wofür das Open-Source-Projekt Z2M ausgelegt ist:
* **Pilotprojekte** zur Bewertung von Sensortypen oder Hersteller-Mischungen, bevor in dedizierte Funkinfrastruktur investiert wird.
* **Mess- und Instrumentierungstechnik in Büro, Labor und Gebäude** — Temperatur-, Feuchte-, CO₂-, Präsenz- und Helligkeitssensoren, Smart Plugs, Belegungszähler.
* **Ergänzungen für das Gebäudemanagement** — ergänzende Sensoren, die ein bestehendes BMS ergänzen, statt es zu ersetzen.
* **Gezielte kommerzielle Beleuchtung** Szenarien, in denen Zigbee-Lampen und -Steckdosen die gewählte Hardware sind.
Z2M ist nicht das richtige Werkzeug für Telemetrie mit hohem Durchsatz, Fabrikautomation oder Szenarien, in denen harte Echtzeitgarantien, deterministische Latenz oder formale Redundanzarchitekturen betrieblich erforderlich sind. Diese Anwendungsfälle werden besser durch Modbus-, OPC-UA-, BACnet- oder Sparkplug-B-Bridges bedient — siehe die [Übersicht über MQTT-Edge-Gateways](/kilo-docs-de/kilo-iot-server/gateways/mqtt-edge-gateways.md) für die breitere Kategorienübersicht.
## Kapazität und Wiederherstellung — validieren, nicht annehmen
Z2M ist die aktive Verbindung zwischen dem Zigbee-Mesh und dem Broker. Wenn der Host oder Container neu startet, pausiert das Routing im Zigbee-Mesh für diese Dauer. Koordinatorkapazität, Verkehrsbewältigung und Wiederherstellungsverhalten sollten vor der Festlegung des Designs anhand der konkreten Geräteanzahl und des Verkehrsmusters Ihres Deployments validiert werden. Akzeptable Ausfallfenster, Neustarthäufigkeit und betriebliche Toleranz gegenüber vorübergehenden Störungen sind deploymentspezifische Entscheidungen, keine allgemeine Empfehlung — bestätigen Sie sie mit einem gezielten Ausfalltest, bevor Sie Z2M für irgendeine betrieblich relevante Telemetrie einsetzen.
Dieser Leitfaden schreibt keine Redundanzmuster für Z2M vor. Redundanz bei Z2M ist nicht trivial und hängt von Annahmen über den Hersteller des Koordinators, die Mesh-Topologie und die Art und Weise ab, wie Clients kurze Unterbrechungen tolerieren; behandeln Sie Redundanz als Frage des Bereitstellungsdesigns, nicht als dokumentiertes Muster.
## Hersteller- und Firmware-Hinweise
* **Zigbee-3.0-Interoperabilität ist gut, aber nicht perfekt.** Bestimmte Gerätemodelle benötigen möglicherweise ein Handling, das von der Firmware-Version abhängt. Validieren Sie die geplante Geräteauswahl anhand der [Liste der von Zigbee2MQTT unterstützten Geräte](https://www.zigbee2mqtt.io/supported-devices/) vor dem Einkauf.
* **Sparkplug B ist in Z2M nicht nativ enthalten.** Z2M veröffentlicht flaches JSON, nicht Sparkplug. Bei Deployments, die auf Sparkplug standardisiert sind, sitzt eine zusätzliche Sparkplug-Kodierungs-Bridge zwischen Z2M und dem Broker.
* **Kompatibilität der Koordinator-Firmware.** Das `serial.adapter` Einstellung in Z2M `configuration.yaml` muss zur Chip-Familie des Koordinators passen — `ezsp` für EFR32MG (Sonoff ZBDongle-E und ähnliche), `zstack` für CC2652P (Sonoff ZBDongle-P). Nicht passende Werte führen dazu, dass Z2M nicht startet.
## Übergabe des Routings an den MQTT-Connector
Sobald Z2M veröffentlicht, wird jedes Zigbee-Gerät aus Sicht der Plattform zu einem normalen MQTT-Publisher. Die Arbeit auf Connector-Seite ist dieselbe wie bei jedem anderen MQTT-publizierenden Gateway:
1. Konfigurieren Sie den [MQTT-Connector](/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector.md) (Cloud MQTT oder External MQTT) und verweisen Sie Z2M darauf über `mqtt.server` und `mqtt.base_topic` in `configuration.yaml`.
2. Registrieren Sie für jedes Zigbee-Gerät einen Geräteeintrag mit **Device ID** gleich dem Friendly Name von Z2M (bytegenau; Leerzeichen werden auf Plattformseite entfernt, verwenden Sie daher Namen ohne Leerzeichen wie `LineA-Sensor-12` oder `lab_temp_03`).
3. Setzen Sie die **Device ID Topic** nach `zigbee2mqtt/{{deviceId}}`.
4. Ordnen Sie die Payload-Schlüssel gemäß dem in [Topics und Geräte-Routing](/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md)beschriebenen Zwei-Durchläufe-Speichermuster zu, und überarbeiten Sie das Mapping iterativ, wenn in Live-Payloads zusätzliche Felder erscheinen.
Für eine vollständige Z2M-Setup-Referenz (`docker-compose.yml`, `configuration.yaml` Vorlage, Auswahl des Koordinators, Wahl des Kanals) konsultieren Sie die Dokumentation des Zigbee2MQTT-Projekts. Der veröffentlichte Topic-Stream von Z2M erreicht den MQTT-Connector der Plattform identisch wie jedes andere MQTT-Edge-Gateway, das flaches JSON am Broker erzeugt.
---
# 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-de/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.
