Просмотр кода страницы Zigbee2mqtt-connection

{{DISPLAYTITLE:Подключение Zigbee2mqtt}}
'''Zigbee2MQTT''' связывает Zigbee-координатор и устройства с XIOT-PLC через локальный MQTT-брокер. Эта инструкция описывает вариант, когда Zigbee2MQTT и XIOT-PLC работают на одном контроллере Wiren Board.

'''Результат:''' в XIOT-EDITOR открывается список устройств Zigbee2MQTT, для них создаются адреса вида <code>/z2m/...</code>, а доступные для записи контролы можно проверить из редактора и затем связать с виртуальными устройствами XIOT.

'''Сверено по опубликованным файлам:''' 13 сентября 2026 года — с публичным пакетом XIOT-PLC <code>14.1-1-1</code>, текущим интерфейсом XIOT-EDITOR и официальной инструкцией Wiren Board. Проверка на конкретном объекте всё равно обязательна.

== Как устроено подключение ==

# Zigbee-координатор обменивается данными с датчиками, кнопками и исполнительными устройствами.
# Служба <code>zigbee2mqtt</code> публикует данные в MQTT-топиках с базовым именем <code>zigbee2mqtt</code>.
# XIOT-PLC подписывается на эти топики через свой локальный MQTT-брокер <code>127.0.0.1:1887</code>.
# XIOT-EDITOR формирует отображаемый список контролов по описанию <code>definition.exposes</code> из данных моста, а XIOT-PLC обменивается значениями и командами через MQTT. Работу каждого созданного адреса нужно проверить отдельно.

Порт <code>1887</code> в штатной конфигурации XIOT доступен только локально. Поэтому приведённый ниже маршрут предполагает, что Zigbee2MQTT запущен на том же устройстве, что и XIOT-PLC.

Эта инструкция использует прямой маршрут '''Zigbee2MQTT → локальный брокер XIOT <code>127.0.0.1:1887</code>'''. Не смешивайте его со стандартной схемой Wiren Board через <code>mqtt://localhost:1883</code> и <code>wb-mqtt-zigbee</code>. После перевода Zigbee2MQTT на порт <code>1887</code> его устройства не обязаны появляться в стандартном интерфейсе Wiren Board.

== Перед началом ==

* Установите и привяжите [[XIOT-PLC]], затем убедитесь, что XIOT-EDITOR видит контроллер.
* Определите точную модель и аппаратную ревизию Zigbee-координатора. Для старых WBE2R-R-ZIGBEE могут требоваться отдельный пакет или обновление прошивки; вариант выбирают по официальной таблице Wiren Board.
* Проверьте, к какому разъёму подключён координатор. Модуль расширения обычно получает имя <code>/dev/ttyMODx</code>, USB-стик — <code>/dev/ttyUSBx</code>; вместо <code>x</code> нужен фактический номер порта.
* Если Zigbee-сеть уже использовалась, сохраните копию каталога <code>/mnt/data/root/zigbee2mqtt/data/</code>. Особенно важны <code>configuration.yaml</code> и файл резервной копии координатора.
* Выполняйте команды по SSH только из доверенной локальной сети.

Не заменяйте целиком рабочий <code>configuration.yaml</code> примером из инструкции: изменение сетевого ключа, PAN ID, канала или резервной копии координатора может потребовать повторного сопряжения всех устройств.

== Установите Zigbee2MQTT ==

Если Zigbee2MQTT уже установлен и сеть работает, сначала зафиксируйте установленную версию, проверьте совместимость координатора и сделайте резервную копию. Не запускайте установку поверх рабочей системы до этой проверки: команда может обновить уже установленный пакет.

Для актуального совместимого координатора Wiren Board установите пакет из репозитория контроллера:

<syntaxhighlight lang="bash">
apt update
apt install zigbee2mqtt
</syntaxhighlight>

