Connecting Third Party Devices to Wiren Board: различия между версиями
(адреса в примере и коде json-файла отличаются) |
Matveevrj (обсуждение | вклад) |
||
(не показаны 42 промежуточные версии 3 участников) | |||
Строка 1: | Строка 1: | ||
{{DISPLAYTITLE: Как | {{DISPLAYTITLE: Как подключить Modbus RTU-устройство стороннего производителя к контроллеру Wiren Board?}} | ||
== Введение == | == Введение == | ||
Modbus RTU — один из распространенных протоколов для связи устройств. Если устройство стороннего производителя поддерживает протокол Modbus RTU, то его можно подключить к контроллеру Wiren Board. | |||
Список всех поддерживаемых контроллером протоколов можно найти в [[Supported_devices | Таблице поддерживаемых устройств]]. | |||
Некоторые производители Modbus-устройств не придерживаются стандартов протокола, что может сказаться на работе всей шины. Поэтому рекомендуем проверять работу новых устройств на отдельной шине и только после того, как добьётесь стабильной работы, подключать к ней другие Modbus-устройства. | Некоторые производители Modbus-устройств не придерживаются стандартов протокола, что может сказаться на работе всей шины. Поэтому рекомендуем проверять работу новых устройств на отдельной шине и только после того, как добьётесь стабильной работы, подключать к ней другие Modbus-устройства. | ||
== | == Подключите устройство == | ||
Для подключения стороннего устройства по протоколу Modbus RTU: | |||
# Откройте документацию на устройство и | # Откройте документацию на устройство и убедитесь, что оно имеет интерфейс RS-485 и поддерживает протокол Modbus RTU. | ||
# Проверьте, нет ли вашего устройства в [[Supported_devices | Таблице поддерживаемых устройств]]. Если устройство там есть — используйте указанные в таблице рекомендации по подключению. | |||
# Определите, какая информация вам нужна и в каких регистрах она находится. | |||
# Подключите устройство к контроллеру по [[RS-485 | шине RS-485]]. | # Подключите устройство к контроллеру по [[RS-485 | шине RS-485]]. | ||
# Узнайте в документации на устройство параметры подключения: скорость (Baud rate), Количество битов данных (Data bits), Бит чётности (Parity), Количество стоповых битов (Stop bits), Modbus-адрес устройства. | |||
# Проверьте связь с устройством и правильность подключения: | # Проверьте связь с устройством и правильность подключения: | ||
#* {{Wbincludes:Stop wb-mqtt-serial}} | #* {{Wbincludes:Stop wb-mqtt-serial}} | ||
#* Подключитесь к устройству с помощью утилиты [[modbus_client]] и считайте данные из любого известного вам регистра. | #* Подключитесь к устройству с помощью утилиты [[modbus_client]] и считайте данные из любого известного вам регистра. | ||
Если чтение данных пройдёт успешно — вы верно подключили устройство и настроили параметры соединения. | |||
== Поиск подключенных устройств на шине == | |||
После физического подключения устройства не всегда получается сразу установить с ним связь: параметры обмена могут быть неизвестны или забыты. Для этого можно воспользоваться утилитой [[Wb-mb-explorer | '''wb-mb-explorer''']]. Она позволяет просканировать шину на наличие устройств: проверить наличие подключенных устройств с указанными параметрами обмена, подобрать параметры обмена для устройства с указанным адресом, провести полный перебор все возможных комбинаций параметров обмена. Если будет обнаружено устройство Wiren Board, то для него будет выведена информация о модели устройства, его серийном номере, версии прошивки и параметрах обмена. Для стороннего modbus-устройства будут выведены только параметры обмена. | |||
== Настройте опрос по Modbus == | |||
После установки соединения с устройством нужно настроить опрос его регистров. Настроить опрос стороннего Modbus-устройства на контроллере Wiren Board можно двумя способами: | |||
*написать и добавить новый шаблон конфигурации устройства в папку пользовательских шаблонов <code>/etc/wb-mqtt-serial.conf.d/templates</code>, удобно если нужно сохранять настройки при обновлении ПО; | |||
*настроить опрос устройства в веб-интерфейсе контроллера без использования шаблона, при этом регистры устройства будут описаны сразу в файле <code>/etc/wb-mqtt-serial.conf</code>, удобно при тестировании. | |||
== Создание шаблона == | ===Создание шаблона конфигурации=== | ||
[[File:serial-configs.png |300px|thumb|right| Выбор шаблона конфигурации из выпадающего списка в веб-интерфейсе контроллера Wiren Board]] | |||
Рассмотрим настройку опроса Modbus-устройства с помощью шаблона конфигурации. Шаблон конфигурации удобен тем, что его можно без проблем переносить между разными контроллерами Wiren Board и использовать повторно. | |||
Шаблон конфигурации — это JSON-файл, который обрабатывается драйвером и определяет как регистры устройства будут отображаться в контроллере, форматы их значений и возможность взаимодействия с ними. | |||
Поддерживаемые устройства, для которых есть шаблоны, отображаются в выпадающем списке в веб-интерфейсе контроллера Wiren Board в разделе '''Настройки — Конфигурационные файлы — Настройка драйвера serial-устройств'''. | |||
Рассмотрим последовательность создания шаблона нового Modbus-устройства. | |||
#Найдите документацию на устройство и таблицу modbus-регистров. По ней будут задаваться адреса нужных регистров. | |||
#Создайте и откройте в редакторе файл шаблона. | |||
# | #:Cоздать файл шаблона можно двумя способами: скопировать существующий шаблон из папки <code>/usr/share/wb-mqtt-serial/templates</code>, внести изменения и сохранить в папку <code>/etc/wb-mqtt-serial.conf.d/templates</code> или создать новый шаблон. Далее описан второй случай. | ||
# | #:<p>Удобнее всего создавать и редактировать JSON-файлы на компьютере в редакторе кода, поддерживающем синтаксис JSON, например, [https://code.visualstudio.com/ VS Code]. Если такого нет, можно использовать любой текстовый редактор.</p> | ||
#:<p>После редактирования файлы шаблонов можно будет [[View_controller_files_from_your_computer | загрузить в контроллер]].</p> | |||
#:<p>Вносить правки в существующий шаблон на контроллере можно с помощью консольного текстового редактора, например, [[nano | nano]].</p> | |||
#:{{note|info|Примечание: если шаблон в папке пользовательских шаблонов идентичен по названию и идентификатору другому шаблону в папке стандартных шаблонов, будет использован тот, который лежит в папке пользовательских шаблонов.}} | |||
#Опишите в созданном файле параметры вашего устройства. | |||
#:[[File:json-example.png |300px|thumb|right| Пример шаблона конфигурации]] | |||
#:JSON-файл состоит из JSON-объектов, которые содержат набор пар '''«Ключ : Значение»''', разделенные запятыми. JSON-объекты выделяются фигурными скобками. В качестве '''«Значения»''' может быть строка, число, булева переменная, массив, другой JSON-объект, массив JSON-объектов и т.д. Для удобства чтения каждый JSON-объект переносят на новую строку, но это не обязательно. | |||
#:<p>Ключ — это и есть имя параметра, который вы хотите задать. Все параметры, которые понимает драйвер и их возможные значения можно найти в [https://github.com/wirenboard/wb-mqtt-serial#%D0%A4%D0%B0%D0%B9%D0%BB-%D0%BA%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B0%D1%86%D0%B8%D0%B8-%D0%B8-%D1%88%D0%B0%D0%B1%D0%BB%D0%BE%D0%BD%D1%8B инструкции на гитхабе].</p> | |||
#:<p>Для работы шаблона обязательно нужно указать параметр '''device_type''', он определяет название устройства, по которому будет выполняться поиск шаблона. Также значение этого параметра будет отображаться в настройках в веб-интерфейсе.</p> | |||
#:<p>Параметр '''group''' определяет группу устройств, в которую будет включено устройство в выпадающем списке в настройках устройства. Если его не указать, новый шаблон будет в самом низу списка. Список доступных групп смотрите в [https://github.com/wirenboard/wb-mqtt-serial#%D0%A4%D0%B0%D0%B9%D0%BB-%D0%BA%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B0%D1%86%D0%B8%D0%B8-%D0%B8-%D1%88%D0%B0%D0%B1%D0%BB%D0%BE%D0%BD%D1%8B инструкции на гитхабе].</p> | |||
#:<p>Непосредственно сами регистры и их адреса задаются в параметре '''channels''', который содержит набор JSON-объектов, с параметрами регистра. Modbus-адрес из документации устройства нужно записать в параметр '''adress''', в параметре '''name''' указать его название. Здесь же задается формат данных, тип регистра и т.д. Полный набор в [https://github.com/wirenboard/wb-mqtt-serial#%D0%A4%D0%B0%D0%B9%D0%BB-%D0%BA%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B0%D1%86%D0%B8%D0%B8-%D0%B8-%D1%88%D0%B0%D0%B1%D0%BB%D0%BE%D0%BD%D1%8B инструкции на гитхабе].</p> | |||
#:<p>Параметр '''groups''' необязательный и служит для группировки параметров в веб-интерфейсе контроллера Wiren Board.</p> | |||
#Сохраните и шаблон и [[View_controller_files_from_your_computer | загрузите его на контроллер]] в папку <code>etc/wb-mqtt-serial.conf.d/templates</code>. | |||
#Затем проверьте шаблон на корректность. Для этого выполните в консоли команду | |||
#:<syntaxhighlight lang="bash"> | #:<syntaxhighlight lang="bash"> | ||
wb-mqtt-serial -g | |||
</syntaxhighlight> | </syntaxhighlight> | ||
#: в | #:Эта команда проверит на корректность файлы шаблонов в папках <code>/usr/share/wb-mqtt-serial/templates</code> и <code>/etc/wb-mqtt-serial.conf.d/templates</code>. Если в шаблонах содержатся ошибки, то на экран будут выведены диагностические сообщения с указанием имени шаблона и описанием ошибки. | ||
#:<p>Перейдите в веб-интерфейс контроллера Wiren Board в раздел '''Настройки — Конфигурационные файлы — Настройка драйвера serial-устройств'''. Проверьте, что в выпадающем списке в настройках последовательного порта появилось название вашего устройства, заданное в параметре '''device_type'''.</p> | |||
Нужное значение рассчитывается по формуле: | При создании шаблона может потребоваться задать параметр <code>guard_interval_us</code> (задержка перед записью каждого запроса в порт) в случае если есть проблемы с работой устройства. Значение этого параметра должно быть не менее 3.5 символа при выбранной скорости. Нужное значение рассчитывается по формуле: | ||
<syntaxhighlight lang="bash"> | <syntaxhighlight lang="bash"> | ||
guard_interval_us = (3.5*11* | guard_interval_us = (3.5*11*106)/(скорость в бит/с). | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Например, для скорости 9600 бит/с <code>guard_interval_us = (3.5*11* | Например, для скорости 9600 бит/с <code>guard_interval_us = (3.5*11*106)/9600 = 4000 мкс</code>. При проблемах с подключением стороннего устройства для теста это значение можно увеличить (например до 100000 мкс), так как сторонние устройства иногда работают не совсем корректно. | ||
=== | ===Конфигурирование в веб-интерфейсе=== | ||
[[File:custom-device-config.png |300px|thumb|right| Конфигурация Custom Modbus Device в веб-интерфейсе контроллера Wiren Board]] | |||
Для конфигурирования нового Modbus-устройства можно указать его регистры прямо в веб-интерфейсе контроллера в разделе '''Настройки — Конфигурационные файлы — Настройка драйвера serial-устройств''', выбрав тип устройства '''Custom Modbus Device'''. | |||
В этом случае появятся поля, в которых можно будет задать параметры регистра и его значение. | |||
При таком способе настройки регистры будут прописаны в файле конфигурации serial-порта <code>/etc/wb-mqtt-serial.conf</code> без создания нового шаблона. Это полезно при тестировании нового устройства. | |||
== Особенности реализации Modbus RTU в устройствах Wiren Board == | |||
Стандартом Modbus RTU предусмотрен обязательный интервал тишины в 3.5 символа между фреймами данных (под символом подразумевается посылка, состоящая из стартового бита, битов данных, бита четности и стоп-битов). | |||
Для ускорения опроса устройств Wiren Board мы соблюдаем этот интервал только перед первым запросом к следующему в цикле опроса устройству (параметр ''frame_timeout_ms'' в шаблонах устройств). | |||
Поэтому, чтобы соответствовать требованиям протокола Modbus-RTU, нужно для сторонних устройств задавать параметр ''guard_interval_us''. Этот параметр задает задержку перед записью каждого запроса в порт. | |||
== | == Совместная работа модулей Wiren Board и устройств сторонних производителей на одной шине== | ||
При работе модулей Wiren Board и устройств сторонних производителей на одной шине RS-485 параметр <code>guard_interval_us</code> следует задавать целиком для порта, также следует изменить параметр '''RS-485 Response Delay (ms)''' (Задержка перед ответом по RS-485) у модулей Wiren Board (если такой параметр имеется), например, установив значение 8 мс. Это необходимо, так как несоблюдение интервалов тишины при обращении к модулям Wiren Board приводит к сбою в работе некоторых устройств сторонних производителей. | |||
== Полезные ссылки == | == Полезные ссылки == | ||
Строка 272: | Строка 91: | ||
* [https://github.com/wirenboard/conventions/blob/main/README.md Описание соглашений MQTT] | * [https://github.com/wirenboard/conventions/blob/main/README.md Описание соглашений MQTT] | ||
* [http://json.parser.online.fr Онлайн проверка JSON] | * [http://json.parser.online.fr Онлайн проверка JSON] | ||
* Темы на | * Темы на форуме: | ||
** [https://support.wirenboard.com/t/oshibki-pri-chtenii-bolid-s2000-pp/8080 Ошибки при чтении Bolid С2000-ПП] | ** [https://support.wirenboard.com/t/oshibki-pri-chtenii-bolid-s2000-pp/8080 Ошибки при чтении Bolid С2000-ПП] | ||
** [https://support.wirenboard.com/t/request-timed-out/8344/17 Request timed out] | ** [https://support.wirenboard.com/t/request-timed-out/8344/17 Request timed out] |
Версия 21:16, 8 февраля 2023
Введение
Modbus RTU — один из распространенных протоколов для связи устройств. Если устройство стороннего производителя поддерживает протокол Modbus RTU, то его можно подключить к контроллеру Wiren Board.
Список всех поддерживаемых контроллером протоколов можно найти в Таблице поддерживаемых устройств.
Некоторые производители Modbus-устройств не придерживаются стандартов протокола, что может сказаться на работе всей шины. Поэтому рекомендуем проверять работу новых устройств на отдельной шине и только после того, как добьётесь стабильной работы, подключать к ней другие Modbus-устройства.
Подключите устройство
Для подключения стороннего устройства по протоколу Modbus RTU:
- Откройте документацию на устройство и убедитесь, что оно имеет интерфейс RS-485 и поддерживает протокол Modbus RTU.
- Проверьте, нет ли вашего устройства в Таблице поддерживаемых устройств. Если устройство там есть — используйте указанные в таблице рекомендации по подключению.
- Определите, какая информация вам нужна и в каких регистрах она находится.
- Подключите устройство к контроллеру по шине RS-485.
- Узнайте в документации на устройство параметры подключения: скорость (Baud rate), Количество битов данных (Data bits), Бит чётности (Parity), Количество стоповых битов (Stop bits), Modbus-адрес устройства.
- Проверьте связь с устройством и правильность подключения:
- Остановите драйвер wb-mqtt-serial или иное ПО, которое опрашивает устройство.
- Подключитесь к устройству с помощью утилиты modbus_client и считайте данные из любого известного вам регистра.
Если чтение данных пройдёт успешно — вы верно подключили устройство и настроили параметры соединения.
Поиск подключенных устройств на шине
После физического подключения устройства не всегда получается сразу установить с ним связь: параметры обмена могут быть неизвестны или забыты. Для этого можно воспользоваться утилитой wb-mb-explorer. Она позволяет просканировать шину на наличие устройств: проверить наличие подключенных устройств с указанными параметрами обмена, подобрать параметры обмена для устройства с указанным адресом, провести полный перебор все возможных комбинаций параметров обмена. Если будет обнаружено устройство Wiren Board, то для него будет выведена информация о модели устройства, его серийном номере, версии прошивки и параметрах обмена. Для стороннего modbus-устройства будут выведены только параметры обмена.
Настройте опрос по Modbus
После установки соединения с устройством нужно настроить опрос его регистров. Настроить опрос стороннего Modbus-устройства на контроллере Wiren Board можно двумя способами:
- написать и добавить новый шаблон конфигурации устройства в папку пользовательских шаблонов
/etc/wb-mqtt-serial.conf.d/templates
, удобно если нужно сохранять настройки при обновлении ПО; - настроить опрос устройства в веб-интерфейсе контроллера без использования шаблона, при этом регистры устройства будут описаны сразу в файле
/etc/wb-mqtt-serial.conf
, удобно при тестировании.
Создание шаблона конфигурации
Рассмотрим настройку опроса Modbus-устройства с помощью шаблона конфигурации. Шаблон конфигурации удобен тем, что его можно без проблем переносить между разными контроллерами Wiren Board и использовать повторно.
Шаблон конфигурации — это JSON-файл, который обрабатывается драйвером и определяет как регистры устройства будут отображаться в контроллере, форматы их значений и возможность взаимодействия с ними.
Поддерживаемые устройства, для которых есть шаблоны, отображаются в выпадающем списке в веб-интерфейсе контроллера Wiren Board в разделе Настройки — Конфигурационные файлы — Настройка драйвера serial-устройств.
Рассмотрим последовательность создания шаблона нового Modbus-устройства.
- Найдите документацию на устройство и таблицу modbus-регистров. По ней будут задаваться адреса нужных регистров.
- Создайте и откройте в редакторе файл шаблона.
- Cоздать файл шаблона можно двумя способами: скопировать существующий шаблон из папки
/usr/share/wb-mqtt-serial/templates
, внести изменения и сохранить в папку/etc/wb-mqtt-serial.conf.d/templates
или создать новый шаблон. Далее описан второй случай. Удобнее всего создавать и редактировать JSON-файлы на компьютере в редакторе кода, поддерживающем синтаксис JSON, например, VS Code. Если такого нет, можно использовать любой текстовый редактор.
После редактирования файлы шаблонов можно будет загрузить в контроллер.
Вносить правки в существующий шаблон на контроллере можно с помощью консольного текстового редактора, например, nano.
- Примечание: если шаблон в папке пользовательских шаблонов идентичен по названию и идентификатору другому шаблону в папке стандартных шаблонов, будет использован тот, который лежит в папке пользовательских шаблонов.
- Cоздать файл шаблона можно двумя способами: скопировать существующий шаблон из папки
- Опишите в созданном файле параметры вашего устройства.
- JSON-файл состоит из JSON-объектов, которые содержат набор пар «Ключ : Значение», разделенные запятыми. JSON-объекты выделяются фигурными скобками. В качестве «Значения» может быть строка, число, булева переменная, массив, другой JSON-объект, массив JSON-объектов и т.д. Для удобства чтения каждый JSON-объект переносят на новую строку, но это не обязательно.
Ключ — это и есть имя параметра, который вы хотите задать. Все параметры, которые понимает драйвер и их возможные значения можно найти в инструкции на гитхабе.
Для работы шаблона обязательно нужно указать параметр device_type, он определяет название устройства, по которому будет выполняться поиск шаблона. Также значение этого параметра будет отображаться в настройках в веб-интерфейсе.
Параметр group определяет группу устройств, в которую будет включено устройство в выпадающем списке в настройках устройства. Если его не указать, новый шаблон будет в самом низу списка. Список доступных групп смотрите в инструкции на гитхабе.
Непосредственно сами регистры и их адреса задаются в параметре channels, который содержит набор JSON-объектов, с параметрами регистра. Modbus-адрес из документации устройства нужно записать в параметр adress, в параметре name указать его название. Здесь же задается формат данных, тип регистра и т.д. Полный набор в инструкции на гитхабе.
Параметр groups необязательный и служит для группировки параметров в веб-интерфейсе контроллера Wiren Board.
- Сохраните и шаблон и загрузите его на контроллер в папку
etc/wb-mqtt-serial.conf.d/templates
. - Затем проверьте шаблон на корректность. Для этого выполните в консоли команду
wb-mqtt-serial -g
- Эта команда проверит на корректность файлы шаблонов в папках
/usr/share/wb-mqtt-serial/templates
и/etc/wb-mqtt-serial.conf.d/templates
. Если в шаблонах содержатся ошибки, то на экран будут выведены диагностические сообщения с указанием имени шаблона и описанием ошибки. Перейдите в веб-интерфейс контроллера Wiren Board в раздел Настройки — Конфигурационные файлы — Настройка драйвера serial-устройств. Проверьте, что в выпадающем списке в настройках последовательного порта появилось название вашего устройства, заданное в параметре device_type.
При создании шаблона может потребоваться задать параметр guard_interval_us
(задержка перед записью каждого запроса в порт) в случае если есть проблемы с работой устройства. Значение этого параметра должно быть не менее 3.5 символа при выбранной скорости. Нужное значение рассчитывается по формуле:
guard_interval_us = (3.5*11*106)/(скорость в бит/с).
Например, для скорости 9600 бит/с guard_interval_us = (3.5*11*106)/9600 = 4000 мкс
. При проблемах с подключением стороннего устройства для теста это значение можно увеличить (например до 100000 мкс), так как сторонние устройства иногда работают не совсем корректно.
Конфигурирование в веб-интерфейсе
Для конфигурирования нового Modbus-устройства можно указать его регистры прямо в веб-интерфейсе контроллера в разделе Настройки — Конфигурационные файлы — Настройка драйвера serial-устройств, выбрав тип устройства Custom Modbus Device. В этом случае появятся поля, в которых можно будет задать параметры регистра и его значение.
При таком способе настройки регистры будут прописаны в файле конфигурации serial-порта /etc/wb-mqtt-serial.conf
без создания нового шаблона. Это полезно при тестировании нового устройства.
Особенности реализации Modbus RTU в устройствах Wiren Board
Стандартом Modbus RTU предусмотрен обязательный интервал тишины в 3.5 символа между фреймами данных (под символом подразумевается посылка, состоящая из стартового бита, битов данных, бита четности и стоп-битов).
Для ускорения опроса устройств Wiren Board мы соблюдаем этот интервал только перед первым запросом к следующему в цикле опроса устройству (параметр frame_timeout_ms в шаблонах устройств).
Поэтому, чтобы соответствовать требованиям протокола Modbus-RTU, нужно для сторонних устройств задавать параметр guard_interval_us. Этот параметр задает задержку перед записью каждого запроса в порт.
Совместная работа модулей Wiren Board и устройств сторонних производителей на одной шине
При работе модулей Wiren Board и устройств сторонних производителей на одной шине RS-485 параметр guard_interval_us
следует задавать целиком для порта, также следует изменить параметр RS-485 Response Delay (ms) (Задержка перед ответом по RS-485) у модулей Wiren Board (если такой параметр имеется), например, установив значение 8 мс. Это необходимо, так как несоблюдение интервалов тишины при обращении к модулям Wiren Board приводит к сбою в работе некоторых устройств сторонних производителей.