Custom-wiren-board-device-templates: различия между версиями

Версия от 07:21, 27 августа 2026

Для кого: интеграторы и администраторы 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.

Источники

@@ Строка 1: / Строка 1: @@
-Статья описывает, куда размещать свои JSON-шаблоны устройств для системной службы Wiren Board <code>wb-mqtt-serial</code> и как безопасно обновлять шаблон без правки штатных файлов пакета. Эта служба производителя не является драйвером XIOT: драйвер XIOT — интеграционный модуль XIOT-PLC, через который проект получает физические адреса.
+'''Для кого:''' интеграторы и администраторы Wiren Board, которым нужно установить новый или переопределить штатный шаблон устройства <code>wb-mqtt-serial</code>.
-== Когда нужен пользовательский шаблон ==
+'''Результат:''' готовый JSON-шаблон находится в пользовательском каталоге, виден в редакторе Serial-устройств с отметкой «Пользовательский» и применяется после штатного сохранения конфигурации.
-Пользовательский шаблон нужен, если устройство работает по поддерживаемому протоколу, но штатного шаблона нет, либо штатный шаблон нужно расширить под конкретную интеграцию. Например, для Ensystec Leak Protect в XIOT нужны отдельные адреса состояния и управления, поэтому используется отдельный шаблон: [[Шаблон Wiren Board Ensystec Leak Protect для XIOT]].
+'''Проверено:''' 27 августа 2026 года по документации и исходному коду <code>wb-mqtt-serial 2.269.0</code>, HomeUI <code>2.249.0</code> и WB-STD-003 версии 1.2 от 13 августа 2026 года. Сквозная установка на физический контроллер в рамках этой проверки не выполнялась.
-== Куда класть шаблон ==
+Эта статья относится к службе производителя <code>wb-mqtt-serial</code>. Она не является драйвером XIOT: драйвер XIOT — интеграционный модуль XIOT-PLC, через который проект получает физические адреса.
-На Wiren Board используются две основные директории шаблонов <code>wb-mqtt-serial</code>:
+== Перед началом ==
+* Подготовьте готовый файл <code>.json</code> и доступ к контроллеру по SSH с правами <code>root</code>.
+* Проверьте установленную версию:
+<pre>
+dpkg-query -W wb-mqtt-serial
+</pre>
+* Если шаблон уже установлен, сохраните его резервную копию вне активных каталогов шаблонов. Файл резервной копии внутри такого каталога не должен заканчиваться на <code>.json</code>.
+* Не редактируйте <code>/etc/wb-mqtt-serial.conf</code> вручную без необходимости. Устройства и порты настраиваются через веб-интерфейс контроллера.
+== Каталоги и приоритет ==
 {| class="wikitable"
 ! Путь !! Назначение
 |-
-| <code>/usr/share/wb-mqtt-serial/templates</code> || Предустановленные шаблоны из пакета <code>wb-mqtt-serial</code>. Эти файлы не стоит редактировать вручную: обновление пакета может заменить изменения.
+| <code>/usr/share/wb-mqtt-serial/templates</code> || Штатные шаблоны из пакета <code>wb-mqtt-serial</code>. Не редактируйте их: обновление пакета заменит изменения.
 |-
-| <code>/etc/wb-mqtt-serial.conf.d/templates</code> || Пользовательские шаблоны. Эта директория имеет приоритет над предустановленными шаблонами и подходит для кастомных правок.
+| <code>/etc/wb-mqtt-serial.conf.d/templates</code> || Пользовательские шаблоны. Для одинакового <code>device_type</code> пользовательский шаблон перекрывает штатный.
 |}
-Если нужно переопределить штатный тип устройства, сохраните шаблон в пользовательскую директорию и оставьте тот же <code>device_type</code>, который используется в настройках устройства. Если создаётся новый тип устройства, задайте новый уникальный <code>device_type</code>.
+Приоритет определяется значением <code>device_type</code>, а не отображаемым именем и не простым совпадением имён файлов. Не храните два пользовательских файла <code>*.json</code> с одинаковым <code>device_type</code>: при ручной установке результат зависит от порядка загрузки. RPC-загрузка, доступная в новых версиях, сама оставляет для типа один пользовательский файл.
+== Идентификатор и имя файла ==
-== Установка шаблона ==
+Для нового шаблона используйте стабильный уникальный <code>device_type</code> в нижнем регистре из символов <code>[a-z0-9._-]</code>. После использования типа в конфигурациях не меняйте его.
-Пример для файла <code>config-ensystec.json</code>:
+По WB-STD-003 имя статического шаблона строится по правилу <code>config-&lt;device_type&gt;.json</code>:
 <pre>