Для старого WBE2R-R-ZIGBEE сначала выберите совместимую версию по [https://wiki.wirenboard.com/wiki/index.php?title=Zigbee&oldid=101964 официальной инструкции Wiren Board]. Не устанавливайте пакет для другой ревизии наугад.

После установки основной файл конфигурации находится здесь:

<syntaxhighlight lang="text">
/mnt/data/root/zigbee2mqtt/data/configuration.yaml
</syntaxhighlight>

== Настройте подключение к XIOT ==

Откройте <code>configuration.yaml</code> и проверьте только относящиеся к подключению параметры. Для модуля Wiren Board фрагмент выглядит так:

<syntaxhighlight lang="yaml">
mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://127.0.0.1:1887'
serial:
  port: /dev/ttyMODx
  adapter: zstack
</syntaxhighlight>

Замените <code>/dev/ttyMODx</code> на фактический порт. Для другого координатора значение <code>adapter</code> и параметры последовательного соединения берите из его документации и из [https://www.zigbee2mqtt.io/guide/adapters/ списка адаптеров Zigbee2MQTT].

Сохраните существующие значения <code>network_key</code>, <code>pan_id</code>, <code>ext_pan_id</code> и <code>channel</code>, если они уже созданы. Сетевой ключ и резервная копия координатора являются секретными: не публикуйте их в вики, переписке или снимках экрана.

Веб-интерфейс Zigbee2MQTT для работы XIOT не требуется. Не включайте <code>frontend</code> на <code>0.0.0.0</code> без отдельной необходимости и мер ограничения доступа.

== Перезапустите службу и проверьте её ==

<syntaxhighlight lang="bash">
systemctl restart zigbee2mqtt
systemctl status --no-pager zigbee2mqtt
</syntaxhighlight>

Перезапуск временно прерывает обмен со всей действующей Zigbee-сетью. На работающем объекте выполняйте его в согласованное окно.

Ожидаемый результат — состояние <code>active (running)</code> без повторяющегося аварийного перезапуска. Последние сообщения можно посмотреть командой:

<syntaxhighlight lang="bash">
journalctl -u zigbee2mqtt --no-pager -n 100
</syntaxhighlight>

До настройки XIOT устраните ошибки открытия последовательного порта, несовместимого адаптера и подключения к MQTT-брокеру.

После запуска убедитесь, что присоединение новых устройств выключено. В Zigbee2MQTT 1.x постоянный параметр <code>permit_join</code> должен иметь значение <code>false</code>. В Zigbee2MQTT 2.x этот параметр удалён, а XIOT открывает присоединение временным MQTT-запросом; не добавляйте <code>permit_join</code> в современный YAML без проверки версии.

== Включите драйвер в XIOT-EDITOR ==

# Откройте '''Драйверы → Zigbee2MQTT'''.
# Включите переключатель '''Активен'''.
# Нажмите '''Загрузить конфигурацию на контроллер'''. Команда сначала сохраняет проект локально и после успешной записи отправляет сохранённую конфигурацию на XIOT-PLC. Облачное сохранение и публикацию приложения проверяют отдельно: успешная загрузка на PLC их не подтверждает.
# Дождитесь статуса '''ПОДКЛЮЧЕН'''.

Отдельная команда '''Сохранить проект''' остаётся самостоятельной контрольной точкой и не загружает изменения на XIOT-PLC.

Статус '''ПОДКЛЮЧЕН''' означает, что XIOT-PLC получил успешный ответ проверки состояния от локального моста Zigbee2MQTT. Сам по себе этот статус не подтверждает связь с каждым Zigbee-устройством и не заменяет проверку реального управления и обратной связи.

== Добавьте устройства ==

# В окне Zigbee2MQTT нажмите '''Сопряжение'''. Кнопка изменится на '''Сопряжение включено'''. Текущий публичный пакет XIOT открывает присоединение не более чем на 254 секунды; если время истекло, включите его снова.
# Переведите одно устройство в режим сопряжения по инструкции его производителя.
# Нажмите '''Сканировать''', чтобы обновить в XIOT список, уже опубликованный мостом Zigbee2MQTT. Эта кнопка сама не запускает радиообнаружение устройств.
# При необходимости повторяйте обновление списка, пока интервью не завершится, затем откройте карточку найденного устройства и проверьте модель, производителя и список контролов.
# Повторите действия для остальных устройств.
# После добавления выключите сопряжение и убедитесь, что кнопка снова называется '''Сопряжение'''. Не оставляйте присоединение новых устройств разрешённым постоянно.

Поддержка конкретной модели зависит от установленной версии Zigbee2MQTT. Сверяйтесь с [https://www.zigbee2mqtt.io/supported-devices/ официальным списком поддерживаемых устройств] и проверяйте, относится ли найденная информация к вашей установленной версии: текущий каталог не гарантирует поддержку в старой сборке. Если карточка помечена '''требует проверки''', интервью не завершено или устройство объявлено неподдерживаемым, не переходите к привязке до устранения причины.

== Проверьте контролы и адреса ==

XIOT формирует адрес каждого контрола в виде:

<syntaxhighlight lang="text">
/z2m/<friendly_name>/<control>
</syntaxhighlight>

Значение <code>friendly_name</code> должно быть уникальным. Для XIOT выберите его до привязки и не используйте символы <code>/</code>, <code>+</code> и <code>#</code>: они имеют специальное значение в адресах и MQTT-топиках.

Поле '''Название в редакторе''' меняет только отображаемое имя и не меняет <code>friendly_name</code> или адрес <code>/z2m/...</code>. Если позднее изменить <code>friendly_name</code> на стороне Zigbee2MQTT, адреса изменятся: снова нажмите '''Сканировать''' и проверьте либо выполните заново все привязки этого устройства.

В карточке устройства:

* контролы только для чтения показывают состояние, измерение или событие;
* доступные для записи контролы имеют поле, переключатель или список для ручной проверки;
* отображаемые назначение, диапазон и единицы берутся из <code>definition.exposes</code>, опубликованного мостом в <code>zigbee2mqtt/bridge/devices</code>.

Перед ручной командой убедитесь, что включение реле, привода, клапана или другой нагрузки безопасно для людей и оборудования.

Проверьте оба направления отдельно:

# Измените доступный для записи контрол в XIOT-EDITOR и убедитесь, что физическое устройство выполнило команду.
# Измените состояние на самом устройстве и убедитесь, что новое значение появилось в редакторе.
# Свяжите нужные адреса управления и состояния с виртуальным устройством: [[Device-bindings|Привязка реальных устройств к виртуальным]].
# Загрузите конфигурацию на контроллер и повторите проверку через XIOT-APP.

== Если подключение не работает ==

{| class="wikitable"
! Симптом !! Что проверить
|-
| '''НЕТ ПОДКЛЮЧЕНИЯ''' || Состояние службы <code>zigbee2mqtt</code>, значение <code>mqtt.server</code>, базовый топик <code>zigbee2mqtt</code>, загрузку проекта на XIOT-PLC и журналы <code>zigbee2mqtt.service</code> и <code>xiot.service</code>.
|-
| Служба постоянно перезапускается || Фактический последовательный порт, тип адаптера, занятость порта другим процессом и совместимость прошивки координатора.
|-
| '''Сканировать''' не показывает устройство || Завершилось ли сопряжение и интервью, поддерживается ли модель текущей версией Zigbee2MQTT, есть ли устройство в данных <code>zigbee2mqtt/bridge/devices</code>. Кнопка только обновляет этот список и не включает радиообнаружение.
|-
| Значения не появляются || Разбудите батарейный датчик или измените его состояние. Затем проверьте наличие свойства в сообщении <code>zigbee2mqtt/&lt;friendly_name&gt;</code> и его описание в <code>definition.exposes</code> внутри <code>zigbee2mqtt/bridge/devices</code>.
|-
| Команда не выполняется || Убедитесь, что контрол допускает запись. Топик команды — <code>zigbee2mqtt/&lt;friendly_name&gt;/set</code>, а допустимые имя свойства и значение указаны в разделе <code>Exposes</code> на странице модели в каталоге Zigbee2MQTT.
|}

Для просмотра сообщений из редактора откройте '''Журнал''' в окне Zigbee2MQTT. Если причина остаётся неясной, приложите к обращению в [[Support|поддержку]] модель и ревизию координатора, версию Zigbee2MQTT, фрагмент журнала за время ошибки и название проблемного устройства. Сетевые ключи, резервную копию координатора и данные доступа прикладывать нельзя.

== Следующие шаги ==

* Обзор остальных интеграционных модулей: [[Driver-setup|Настройка драйверов]].
* Значение адресов управления и состояния: [[Xiot-tags|Механизм работы тегов в XIOT]].
* Привязка к пользовательскому устройству: [[Device-bindings|Привязка реальных устройств к виртуальным]].

== Официальные источники ==

* [https://wiki.wirenboard.com/wiki/index.php?title=Zigbee&oldid=101964 Подключение Zigbee к Wiren Board, установка и конфигурация Zigbee2MQTT]
* [https://www.zigbee2mqtt.io/guide/configuration/mqtt.html Настройка MQTT в Zigbee2MQTT]
* [https://www.zigbee2mqtt.io/guide/usage/pairing_devices.html Сопряжение устройств в Zigbee2MQTT]
* [https://www.zigbee2mqtt.io/guide/usage/exposes.html Описание Exposes в Zigbee2MQTT]
* [https://www.zigbee2mqtt.io/guide/usage/mqtt_topics_and_messages.html MQTT-топики и сообщения Zigbee2MQTT]

[[Category:XIOT-PLC]]
[[Category:Драйверы]]
[[Category:Интеграции]]
[[Category:Zigbee]]
{{DEFAULTSORT:Подключение Zigbee2mqtt}}