Zigbee-Einrichtung und Fehlerbehebung

Wenn Sie das Erweiterungsmodul WBE2R-R-ZIGBEE verwenden, stellen Sie sicher, dass in der Weboberfläche das richtige Modul ausgewählt ist unter Settings → Configs → Hardware Modules Configuration.

Portname:

• Bei Verwendung des Erweiterungsmoduls WBE2R-R-ZIGBEE heißt der Port /dev/ttyMODx, wobei x die Portnummer ist;
• bei Verwendung eines USB-Sticks heißt der Port /dev/ttyUSBx, wobei x die bei null beginnende Portnummer ist.

Nummerierung der Erweiterungsmodulanschlüsse (WB 6.7–8.4)

Nummerierung der Erweiterungsmodulanschlüsse (WB 8.5, 8M)

Konfiguration:

1. Öffnen Sie die Konfigurationsdatei zur Bearbeitung (vollständige Parameterreferenz auf Englisch):

   nano /mnt/data/root/zigbee2mqtt/data/configuration.yaml
   

   Die Standardkonfigurationsdatei sieht wie folgt aus:

   homeassistant: false
   permit_join: false
   mqtt:
     base_topic: zigbee2mqtt
     server: 'mqtt://localhost'
   serial:
     port: /dev/ttyMOD4
     adapter: zstack
   advanced:
     rtscts: false
     last_seen: epoch
     channel: 11
     pan_id: GENERATE
     network_key: GENERATE
   ota:
       image_block_response_delay: 50
       default_maximum_data_size: 60
   

2. Ändern Sie die erforderlichen Parameter:
   • Der Parameter port Geben Sie den Steckverbinder an, in dem das Modul physisch installiert ist. Wenn bereits der richtige Port angegeben ist, lassen Sie die Datei unverändert.
   • Nach dem ersten Start der Brücke ersetzen Werte GENERATE; ändern Sie diese nicht . Falls Sie sie ändern, aktualisieren oder löschen Sie die Sicherung.
3. Klicken Sie auf Ctrl+S zum Speichern der Änderungen, Ctrl+X — zum Verlassen des Editors.
4. Starten Sie den Dienst neu zigbee2mqtt:

   systemctl restart zigbee2mqtt
   

Sie können nun den Konverter installieren. Die Zigbee-Geräte erscheinen anschließend auf der Registerkarte Devices in der standardmäßigen Weboberfläche des Controllers.

Mögliche Probleme:

• Wenn Sie in der Weboberfläche die falsche Steckverbindernummer für das Zigbee-Erweiterungsmodul auswählen, zeigt das Protokoll diesen Fehler: z2m: Error: Error: Input/output error setting custom baud rate of 115200

Beispielprotokoll:

# journalctl -u zigbee2mqtt --no-pager -n 30

