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

Текущая версия от 22:19, 2 октября 2026

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

Готовый файл шаблона с расширением .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.

Подключайтесь по SFTP или SSH только из локальной либо другой доверенной сети. Не публикуйте порт 22 контроллера в интернет и не передавайте пароль root посторонним.

Шаг 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: @@
-__NOTOC__
+{{DISPLAYTITLE:Пользовательские шаблоны устройств Wiren Board}}
-= Пользовательские шаблоны устройств Wiren Board =
+Статья описывает пользовательские JSON-шаблоны для системной службы Wiren Board <code>wb-mqtt-serial</code>. Эта служба производителя не является драйвером XIOT: драйвер XIOT — отдельный интеграционный модуль XIOT-PLC. Если вы настраиваете модуль XIOT, начните со статьи [[Driver-setup|Настройка драйверов]].
-Статья описывает, куда размещать свои JSON-шаблоны устройств для драйвера <code>wb-mqtt-serial</code> и как безопасно обновлять шаблон без правки штатных файлов пакета.
+Готовый файл шаблона с расширением <code>.json</code> скопируйте на контроллер в каталог:
-== Когда нужен пользовательский шаблон ==
+<pre>
+/etc/wb-mqtt-serial.conf.d/templates/
+</pre>
-Пользовательский шаблон нужен, если устройство работает по поддерживаемому протоколу, но штатного шаблона нет, либо штатный шаблон нужно расширить под конкретную интеграцию. Например, для Ensystec Leak Protect в XIOT нужны отдельные теги состояния и управления, поэтому используется отдельный шаблон: [[Шаблон Wiren Board Ensystec Leak Protect для XIOT]].
+Не копируйте пользовательский файл в <code>/usr/share/wb-mqtt-serial/templates/</code>. Там находятся штатные шаблоны, которые могут быть заменены при обновлении программного обеспечения контроллера.
-== Куда класть шаблон ==
+== Перед началом ==
-На Wiren Board используются две основные директории шаблонов <code>wb-mqtt-serial</code>:
+Подготовьте:
-{| class="wikitable"
+* готовый файл шаблона с расширением <code>.json</code>, например <code>config-soil-multi-sensor-v2.2.json</code>;
-! Путь !! Назначение
+* IP-адрес контроллера;
-|-
+* имя пользователя <code>root</code> и пароль контроллера;
-| <code>/usr/share/wb-mqtt-serial/templates</code> || Предустановленные шаблоны из пакета <code>wb-mqtt-serial</code>. Эти файлы не стоит редактировать вручную: обновление пакета может заменить изменения.
+* параметры связи устройства: Modbus-адрес, скорость, чётность, число бит данных и стоп-битов.
-|-
-| <code>/etc/wb-mqtt-serial.conf.d/templates</code> || Пользовательские шаблоны. Эта директория имеет приоритет над предустановленными шаблонами и подходит для кастомных правок.
-|}
-Если нужно переопределить штатный тип устройства, сохраните шаблон в пользовательскую директорию и оставьте тот же <code>device_type</code>, который используется в настройках устройства. Если создаётся новый тип устройства, задайте новый уникальный <code>device_type</code>.
+Для подключения к файлам контроллера используется SFTP, порт <code>22</code>.
-== Установка шаблона ==
+Подключайтесь по SFTP или SSH только из локальной либо другой доверенной сети. Не публикуйте порт <code>22</code> контроллера в интернет и не передавайте пароль <code>root</code> посторонним.
-Пример для файла <code>config-ensystec.json</code>:
+== Шаг 1. Скопируйте файл через SFTP ==
-<pre>
+# Откройте программу для работы с SFTP:
-mkdir -p /etc/wb-mqtt-serial.conf.d/templates
+#* Windows — WinSCP;
-cp config-ensystec.json /etc/wb-mqtt-serial.conf.d/templates/config-ensystec.json
+#* macOS — Cyberduck;
+#* Linux — файловый менеджер с поддержкой адресов вида <code>sftp://IP-КОНТРОЛЛЕРА</code>.
+# Создайте подключение со следующими параметрами:
+#* протокол — '''SFTP''';
+#* сервер — IP-адрес контроллера;
+#* порт — <code>22</code>;
+#* пользователь — <code>root</code>;
+#* пароль — пароль контроллера.
+# После подключения откройте на контроллере каталог:
+#:<pre>
+/etc/wb-mqtt-serial.conf.d/templates/
 </pre>
+# Если каталога <code>templates</code> нет, создайте его.
+# Если файл с таким именем уже существует, сначала скачайте его на компьютер как резервную копию.
+# Перетащите новый файл <code>.json</code> в открытый каталог контроллера. При обновлении шаблона подтвердите замену существующего файла.
+'''Ожидаемый результат:''' файл, например <code>config-soil-multi-sensor-v2.2.json</code>, виден в каталоге <code>/etc/wb-mqtt-serial.conf.d/templates/</code>.
+Обычно перезапуск служб после копирования не требуется. Если страница настройки устройств уже была открыта, обновите её.
+== Копирование из командной строки ==
-Если шаблон является обычным строгим JSON без комментариев, можно проверить синтаксис командой:
+Этот способ необязателен. На macOS или Linux тот же файл можно скопировать командой <code>scp</code>. Замените IP-адрес своим:
 <pre>
-python3 -m json.tool /etc/wb-mqtt-serial.conf.d/templates/config-ensystec.json >/dev/null
+scp config-soil-multi-sensor-v2.2.json root@192.168.1.10:/etc/wb-mqtt-serial.conf.d/templates/
 </pre>
-После добавления или изменения шаблона подождите около 20 секунд и обновите страницу конфигуратора Wiren Board через <code>Ctrl</code>+<code>F5</code>. Если шаблон не появился в веб-интерфейсе, перезапустите конфигуратор:
+Если каталога ещё нет, сначала создайте его:
 <pre>