-mkdir -p /etc/wb-mqtt-serial.conf.d/templates
+device_type: soil-multi-sensor-v2.2
-cp config-ensystec.json /etc/wb-mqtt-serial.conf.d/templates/config-ensystec.json
+имя файла:  config-soil-multi-sensor-v2.2.json
 </pre>
-Если шаблон является обычным строгим JSON без комментариев, можно проверить синтаксис командой:
+Для унаследованных штатных шаблонов встречаются заглавные буквы и другие legacy-имена. При переопределении такого шаблона сохраняйте его существующий <code>device_type</code>, чтобы не сломать созданные конфигурации.
+На контроллер устанавливается готовый файл <code>.json</code>. Файлы <code>.json.jinja</code> — исходники для генерации шаблонов на этапе сборки; перед установкой их нужно отрендерить в JSON.
+== Установка файла по SSH ==
+Ниже приведён пример для <code>config-soil-multi-sensor-v2.2.json</code>. Для другого шаблона замените значение <code>name</code>:
 <pre>
-python3 -m json.tool /etc/wb-mqtt-serial.conf.d/templates/config-ensystec.json >/dev/null
+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" &gt;/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"
 </pre>
-После добавления или изменения шаблона подождите около 20 секунд и обновите страницу конфигуратора Wiren Board через <code>Ctrl</code>+<code>F5</code>. Если шаблон не появился в веб-интерфейсе, перезапустите конфигуратор:
+Команда <code>python3 -m json.tool</code> проверяет только синтаксис строгого JSON. Она не проверяет JSON-схему Wiren Board и выражения <code>condition</code>. Если в файле есть комментарии, эта команда для него не подходит; полную проверку даёт RPC-загрузка из следующего раздела.
+Атомарное перемещение <code>mv</code> поддерживается файловым наблюдателем начиная с <code>wb-mqtt-serial 2.260.0</code>. В актуальном драйвере новый файл подхватывается автоматически: ждать 20 секунд и перезапускать <code>wb-mqtt-confed</code> не требуется.
+== Безопасная загрузка через MQTT RPC ==
+Начиная с <code>wb-mqtt-serial 2.260.0</code> статический JSON-шаблон можно загрузить запросом в топик:
 <pre>
-systemctl restart wb-mqtt-confed
+/rpc/v1/wb-mqtt-serial/templates/Upload/&lt;client_id&gt;
 </pre>
-Если устройство уже добавлено и используется службой <code>wb-mqtt-serial</code>, после замены шаблона перезапустите службу:
+Ответ приходит в тот же топик с суффиксом <code>/reply</code>. Стандартная обёртка MQTT RPC имеет вид <code>{"id": 1, "params": {...}}</code>, а объект <code>params</code> содержит:
+{| class="wikitable"
+! Параметр !! Назначение
+|-
+| <code>content</code> || Обязательный JSON-экранированный полный текст файла шаблона.
+|-
+| <code>filename</code> || Обязательное имя файла, например <code>config-soil-multi-sensor-v2.2.json</code>.
+|-
+| <code>lang</code> || Необязательный язык ответа; по умолчанию <code>en</code>, для русского интерфейса укажите <code>ru</code>.
+|-
+| <code>force</code> || Необязательное подтверждение замены шаблона типа, используемого текущей конфигурацией; по умолчанию <code>false</code>.
+|}
+RPC до записи полностью проверяет синтаксис JSON, непустой <code>device_type</code>, JSON-схему, выражения <code>condition</code>, адреса параметров и вложенность <code>subdevices</code>. Невалидный шаблон отклоняется, файловая система не изменяется. Запись выполняется атомарно, а список типов и схема редактора актуальны уже в момент успешного ответа.
+Если тип уже используется, запрос без <code>force</code> возвращает <code>template-in-use</code>. Повторяйте запрос с <code>force: true</code> только после проверки совместимости и создания резервной копии. Актуальный HomeUI показывает пользовательские типы, но пока не содержит кнопки загрузки или удаления шаблона: используйте MQTT-клиент либо установку по SSH.
+== Как применить и проверить результат ==
+# Откройте или заново загрузите редактор Serial-устройств в веб-интерфейсе Wiren Board.
+# Найдите новый тип устройства. В актуальном HomeUI рядом с ним должна быть отметка «Пользовательский».
+# Если устройство уже было добавлено, откройте его конфигурацию и нажмите штатную кнопку сохранения настроек. Загрузка или удаление файла меняет каталог типов и схему редактора, но не перестраивает уже запущенный цикл опроса; новый шаблон применяется к опросу после сохранения Serial-конфигурации.
+# Проверьте службу и журнал:
 <pre>
