Connecting Zigbee devices to a Wiren Board controller

From Wiren Board
This is the approved revision of this page, as well as being the most recent.
Other languages:

Description

To use Zigbee devices with a Wiren Board controller, you need:

  1. An extension module WBE2R-R-ZIGBEE v.2 (WBE2R-R-ZIGBEE v.1) or any USB Zigbee stick.
  2. Additional software:

Installation instructions are below on this page.

Copy the commands from the instructions, paste them into controller console using the Shift+Insert keys and run with the Enter key. In case of errors, carefully read the output, there will be instructions and hints.

Installing and configuring zigbee2mqtt

Installation process

The zigbee2mqtt package version in the stable release may lag behind the latest version available from the author. The most recent version is always available in the testing release.

We recommend installing the pre-built package from our repository; there are two:

  • zigbee2mqtt — always the latest version, we recommend installing this one.
  • zigbee2mqtt-1.18.1 — version for older WBE2R-R-ZIGBEE v.1 adapters released before January 2022. Revision table.

To install the latest version, run the command: 

apt update && apt install zigbee2mqtt

To install version 1.18.1, required for zigbee v1 module revisions v1.1A–v1.2D, run: 

apt update && apt install zigbee2mqtt-1.18.1

To install 2.1.1 for zigbee v1 module revisions v1.2D/2, v1.2E, v1.2F, run: 

apt update && apt install zigbee2mqtt-2.1.1

An alternative installation method is to build from source by following the instructions.

Next, configure the bridge — see the Configuration section.

Auto-start configuration

After installing the package, the zigbee2mqtt service will start automatically when the controller boots. You can disable or enable auto-start with the commands: 

systemctl disable zigbee2mqtt
systemctl enable zigbee2mqtt

Configuration

If you are using the WBE2R-R-ZIGBEE extension module, make sure the module is set correctly in the web interface under Settings → Configs → Hardware Modules Configuration.

Port name:

  • when using the WBE2R-R-ZIGBEE extension module, the port will be named /dev/ttyMODx, where x is the port number;
  • when using a USB stick, the port will be named /dev/ttyUSBx, where x is the port number, numbered from zero

  • Port numbering for extension modules (WB 6.7–8.4)

  • Port numbering for extension modules (WB 8.5, 8M)

    • Configuration:

    1. Open the configuration file for editing (full parameter reference in English): 
      nano /mnt/data/root/zigbee2mqtt/data/configuration.yaml
      By default the configuration file looks like this:
      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. Change the parameters you need
      • In the port parameter, specify the socket where the module is physically connected. If the port is already specified and correct, do not modify the file.
      • After the first bridge start, the GENERATE placeholders will be replaced with actual values; do not change them. If you do change them, adjust or delete the backup.
    3. Restart the zigbee2mqtt service: 
      systemctl restart zigbee2mqtt

    Now you can install the wb-zigbee2mqtt converter, and Zigbee devices will appear under the Devices tab in the standard controller web interface.


    Possible issues

    - If you entered the wrong socket number in the WebUI for the zigbee extension board, the log will show the error z2m: Error: Error: Input/output error setting custom baud rate of 115200

    Example log: 

    # 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.

    Web interface (Frontend)

    zigbee2mqtt interface

    The zigbee2mqtt web interface runs on a separate port and is a potential security hole — do not enable it if you don't need it: devices can be added and removed via our wb-zigbee2mqtt converter.

    If you do need the native zigbee2mqtt web interface, you can enable it in the settings file:

    1. Open the configuration.yaml file for editing: 
      nano /mnt/data/root/zigbee2mqtt/data/configuration.yaml
    2. Add the following block: 
      frontend:
  enabled: true
  port: 8081
  host: 0.0.0.0
    3. Save and close the file.
    4. Restart the zigbee2mqtt service: 
      systemctl restart zigbee2mqtt

    The zigbee2mqtt bridge web interface will be available at http://wb-ip-address:PORT — for example, if the controller's IP address is 192.168.42.1 and the port is 8081, the web interface will be available at http://192.168.42.1:8081

    Status check

    There are two ways to check whether z2m started successfully:

    1) A quick check of its operating status.

    Below is the expected output when no errors are detected. 

    # 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
