Warning Cookies are used on this site to provide the best user experience. If you continue, we assume that you agree to receive cookies from this site. OK

Installing Zigbee2MQTT in Armbian

When working with Home Assistant supervised or HassOS, instead of the installation method described below, it is advisable to use the hassio-zigbee2mqtt addon

This installation option is designed to install the zigbee2mqtt service on a computer or on JetHub H1/D1 controllers.

For zigbee2mqtt to work, you must first install an MQTT broker, for example mosquitto:

 sudo apt install -y mosquitto mosquitto-clients

When installing MQTT, the broker will be configured to start automatically and start. You can check the service status with the command:

 sudo systemctl status mosquitto.service

Install additional packages required to build zigbee2mqtt:

 sudo apt-get install -y nodejs npm git make gcc g++

Download zigbee2mqtt sources:

 sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
sudo chown -R $USER:$USER /opt/zigbee2mqtt


 cd /opt/zigbee2mqtt
npm ci

Make changes to the configuration file:

 nano /opt/zigbee2mqtt/data/configuration.yaml

Sample contents of the configuration file:

 # Home Assistant integration (MQTT discovery)
homeassistant: true

# Allow new devices to join
permit_join: false

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

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

# optional: advanced settings
  # 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]

  # Optional, default 8080
  port: 8080
  # Optional, default

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 the documentation for the controller).

Translated default pan_id and network_key values. It is recommended to set other values for these parameters.

Run zigbee2mqtt:

 cd /opt/zigbee2mqtt
npm start

To automatically start zigbee2mqtt at system startup, you need to create a file:

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

The content of the file (where - the username under which the installation was performed):


ExecStart=/usr/bin/npm start


Activate and start the zigbee2mqtt service:

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

After starting the service, you can verify its operation in the logs:

 sudo journalctl -u zigbee2mqtt.service -f

MQTT integration must be included in the Home Assistant configuration file. This can be done in two ways:

1. (Recommended) In the Home Assistant web interface, select the "Integrations" menu, click the "Add" button, and select the "MQTT" integration from the list. When prompted for integration settings, enter "" in the "Address" line.

2. Add the following parameters to the Home Assistant configuration file:

  discovery: true
  broker: localhost
    topic: 'hass/status'
    payload: 'online'
    topic: 'hass/status'
    payload: 'offline'

Possible problems

No permissions to access the serial port

If an error occurs during startup:

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

It is necessary to include the user under which Zigbee2MQTT is launched into the dialout group:

 sudo gpasswd --add ${USER} dialout

Then log out of the system and log in again under this user.