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

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

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

Результат: файл шаблона скопирован на контроллер, устройство добавлено через веб-интерфейс и его каналы появились в разделе «Устройства».

Проверено: 27 августа 2026 года по актуальной документации Wiren Board и HomeUI 2.249.0.

Главное: готовый файл .json нужно скопировать на контроллер в каталог:

/etc/wb-mqtt-serial.conf.d/templates/

Не копируйте пользовательский файл в /usr/share/wb-mqtt-serial/templates/. Там находятся штатные шаблоны, которые могут быть заменены при обновлении программного обеспечения контроллера.

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

Подготовьте:

готовый файл шаблона с расширением .json, например config-soil-multi-sensor-v2.2.json;
IP-адрес контроллера;
имя пользователя root и пароль контроллера;
параметры связи устройства: Modbus-адрес, скорость, чётность, число бит данных и стоп-битов.

Для подключения к файлам контроллера используется SFTP, порт 22.

Шаг 1. Скопируйте файл через SFTP

Откройте программу для работы с SFTP:
- Windows — WinSCP;
- macOS — Cyberduck;
- Linux — файловый менеджер с поддержкой адресов вида sftp://IP-КОНТРОЛЛЕРА.
Создайте подключение со следующими параметрами:
- протокол — SFTP;
- сервер — IP-адрес контроллера;
- порт — 22;
- пользователь — root;
- пароль — пароль контроллера.
После подключения откройте на контроллере каталог:

/etc/wb-mqtt-serial.conf.d/templates/

Если каталога templates нет, создайте его.
Если файл с таким именем уже существует, сначала скачайте его на компьютер как резервную копию.
Перетащите новый файл .json в открытый каталог контроллера. При обновлении шаблона подтвердите замену существующего файла.

Ожидаемый результат: файл, например config-soil-multi-sensor-v2.2.json, виден в каталоге /etc/wb-mqtt-serial.conf.d/templates/.

Обычно перезапуск служб после копирования не требуется. Если страница настройки устройств уже была открыта, обновите её.

Копирование из командной строки

Этот способ необязателен. На macOS или Linux тот же файл можно скопировать командой scp. Замените IP-адрес своим:

scp config-soil-multi-sensor-v2.2.json root@192.168.1.10:/etc/wb-mqtt-serial.conf.d/templates/

Если каталога ещё нет, сначала создайте его:

ssh root@192.168.1.10 "mkdir -p /etc/wb-mqtt-serial.conf.d/templates"

Шаг 2. Добавьте устройство в веб-интерфейсе

Откройте веб-интерфейс контроллера Wiren Board.
Перейдите: Настройки → Конфигурационные файлы → Настройка драйвера Serial-устройств.
Нажмите Добавить любые устройства вручную.
Выберите порт, к которому подключён датчик.
В поле Тип устройства выберите загруженный шаблон. В актуальном интерфейсе пользовательский шаблон отмечен как Пользовательский.
Нажмите Добавить.
Откройте добавленное устройство и укажите Адрес устройства — Modbus Slave ID из документации или настроек датчика.
Нажмите Сохранить настройки.

Если нужный порт ещё не настроен, выберите его слева, включите порт и задайте скорость, чётность, число бит данных и стоп-битов точно как в документации устройства. Затем сохраните настройки.

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

Шаг 3. Проверьте устройство

Откройте раздел Устройства веб-интерфейса.
Найдите добавленное устройство.
Убедитесь, что появились каналы из шаблона и значения обновляются.
Подождите один-два цикла опроса.

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

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

Шаблона нет в списке. Проверьте, что файл находится именно в /etc/wb-mqtt-serial.conf.d/templates/, его имя заканчивается на .json, затем обновите страницу настройки устройств.
В журнале есть ошибка шаблона. Откройте Настройки → Системный журнал, выберите сервис wb-mqtt-serial.service, тип сообщений error и нажмите Загрузить. В сообщении будет указана строка файла с ошибкой.
Устройство есть, но значений нет. Проверьте адрес устройства, параметры порта и подключение RS-485. Они должны совпадать с настройками датчика.
Часть каналов отсутствует. Откройте настройки устройства, включите нужные каналы шаблона и снова нажмите Сохранить настройки.
Новый файл заменён, но изменения не применились. Откройте уже добавленное устройство и повторно сохраните настройки.