-systemctl restart wb-mqtt-serial
+systemctl status wb-mqtt-serial --no-pager
-systemctl status wb-mqtt-serial
+journalctl -u wb-mqtt-serial -n 100 --no-pager
 </pre>
-Ошибки загрузки шаблона и конфигурации смотрите в журнале:
+'''Ожидаемый результат:''' служба активна, в журнале нет ошибки загрузки шаблона, устройство и его включённые каналы публикуют данные.
+== Если не получилось ==
+* '''Тип не появился.''' Проверьте, что установлен готовый файл с окончанием <code>.json</code>, затем обновите или заново откройте страницу редактора и посмотрите журнал <code>wb-mqtt-serial</code>. Перезапуск <code>wb-mqtt-confed</code> не является штатным шагом для актуальных версий.
+* '''RPC вернул <code>template-in-use</code>.''' Тип уже используется устройствами из текущей конфигурации. Проверьте совместимость нового шаблона; только затем повторите запрос с <code>force: true</code>.
+* '''Канал есть, но не опрашивается.''' Настройки канала, сохранённые прямо в конфигурации экземпляра устройства, имеют приоритет над шаблоном. Проверьте <code>enabled</code> и другие переопределения канала в редакторе и снова сохраните конфигурацию.
+* '''Установлена версия старше 2.260.0.''' RPC и обработка атомарного <code>mv</code> могут отсутствовать. После ручного копирования используйте перезапуск как запасной вариант:
 <pre>
-journalctl -u wb-mqtt-serial -n 100 --no-pager
+systemctl restart wb-mqtt-serial
+systemctl status wb-mqtt-serial --no-pager
 </pre>
-== Важные нюансы ==
+Для актуальной версии отдельный перезапуск <code>wb-mqtt-serial</code> обычно не нужен: штатное сохранение Serial-конфигурации само применяет изменения к опросу.
+== Следующий шаг и связанные статьи ==
-* Не правьте <code>/etc/wb-mqtt-serial.conf</code> вручную без необходимости: основной путь настройки устройств — веб-интерфейс Wiren Board.
+* [[Шаблон Wiren Board Ensystec Leak Protect для XIOT]] — пример готового пользовательского шаблона.
-* Параметры каналов, заданные прямо в конфигурации устройства, имеют приоритет над параметрами из шаблона. Поэтому если канал в шаблоне добавлен, но в интерфейсе не появился, проверьте, нет ли для него переопределения <code>enabled: false</code> в конфигурации устройства.
+* [[Подключение Ensystec в XIOT через Wirenboard]] — пример его использования в XIOT.
-* Перед заменой рабочего шаблона сделайте копию текущего файла и запишите, какая версия установлена на объекте.
-* Для шаблонов с комментариями проверка через <code>python3 -m json.tool</code> не подходит, потому что это уже не строгий JSON. В этом случае ориентируйтесь на проверку через сервисы Wiren Board и журнал <code>wb-mqtt-serial</code>.
 == Источники ==
-* [https://wiki.wirenboard.com/wiki/Wb-mqtt-serial_driver Служба wb-mqtt-serial — Wiren Board]
+* [https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md Официальная документация wb-mqtt-serial: шаблоны и templates/Upload]
-* [https://github.com/wirenboard/wb-mqtt-serial Описание wb-mqtt-serial на GitHub]
+* [https://github.com/wirenboard/wb-mqtt-serial/blob/master/debian/changelog Журнал версий wb-mqtt-serial]
-* [https://wiki.wirenboard.com/wiki/index.php?title=Wb-mqtt-serial_templates/en WB-mqtt-serial driver: examples of writing templates]
+* [https://github.com/wirenboard/wb-standards/blob/main/WB-STD-003%20%D0%A8%D0%B0%D0%B1%D0%BB%D0%BE%D0%BD%D1%8B%20%D1%83%D1%81%D1%82%D1%80%D0%BE%D0%B9%D1%81%D1%82%D0%B2%20%D0%B4%D0%BB%D1%8F%20%D0%B4%D1%80%D0%B0%D0%B9%D0%B2%D0%B5%D1%80%D0%B0%20wb-mqtt-serial.md WB-STD-003 v1.2]
+* [https://github.com/wirenboard/wb-mqtt-serial/blob/master/wb-mqtt-serial-device-template.schema.json JSON-схема шаблона]
+* [https://wiki.wirenboard.com/wiki/Wiren_Board_Template_Generator Официальный генератор и редактор шаблонов Wiren Board]
+[[Категория:Документация XIOT]]

Admin (обсуждение | вклад)