May 12 13:53:25 wirenboard-AQLNJER2 systemd[1]: Started zigbee2mqtt.
May 12 13:53:25 wirenboard-AQLNJER2 npm[27834]: > zigbee2mqtt@2.1.1 start
May 12 13:53:25 wirenboard-AQLNJER2 npm[27834]: > node index.js
May 12 13:53:26 wirenboard-AQLNJER2 npm[27846]: Starting Zigbee2MQTT without watchdog.
May 12 13:53:32 wirenboard-AQLNJER2 npm[27846]: [2025-05-12 13:53:32] info:         z2m: Logging to console, file (filename: log.log)
May 12 13:53:32 wirenboard-AQLNJER2 npm[27846]: [2025-05-12 13:53:32] info:         z2m: Starting Zigbee2MQTT version 2.1.1 (commit #unknown)
May 12 13:53:32 wirenboard-AQLNJER2 npm[27846]: [2025-05-12 13:53:32] info:         z2m: Starting zigbee-herdsman (3.2.5)
May 12 13:53:32 wirenboard-AQLNJER2 npm[27846]: [2025-05-12 13:53:32] info:         zh:zstack:znp: Opening SerialPort with {"path":"/dev/ttyMOD3","baudRate":115200,"rtscts":false,"autoOpen":false}
May 12 13:53:32 wirenboard-AQLNJER2 npm[27846]: [2025-05-12 13:53:32] error:         z2m: Error while starting zigbee-herdsman
May 12 13:53:32 wirenboard-AQLNJER2 npm[27846]: [2025-05-12 13:53:32] error:         z2m: Failed to start zigbee-herdsman
May 12 13:53:32 wirenboard-AQLNJER2 npm[27846]: [2025-05-12 13:53:32] error:         z2m: Check https://www.zigbee2mqtt.io/guide/installation/20_zigbee2mqtt-fails-to-start_crashes-runtime.html for possible solutions
May 12 13:53:32 wirenboard-AQLNJER2 npm[27846]: [2025-05-12 13:53:32] error:         z2m: Exiting...
May 12 13:53:32 wirenboard-AQLNJER2 npm[27846]: [2025-05-12 13:53:32] error:         z2m: Error: Error: Input/output error setting custom baud rate of 115200
May 12 13:53:32 wirenboard-AQLNJER2 systemd[1]: zigbee2mqtt.service: Main process exited, code=exited, status=1/FAILURE
May 12 13:53:32 wirenboard-AQLNJER2 systemd[1]: zigbee2mqtt.service: Failed with result 'exit-code'.
May 12 13:53:32 wirenboard-AQLNJER2 systemd[1]: zigbee2mqtt.service: Consumed 10.578s CPU time.
May 12 13:54:22 wirenboard-AQLNJER2 systemd[1]: Stopped zigbee2mqtt.
May 12 13:54:22 wirenboard-AQLNJER2 systemd[1]: zigbee2mqtt.service: Consumed 10.578s CPU time.

Weboberfläche (Frontend)

Die zigbee2mqtt-Weboberfläche läuft auf einem separaten Port und kann ein Sicherheitsrisiko darstellen — aktivieren Sie sie nicht, wenn sie nicht benötigt wird: Geräte können über unsere Oberfläche hinzugefügt und entfernt werden: Konverter installieren.

Verfügbar in Release testing Der Zugriff auf die Weboberfläche kann durch die Benutzerauthentifizierung des Controllers geschützt werden. Siehe Drittanbieterdienste in der Wiren Board-Weboberfläche.

Wenn Sie die native zigbee2mqtt-Weboberfläche benötigen, aktivieren Sie sie in der Einstellungsdatei:

1. Öffnen Sie die Datei configuration.yaml zur Bearbeitung:

   nano /mnt/data/root/zigbee2mqtt/data/configuration.yaml
   

2. Fügen Sie diesen Block hinzu:

   frontend:
     enabled: true
     port: 8081
     host: 0.0.0.0
   

3. Speichern und schließen Sie die Datei.
4. Starten Sie den Dienst neu zigbee2mqtt:

   systemctl restart zigbee2mqtt
   

Die Weboberfläche der zigbee2mqtt-Brücke ist erreichbar unter http://wb-ip-address:PORT. Wenn die IP-Adresse des Controllers beispielsweise 192.168.42.1und der konfigurierte Port 8081ist, ist die Weboberfläche erreichbar unter http://192.168.42.1:8081.

Cloud-Zugriff

Auf die zigbee2mqtt-Weboberfläche kann auch von außerhalb des lokalen Netzwerks zugegriffen werden. Wenn der Controller mit Wiren Board Cloud verbunden ist, klicken Sie auf der Controller-Seite auf Services und fügen Sie Zigbee2MQTT hinzu. Eine Schaltfläche erscheint, die die Oberfläche von jedem Gerät aus öffnet, das bei Ihrem Cloud-Konto angemeldet ist.

Status prüfen

Es gibt zwei Möglichkeiten zu prüfen, ob z2m erfolgreich gestartet wurde:

1) Prüfen Sie kurz den Betriebsstatus.

Die folgende Ausgabe ist normal und enthält keine Fehler:

# systemctl status zigbee2mqtt
● zigbee2mqtt.service - zigbee2mqtt
     Loaded: loaded (/lib/systemd/system/zigbee2mqtt.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2025-03-06 10:23:02 UTC; 1s ago
   Main PID: 630240 (npm start)
      Tasks: 26 (limit: 2340)
     Memory: 34.0M
        CPU: 2.087s
     CGroup: /system.slice/zigbee2mqtt.service
             ├─630240 npm start
             ├─630262 sh -c node index.js
             └─630263 node index.js

Mar 06 10:23:02 wirenboard-AQLNJER2 systemd[1]: Started zigbee2mqtt.
Mar 06 10:23:03 wirenboard-AQLNJER2 npm[630240]: > zigbee2mqtt@2.1.1 start
Mar 06 10:23:03 wirenboard-AQLNJER2 npm[630240]: > node index.js

Beachten Sie die Zeile Active: active (running) since ... und das Fehlen von Fehlern oder Warnungen.

Wenn Sie im vorherigen Schritt die falsche Modulsteckverbindernummer angegeben haben, sieht die Ausgabe etwa wie folgt aus:

# systemctl status zigbee2mqtt
● zigbee2mqtt.service - zigbee2mqtt
     Loaded: loaded (/lib/systemd/system/zigbee2mqtt.service; enabled; vendor preset: enabled)
     Active: activating (auto-restart) (Result: exit-code) since Thu 2025-03-06 10:19:33 UTC; 5s ago
   Main PID: 628249 (code=exited, status=1/FAILURE)
      Tasks: 0 (limit: 2340)
     Memory: 0B
        CPU: 0
     CGroup: /system.slice/zigbee2mqtt.service

Die obige PID-Zeile weist auf einen Fehler hin: Main PID: 628249 (code=exited, status=1/FAILURE).

2) Untersuchen Sie das zigbee2mqtt-Protokoll im Detail.

# journalctl -u zigbee2mqtt --no-pager -n 30
-- Journal begins at Tue 2025-03-04 16:14:09 UTC. --
Mar 06 14:17:00 wirenboard-AQLNJER2 npm[27126]: [2025-03-06 14:17:00] error:         z2m: Exiting...
Mar 06 14:17:01 wirenboard-AQLNJER2 npm[27126]: [2025-03-06 14:17:01] error:         z2m: Error: Failed to connect to the adapter (Error: SRSP - SYS - ping after 6000ms)
Mar 06 14:17:01 wirenboard-AQLNJER2 npm[27126]:     at ZStackAdapter.start (/mnt/data/root/zigbee2mqtt/node_modules/.pnpm/zigbee-herdsman@3.2.5/node_modules/zigbee-herdsman/src/adapter/z-stack/adapter/zStackAdapter.ts:113:27)
Mar 06 14:17:01 wirenboard-AQLNJER2 npm[27126]:     at Controller.start (/mnt/data/root/zigbee2mqtt/node_modules/.pnpm/zigbee-herdsman@3.2.5/node_modules/zigbee-herdsman/src/controller/controller.ts:136:29)
Mar 06 14:17:01 wirenboard-AQLNJER2 npm[27126]:     at Zigbee.start (/mnt/data/root/zigbee2mqtt/lib/zigbee.ts:69:27)
Mar 06 14:17:01 wirenboard-AQLNJER2 npm[27126]:     at Controller.start (/mnt/data/root/zigbee2mqtt/lib/controller.ts:142:13)
Mar 06 14:17:01 wirenboard-AQLNJER2 npm[27126]:     at start (/mnt/data/root/zigbee2mqtt/index.js:161:5)
Mar 06 14:17:01 wirenboard-AQLNJER2 systemd[1]: zigbee2mqtt.service: Main process exited, code=exited, status=1/FAILURE
Mar 06 14:17:01 wirenboard-AQLNJER2 systemd[1]: zigbee2mqtt.service: Failed with result 'exit-code'.
Mar 06 14:17:01 wirenboard-AQLNJER2 systemd[1]: zigbee2mqtt.service: Consumed 14.449s CPU time.
Mar 06 14:18:19 wirenboard-AQLNJER2 systemd[1]: Stopped zigbee2mqtt.
...

Startprobleme und Fehler können weitere Dienststarts verhindern. In diesem Fall können die Fehler mit dem folgenden Befehl zurückgesetzt werden:

# systemctl reset-failed zigbee2mqtt.service

Dies kann beispielsweise beim folgenden Fehler nach Änderung der Portnummer in den z2m-Einstellungen helfen:

