Zigbee2MQTT не запускается: не указан тип адаптера

Zigbee2MQTT не запускается, когда тип Zigbee-адаптера не задан в секции serial или задан неверно. Обычно помогает одно из двух: прописать в configuration.yaml правильное значение adapter - zstack для донглов на чипе CC2652, ember для донглов Silicon Labs - или прошить донгл обычной Zigbee-прошивкой NCP, если на нем стоит мультипротокольная прошивка Zigbee и Thread.

Как выглядит проблема

Аддон Zigbee2MQTT (дополнение Home Assistant) не запускается, а внятного текста ошибки в логе может не быть - в одной из веток пользователь показал ошибку только скриншотом. В ветках форума проблема выглядела по-разному.

• Zigbee2MQTT не стартует с Sonoff Zigbee 3.0 USB Dongle Plus, ошибка видна только на скриншоте.
• Аддон с донглом Sonoff ZBDongle-E не работает, при настройке MQTT появляется ошибка.
• Аддон перестает запускаться после месяцев нормальной работы.
• Аддон не запускается, хотя MQTT-брокер работает нормально.
• После обновления Zigbee2MQTT не стартует, а в конфигурации serial не задан adapter: zstack.
• После обновления аддона с 1.41.0-1 до 2.4.0-1 веб-интерфейс Z2M останавливается сразу, и SLZB-06 не подключается.
• Мастер первоначальной настройки (onboarding) подставляет zstack вместо ezsp (так раньше называли значение для донглов Silicon Labs, сейчас это ember) для Sonoff ZBDongle-E, и аддон не запускается.

Отдельная страница посвящена onboarding Zigbee2MQTT с недоступными полями.

Причины

Дело обычно в одном из четырех: прошивка донгла, которую Zigbee2MQTT не принимает, отсутствующий ключ adapter, конфликт ручной секции serial с настройками аддона или неверное значение adapter.

Причина	Как проверить	Что сделать
На донгле прошивка, которую Zigbee2MQTT не принимает: MultiPAN или мультипротокольная Zigbee и Thread	Проверить, какая прошивка залита на донгл	Прошить донгл Silicon Labs прошивкой NCP Zigbee вместо MultiPAN
В секции serial нет ключа adapter, а донглу на чипе CC2652 нужен adapter: zstack	Открыть секцию serial в configuration.yaml и посмотреть, задан ли adapter	Добавить adapter: zstack
Секция serial, вписанная в конфиг вручную, конфликтует с настройками аддона	Проверить, не задан ли адаптер и в опциях аддона, и в ручной секции serial	Убрать ручную секцию serial и задать адаптер в настройках аддона
adapter задан неверным значением: ZSTACK вместо EZSP (ezsp - старое название, сейчас ember)	Сверить значение adapter с типом донгла	Поставить значение, соответствующее донглу; для Silicon Labs сейчас это ember, раньше писали ezsp

Первые две причины встретились в двух ветках форума каждая (вторая прямо названа в одной из них), третья и четвертая - в одной.

Решения

В ветках проблема уходила после правильного значения adapter в секции serial либо после прошивки донгла обычной Zigbee-прошивкой.

Прошить донгл прошивкой NCP вместо MultiPAN

Это опыт пользователей. Если на донгле Silicon Labs стоит прошивка MultiPAN или мультипротокольная прошивка Zigbee и Thread, Zigbee2MQTT с ней не работает: донгл прошивают прошивкой NCP Zigbee. Это сработало в 2 ветках форума из 2, где его пробовали; один из отчетов описывает лишь частичный результат. Прошивки собирает инструмент silabs-firmware-builder, сборки для Sonoff ZBDongle-E лежат в его репозитории. В одной ветке после прошивки дополнительно задали адаптер:

port: {the id of the SonOff ZBDongle-E}.
adapter: ember

Строку port замените на реальный идентификатор вашего донгла.

Добавить adapter: ezsp (устаревший способ)

В двух ветках в секцию serial файла configuration.yaml добавляли строку adapter: ezsp. Это сработало в 1 ветке из 2, где его пробовали, во второй не помогло. Способ устарел: в документации Zigbee2MQTT этого значения в списке нет - Possible adapters are zstack , ember , deconz , zigate or zboss .

Добавить adapter: zstack

