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

Assembly:

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

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 contents of the file (where <USER> is the username under which the installation was performed):

[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

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 “127.0.0.1” in the “Address” line.

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

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

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.