# systemctl restart zigbee2mqtt
Job for zigbee2mqtt.service failed because the control process exited with error code.
See "systemctl status zigbee2mqtt.service" and "journalctl -xe" for details.
# systemctl reset-failed zigbee2mqtt.service
# systemctl restart zigbee2mqtt

Aktualisieren

Um zigbee2mqtt auf die neueste Version zu aktualisieren, aktualisieren Sie die Controller-Software gemäß den Anweisungen. Alle Einstellungen und gekoppelten Geräte bleiben erhalten.

Wenn Sie einen älteren WBE2R-R-ZIGBEE v.1Adapter haben, der vor Januar 2022 hergestellt wurde, funktioniert die neue Version nicht. Es gibt drei Möglichkeiten:

• Flashen Sie den älteren Adapter mit neuerer Firmware, Anleitung.
• installieren Sie die mit diesen Adaptern kompatible Paketversion:

  apt install zigbee2mqtt-1.18.1
  

• ersetzen Sie den Adapter durch WBE2R-R-ZIGBEE v.2 oder verwenden Sie einen unterstützten USB-Stick.

Sendeleistung einstellen

Die standardmäßige Sendeleistung beträgt 9 dBm. So erhöhen Sie sie (verfügbare Werte: 0…20 dBm):

1. Öffnen Sie die Datei configuration.yaml zur Bearbeitung:

   nano /mnt/data/root/zigbee2mqtt/data/configuration.yaml
   

2. Ergänzen Sie im Block advanced:

   advanced:
     transmit_power: 20
   

3. Speichern und schließen Sie die Datei.
4. Starten Sie den Dienst neu zigbee2mqtt:

   systemctl restart zigbee2mqtt
   

Konverter wb-mqtt-zigbee

Verfügbar seit Release wb-2606

Beschreibung

wb-mqtt-zigbee ist der neue Konverter , der zigbee2mqtt-Daten auf Topics virtueller Geräte abbildet. Er zeigt Zigbee-Geräte in der Weboberfläche des Wiren Board-Controllers an und steuert sie.

Der Konverter übersetzt die Namen von Zigbee-Gerätebedienelementen wb-mqtt-zigbee mithilfe seines eigenen Wörterbuchs ins Russische. Wenn ein Bedienelementname auf Englisch bleibt, ist er noch nicht im Wörterbuch enthalten. Kontaktieren Sie uns über das Portal für technischen Support, und wir fügen die Übersetzung in einem zukünftigen Update hinzu.

Funktionsweise

Zigbee2mqtt verbindet sich mit dem Zigbee-Koordinator, erkennt Geräte und veröffentlicht alle Informationen beim MQTT-Broker. Der Topic-Namensraum wird in der zigbee2mqtt-Konfiguration (/mnt/data/root/zigbee2mqtt/data/configuration.yaml, Parameter base_topic) konfiguriert und ist standardmäßig zigbee2mqtt. Der Konverter führt anschließend Folgendes aus:

1. Er abonniert Topics zigbee2mqtt/ und empfängt Brückenstatus, Geräteliste, Protokolle und Ereignisse.
2. Er erstellt virtuelle WB-Geräte in /devices/ — und veröffentlicht Metadaten (/meta) und Werte der Bedienelemente gemäß WB MQTT Conventions.
3. Er leitet Befehle zurück: Wenn ein Benutzer in der Controller-Weboberfläche einen Dropdown-Wert auswählt, einen Schieberegler bewegt oder einen Schalter betätigt, empfängt der Dienst einen Befehl von /devices/.../on und veröffentlicht die entsprechende Anfrage an zigbee2mqtt/bridge/request/....

Das folgende Diagramm zeigt den Datenfluss durch den MQTT-Broker (mosquitto): zigbee2mqtt-Topics links und Topics des Wiren Board-Controllers rechts. Die Pfeile sind bidirektional: Gerätezustände fließen von links nach rechts, Befehle von rechts nach links.

Installation

Warnung: Die Installation des neuen Konverters kann benutzerdefinierte Skripte beeinträchtigen wb-rules, insbesondere wenn Regeln zuvor den Zeichenfolgenwert ONund jetzt den booleschen Wert 1 für einen Schalter verwenden. wb-mqtt-zigbee wird automatisch mit dem Paket zigbee2mqttinstalliert, wenn wb-zigbee2mqttnicht bereits installiert war. Andernfalls installieren Sie es mit:

apt update && apt install wb-mqtt-zigbee

In der standardmäßigen Weboberfläche des Controllers erscheint anschließend auf der Registerkarte Devices das Gerät Zigbee2MQTT.

Geräte hinzufügen

Geräte können einzeln oder gemeinsam hinzugefügt werden. So fügen Sie neue Geräte hinzu:

1. Öffnen Sie die Weboberfläche des Controllers und wählen Sie die Registerkarte Devices.
2. Suchen Sie das Geräte-Widget Zigbee2MQTT und prüfen Sie seinen Status im Feld State. Es sollte online anzeigen. Wurde zigbee2mqtt gerade erst installiert, warten Sie einige Minuten.
3. Aktivieren Sie den Schalter Permit join.
4. Befolgen Sie die Anleitung des Zigbee-Geräts: Halten Sie üblicherweise die Taste pair einige Sekunden lang gedrückt und warten Sie, bis die Anzeige blinkt.
5. Beim Hinzufügen eines Geräts zeigt das Feld Last joined im Widget Zigbee2MQTT die IEEE-Adresse des Geräts an (beispielsweise 0xa4c1385da71ff53c). Die Geräteanzahl erhöht sich mit jedem hinzugefügten Gerät um eins.
6. Wiederholen Sie die Schritte 4 und 5 für jedes Zigbee-Gerät.
7. Beenden Sie das Hinzufügen von Geräten, indem Sie Folgendes deaktivieren: Permit join.

friendly_name ändern

friendly_name ist ein benutzerdefinierter Gerätename. Behalten Sie den Standard bei oder legen Sie einen eigenen fest:

1. Öffnen Sie die Konfigurationsdatei zur Bearbeitung:

   nano /mnt/data/root/zigbee2mqtt/data/configuration.yaml
   

2. Suchen Sie im Abschnitt devices Ihr Gerät.
3. Änderung friendly_name.
4. Speichern Sie die Konfigurationsdatei und starten Sie den Dienst neu:

   systemctl restart zigbee2mqtt
   

5. Auf der Registerkarte Devices sollte ein Gerät mit dem angegebenen Namen erscheinen.
6. Entfernen Sie das Widget mit dem alten Namen durch Klicken auf das Papierkorbsymbol in seiner Überschrift.

Der neue Name muss für jedes Gerät eindeutig sein, darf keinen Schrägstrich enthalten / und muss die Parameteranforderungen erfüllen und die Wiren Board MQTT Conventions.

• friendly_name ändern
• 
  Geräte-Widget mit friendly_name Standard
• 
  Ändern von friendly_name in der Konfigurationsdatei
• 
  Geräte-Widget mit dem neuen friendly_name

Gerät steuern

Geräte werden über Standardbedienelemente bedient: Schalter oder Dropdown-Listen.

Geräte entfernen

1. Stellen Sie sicher, dass im Geräte-Widget Zigbee2MQTT der Schalter Permit join ausgeschaltet ist.
2. Entkoppeln Sie das Gerät vom Koordinator. Dazu muss normalerweise seine Kopplungstaste 5 Sekunden lang gedrückt gehalten werden; siehe Gerätedokumentation.
3. Prüfen Sie, dass beim Gerät Zigbee2MQTT Widget im Feld das Feld Last removed den Namen des zu entfernenden Geräts anzeigt.
4. Entfernen Sie das Widget des getrennten Zigbee-Geräts aus der Weboberfläche durch Klicken auf das Papierkorbsymbol in seiner Überschrift.

• 
  Zuletzt entferntes Gerät
• 
  Zigbee-Geräte-Widget entfernen

Übersetzungen der Gerätekanäle

Verfügbar seit Release wb-2609 Die Kanalnamen von Zigbee-Geräten werden in der ausgewählten Sprache der Weboberfläche angezeigt.

Gerätemodell

Verfügbar seit Release wb-2609 Bei neuen Geräten wird das Modell jetzt im Kartentitel angezeigt. Zigbee2MQTT-Geräte haben außerdem einen Kanal Model.

Fehlerbehebung

