Стабильный serial‑порт для USB‑донгла в Home Assistant

Чтобы порт не “прыгал” после перезагрузки, указывайте не /dev/ttyUSB0 или /dev/ttyACM0, а стабильный путь /dev/serial/by-id/... (иногда — by-path). Это решает большинство отвалов Zigbee/Z‑Wave/USB‑UART в Home Assistant.

Какой путь выбирать: ttyUSB vs by-id vs by-path

/dev/ttyUSB0, /dev/ttyUSB1, /dev/ttyACM0 — это имена “по порядку обнаружения”. Сегодня донгл может быть ttyUSB0, завтра (после ребута, переподключения, появления второго USB‑устройства) — ttyUSB1.

/dev/serial/by-id/... — симлинк, собранный из идентификаторов USB‑устройства (модель/чип/серийник). Обычно не меняется и подходит для сценария “настроил и забыл”.

/dev/serial/by-path/... — привязка к физическому USB‑порту/топологии. Полезно, если:

• у устройства нет уникального серийника и by-id получается неуникальным;
• у вас несколько одинаковых донглов.

Быстрое сравнение

Где найти правильный порт в Home Assistant

Вариант 1 (через интерфейс):

1. Откройте Settings → System → Hardware → All hardware.
2. Найдите ваш донгл (можно поиском по tty или serial).
3. Скопируйте путь вида /dev/serial/by-id/....

Вариант 2 (через терминал в HA): Если установлен аддон Terminal & SSH, выполните:

ls -l /dev/serial/by-id

Слева будет нужный стабильный путь, справа — куда он указывает (например, ../../ttyUSB0).

Куда прописывать порт: Z-Wave JS, ZHA, Zigbee2MQTT, YAML

Z‑Wave JS

В настройках аддона/интеграции укажите Serial port / Device:

/dev/serial/by-id/usb-...-if00-port0

Zigbee (ZHA)

При добавлении координатора в поле Serial device path укажите:

/dev/serial/by-id/usb-...-if00-port0

Если ZHA уже настроена и “сломалась” из‑за смены порта — обычно достаточно заменить путь и перезапустить Home Assistant.

Zigbee2MQTT (аддон)

В configuration.yaml Zigbee2MQTT:

serial:
  port: /dev/serial/by-id/usb-...-if00-port0

Интеграции, которые читают данные с COM‑порта (YAML)

Типовой принцип тот же: вместо ttyUSB0 указывайте by-id. Пример:

sensor:
  - platform: serial
    serial_port: /dev/serial/by-id/usb-...-if00-port0
    baudrate: 9600

Home Assistant в Docker: как пробросить порт

Если Home Assistant запущен в контейнере, сам по себе путь на хосте не гарантирует, что устройство видно внутри контейнера.

Рекомендуемый вариант — пробросить конкретный by-id:

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    devices:
      - /dev/serial/by-id/usb-...-if00-port0:/dev/serial/by-id/usb-...-if00-port0
    restart: unless-stopped

Если устройств несколько, иногда пробрасывают каталог целиком:

volumes:
  - /dev/serial:/dev/serial

Но это менее “точечно” с точки зрения доступа к устройствам.

Если /dev/serial/by-id не появился: диагностика

1. Проверьте, видит ли Home Assistant донгл в Settings → System → Hardware → All hardware. Если там пусто — проблема ниже уровня интеграций (кабель, питание, хаб, проброс в VM).

2. Переподключение и другой USB‑порт. Особенно при использовании фронтальных портов, пассивных хабов и длинных кабелей.

3. Виртуализация (Proxmox/VirtualBox/ESXi). Убедитесь, что USB‑устройство проброшено именно как USB‑девайс (passthrough) и после перезагрузок хоста не “отваливается”.

4. Питание и помехи. Для Zigbee/Z‑Wave часто помогает:

• USB‑удлинитель 0,5–1 м (отнести донгл от USB3/корпуса/SSD);
• питательный (powered) USB‑хаб, если порт “проседает”.

5. by-id есть в системе, но не в выпадающем списке аддона. Это нормально: возьмите путь из Hardware/терминала и вставьте вручную в поле порта.

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

• Указать /dev/ttyUSB0, потому что “сейчас работает”, и получить отвал после ребута.
• Подключить второй USB‑Serial и не понять, почему номера ttyUSB* поменялись местами.
• Скопировать путь с лишним пробелом/переносом — порт выглядит правильно, но не открывается.
• В Docker пробросить ttyUSB0 вместо by-id: при смене номера контейнер “теряет” устройство.
• Путать by-path и by-id: by-path ломается, если переставить донгл в другой USB‑разъём.

FAQ

Можно ли поменять порт без перепривязки устройств Zigbee/Z‑Wave?
Обычно да: вы меняете только путь к тому же физическому координатору/контроллеру. Сеть и устройства остаются на месте.

Что лучше — by-id или by-path?
by-id — лучший выбор по умолчанию. by-path используйте, если by-id неуникален (например, два одинаковых адаптера без серийника) и донглы всегда стоят в фиксированных USB‑портах.

Почему by-id “пропадает” после переноса Home Assistant в VM/контейнер?
Чаще всего устройство не проброшено внутрь VM/контейнера или проброшено как “временный” ttyUSB*, который меняется. Пробрасывайте именно by-id и перепроверьте настройки passthrough/devices.