Zigbee2MQTT ist eine Open-Source Zigbee-Bridge welche sich, dank dem Netzwerkprotokoll MQTT, leicht in bestehende Smarthome-Lösungen integrieren lässt. Als Beispiel kann Zigbee2MQTT kombiniert mit MQTT - Broker  Mosquitto und Home-Assistant Daten der Zigbee-Geräte erfassen, anzeigen, aufzeichnen und diese steuern. Das hier beschriebene Setup verwendet Docker als Basis. Herstellerseite: https://www.zigbee2mqtt.io

Wie der Name schon sagt, wird für das Setup ein MQTT-Broker vorausgesetzt: siehe:  MQTT - Broker  Mosquitto, bzw. für das komplette Setup siehe: Home-Assistant Docker Conbee 2 und Zigbee2MQTT / deCONZ.

Docker-Container mit Zigbee2MQTT starten

Ich habe Home-Assistant in Docker gestartet, daher kann Zigbee2MQTT nicht über den AddOn Store installiert werden. Um Zigbee2MQTT dennoch zu starten, kann folgendes Docker-Image verwendet werden: "koenkk/zigbee2mqtt". Aktuelle Zigbee2MQTTVersion: 1.42.0 (gefunden: 02.12.2024)

version: "3"
services:
  zigbee2mqtt:
      container_name: zigbee2mqtt
      restart: always
      image: koenkk/zigbee2mqtt
      volumes:
        - ./zigbee2mqtt-data:/app/data
        - /run/udev:/run/udev:ro
      ports:
        - 83:8080
      environment:
        - TZ=Europe/Vienna

Das Beispiel verwendet Bind-Mounts und keine Docker Volumes für das permanente Speichern der Daten. Siehe: Docker Daten speichern: Docker Volumes vs. Host-Ordner

Der Docker-Container wird nach dem Anlegen der Datei "docker-compose.yml" mit dem Befehl "docker compose up" gestartet.

Beim ersten Start legt Zigbee2MQTT eine configuration.yaml-Datei im Ordner zigbee2mqtt-data an. In der Datei kann der Hostname, Benutzername und das Kennwort des MQTT-Broker angegeben werden. Zudem muss bei einer neuen Installation der Zugriff auf den ZigBee-USB-Stick angepasst werden.

# Home Assistant integration (MQTT discovery)
homeassistant: true

# allow new devices to join
permit_join: true

# MQTT settings
mqtt:
  # MQTT base topic for zigbee2mqtt MQTT messages
  base_topic: zigbee2mqtt
  # MQTT server URL
  server: 'mqtt://mqtt'
  # MQTT server authentication, uncomment if required:
  user: mqtt
  password: ???xx

# Serial settings
serial:
  # Location of CC2531 USB sniffer
  port: /dev/ttyACM0
  
# Enable the Zigbee2MQTT frontend
frontend:
  port: 8080
# Let Zigbee2MQTT generate a new network key on first start
advanced:
  network_key: GENERATE

Die komplette Docker-Compose-Datei mit vorgeschaltetem LetsEncrypt Reverse Proxy,  MQTT - Broker  Mosquitto und Home-Assistant habe ich auf der folgenden Seite notiert: docker-compose.yml für Zigbee2MQTT, MQTT und HomeAssistant

Nach dem Start kann die Weboberfläche mit dem in der Konfig-Datei angegebenen Port im Browser aufgerufen werden:

Weboberfläche

Beim ersten Start ist das Anlernen für alle Geräte aktiv, entsprechend registrieren sich diese automatisch nach einem Reset oder beim Aktivieren des Verbindungsmodus. Beim Einsatz des MQTT - Broker und Home-Assistant werden die Geräte mit folgender Einstellung automatisch auch in Home-Assistant angelegt: "Home Assistant integration"

Damit nicht jeder im WLAN auf die Verwaltung von Zigbee2MQTT zugreifen kann, sollte in den Einstellungen ein Authentifizierungstoken gesetzt werden. 

Authentifizierung - Token

Das Frontend besitzt keine Benutzerverwaltung, als Absicherung kann lediglich ein Token hinterlegt werden:

Der Token muss nach dem Aktivieren für den Zugriff auf die Weboberläche im Browser angegeben werden:

Zigbee - Bindungen (Binding)