Wenn zigbee2mqtt nicht richtig funktioniert, prüfen Sie den Dienststatus und die ausführlichen Protokolle. Verbinden Sie sich zum Ausführen von Befehlen über SSH mit dem Controller.

Führen Sie zur Anzeige des aktuellen Status und der neuesten Protokollmeldungen Folgendes aus:

# systemctl status zigbee2mqtt
● zigbee2mqtt.service - zigbee2mqtt
   Loaded: loaded (/lib/systemd/system/zigbee2mqtt.service; enabled; vendor preset: enabled)
   Active: activating (auto-restart) (Result: exit-code) since Fri 2022-05-13 10:06:04 +04; 3s ago
  Process: 25986 ExecStart=/usr/bin/npm start (code=exited, status=1/FAILURE)
 Main PID: 25986 (code=exited, status=1/FAILURE)

May 13 10:06:04 wirenboard-AYXIHFQ6 systemd[1]: zigbee2mqtt.service: Main process exited, code=exited, status=1/FAILURE
May 13 10:06:04 wirenboard-AYXIHFQ6 systemd[1]: zigbee2mqtt.service: Unit entered failed state.
May 13 10:06:04 wirenboard-AYXIHFQ6 systemd[1]: zigbee2mqtt.service: Failed with result 'exit-code'.

Oft zeigt der vorherige Schritt ein Problem, ohne dessen Ursache zu erkennen. Untersuchen Sie in diesem Fall die Protokolle:

1. Stoppen Sie den Dienst:

   systemctl stop zigbee2mqtt
   

2. Wechseln Sie in das zigbee2mqtt-Verzeichnis:

   cd /mnt/data/root/zigbee2mqtt/
   

