Настройка ZBDongle‑E в Docker/Proxmox/HA OS: правильный порт, проброс USB и типовые ошибки

Чтобы ZBDongle‑E заработал, обычно не нужны “отдельные драйверы”: в Linux он поднимается как CDC ACM (/dev/ttyACM*). Главные задачи — взять стабильный порт /dev/serial/by-id/..., корректно пробросить USB в Docker/VM/LXC и в Zigbee2MQTT выбрать adapter: ember (и не включать rtscts).

Оглавление

Как убедиться, что донгл виден в Linux

Подключите ZBDongle‑E к той машине, где он физически стоит (Proxmox‑хост или Linux с Docker), и проверьте:

ls -l /dev/serial/by-id
ls -l /dev/ttyACM*
dmesg | tail -n 80

Нормальная ситуация: есть симлинк вида /dev/serial/by-id/... -> ../../ttyACM0.

Для конфигов всегда выбирайте /dev/serial/by-id/..., а не /dev/ttyACM0: так устройство не “переедет” на другой номер после перезагрузки/переподключения.

Docker: доступ к USB для Zigbee2MQTT

Самый надёжный способ — пробросить конкретный by-id внутрь контейнера.

docker-compose.yml (фрагмент):

services:
  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    devices:
      - /dev/serial/by-id/usb-ITEAD_SONOFF_XXXXXXXX-if00:/dev/ttyZigbee

Zigbee2MQTT configuration.yaml (фрагмент):

serial:
  port: /dev/ttyZigbee
  adapter: ember
  rtscts: false
  baudrate: 115200

ZBDongle‑E обычно не требует аппаратного flow control. Если включить rtscts: true, можно получить нестабильность или “Failure to connect”.

Proxmox и Home Assistant OS: VM или LXC

Сначала решите, где будет работать Zigbee2MQTT:

  • HA OS в VM (а Zigbee2MQTT — аддоном/контейнером внутри HA) → пробрасывайте донгл в VM.
  • Zigbee2MQTT в LXC на Proxmox → пробрасывайте донгл в LXC.

Один USB‑донгл нельзя одновременно “раздать” в два места. Если он занят ZHA или второй копией Zigbee2MQTT — будет ошибка подключения.

Вариант A: HA OS в VM (рекомендуемо для новичков)

  1. Proxmox → VM → Hardware → Add → USB Device (выберите донгл по устройству/ID).
  2. В Home Assistant проверьте, что появился /dev/serial/by-id/....
  3. В Zigbee2MQTT укажите serial.port на /dev/serial/by-id/... и adapter: ember.

Вариант B: LXC (Zigbee2MQTT в контейнере Proxmox)

В конфиг контейнера добавьте разрешение на символьные устройства и bind‑mount:

# /etc/pve/lxc/<CTID>.conf
lxc.cgroup2.devices.allow: c 166:* rwm
lxc.mount.entry: /dev/ttyACM0 dev/ttyACM0 none bind,optional,create=file
lxc.mount.entry: /dev/serial/by-id dev/serial/by-id none bind,optional,create=dir

Внутри LXC проверьте:

ls -l /dev/ttyACM0
ls -l /dev/serial/by-id

Если by-id внутри пустой — временно используйте /dev/ttyACM0, но лучше довести проброс by-id до рабочего состояния.

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

  • Выбран не тот порт: указали /dev/ttyACM0, а после перезагрузки стал /dev/ttyACM1. Решение: перейти на /dev/serial/by-id/....
  • Неверный адаптер в Zigbee2MQTT: для ZBDongle‑E обычно нужен adapter: ember. Если оставить другой — возможны ошибки и зависания старта.
  • Конфликт ZHA и Zigbee2MQTT: оба пытаются открыть один и тот же донгл. Решение: остановить/удалить один из вариантов и оставить только один стек.
  • Нет доступа к устройству в контейнере: USB не проброшен или не разрешён cgroup’ом. Решение: проверить devices: (Docker) или lxc.cgroup2.devices.allow + bind‑mount (LXC).
  • Включили rtscts: ухудшение связи/подключения. Решение: rtscts: false.

FAQ

Нужно ли ставить драйвер для ZBDongle‑E в Linux?
Обычно нет: он определяется как cdc_acm и появляется как /dev/ttyACM*.

Почему внутри контейнера нет /dev/serial/by-id?
Потому что это не “порт”, а каталог с симлинками. Его нужно пробрасывать/монтировать внутрь контейнера отдельно (или использовать /dev/ttyACM0 временно).

Что выбрать: ZHA или Zigbee2MQTT?
Выбирайте один вариант. Для Zigbee2MQTT чаще всего достаточно adapter: ember, правильного порта и отсутствия конфликтов.

Можно ли пробросить донгл одновременно в HA VM и LXC?
Надёжно — нет. Он должен быть подключён только к одному окружению, иначе получите “Failure to connect” и гонку за порт.