Установка Zigbee2MQTT в Linux

Предупреждение

При работе с Home Assistant supervised или HassOS вместо описанного ниже способа установки желательно использовать аддон HassIO Zigbee2MQTT Addon.

Данный вариант установки предназначен для установки сервиса Zigbee2MQTT на компьютере или на контроллерах JetHome JetHub. Актуальная инструкция по установки Zigbee2MQTT на компьютере с Linux находится на странице проекта Zigbee2MQTT Linux installation guide

Установка

Для работы Zigbee2MQTT необходимо предварительно установить MQTT брокер, например mosquitto:

sudo apt install -y mosquitto mosquitto-clients

При установке MQTT брокер будет настроен на автоматический запуск и запущен. Проверить статус службы можно командой:

sudo systemctl status mosquitto.service

Для работы Zigbee2MQTT необходим node.js версии не ниже 20.x. Установите также дополнительные пакеты, необходимые для сборки:

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

Загрузите исходные тексты Zigbee2MQTT:

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

Сборка:

cd /opt/zigbee2mqtt
npm ci

Внести изменения в файл конфигурации:

nano /opt/zigbee2mqtt/data/configuration.yaml

Примерное содержимое файла конфигурации:

# 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

Примечание

В примере приведено название порта для контроллера JetHub H1 (/dev/ttyAML2) для других контроллеров или USB-стиков название порта может быть другим (см. документацию к вашему устройству).
Приведены значения pan_id и network_key, устанавливаемые по умолчанию. Рекомендуется задать другие значения для этих параметров.

Ручной запуск

cd /opt/zigbee2mqtt
npm start

Автоматический запуск

Для автоматического запуска Zigbee2MQTT при запуске системы необходимо создать файл:

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

Содержимое файла:

[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

где <USER> имя пользователя под которым была выполнена установка.

Активировать и запустить сервис:

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

После запуска службы, удостовериться в ее работе можно в логах:

sudo journalctl -u zigbee2mqtt.service -f

Возможные проблемы

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

Невозможно подключиться к адаптеру Zigbee (встроенный модуль Zigbee, USB-стик). Возможные причины возникновения данной ошибки:

Неправильно указан порт к которому подключен адаптер Zigbee. Укажите правильный порт для вашего устройства в файле конфигурации

Адаптер Zigbee содержит неправильную прошивку координатора или прошивка повреждена. В адаптер Zigbee необходимо записать прошивку координатора для данного устройства

Адаптер Zigbee уже используется другим приложением (например Home Assistant ZHA). Необходимо отключить другие приложения, которые могут использовать Zigbee

Error: Error while opening serialport „Error: Error: Permission denied, cannot open /dev/ttyAML2“

Для пользователя, под которым производилась установка и запуск Zigbee2MQTT, отсутствуют права доступа к последовательному порту у которому подключен адаптер Zigbee.

Необходимо включить пользователя, под которым производится запуск Zigbee2MQTT в группу dialout:

sudo gpasswd --add ${USER} dialout

После чего выйти из системы и заново зайти в нее под данным пользователем.

Примечание

Другие возможные проблемы при запуске Zigbee2MQTT и способы их решения описаны в документации проекту Zigbee2MQTT Fails to start

Полезные ссылки

Zigbee2MQTT Linux installation guide