#

    Note the line "Active: active (running) since ..." and the absence of errors/warnings.

    If you entered the wrong socket number for the module at the previous step, the output will look roughly like this: 

    # 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
#

    In the output above, the PID line indicates the error "Main PID: 628249 (code=exited, status=1/FAILURE)"

    2) Detailed — view the zigbee2mqtt log. 

    # 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.
...

    At startup, problems and errors may occur that prevent the service from starting later; in this case a command that resets the errors can help: 

    # systemctl reset-failed zigbee2mqtt.service

    For example, this can help with the kind of error that occurs after changing the port number in z2m settings: 

    # 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
#

    Updating

    To update zigbee2mqtt to the latest version, simply update the controller software per the instructions. All settings and paired devices will be preserved.

    If you have an older WBE2R-R-ZIGBEE v.1 adapter released before January 2022, the latest version will not work; you have three options:

    • Flash the older adapter with the latest firmware — instructions.
    • Install the package version that works with these adapters: 
      apt install zigbee2mqtt-1.18.1
    • Replace the adapter with WBE2R-R-ZIGBEE v.2, or use a supported USB stick.

    Transmit power configuration

    By default the module uses a transmit power setting of 9 dBm. To increase the power (allowed values 0..20):

    1. Open the configuration.yaml file for editing: 
      nano /mnt/data/root/zigbee2mqtt/data/configuration.yaml
    2. Add to the advanced block: 
      advanced:
  transmit_power: 20
    3. Save and close the file.
    4. Restart the zigbee2mqtt service: 
      systemctl restart zigbee2mqtt

    wb-zigbee2mqtt converter

    Description

    Zigbee device on the Devices tab — the header shows the friendly_name

    wb-zigbee2mqtt is a converter from zigbee2mqtt data into virtual-device topics. It is written on the wb-rules engine and installed into the system rules folder wb-rules-system. It can display Zigbee devices in the Wiren Board controller interface, but to control them the user must write to zigbee2mqtt controls themselves using the publish function.

    How it works

    The wb-zigbee2mqtt converter requests the list of all connected devices from zigbee2mqtt and subscribes to their topics. When data arrives from physical devices, the converter parses the JSON, creates a virtual device and forwards the received information into it.

    The converter also creates a zigbee2mqtt virtual device and forwards into it the logs, version and state (online/offline) of the zigbee2mqtt bridge. The device-pairing mode can be toggled on and off. There is also an Update devices button. When pressed, the converter re-requests the list of added devices from the bridge and, if any new ones appeared, subscribes to them.

    Installation

    wb-zigbee2mqtt is installed automatically when the zigbee2mqtt package is installed; if that did not happen, install it with the command: 

    apt update && apt install wb-zigbee2mqtt

    After this, a zigbee2mqtt device will appear in the standard controller web interface on the Devices tab.

    Adding devices

    Adding a device — the message Device '0x00158d0007013f71' is supported.
    Unsupported device — the message Device '0x2c1165fffeabe0b8' not supported.

    You can add devices one at a time or all at once. To add new devices:

    1. Go to the standard controller web interface.
    2. Open the Devices tab.
    3. Find the Zigbee2mqtt device card and check the State field — it should read online. If you have only just installed zigbee2mqtt and the status is offline, wait a couple of minutes.
    4. Enable the Permit join switch.
    5. Follow the instructions for the Zigbee device: typically you need to hold the pair button on the device for a few seconds and wait for the indicator to start blinking.
    6. As the device is being added, messages Starting interview on 0xN → Device 0xN is supported will appear in turn in the Log field of the Zigbee2mqtt card. The last message means the device has been interrogated successfully.
    7. Repeat steps 5 and 6 for each Zigbee device you have.
    8. Finish adding devices by disabling the Permit join switch.
    9. Click Update devices — the added devices will become available on the Devices tab.

    Sometimes new devices do not appear on the Devices tab — possible reasons:

    1. An error occurred in the converter while parsing data from zigbee2mqtt; in this case restart the rules engine: 
      systemctl restart wb-rules
    2. Some devices are not supported by zigbee2mqtt; for such devices the message will read Starting interview on 0xN → Device 0xN ... is NOT supported. In that case, make sure the device is in the list of supported devices and that you have the latest zigbee2mqtt installed.

    It also happens that the device card appears but is empty — this means the device has been added but no data has been received yet. For a sensor, just wait a bit; for a switch, toggle it on or off.

    Changing friendly_name

    friendly_name is a human-readable device name. You can leave the default value or set your own:

    1. Open the configuration file for editing: 
      nano /mnt/data/root/zigbee2mqtt/data/configuration.yaml
    2. In the devices section, locate your device.
    3. Change the friendly_name.
    4. Save the configuration file and restart the service: 
      systemctl restart zigbee2mqtt
    5. A device with the chosen name should appear on the Devices tab in the standard controller web interface.
    6. Delete the card with the old name from the Devices tab by clicking the trash icon in its header.

    The new device name must meet these requirements (plus a forward slash / cannot be used), must be unique across devices, and must follow certain rules — the so-called conventions (Wiren Board MQTT Conventions).

    • Changing friendly_name

    • Device card with the default friendly_name

    • Changing friendly_name in the configuration file

    • Device card with the new friendly_name

    Controlling devices

    Direct device control via the wb-zigbee2mqtt converter is not yet implemented, but you can control devices using the standard zigbee2mqtt tools through wb-rules, sending commands via the publish function.

    In other words, instead of the wb-rules pattern you might expect: 

    dev["friendly_name/control_name"] = "OFF"

    the script needs to do: 

    publish("zigbee2mqtt/friendly_name/set", JSON.stringify({ control_name: "OFF" }), 2, false);

    Here is an example of turning a relay with friendly_name equal to 0x00158d0001f3fc34 on and off in wb-rules: 

     publish("zigbee2mqtt/0x00158d0001f3fc34/set", JSON.stringify({ state: "ON" }), 2, false);
 publish("zigbee2mqtt/0x00158d0001f3fc34/set", JSON.stringify({ state: "OFF" }), 2, false);

    If wb-rules feels too complex, you can always use the Node-RED visual automation editor.

    Removing devices

    To remove a device:

    1. Make sure the Permit join switch in the Zigbee2mqtt device card is set to OFF.
    2. Unpair the device from the coordinator. This usually requires holding the pairing button for 5 seconds — see the device documentation.
    3. Wait for the left_network message to appear in the Log field of the Zigbee2mqtt card.
    4. Delete this Zigbee device card from the web interface: hover over the card header and click the trash icon.
    5. Connect to the controller via SSH and restart wb-rules — this restarts the wb-zigbee2mqtt converter: 
      systemctl restart wb-rules

    • The left_network message

    • Trash icon for deleting a Zigbee device card

    How to reinstall while preserving data

    In some cases you may need to reinstall the converter while preserving data — for example, if the bridge fails to start after an update.

    Procedure:

    1. Go to the home directory: 
      cd ~
    2. Back up the settings: 
      cp -R /mnt/data/root/zigbee2mqtt/data data-backup
    3. Remove zigbee2mqtt: 
      apt purge zigbee2mqtt
    4. If a node-modules directory remains, remove it: 
      rm -r /mnt/data/root/zigbee2mqtt/node_modules
    5. Reinstall zigbee2mqtt: 
      apt install zigbee2mqtt
    6. Restore the settings from the backup: 
      cp -R data-backup/* /mnt/data/root/zigbee2mqtt/data
    7. Restart the service: 
      systemctl restart zigbee2mqtt

    wb-mqtt-zigbee converter

    Description

    Zigbee device on the Devices tab — the header shows the friendly_name

    wb-mqtt-zigbee is a new converter from zigbee2mqtt data into virtual-device topics. It displays Zigbee devices in the Wiren Board controller web interface and lets you control them.

    How it works

    Zigbee2mqtt connects to the Zigbee coordinator, discovers devices, and publishes all information to the MQTT broker. The topic namespace is configured in the zigbee2mqtt config (`/mnt/data/root/zigbee2mqtt/data/configuration.yaml`, parameter `base_topic`), defaulting to `zigbee2mqtt`. The converter then:

    1. Subscribes to `zigbee2mqtt/` topics and receives the bridge state, device list, logs and events.
    2. Creates virtual WB devices under `/devices/` — publishing metadata (`/meta`) and control values per the WB MQTT Conventions.
    3. Translates commands back — when the user picks a value from a dropdown, moves a slider or uses a switch in the controller web interface, the service receives the command from `/devices/.../on` and publishes the corresponding request to `zigbee2mqtt/bridge/request/...`.

    The diagram below shows data flow through the MQTT broker (mosquitto): on the left — the zigbee2mqtt topic namespace; on the right — the Wiren Board controller namespace. Arrows are bidirectional: device states flow left-to-right, commands right-to-left.

    Data processing diagram for the wb-mqtt-zigbee converter

    Installation

    Warning: installing the new converter may break user wb-rules scripts, especially those that relied on the string value ON while the new switch now uses the boolean 1. wb-mqtt-zigbee is installed automatically when the zigbee2mqtt package is installed, provided wb-zigbee2mqtt was not previously installed. Otherwise install it with the command: 

    apt update && apt install wb-mqtt-zigbee

    After this, a Zigbee2MQTT device will appear in the standard controller web interface on the Devices tab.

    Adding devices

    Adding a device — last added '0xa4c1385da71ff53c'

    You can add devices one at a time or all at once. To add new devices:

    1. Open the Devices tab in the controller web interface.
    2. Find the Zigbee2MQTT device widget and check the State field — it should read online. If you have only just installed zigbee2mqtt, wait a couple of minutes.
    3. Enable the Permit join switch.
    4. Follow the instructions for the Zigbee device: typically you need to hold the pair button on the device for a few seconds and wait for the indicator to start blinking.
    5. As the device is being added, the Last paired field of the Zigbee2MQTT widget will display the device's IEEE address (e.g. 0xa4c1385da71ff53c), and the device count will increase by 1 for each added device.
    6. Repeat steps 5 and 6 for each Zigbee device you have.
    7. Finish adding devices by disabling the Permit join switch.

    Changing friendly_name

    friendly_name is a user-defined device name. You can leave the default value or set your own:

    1. Open the configuration file for editing: 
      nano /mnt/data/root/zigbee2mqtt/data/configuration.yaml
    2. In the devices section, locate your device.
    3. Change the friendly_name.
    4. Save the configuration file and restart the service: 
      systemctl restart zigbee2mqtt
    5. A device with the chosen name should appear on the Devices tab.
    6. Delete the widget with the old name by clicking the trash icon in its header.

    The new name must be unique per device, must not contain a forward slash /, and must meet the parameter requirements and the Wiren Board MQTT Conventions.

    • Changing friendly_name

    • Device widget with the default friendly_name

    • Changing friendly_name in the configuration file

    • Device widget with the new friendly_name

    Controlling a device

    Example controls for managing a device — switch and dropdown

    Standard controls are used to manage a device: switches or dropdown lists.

    Removing devices

    1. Make sure the Permit join switch in the Zigbee2MQTT widget is off.
    2. Unpair the device from the coordinator. This usually requires holding the pairing button for 5 seconds — see the device documentation.
    3. Wait for the name of the removed device to appear in the Last removed field of the Zigbee2MQTT widget.
    4. Delete the widget of the disconnected Zigbee device from the web interface by clicking the trash icon in the widget header.

    • Last removed device

    • Deleting a Zigbee device widget

    Troubleshooting

    If you encounter issues with zigbee2mqtt, checking the service status and reading detailed logs will help clarify the situation. To run the commands, connect to the controller via SSH.

    You can view the current status and the last few log messages with the command: 

    # 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'.
    Example of zigbee2mqtt start-up problems with the npm start command
    Example of a successful zigbee2mqtt start with the npm start command

    It often happens that we can see from the previous step that there is a problem, but the cause is unclear — in that case we need to look at the logs:

    1. Stop the service: 
      systemctl stop zigbee2mqtt
    2. Go to the zigbee2mqtt directory: 
      cd /mnt/data/root/zigbee2mqtt/
    3. Start zigbee2mqtt in manual mode with all output to the console using the npm start command: 
      # 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
      here you can immediately see that we specified the wrong port in the settings.
    4. Once you have found and fixed the problem, start the service again: 
      systemctl start zigbee2mqtt

    If npm start launches the service successfully, you can stop it by pressing Ctrl+C.

    Sometimes you may need to disable service auto-start; auto-start can be controlled with the commands: 

    systemctl disable zigbee2mqtt
systemctl enable zigbee2mqtt

    Troubleshooting

    1.18.1 does not start after update

    You see something like this in the console: 

    Zigbee2MQTT version 1.18.1.
Doesn't like the node version. Zigbee2MQTT requires node version ^10  ^12  ^14 |
| ^15 || ^16, you are running v20.5.1!

    Install the previous nodejs package version: 

    apt install nodejs=16.20.2-deb-1nodesource1

    zigbee2mqtt complains about the module

    Here you need to figure out whether the problem is in zigbee2mqtt, the configuration, or the module.

    First, check that the module is correctly configured — see the extension module documentation.

    If the configuration looks fine, you can test the module with the third-party script check-cc2652p:

    1. Download the module per the instructions in the repository.
    2. Stop zigbee2mqtt: 
      systemctl stop zigbee2mqtt
    3. Run the command, replacing the port with your own: 
      python3 ./check_cc2652p.py /dev/ttyMOD4

    If you get firmware and module version messages back, the module is working and the problem is in zigbee2mqtt: a wrong port was specified or something is broken.

    Example of successful output: 

    # 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

    Issue updating zigbee2mqtt to 2.1.1

    If, when updating zigbee2mqtt to 2.1.1, you run into the package failing to start with symptoms like this: 

    > 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)

    then the recommended fix is:

    1. Make a backup of the configuration.yaml file.
    2. Remove the current version: apt remove zigbee2mqtt
    3. In configuration.yaml, add the adapter type adapter to the serial section. Example for our module: 
      serial:
  port: /dev/ttyMOD1
  adapter: zstack
    4. Reinstall the package: apt update && apt install zigbee2mqtt

    Configuration file accidentally replaced when updating zigbee2mqtt to 2.1.1

    When updating zigbee2mqtt to 2.1.1 from an earlier version, the system asks whether to install the new config file or keep the old one: 

    Configuration file '/mnt/data/root/zigbee2mqtt/data/configuration.yaml'
 ==> Modified (by you or by a script) since installation.
 ==> Package distributor has shipped an updated version.
   What would you like to do about it ?  Your options are:
    Y or I  : install the package maintainer's version
    N or O  : keep your currently-installed version
      D     : show the differences between the versions
      Z     : start a shell to examine the situation
 The default action is to keep your current version.
*** configuration.yaml (Y/I/N/O/D/Z) [default=N] ? y

    If you accidentally chose to replace the file and run into a zigbee2mqtt startup problem like this: 

    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

    then, to restore zigbee2mqtt and recover the deleted configuration:

    • Do not delete the ~/zigbee2mqtt/data/coordinator_backup.json file. Removing it will force you to re-pair all devices.
    • Stop the service with systemctl stop zigbee2mqtt
    • Back up the existing config:
      cp ~/zigbee2mqtt/data/configuration.yaml ~/zigbee2mqtt/data/configuration.yaml-wb-backup
    • Restore the previous config:
      cp ~/zigbee2mqtt/data/configuration.yaml.dpkg-old ~/zigbee2mqtt/data/configuration.yaml
    • Verify that the adapter type is specified in the file — there should be a line adapter: zstack; if not, add it to the serial section.
    • Restart the service: systemctl restart zigbee2mqtt

    As a result, zigbee2mqtt should start with the configuration that was in place before the update.

    Archive of all versions (Pool)

    This is where every z2m package is stored (both testing and release builds). The main value of this section is the publication date, which is absent from the regular repository. It helps pinpoint exactly when a bug or feature entered the system.

    All z2m packages

    History of a specific version (e.g. 2.1.1)

    Why: incident analysis and finding the release date of a specific build.

    Official release (Packages)

    This is the "allow-list" of what the controller (e.g. WB7) sees via apt update. A package only enters this list after testing and official release tagging (e.g. branch 2507).

    List for WB7 (release 2507)

    Why: verifying which z2m version is currently available for a clean install or upgrade on a user's controller.

    Useful links

    Retrieved from "https://wiki.wirenboard.com/wiki/index.php?title=Zigbee/en&oldid=98180"