Zigbee2mqtt-connection

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

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

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

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

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

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

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

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

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

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

Установите Zigbee2MQTT

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

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

apt update
apt install zigbee2mqtt

Для старого WBE2R-R-ZIGBEE сначала выберите совместимую версию по официальной инструкции Wiren Board. Не устанавливайте пакет для другой ревизии наугад.

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

/mnt/data/root/zigbee2mqtt/data/configuration.yaml

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

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

mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://127.0.0.1:1887'
serial:
  port: /dev/ttyMODx
  adapter: zstack

Замените /dev/ttyMODx на фактический порт. Для другого координатора значение adapter и параметры последовательного соединения берите из его документации и из списка адаптеров Zigbee2MQTT.

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

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

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

systemctl restart zigbee2mqtt
systemctl status --no-pager zigbee2mqtt

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

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

journalctl -u zigbee2mqtt --no-pager -n 100

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

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

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

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

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

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

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

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

Поддержка конкретной модели зависит от установленной версии Zigbee2MQTT. Сверяйтесь с официальным списком поддерживаемых устройств и проверяйте, относится ли найденная информация к вашей установленной версии: текущий каталог не гарантирует поддержку в старой сборке. Если карточка помечена требует проверки, интервью не завершено или устройство объявлено неподдерживаемым, не переходите к привязке до устранения причины.

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

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

/z2m/<friendly_name>/<control>

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

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

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

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

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

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

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

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

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

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

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

Обзор остальных интеграционных модулей: Настройка драйверов.
Значение адресов управления и состояния: Механизм работы тегов в XIOT.
Привязка к пользовательскому устройству: Привязка реальных устройств к виртуальным.

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