Installing Zigbee2MQTT on Linux

Warning

When working with Home Assistant supervised or HassOS, it is advisable to use the addon HassIO Zigbee2MQTT Addon instead of the installation method described below.

This installation option is for installing the Zigbee2MQTT service on a computer or on JetHome JetHub controllers. The up-to-date instructions for installing Zigbee2MQTT on a Linux computer can be found on the Zigbee2MQTT Linux installation guide project page.

Installing

To operate Zigbee2MQTT, you must first install an MQTT broker, such as mosquitto:

sudo apt install -y mosquitto mosquitto-clients

When MQTT is installed, the broker will be set to start automatically and run. You can check the status of the service with the command:

sudo systemctl status mosquitto.service

For Zigbee2MQTT to work, you need node.js version at least 20.x. Also install additional packages required for the build:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt-get update
sudo apt-get install -y nodejs git make g++ gcc

Download the source code of Zigbee2MQTT:

sudo mkdir /opt/zigbee2mqtt
sudo chown -R ${USER}: /opt/zigbee2mqtt
git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt

Assembly:

cd /opt/zigbee2mqtt
npm ci

Make changes to the configuration file:

nano /opt/zigbee2mqtt/data/configuration.yaml

Approximate contents of the configuration file:

# Home Assistant integration (MQTT discovery)
homeassistant: true

# Allow new devices to join
permit_join: false

# MQTT settings
mqtt:
  # MQTT base topic for Zigbee2MQTT MQTT messages
  base_topic: zigbee2mqtt
  # MQTT server URL
  server: 'mqtt://localhost'

# Serial settings
serial:
  # Location of CC2538 Zigbee module for JetHub H1
  port: /dev/ttyAML2

# Optional: advanced settings
advanced:
  # Optional: ZigBee channel (Note: changing requires re-pairing of all devices)
  channel: 15
  # Optional: ZigBee pan ID
  pan_id: 0x1a62
  # Optional: network encryption key, will improve security (Note: changing requires repairing of all devices)
  network_key: [1, 3, 5, 7, 9, 11, 13, 15, 0, 2, 4, 6, 8, 10, 12, 13]

frontend:
  # Optional, default 8080
  port: 8080
  # Optional, default 0.0.0.0
  host: 0.0.0.0

Note

  • The example shows the port name for the JetHub H1 controller (/dev/ttyAML2) for other controllers or USB sticks the port name may be different (see your device documentation).

  • The default values shown are pan_id and network_key. It is recommended that you set other values for these parameters.

See also

Manual start

cd /opt/zigbee2mqtt
npm start

Automatic start

To start Zigbee2MQTT automatically at system startup, a file must be created:

sudo nano /etc/systemd/system/zigbee2mqtt.service

File Contents:

[Unit]
Description=zigbee2mqtt
After=network.target

[Service]
ExecStart=/usr/bin/npm start
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=inherit
StandardError=inherit
Restart=always
User=<USER>

[Install]
WantedBy=multi-user.target

where <USER> is the user name under which the installation was performed.

Activate and run the service:

sudo systemctl enable zigbee2mqtt.service
sudo systemctl start zigbee2mqtt.service

After starting the service, you can check the logs to make sure it is working:

sudo journalctl -u zigbee2mqtt.service -f

Possible problems

Error: Failed to connect to the adapter (Error: SRSP - SYS - ping after 6000ms)

Unable to connect to a Zigbee adapter (built-in Zigbee module, USB stick). Possible reasons for this error:

  • The port to which the Zigbee adapter is connected is incorrect. Specify the correct port for your device in the configuration file

  • The Zigbee adapter contains incorrect coordinator firmware or the firmware is damaged. You need to write coordinator firmware to the Zigbee adapter for this device

  • The Zigbee adapter is already in use by another application (e.g. Home Assistant ZHA). You must disable other applications that can use Zigbee

Error: Error while opening serialport ‘Error: Error: Permission denied, cannot open /dev/ttyAML2’

The user who installed and ran Zigbee2MQTT has no access rights to the serial port where the Zigbee adapter is connected.

The user under which Zigbee2MQTT is started must be included in the dialout group:

sudo gpasswd --add ${USER} dialout

Then log out and log in again as this user.

Note

Other possible problems when starting Zigbee2MQTT and how to solve them are described in the project documentation Zigbee2MQTT Fails to start.