На старом программном обеспечении контроллера, если шаблон не появился после обновления страницы и сохранения настроек, можно один раз перезапустить драйвер:

systemctl restart wb-mqtt-serial

Для актуальной версии это запасной, а не обязательный шаг. Перезапуск wb-mqtt-confed не требуется.

Как обновить шаблон

Скачайте установленный файл на компьютер как резервную копию.
Скопируйте новый файл в /etc/wb-mqtt-serial.conf.d/templates/ с заменой старого.
Откройте устройство в Настройке драйвера Serial-устройств и нажмите Сохранить настройки.
Проверьте устройство и его каналы в разделе Устройства.

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

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

Источники

@@ Строка 1: / Строка 1: @@
-'''Для кого:''' интеграторы и администраторы Wiren Board, которым нужно установить новый или переопределить штатный шаблон устройства <code>wb-mqtt-serial</code>.
+'''Для кого:''' интеграторы, которым нужно установить готовый шаблон устройства на контроллер Wiren Board.
-'''Результат:''' готовый JSON-шаблон находится в пользовательском каталоге, виден в редакторе Serial-устройств с отметкой «Пользовательский» и применяется после штатного сохранения конфигурации.
+'''Результат:''' файл шаблона скопирован на контроллер, устройство добавлено через веб-интерфейс и его каналы появились в разделе «Устройства».
-'''Проверено:''' 27 августа 2026 года по документации и исходному коду <code>wb-mqtt-serial 2.269.0</code>, HomeUI <code>2.249.0</code> и WB-STD-003 версии 1.2 от 13 августа 2026 года. Сквозная установка на физический контроллер в рамках этой проверки не выполнялась.
+'''Проверено:''' 27 августа 2026 года по актуальной документации Wiren Board и HomeUI <code>2.249.0</code>.
-Эта статья относится к службе производителя <code>wb-mqtt-serial</code>. Она не является драйвером XIOT: драйвер XIOT — интеграционный модуль XIOT-PLC, через который проект получает физические адреса.
+'''Главное:''' готовый файл <code>.json</code> нужно скопировать на контроллер в каталог:
-== Перед началом ==
-* Подготовьте готовый файл <code>.json</code> и доступ к контроллеру по SSH с правами <code>root</code>.
-* Проверьте установленную версию:
 <pre>
-dpkg-query -W wb-mqtt-serial
+/etc/wb-mqtt-serial.conf.d/templates/
 </pre>
-* Если шаблон уже установлен, сохраните его резервную копию вне активных каталогов шаблонов. Файл резервной копии внутри такого каталога не должен заканчиваться на <code>.json</code>.
+Не копируйте пользовательский файл в <code>/usr/share/wb-mqtt-serial/templates/</code>. Там находятся штатные шаблоны, которые могут быть заменены при обновлении программного обеспечения контроллера.
-* Не редактируйте <code>/etc/wb-mqtt-serial.conf</code> вручную без необходимости. Устройства и порты настраиваются через веб-интерфейс контроллера.
-== Каталоги и приоритет ==
+== Перед началом ==
-{| class="wikitable"
+Подготовьте:
-! Путь !! Назначение
-|-
-| <code>/usr/share/wb-mqtt-serial/templates</code> || Штатные шаблоны из пакета <code>wb-mqtt-serial</code>. Не редактируйте их: обновление пакета заменит изменения.
-|-
-| <code>/etc/wb-mqtt-serial.conf.d/templates</code> || Пользовательские шаблоны. Для одинакового <code>device_type</code> пользовательский шаблон перекрывает штатный.
-|}
-Приоритет определяется значением <code>device_type</code>, а не отображаемым именем и не простым совпадением имён файлов. Не храните два пользовательских файла <code>*.json</code> с одинаковым <code>device_type</code>: при ручной установке результат зависит от порядка загрузки. RPC-загрузка, доступная в новых версиях, сама оставляет для типа один пользовательский файл.
+* готовый файл шаблона с расширением <code>.json</code>, например <code>config-soil-multi-sensor-v2.2.json</code>;
+* IP-адрес контроллера;
+* имя пользователя <code>root</code> и пароль контроллера;
+* параметры связи устройства: Modbus-адрес, скорость, чётность, число бит данных и стоп-битов.
-== Идентификатор и имя файла ==
+Для подключения к файлам контроллера используется SFTP, порт <code>22</code>.
-Для нового шаблона используйте стабильный уникальный <code>device_type</code> в нижнем регистре из символов <code>[a-z0-9._-]</code>. После использования типа в конфигурациях не меняйте его.
+== Шаг 1. Скопируйте файл через SFTP ==
-По WB-STD-003 имя статического шаблона строится по правилу <code>config-&lt;device_type&gt;.json</code>:
+# Откройте программу для работы с SFTP:
+#* Windows — WinSCP;
-<pre>
+#* macOS — Cyberduck;
-device_type: soil-multi-sensor-v2.2
+#* Linux — файловый менеджер с поддержкой адресов вида <code>sftp://IP-КОНТРОЛЛЕРА</code>.
-имя файла:  config-soil-multi-sensor-v2.2.json
+# Создайте подключение со следующими параметрами:
+#* протокол — '''SFTP''';
+#* сервер — IP-адрес контроллера;
+#* порт — <code>22</code>;
+#* пользователь — <code>root</code>;
+#* пароль — пароль контроллера.
+# После подключения откройте на контроллере каталог:
+#:<pre>
+/etc/wb-mqtt-serial.conf.d/templates/
 </pre>
