Первый запуск Zigbee2MQTT: установка и подключение первого устройства

Чтобы настроить Zigbee2MQTT с нуля, установите MQTT‑брокер и Zigbee2MQTT (проще всего через Docker Compose), укажите правильный serial.port и serial.adapter в configuration.yaml, запустите контейнеры и включите Permit join для добавления первого Zigbee‑устройства.

Что нужно перед стартом

Минимальный набор:

• Linux‑хост 24/7 (мини‑ПК/сервер/Raspberry Pi/VM).
• Zigbee‑координатор (USB или LAN).
• Желательно USB‑удлинитель 0,5–1 м, чтобы убрать координатор подальше от помех (особенно рядом с USB 3.0).

Ключевой момент №1 — стабильный путь к порту. Узнайте его так:

ls -l /dev/serial/by-id

Дальше используйте именно /dev/serial/by-id/..., а не ttyUSB0/ttyACM0 (они могут меняться после перезагрузок).

Ключевой момент №2 — правильный serial.adapter. Быстрая шпаргалка:

Как выбрать serial.adapter по координатору

Установка Mosquitto и Zigbee2MQTT через Docker Compose

Создайте рабочую папку:

mkdir -p ~/smarthome/z2m/{zigbee2mqtt-data,mosquitto/config,mosquitto/data,mosquitto/log}
cd ~/smarthome/z2m

1) Mosquitto: минимальный конфиг с паролем

Файл mosquitto/config/mosquitto.conf:

persistence true
persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log

listener 1883 0.0.0.0

allow_anonymous false
password_file /mosquitto/config/passwordfile

2) Docker Compose

Файл docker-compose.yml:

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

  zigbee2mqtt:
    image: ghcr.io/koenkk/zigbee2mqtt
    container_name: zigbee2mqtt
    restart: unless-stopped
    depends_on:
      - mosquitto
    ports:
      - "8080:8080"
    environment:
      - TZ=Europe/Moscow
    volumes:
      - ./zigbee2mqtt-data:/app/data
      - /run/udev:/run/udev:ro
    devices:
      # Подставьте свой путь из /dev/serial/by-id
      - /dev/serial/by-id/PASTE_YOUR_DONGLE_ID_HERE:/dev/ttyACM0

Конфиг Zigbee2MQTT и первый запуск

1) Создайте configuration.yaml

Файл zigbee2mqtt-data/configuration.yaml:

version: 5

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mosquitto:1883
  user: z2m
  password: "CHANGE_ME"

serial:
  port: /dev/ttyACM0
  adapter: zstack   # zstack / ember / deconz

frontend:
  enabled: true

homeassistant:
  enabled: true

advanced:
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE

Если Home Assistant не нужен:

homeassistant:
  enabled: false

2) Задайте пароль MQTT пользователю

Запустите Mosquitto:

docker compose up -d mosquitto

Создайте пароль для z2m:

docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwordfile z2m

Перезапустите брокер:

docker compose restart mosquitto

3) Первый запуск и проверка

Запуск всего проекта:

docker compose up -d

Логи Zigbee2MQTT:

docker logs -f zigbee2mqtt

Признаки, что всё нормально:

• serial‑порт открылся без ошибок;
• Zigbee‑стек стартовал;
• подключение к MQTT успешно.

Веб‑интерфейс:

• http://IP_ВАШЕГО_СЕРВЕРА:8080

4) Добавьте первое Zigbee‑устройство

1. Откройте веб‑интерфейс Zigbee2MQTT.
2. Нажмите Permit join (временное разрешение на подключение).
3. Переведите устройство в режим сопряжения (обычно это сброс + удержание кнопки).
4. Дождитесь окончания интервью (в логах и в списке устройств).

Частые ошибки

• No valid USB adapter found — неверный порт, не проброшено устройство в контейнер, выбран не тот serial.adapter, или координатор занят другим сервисом.
• Zigbee2MQTT не подключается к MQTT — проверьте mqtt.server, логин/пароль и что Mosquitto слушает 0.0.0.0:1883.
• Не открывается UI на :8080 — проверьте проброс порта в compose и что контейнер не перезапускается (смотрите docker logs zigbee2mqtt).
• Устройства плохо добавляются/отваливаются — уберите координатор на удлинителе дальше от USB 3.0/роутера и не ставьте его вплотную к корпусу мини‑ПК.

FAQ

Можно ли поставить Zigbee2MQTT без Docker?
Да, но Docker проще: меньше ручных зависимостей, легче переносить и обновлять.

Что важнее всего в конфиге для старта?
Два поля: serial.port (лучше /dev/serial/by-id/...) и правильный serial.adapter.

Нужно ли менять network_key/pan_id/ext_pan_id?
Для первого запуска — нет, оставьте GENERATE. Менять их «после» нужно осознанно: часть устройств может потребовать повторного подключения.

Как быстро понять, что система жива?
docker compose ps (контейнеры Up), docker logs -f zigbee2mqtt (нет ошибок serial/MQTT) и открывается UI на http://<ip>:8080.