Этот вариант подтвержден документацией: zstack входит в список допустимых значений адаптера. Помогло в 1 ветке форума из 2, где его пробовали; результат во второй ветке неизвестен. Для донглов на чипе CC2652 значение задают в секции serial файла configuration.yaml:

serial:
  adapter: zstack
  port: >
    /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_feb48308ed12ec11a00521c7bd930c07-if00-port0

После правки конфигурации перезапустите аддон.

Убрать ручную секцию serial из конфигурации аддона

В одном случае аддон не запускался, потому что секция serial, вписанная в конфигурацию вручную, конфликтовала с настройками аддона. Помогло удаление этой секции - в ней был фрагмент вида

port: >-
  /dev/...
adapter: ezsp

После удаления адаптер задали в настройках самого аддона. Сработало в 1 ветке из 1. У способа две оговорки. Значение ezsp устарело (для Silicon Labs сейчас ember) и в списке допустимых значений документации отсутствует, а интерфейс настроек аддона в документации не описан, так что способ опирается на опыт форума.

Откатить аддон к версии 1.41.0-1

В одной ветке аддон перестал запускаться после перехода с 1.41.0-1 на 2.4.0-1. Одному пользователю после отката к 1.41.0-1 аддон снова заработал. Это опыт форума, в документации такой рекомендации нет.

Если не помогло

Остался один способ, который не сработал, и три непроверенных варианта.

Выбор ezsp (устаревшее значение, сейчас ember) на странице onboarding в одной ветке не помог: мастер настройки сам подставлял zstack для Sonoff ZBDongle-E.

Непроверенные варианты - их предлагали, но отчетов о результате нет.

• adapter: ember в секции serial. Значение допустимо по документации, но в двух ветках, где его упоминали, результата нет.
• Отключить интеграцию ZHA, если она настроена на тот же донгл. Документация Zigbee2MQTT советует: Try to disable the ZHA integration and restart the Zigbee2MQTT add-on.
• Указать порт через /dev/serial/by-id вместо /dev/ttyACM0.

Если вместо молчаливого отказа при старте вы видите сообщение Failed to connect to the adapter, посмотрите разбор ошибки Failed to connect to the adapter в Zigbee2MQTT.

Базовую настройку аддона удобно сверять с инструкцией по установке и настройке Zigbee2MQTT в Home Assistant.

Частые вопросы

Какие значения adapter допустимы?

Допустимы пять значений: zstack, ember, deconz, zigate и zboss. Такой список приводит документация Zigbee2MQTT по настройке адаптера. Значение ezsp, которое встречается в старых конфигах и ветках форума, в этом списке не числится - для донглов Silicon Labs теперь используется ember. Донглам на чипе CC2652 нужен zstack, поэтому перед правкой конфигурации сверьте модель донгла.

Какой adapter нужен Sonoff ZBDongle-E?

Для ZBDongle-E значение zstack неверно: это донгл Silicon Labs. В старых версиях для него писали ezsp, сейчас по документации используется ember. Отдельное условие - прошивка: донгл должен работать на обычной Zigbee-прошивке NCP, а мультипротокольная прошивка Zigbee и Thread для Zigbee2MQTT не годится. Если после исправления adapter аддон все равно не стартует, проверьте прошивку донгла.

Может ли ZHA мешать запуску Zigbee2MQTT?

Возможно, если ZHA и Zigbee2MQTT настроены на один и тот же донгл. Документация Zigbee2MQTT советует отключить интеграцию ZHA и перезапустить аддон. В одной из веток форума этот вариант предлагали, но отчета о результате нет.

Как правильно указать порт адаптера?

Документация Zigbee2MQTT рекомендует путь /dev/serial/by-id для USB-адаптеров. На Linux список таких путей выводит команда ls -l /dev/serial/by-id, полученное значение подставляют в параметр port секции serial. Путь /dev/ttyACM0 в конфигах тоже встречается, но в ветках форума при проблемах со стартом советовали перейти на by-id. Отчета о результате этого перехода нет.

Стоит ли откатывать аддон на старую версию?

Одному пользователю это помогло. В одной ветке откат с 2.4.0-1 к 1.41.0-1 вернул аддону работоспособность - это опыт одного пользователя, в документации такой рекомендации нет. Перед откатом проверьте значение adapter в секции serial - возможно, дело именно в нем.