+# Если каталога <code>templates</code> нет, создайте его.
+# Если файл с таким именем уже существует, сначала скачайте его на компьютер как резервную копию.
+# Перетащите новый файл <code>.json</code> в открытый каталог контроллера. При обновлении шаблона подтвердите замену существующего файла.
-Для унаследованных штатных шаблонов встречаются заглавные буквы и другие legacy-имена. При переопределении такого шаблона сохраняйте его существующий <code>device_type</code>, чтобы не сломать созданные конфигурации.
+'''Ожидаемый результат:''' файл, например <code>config-soil-multi-sensor-v2.2.json</code>, виден в каталоге <code>/etc/wb-mqtt-serial.conf.d/templates/</code>.
-На контроллер устанавливается готовый файл <code>.json</code>. Файлы <code>.json.jinja</code> — исходники для генерации шаблонов на этапе сборки; перед установкой их нужно отрендерить в JSON.
+Обычно перезапуск служб после копирования не требуется. Если страница настройки устройств уже была открыта, обновите её.
-== Установка файла по SSH ==
+== Копирование из командной строки ==
-Ниже приведён пример для <code>config-soil-multi-sensor-v2.2.json</code>. Для другого шаблона замените значение <code>name</code>:
+Этот способ необязателен. На macOS или Linux тот же файл можно скопировать командой <code>scp</code>. Замените IP-адрес своим:
 <pre>
-name=config-soil-multi-sensor-v2.2.json
+scp config-soil-multi-sensor-v2.2.json root@192.168.1.10:/etc/wb-mqtt-serial.conf.d/templates/
-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>
-Команда <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>
-/rpc/v1/wb-mqtt-serial/templates/Upload/&lt;client_id&gt;
+ssh root@192.168.1.10 "mkdir -p /etc/wb-mqtt-serial.conf.d/templates"
 </pre>