-systemctl restart wb-mqtt-confed
+ssh root@192.168.1.10 "mkdir -p /etc/wb-mqtt-serial.conf.d/templates"
 </pre>
-Если устройство уже добавлено и используется драйвером <code>wb-mqtt-serial</code>, после замены шаблона перезапустите драйвер:
+== Шаг 2. Добавьте устройство в веб-интерфейсе ==
+# Откройте веб-интерфейс контроллера Wiren Board.
+# Перейдите: '''Настройки → Конфигурационные файлы → Настройка драйвера Serial-устройств'''.
+# Нажмите '''Добавить любые устройства вручную'''.
+# Выберите порт, к которому подключён датчик.
+# В поле '''Тип устройства''' выберите загруженный шаблон. В актуальном интерфейсе пользовательский шаблон отмечен как '''Пользовательский'''.
+# Нажмите '''Добавить'''.
+# Откройте добавленное устройство и укажите '''Адрес устройства''' — Modbus Slave ID из документации или настроек датчика.
+# Нажмите '''Сохранить настройки'''.
+Если нужный порт ещё не настроен, выберите его слева, включите порт и задайте скорость, чётность, число бит данных и стоп-битов точно как в документации устройства. Затем сохраните настройки.
+Если устройство уже было добавлено раньше и вы только заменили файл шаблона, повторно добавлять устройство не нужно. Откройте его настройки и нажмите '''Сохранить настройки''', чтобы применить новую версию шаблона к опросу.
+== Шаг 3. Проверьте устройство ==
+# Откройте раздел '''Устройства''' веб-интерфейса.
+# Найдите добавленное устройство.
+# Убедитесь, что появились каналы из шаблона и значения обновляются.
+# Подождите один-два цикла опроса.
+'''Ожидаемый результат:''' устройство отображается в интерфейсе, его включённые каналы получают значения без ошибок связи.
+== Если не получилось ==
+* '''Шаблона нет в списке.''' Проверьте, что файл находится именно в <code>/etc/wb-mqtt-serial.conf.d/templates/</code>, его имя заканчивается на <code>.json</code>, затем обновите страницу настройки устройств.
+* '''В журнале есть ошибка шаблона.''' Откройте '''Настройки → Системный журнал''', выберите сервис <code>wb-mqtt-serial.service</code>, тип сообщений <code>error</code> и нажмите '''Загрузить'''. В сообщении будет указана строка файла с ошибкой.
+* '''Устройство есть, но значений нет.''' Проверьте адрес устройства, параметры порта и подключение RS-485. Они должны совпадать с настройками датчика.
+* '''Часть каналов отсутствует.''' Откройте настройки устройства, включите нужные каналы шаблона и снова нажмите '''Сохранить настройки'''.
+* '''Новый файл заменён, но изменения не применились.''' Откройте уже добавленное устройство и повторно сохраните настройки.
+На старом программном обеспечении контроллера, если шаблон не появился после обновления страницы и сохранения настроек, можно один раз перезапустить драйвер:
 <pre>
 systemctl restart wb-mqtt-serial
-systemctl status wb-mqtt-serial
 </pre>
-Ошибки загрузки шаблона и конфигурации смотрите в журнале:
+Для актуальной версии это запасной, а не обязательный шаг. Перезапуск <code>wb-mqtt-confed</code> не требуется.
-<pre>
+== Как обновить шаблон ==
-journalctl -u wb-mqtt-serial -n 100 --no-pager
-</pre>
+# Скачайте установленный файл на компьютер как резервную копию.
+# Скопируйте новый файл в <code>/etc/wb-mqtt-serial.conf.d/templates/</code> с заменой старого.
+# Откройте устройство в '''Настройке драйвера Serial-устройств''' и нажмите '''Сохранить настройки'''.
+# Проверьте устройство и его каналы в разделе '''Устройства'''.
-== Важные нюансы ==
+== Следующий шаг и связанные статьи ==
-* Не правьте <code>/etc/wb-mqtt-serial.conf</code> вручную без необходимости: основной путь настройки устройств — веб-интерфейс Wiren Board.
+* [[Ensystec-leak-protect-wiren-board-template|Шаблон Wiren Board Ensystec Leak Protect для XIOT]] — пример готового пользовательского шаблона.
-* Параметры каналов, заданные прямо в конфигурации устройства, имеют приоритет над параметрами из шаблона. Поэтому если канал в шаблоне добавлен, но в интерфейсе не появился, проверьте, нет ли для него переопределения <code>enabled: false</code> в конфигурации устройства.
+* [[Ensystec-wiren-board-integration|Подключение 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://wirenboard.com/wiki/Connecting_Third_Party_Devices_to_Wiren_Board Как подключать сторонние Modbus-устройства — Wiren Board]
-* [https://github.com/wirenboard/wb-mqtt-serial Описание wb-mqtt-serial на GitHub]
+* [https://wirenboard.com/wiki/View_controller_files_from_your_computer Просмотр и копирование файлов контроллера с компьютера — Wiren Board]
-* [https://wiki.wirenboard.com/wiki/index.php?title=Wb-mqtt-serial_templates/en WB-mqtt-serial driver: examples of writing templates]
+* [https://wirenboard.com/wiki/RS-485:Configuration_via_Web_Interface Настройка устройств RS-485 через веб-интерфейс — Wiren Board]
+* [https://github.com/wirenboard/wb-mqtt-serial Описание и пользовательские шаблоны wb-mqtt-serial — GitHub Wiren Board]
+[[Категория:Документация XIOT]]
+{{DEFAULTSORT:Пользовательские шаблоны устройств Wiren Board}}

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