Zugegeben, habe ich es mit deConz und Phoscon bisher nicht geschafft Geräte, wie den Philips Dimmer Switch direkt mit einem Licht zu verbinden. Schuld war im Nachhinein, denke ich, nicht die umständliche Oberfläche von deConz, sondern die Tatsache, dass ein Schalter vor dem Verbinden mit einem Licht vom Coordinator getrennt werden muss: Dieses Licht ist mir erst jetzt mit Zigbee2MQTT aufgegangen. Das Zigbee2MQTT-Webfrontend ist hier eindeutig wesentlich übersichtlicher und nach dem Trennen des Coordinators konnte ich zuvor angelegte Gruppen bestehend aus mehreren Lampen ganz einfach mit einem Schalter verbinden. Der Schaltvorgang funktioniert nach dem Binding auch wenn das Zigbee-Gateway komplett ausgeschaltet ist und trägt neben einer schnellen Reaktion wesentlich zur Stabilität bei.

Gruppen anlegen

Direkt ohne Gateway verbinden

Die Schalter können, wie beschrieben,  in "Bindungen" vom Coordinator (Zigbee-Gateway) getrennt und im Anschluss mit bestimmten Geräten oder Gruppen verbunden werden:

Firmware

Für bestimmte Geräte schlägt Zigbee2MQTT neue Firmwareversionen vor und kann diese bei Bedarf installieren:

Nicht unterstützt: der Yagusmart Zigbee Smart Vorhangschalter

Sollte ein Gerät nicht unterstützt werden, kann dies vorerst trotzdem verbunden und mittels einer externen Konverterdatei eingebunden werden:

Dazu kann eine Datei mit der Endung .js im Daten-Ordner von Zigbee2MQTT angelegt werden:

 Um die Aktionen des Gerätes sichtbar zu machen, kann in der configuration.yml-Datei der Log-Level auf "debug" gesetzt werden.

advanced:
  log_level: debug
...
external_converters:
  - FB56+CUR17SB2.2.js

Beim Betätigen des Schalters meldet sich dieser damit im Log:

Ich konnte daraus noch nicht wirklich rauslesen, wie die .js-Datei aussehen muss damit der Schalter funktioniert, dafür habe ich aber im Internet ein Beispiel für einen ähnlichen Schalter gefunden und dieses verwenden können:

const fz = require('zigbee-herdsman-converters/converters/fromZigbee');
const tz = require('zigbee-herdsman-converters/converters/toZigbee');
const exposes = require('zigbee-herdsman-converters/lib/exposes');
const reporting = require('zigbee-herdsman-converters/lib/reporting');
const extend = require('zigbee-herdsman-converters/lib/extend');
const e = exposes.presets;
const ea = exposes.access;

const definition = {
    zigbeeModel: ['FB56+CUR17SB2.2'],
    model: 'FB56+CUR17SB2.2', 
    vendor: 'Feibit Co.Ltd', 
    description: 'Smart Zigbee 3.0 curtain controller',
    fromZigbee: [fz.tuya_cover_options],
    toZigbee: [tz.cover_state],
    whiteLabel: [{vendor: 'Zemismart', model: 'ZW-EU-01', description: 'Smart light relay - 1 gang'}],
    meta: {configureKey: 2},
    exposes: [e.cover_position(), exposes.enum('moving', ea.STATE, ['UP', 'STOP', 'DOWN'])],
    configure: async (device, coordinatorEndpoint, logger) => {
        const endpoint1 = device.getEndpoint(1);
        await reporting.bind(endpoint1, coordinatorEndpoint, ['genOnOff']);
        await reporting.onOff(endpoint1);
        await reporting.bind(endpoint1, coordinatorEndpoint, ['closuresWindowCovering'])      
        device.powerSource = 'Mains (single phase)';
        device.type = 'EndDevice';
        device.save();
    },
};

module.exports = definition;

Quelle: github.com/Koenkk/zigbee-herdsman-converters/issues/2489 bzw. github.com/Koenkk/zigbee-herdsman-converters/blob/master/devices/nue_3a.js

Übersicht Mesh-Netzwerk

Der Reiter "Karte" zeigt das Zigbee-Mesh-Netzwerk grafisch an. Für einen besseren Überblick verschwinden beim Klick auf ein Gerät anderen Verbindungen im Hintergrund.

Fazit

Verglichen mit deConz und Phoscon finde ich die Verwaltung der Geräte in Zigbee2MQTT wesentlich übersichtlicher. Alle Funktionen sind gesammelt in einer Oberfläche vorhanden und können bei Bedarf auch von einem Smartphone bedient werden. Für eine Integration in HomeAssistant, siehe: Home-Assistant Docker Conbee 2 und Zigbee2MQTT / deCONZ und Zigbee2MQTT vs deCONZ und Phoscon.   Siehe auch: ZHA Inbetriebnahme und Wechsel von Zigbee2MQTT