Как настроить adapter в Zigbee2MQTT и запустить сеть после обновления координатора

Если Zigbee2MQTT перестал стартовать после прошивки/замены стика, почти всегда причина в трёх вещах: не тот порт, не тот serial.adapter (zstack vs ember/ezsp) или рассинхрон сети/бэкапа. Ниже — порядок действий, который обычно возвращает запуск за 10–15 минут.

Главное правило: сначала фиксируем порт по by-id, затем явно задаём adapter, и только потом разбираемся с сетью (PAN ID/KEY/backup).

Оглавление

1) Быстрая диагностика: порт, права, конфликт за UART

  1. Найдите стабильный порт (лучше, чем /dev/ttyUSB0//dev/ttyACM0):
ls -l /dev/serial/by-id

  1. Проверьте, что порт не занят другим Zigbee-стеком/сервисом (ZHA, другой контейнер, minicom/screen). Симптомы — Cannot lock port, таймауты, падения при старте.

  2. Проверьте права на устройство (если Zigbee2MQTT не в root): контейнеру/пользователю должен быть доступен /dev/serial/....

  3. Уточните UART-параметры:

  • типично baudrate: 115200;
  • для многих Silicon Labs координаторов полезно/нужно rtscts: true.

2) Как выбрать adapter: zstack, ember или ezsp

Ориентируйтесь на чип и прошивку координатора:

  • TI CC2652/CC1352/CC2538 → почти всегда adapter: zstack.
  • Silicon Labs EFR32 (например, Dongle‑E, SkyConnect/Connect-подобные) → чаще adapter: ember.
  • Silicon Labs на старых/других NCP-прошивках → иногда нужен adapter: ezsp.

После обновления прошивки Silicon Labs может измениться «язык» NCP: раньше работало с ezsp, а после обновления требуется ember. Если видите ошибки слоя EZSP или HOST_FATAL_ERROR, первым делом проверьте именно это.

3) Рабочие примеры configuration.yaml

TI (zStack)

mqtt:
  server: "mqtt://localhost"

serial:
  port: /dev/serial/by-id/usb-...TI...
  adapter: zstack

Silicon Labs (EmberZNet) — частый вариант после обновлений

serial:
  port: /dev/serial/by-id/usb-...Silicon_Labs...
  adapter: ember
  baudrate: 115200
  rtscts: true

Silicon Labs (EZSP) — если вы точно знаете, что прошивка под EZSP

serial:
  port: /dev/serial/by-id/usb-...Silicon_Labs...
  adapter: ezsp
  baudrate: 115200
  rtscts: false

Короткая памятка по выбору adapter

КоординаторПризнакserial.adapter
TI CC2652/CC1352Dongle‑P и аналоги на TIzstack
Silicon Labs EFR32большинство актуальных NCPember
Silicon Labs EFR32 (другая NCP-прошивка)раньше работало только такezsp

4) Ошибки запуска после обновления и что делать

No valid USB adapter found

Обычно автодетект не сработал или порт «прыгает».

  • Укажите порт через /dev/serial/by-id/...
  • Явно пропишите serial.adapter.

SRSP - SYS - ping after 6000ms (часто TI)

Zigbee2MQTT не может поговорить с координатором.

  • проверьте, что выбран правильный /dev/serial/by-id/...;
  • убедитесь, что порт не занят другим сервисом;
  • проверьте, что прошивка именно координатора, а не роутера.

HOST_FATAL_ERROR / Failed to start EZSP layer

Почти всегда одно из:

  • неверный adapter (попробуйте ember ↔ ezsp);
  • неверные rtscts/baudrate;
  • порт занят или недоступен по правам.

NCP EZSP protocol version ... does not match Host version ...

Несовместимость версии протокола между Zigbee2MQTT и прошивкой координатора.

  • Самый быстрый путь: привести к совместимой паре прошивка ↔ adapter (часто помогает переход на ember после обновления NCP).
  • Если обновляли сразу и Zigbee2MQTT, и прошивку — временно откатите одно из изменений, чтобы проверить связку.

Восстановление сети и coordinator-backup

Ошибка вида startup failed - configuration-adapter mismatch означает, что параметры сети в Zigbee2MQTT и в координаторе/бэкапе не совпадают (PAN ID, extended PAN ID, network key).

Выберите стратегию:

  1. Сохранить старую сеть
    Верните в configuration.yaml те значения сети, которые соответствуют текущему состоянию координатора/бэкапа (сверяйте по логам и вашим сохранённым параметрам).

  2. Создать сеть заново (быстрее, но потребует переподключений)
    Удалите/переименуйте файл бэкапа координатора в папке data/ (часто это coordinator-backup.json) и запустите Zigbee2MQTT, затем заново присоединяйте устройства.

Сброс сети почти всегда означает повторное спаривание части устройств (иногда всех), особенно батарейных.

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

  • Указывают /dev/ttyUSB0, после перезагрузки он становится другим → используйте /dev/serial/by-id.
  • Меняют прошивку Silicon Labs и забывают переключить ezsp на ember (или наоборот).
  • Держат один и тот же стик одновременно в ZHA и Zigbee2MQTT → получаются Cannot lock port и таймауты.
  • Включают rtscts: true на железе/прошивке, где это не нужно (или наоборот не включают там, где нужно) → нестабильный старт.

FAQ

Нужно ли трогать baudrate?
Только если ваш координатор прошит под нестандартную скорость. В большинстве случаев достаточно 115200.

Можно ли просто заменить координатор и ничего не переподключать?
Иногда да, если корректно перенести/восстановить параметры сети и бэкап координатора. Если получаете configuration-adapter mismatch, сеть не совпадает.

Что сначала: обновлять Zigbee2MQTT или прошивку стика?
Практичнее обновлять по одному шагу и проверять запуск. Если обновили оба сразу и получили EZSP version mismatch, сложнее понять, что именно несовместимо.