3. Starten Sie zigbee2mqtt manuell und geben Sie alle Meldungen auf der Konsole aus mit npm start:

   # npm start
   
    > zigbee2mqtt@1.18.1 start /mnt/data/root/zigbee2mqtt
    > node index.js
   
   Zigbee2MQTT:info  2022-05-13 09:59:30: Logging to console and directory: '/mnt/data/root/zigbee2mqtt/data/log/2022-05-13.09-59-19' filename: log.txt
   Zigbee2MQTT:info  2022-05-13 09:59:30: Starting Zigbee2MQTT version 1.18.1 (commit #unknown)
   Zigbee2MQTT:info  2022-05-13 09:59:30: Starting zigbee-herdsman (0.13.71)
   Zigbee2MQTT:error 2022-05-13 09:59:39: Error while starting zigbee-herdsman
   Zigbee2MQTT:error 2022-05-13 09:59:39: Failed to start zigbee
   Zigbee2MQTT:error 2022-05-13 09:59:39: Exiting...
   Zigbee2MQTT:error 2022-05-13 09:59:39: Error: Error while opening serialport 'Error: Error: No such file or directory, cannot open /dev/ttyUSB01'
       at Znp.<anonymous> (/mnt/data/root/zigbee2mqtt/node_modules/zigbee-herdsman/dist/adapter/z-stack/znp/znp.js:136:32)
       at Generator.next (<anonymous>)
       at /mnt/data/root/zigbee2mqtt/node_modules/zigbee-herdsman/dist/adapter/z-stack/znp/znp.js:27:71
       at new Promise (<anonymous>)
       at __awaiter (/mnt/data/root/zigbee2mqtt/node_modules/zigbee-herdsman/dist/adapter/z-stack/znp/znp.js:23:12)
       at SerialPort.<anonymous> (/mnt/data/root/zigbee2mqtt/node_modules/zigbee-herdsman/dist/adapter/z-stack/znp/znp.js:134:49)
       at SerialPort._error (/mnt/data/root/zigbee2mqtt/node_modules/zigbee-herdsman/node_modules/@serialport/stream/lib/index.js:198:14)
       at /mnt/data/root/zigbee2mqtt/node_modules/zigbee-herdsman/node_modules/@serialport/stream/lib/index.js:242:12
   npm ERR! code ELIFECYCLE
   npm ERR! errno 1
   npm ERR! zigbee2mqtt@1.18.1 start: `node index.js`
   npm ERR! Exit status 1
   npm ERR! 
   npm ERR! Failed at the zigbee2mqtt@1.18.1 start script.
   npm ERR! This is probably not a problem with npm. There is likely additional logging output above.
   
   npm ERR! A complete log of this run can be found in:
   npm ERR!     /root/.npm/_logs/2022-05-13T05_59_39_596Z-debug.log
   

   Hier ist sofort erkennbar, dass der konfigurierte Port falsch ist.

4. Starten Sie nach Erkennen und Beheben des Problems den Dienst erneut:

   systemctl start zigbee2mqtt
   

Wenn das Ausführen von npm start den Dienst automatisch erfolgreich startet, stoppen Sie ihn durch Drücken von Ctrl+C.

Manchmal muss der automatische Dienststart deaktiviert werden. Verwenden Sie diese Befehle zu seiner Steuerung:

systemctl disable zigbee2mqtt
systemctl enable zigbee2mqtt

Probleme beheben

Version 1.18.1 startet nach einem Update nicht

Die Konsole zeigt:

Zigbee2MQTT version 1.18.1. Does not accept version node. Zigbee2MQTT requires node version ^10  ^12  ^14 |
| ^15 || ^16, you are running v20.5.1!

Installieren Sie die vorherige Version des nodejs-Pakets:

apt install nodejs=16.20.2-deb-1nodesource1

zigbee2mqtt meldet einen Modulfehler

Ermitteln Sie, ob das Problem in zigbee2mqtt, seiner Konfiguration oder dem Modul liegt.

Prüfen Sie zuerst, ob das Modul korrekt konfiguriert ist; siehe Dokumentation des Erweiterungsmoduls.

Wenn die Konfiguration korrekt ist, testen Sie das Modul mit dem Drittanbieterskript check-cc2652p:

1. Laden Sie das Skript gemäß den Repository-Anweisungen herunter.
2. Stoppen Sie zigbee2mqtt:

   systemctl stop zigbee2mqtt
   

3. Führen Sie den Befehl aus und ersetzen Sie den Port durch Ihren eigenen:

   python3 ./check_cc2652p.py /dev/ttyMOD4
   

Wenn die Antwort Informationen zur Firmware- und Modulversion enthält, funktioniert das Modul. Das Problem liegt daher in zigbee2mqtt: ein falscher Port oder ein anderer Fehler.

Beispiel für eine erfolgreiche Ausgabe:

# python3 ./check_cc2652p.py /dev/ttyMOD4
SYS Version response detected for CC2652:
Transport Version: 2
Product ID: 1 — CC2652 Zigbee Module.
Major Release: 2
Minor Release: 7
Maintenance Release: 1
Stack Version: 2.7.1 — Indicates Z-Stack compatibility.
Revision: 6bb1340100 — Firmware Revision Details.
Additional asynchronous data detected. Skipping:
Raw data: 81fe0345c4f2dd00ad

Problem beim Aktualisieren von zigbee2mqtt auf Version 2.1.1

Wenn zigbee2mqtt nach dem Update auf Version 2.1.1 mit folgenden Symptomen nicht startet:

> zigbee2mqtt@2.1.1 start
> node index.js
node:internal/modules/cjs/loader:1051
  throw err;
  ^
Error: Cannot find module 'semver'
Require stack:
- /mnt/data/root/zigbee2mqtt/index.js
at Module._resolveFilename (node:internal/modules/cjs/loader:1048:15)

versuchen Sie die folgenden Schritte:

1. Sichern Sie die Datei configuration.yaml.
2. Entfernen Sie die aktuelle Version: apt remove zigbee2mqtt.
3. Fügen Sie in der Datei configuration.yaml den Adaptertyp adapter zum Abschnitt serialhinzu. Beispiel für unser Modul:

   serial:
     port: /dev/ttyMOD1
     adapter: zstack
   

4. Installieren Sie das Paket erneut: apt update && apt install zigbee2mqtt.

Konfigurationsdatei beim Update von zigbee2mqtt auf 2.1.1 versehentlich ersetzt

Beim Update von zigbee2mqtt von einer älteren Version auf 2.1.1 fragt das System, ob eine neue Konfigurationsdatei installiert oder die alte beibehalten werden soll:

File configuration «/mnt/data/root/zigbee2mqtt/data/configuration.yaml»
 ==> Modified s since installation (by you or by a script).
 ==> The author of the package has supplied an updated version.
  What should be done? The following options are available:
   Y or I : install the version provided by the maintainer of the package
   N or O : keep the installed at the current time version
      D    : show the differences between the versions
      Z    : start a shell command line to inspect the situation
 By default the system keeps the current version file configuration. *** configuration.yaml (Y/I/N/O/D/Z) [by default N] ? y

Wenn Sie versehentlich das Ersetzen der Datei gewählt haben und zigbee2mqtt mit einem Fehler wie diesem nicht startet:

zh:adapter:zstack:manager: Configuration is not consistent with adapter state/backup!
zh:adapter:zstack:manager: - PAN ID: configured=43787, adapter=47905
zh:adapter:zstack:manager: - Extended PAN ID: configured=00124b0030d540fa, adapter=00124b0030d540fa
zh:adapter:zstack:manager: - Network Key: configured=d9bf90f96d74b793c1f136ecee3660cf, adapter=ab64f03813fd7cc36c6f3383b7d58ad9
zh:adapter:zstack:manager: - Channel List: configured=11, adapter=11
zh:adapter:zstack:manager: Please update configuration to prevent further issues.
zh:adapter:zstack:manager: If you wish to re-commission your network, please remove coordinator backup at /mnt/data/root/zigbee2mqtt/data/coordinator_backup.json.
zh:adapter:zstack:manager: Re-commissioning your network will require re-pairing of all devices!
z2m: Error while starting zigbee-herdsman
z2m: Failed to start zigbee-herdsman

stellen Sie den Start und die gelöschte Konfiguration wie folgt wieder her:

• Löschen Sie die Datei nicht: ~/zigbee2mqtt/data/coordinator_backup.json. Wenn Sie sie löschen, müssen alle Geräte erneut gekoppelt werden.
• Stoppen Sie den Dienst mit systemctl stop zigbee2mqtt.
• Sichern Sie die vorhandene Konfiguration:

  cp ~/zigbee2mqtt/data/configuration.yaml ~/zigbee2mqtt/data/configuration.yaml-wb-backup

• Stellen Sie die vorherige Konfiguration wieder her:

  cp ~/zigbee2mqtt/data/configuration.yaml.dpkg-old ~/zigbee2mqtt/data/configuration.yaml

• Prüfen Sie, ob die Datei den Adaptertyp angibt: Sie muss die folgende Zeile enthalten: adapter: zstack. Falls diese fehlt, fügen Sie sie zum Abschnitt hinzu: serial.
• Starten Sie den Dienst neu mit systemctl restart zigbee2mqtt.

zigbee2mqtt sollte mit der vor dem Update vorhandenen Konfiguration starten.

Archiv aller Versionen (Pool)

Dieses enthält alle z2m-Pakete, sowohl Testing- als auch Release-Builds. Es enthält außerdem Veröffentlichungsdaten, die das normale Repository nicht anzeigt. Damit lässt sich feststellen, wann ein Fehler oder eine Funktion in das System gelangt ist.

Alle z2m-Pakete

Verlauf einer bestimmten Version (z. B. 2.1.1)

Zweck: Untersuchung von Vorfällen und Ermitteln des Veröffentlichungsdatums eines bestimmten Builds.

Offizielles Release (Packages)

Dies ist die freigegebene Paketliste, die ein Controller (beispielsweise WB7) über apt update sieht. Ein Paket wird erst nach Tests und offizieller Release-Registrierung (beispielsweise Zweig 2507) aufgenommen.

Liste für WB7 (Release 2507)

Zweck: Prüfen, welche z2m-Version für eine Neuinstallation oder ein Update auf dem Controller eines Benutzers verfügbar ist.

Älterer Konverter

• wb-zigbee2mqtt

Nützliche Links

• zigbee2mqtt-Dokumentation
• Zigbee-Geräte über Zigbee2mqtt und Node-RED verwenden
• Zigbee-Geräte mit einem Wiren Board-Controller verbinden und wb-rules-Skripte schreiben
• zigbee2mqtt aus dem Quellcode kompilieren
• Lokale OTA-Firmware-Updates über zigbee2mqtt