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 addon hassio-zigbee2mqtt ">hassio-zigbee2mqtt

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

For work Zigbee2MQTT 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 launched. You can check the status of the service with the command:

sudo systemctl status mosquitto.service

Node.js version 14.x or later is required for Zigbee2MQTT to work. Install additional packages required to build Zigbee2MQTT:

sudo curl -fsSL | sudo  -E bash -
sudo apt-get install -y nodejs npm git make gcc g++

Download the Zigbee2MQTT sources:

sudo mkdir /opt/ zigbee2mqtt
sudo chown -R $USER:$USER /opt/zigbee2mqtt
git clone --depth 1 /opt/zigbee2mqtt


cd /opt/zigbee2mqtt
npm ci

Change configuration file:

nano /opt/zigbee2mqtt/data/configuration.yaml

Example file contents configuration:

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

Default values pan_id and network_key are given. It is recommended to set other values for these parameters.

Running 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

File content (where is the username under which the installation was performed):


ExecStart=/usr/bin/npm start


Enable 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 needs to 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

After Why log out and log back in as the given user.