-Ответ приходит в тот же топик с суффиксом <code>/reply</code>. Стандартная обёртка MQTT RPC имеет вид <code>{"id": 1, "params": {...}}</code>, а объект <code>params</code> содержит:
+== Шаг 2. Добавьте устройство в веб-интерфейсе ==
-{| class="wikitable"
+# Откройте веб-интерфейс контроллера Wiren Board.
-! Параметр !! Назначение
+# Перейдите: '''Настройки → Конфигурационные файлы → Настройка драйвера Serial-устройств'''.
-|-
+# Нажмите '''Добавить любые устройства вручную'''.
-| <code>content</code> || Обязательный JSON-экранированный полный текст файла шаблона.
+# Выберите порт, к которому подключён датчик.
-|-
+# В поле '''Тип устройства''' выберите загруженный шаблон. В актуальном интерфейсе пользовательский шаблон отмечен как '''Пользовательский'''.
-| <code>filename</code> || Обязательное имя файла, например <code>config-soil-multi-sensor-v2.2.json</code>.
+# Нажмите '''Добавить'''.
-|-
+# Откройте добавленное устройство и укажите '''Адрес устройства''' — Modbus Slave ID из документации или настроек датчика.
-| <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.
+Если устройство уже было добавлено раньше и вы только заменили файл шаблона, повторно добавлять устройство не нужно. Откройте его настройки и нажмите '''Сохранить настройки''', чтобы применить новую версию шаблона к опросу.
-== Как применить и проверить результат ==
+== Шаг 3. Проверьте устройство ==
-# Откройте или заново загрузите редактор Serial-устройств в веб-интерфейсе Wiren Board.
+# Откройте раздел '''Устройства''' веб-интерфейса.
-# Найдите новый тип устройства. В актуальном HomeUI рядом с ним должна быть отметка «Пользовательский».
+# Найдите добавленное устройство.
-# Если устройство уже было добавлено, откройте его конфигурацию и нажмите штатную кнопку сохранения настроек. Загрузка или удаление файла меняет каталог типов и схему редактора, но не перестраивает уже запущенный цикл опроса; новый шаблон применяется к опросу после сохранения Serial-конфигурации.
+# Убедитесь, что появились каналы из шаблона и значения обновляются.
-# Проверьте службу и журнал:
+# Подождите один-два цикла опроса.
-<pre>
+'''Ожидаемый результат:''' устройство отображается в интерфейсе, его включённые каналы получают значения без ошибок связи.
-systemctl status wb-mqtt-serial --no-pager
-journalctl -u wb-mqtt-serial -n 100 --no-pager
-</pre>
-'''Ожидаемый результат:''' служба активна, в журнале нет ошибки загрузки шаблона, устройство и его включённые каналы публикуют данные.
+== Если не получилось ==
-== Если не получилось ==
+* '''Шаблона нет в списке.''' Проверьте, что файл находится именно в <code>/etc/wb-mqtt-serial.conf.d/templates/</code>, его имя заканчивается на <code>.json</code>, затем обновите страницу настройки устройств.
+* '''В журнале есть ошибка шаблона.''' Откройте '''Настройки → Системный журнал''', выберите сервис <code>wb-mqtt-serial.service</code>, тип сообщений <code>error</code> и нажмите '''Загрузить'''. В сообщении будет указана строка файла с ошибкой.
+* '''Устройство есть, но значений нет.''' Проверьте адрес устройства, параметры порта и подключение RS-485. Они должны совпадать с настройками датчика.
+* '''Часть каналов отсутствует.''' Откройте настройки устройства, включите нужные каналы шаблона и снова нажмите '''Сохранить настройки'''.
+* '''Новый файл заменён, но изменения не применились.''' Откройте уже добавленное устройство и повторно сохраните настройки.
-* '''Тип не появился.''' Проверьте, что установлен готовый файл с окончанием <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>
 systemctl restart wb-mqtt-serial
-systemctl status wb-mqtt-serial --no-pager
 </pre>
-Для актуальной версии отдельный перезапуск <code>wb-mqtt-serial</code> обычно не нужен: штатное сохранение Serial-конфигурации само применяет изменения к опросу.
+Для актуальной версии это запасной, а не обязательный шаг. Перезапуск <code>wb-mqtt-confed</code> не требуется.
+== Как обновить шаблон ==
+# Скачайте установленный файл на компьютер как резервную копию.
+# Скопируйте новый файл в <code>/etc/wb-mqtt-serial.conf.d/templates/</code> с заменой старого.
+# Откройте устройство в '''Настройке драйвера Serial-устройств''' и нажмите '''Сохранить настройки'''.
+# Проверьте устройство и его каналы в разделе '''Устройства'''.
 == Следующий шаг и связанные статьи ==
@@ Строка 130: / Строка 116: @@
 == Источники ==
-* [https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md Официальная документация wb-mqtt-serial: шаблоны и templates/Upload]
+* [https://wirenboard.com/wiki/Connecting_Third_Party_Devices_to_Wiren_Board Как подключать сторонние Modbus-устройства — Wiren Board]
-* [https://github.com/wirenboard/wb-mqtt-serial/blob/master/debian/changelog Журнал версий wb-mqtt-serial]
+* [https://wirenboard.com/wiki/View_controller_files_from_your_computer Просмотр и копирование файлов контроллера с компьютера — Wiren Board]
-* [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://wirenboard.com/wiki/RS-485:Configuration_via_Web_Interface Настройка устройств RS-485 через веб-интерфейс — Wiren Board]
-* [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 (обсуждение | вклад)