Custom-wiren-board-device-templates

Для кого: интеграторы и администраторы Wiren Board, которым нужно установить новый или переопределить штатный шаблон устройства wb-mqtt-serial.

Результат: готовый JSON-шаблон находится в пользовательском каталоге, виден в редакторе Serial-устройств с отметкой «Пользовательский» и применяется после штатного сохранения конфигурации.

Проверено: 27 августа 2026 года по документации и исходному коду wb-mqtt-serial 2.269.0, HomeUI 2.249.0 и WB-STD-003 версии 1.2 от 13 августа 2026 года. Сквозная установка на физический контроллер в рамках этой проверки не выполнялась.

Эта статья относится к службе производителя wb-mqtt-serial. Она не является драйвером XIOT: драйвер XIOT — интеграционный модуль XIOT-PLC, через который проект получает физические адреса.

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

Подготовьте готовый файл .json и доступ к контроллеру по SSH с правами root.
Проверьте установленную версию:

dpkg-query -W wb-mqtt-serial

Если шаблон уже установлен, сохраните его резервную копию вне активных каталогов шаблонов. Файл резервной копии внутри такого каталога не должен заканчиваться на .json.
Не редактируйте /etc/wb-mqtt-serial.conf вручную без необходимости. Устройства и порты настраиваются через веб-интерфейс контроллера.

Каталоги и приоритет

Путь	Назначение
`/usr/share/wb-mqtt-serial/templates`	Штатные шаблоны из пакета `wb-mqtt-serial`. Не редактируйте их: обновление пакета заменит изменения.
`/etc/wb-mqtt-serial.conf.d/templates`	Пользовательские шаблоны. Для одинакового `device_type` пользовательский шаблон перекрывает штатный.

Приоритет определяется значением device_type, а не отображаемым именем и не простым совпадением имён файлов. Не храните два пользовательских файла *.json с одинаковым device_type: при ручной установке результат зависит от порядка загрузки. RPC-загрузка, доступная в новых версиях, сама оставляет для типа один пользовательский файл.

Идентификатор и имя файла

Для нового шаблона используйте стабильный уникальный device_type в нижнем регистре из символов [a-z0-9._-]. После использования типа в конфигурациях не меняйте его.

По WB-STD-003 имя статического шаблона строится по правилу config-<device_type>.json:

device_type: soil-multi-sensor-v2.2
имя файла:  config-soil-multi-sensor-v2.2.json

Для унаследованных штатных шаблонов встречаются заглавные буквы и другие legacy-имена. При переопределении такого шаблона сохраняйте его существующий device_type, чтобы не сломать созданные конфигурации.

На контроллер устанавливается готовый файл .json. Файлы .json.jinja — исходники для генерации шаблонов на этапе сборки; перед установкой их нужно отрендерить в JSON.

Установка файла по SSH

Ниже приведён пример для config-soil-multi-sensor-v2.2.json. Для другого шаблона замените значение name:

name=config-soil-multi-sensor-v2.2.json
dir=/etc/wb-mqtt-serial.conf.d/templates

install -d -m 0755 "$dir"
python3 -m json.tool "$name" >/dev/null

if [ -e "$dir/$name" ]; then
    cp -a "$dir/$name" "$dir/$name.bak-$(date +%Y%m%d-%H%M%S)"
fi

install -m 0644 "$name" "$dir/.$name.new"
mv -f "$dir/.$name.new" "$dir/$name"

Команда python3 -m json.tool проверяет только синтаксис строгого JSON. Она не проверяет JSON-схему Wiren Board и выражения condition. Если в файле есть комментарии, эта команда для него не подходит; полную проверку даёт RPC-загрузка из следующего раздела.

Атомарное перемещение mv поддерживается файловым наблюдателем начиная с wb-mqtt-serial 2.260.0. В актуальном драйвере новый файл подхватывается автоматически: ждать 20 секунд и перезапускать wb-mqtt-confed не требуется.

Безопасная загрузка через MQTT RPC

Начиная с wb-mqtt-serial 2.260.0 статический JSON-шаблон можно загрузить запросом в топик:

/rpc/v1/wb-mqtt-serial/templates/Upload/<client_id>

Ответ приходит в тот же топик с суффиксом /reply. Стандартная обёртка MQTT RPC имеет вид {"id": 1, "params": {...}}, а объект params содержит:

Параметр	Назначение
`content`	Обязательный JSON-экранированный полный текст файла шаблона.
`filename`	Обязательное имя файла, например `config-soil-multi-sensor-v2.2.json`.
`lang`	Необязательный язык ответа; по умолчанию `en`, для русского интерфейса укажите `ru`.
`force`	Необязательное подтверждение замены шаблона типа, используемого текущей конфигурацией; по умолчанию `false`.

RPC до записи полностью проверяет синтаксис JSON, непустой device_type, JSON-схему, выражения condition, адреса параметров и вложенность subdevices. Невалидный шаблон отклоняется, файловая система не изменяется. Запись выполняется атомарно, а список типов и схема редактора актуальны уже в момент успешного ответа.

Если тип уже используется, запрос без force возвращает template-in-use. Повторяйте запрос с force: true только после проверки совместимости и создания резервной копии. Актуальный HomeUI показывает пользовательские типы, но пока не содержит кнопки загрузки или удаления шаблона: используйте MQTT-клиент либо установку по SSH.

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

Откройте или заново загрузите редактор Serial-устройств в веб-интерфейсе Wiren Board.
Найдите новый тип устройства. В актуальном HomeUI рядом с ним должна быть отметка «Пользовательский».
Если устройство уже было добавлено, откройте его конфигурацию и нажмите штатную кнопку сохранения настроек. Загрузка или удаление файла меняет каталог типов и схему редактора, но не перестраивает уже запущенный цикл опроса; новый шаблон применяется к опросу после сохранения Serial-конфигурации.
Проверьте службу и журнал:

systemctl status wb-mqtt-serial --no-pager
journalctl -u wb-mqtt-serial -n 100 --no-pager

Ожидаемый результат: служба активна, в журнале нет ошибки загрузки шаблона, устройство и его включённые каналы публикуют данные.

Если не получилось

Тип не появился. Проверьте, что установлен готовый файл с окончанием .json, затем обновите или заново откройте страницу редактора и посмотрите журнал wb-mqtt-serial. Перезапуск wb-mqtt-confed не является штатным шагом для актуальных версий.
RPC вернул template-in-use. Тип уже используется устройствами из текущей конфигурации. Проверьте совместимость нового шаблона; только затем повторите запрос с force: true.
Канал есть, но не опрашивается. Настройки канала, сохранённые прямо в конфигурации экземпляра устройства, имеют приоритет над шаблоном. Проверьте enabled и другие переопределения канала в редакторе и снова сохраните конфигурацию.
Установлена версия старше 2.260.0. RPC и обработка атомарного mv могут отсутствовать. После ручного копирования используйте перезапуск как запасной вариант:

systemctl restart wb-mqtt-serial
systemctl status wb-mqtt-serial --no-pager

Для актуальной версии отдельный перезапуск wb-mqtt-serial обычно не нужен: штатное сохранение Serial-конфигурации само применяет изменения к опросу.

Следующий шаг и связанные статьи

Шаблон Wiren Board Ensystec Leak Protect для XIOT — пример готового пользовательского шаблона.
Подключение Ensystec в XIOT через Wirenboard — пример его использования в XIOT.

Источники