Wb-mqtt-serial templates/en: различия между версиями
FuzzyBot (обсуждение | вклад) м (FuzzyBot переименовал страницу Драйвер wb-mqtt-serial:Примеры написания шаблонов/en в Wb-mqtt-serial templates/en без оставления перенаправления: Часть переводимой страницы Драйвер wb-mqtt-serial:Примеры написания шаблонов.) |
(Новая страница: «The following are sample template files for some Wiren Board devices, covering a basic list of options used when creating templates.») |
||
(не показано 27 промежуточных версий 1 участника) | |||
Строка 1: | Строка 1: | ||
<languages/> | <languages/> | ||
=== The general structure of the device template=== | === The general structure of the device template | ||
=== | |||
A device template file is a [https://en.wikipedia.org/wiki/JSON JSON] structure that describes device parameters. The template allows comments. The JSON structure is written inside the space between the opening and closing braces:<code> { ... }</code> | A device template file is a [https://en.wikipedia.org/wiki/JSON JSON] structure that describes device parameters. The template allows comments. The JSON structure is written inside the space between the opening and closing braces:<code> { ... }</code> | ||
Строка 100: | Строка 101: | ||
==== WB-MS-THLS v.2 ==== | ==== WB-MS-THLS v.2 ==== | ||
Устройство [[WB-MS_Modbus_Sensor|WB-MS-THLS]] — универсальный комбинированный Modbus-датчик температуры, влажности, освещённости и звукового давления. Устройство предоставляет доступ к данным через input-регистры Modbus. Первоначальные настройки устройства записаны в holding-регистры, но не используются для получения данных и управления устройством, поэтому в шаблон не входят. | |||
По ссылке "Expand" можно увидеть полный код шаблона. | |||
<div class="mw-collapsible mw-collapsed" style="width:500px; overflow: hidden;" > | <div class="mw-collapsible mw-collapsed" style="width:500px; overflow: hidden;" > | ||
Строка 172: | Строка 174: | ||
</div> | </div> | ||
В настройках устройства интересен параметр <syntaxhighlight lang="JSON"> "max_read_registers": 0,</syntaxhighlight> Этот параметр описывает максимальное количество регистров, считываемых с устройства при запросе. Значение по умолчанию — 1, в нашем случае мы указываем считывать все регистры за один проход (bulk read). | |||
В настройках канала "Temperature" имеются три параметра, на которые стоит обратить внимание: | |||
<syntaxhighlight lang="JSON"> | <syntaxhighlight lang="JSON"> | ||
"format": "s16", | "format": "s16", | ||
Строка 179: | Строка 181: | ||
"error_value": "0x7FFF" | "error_value": "0x7FFF" | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Параметр '''"format": "s16"''' указывает на то, что число в регистрах представлено в виде знакового 16-битного целого, '''"scale": 0.1''' — говорит о том, что полученное из регистров значение следует домножить на коэффициент масштабирования 0,1 для получения значения температуры, а параметр '''"error_value": "0x7FFF"''' задает значение, получаемое из регистра, указывающее на то, что при опросе датчика произошла ошибка. Такой параметр будет выделен красным цветом в Web-интерфейсе контроллера. Применять такой параметр следует, если вы знаете, какое значение выдает ваше устройство в случае ошибки. | |||
---- | ---- | ||
==== WB-MRGBW-D ==== [[WB-MRGBW-D | ==== WB-MRGBW-D ==== | ||
Устройство [[WB-MRGBW-D|WB-MRGBW-D]] — четырехканальный диммер для управления светодиодными лентами. Может управлять лентой RGB+W либо независимо четырьмя одноцветными лентами. | |||
Настройки яркости хранятся в holding-регистрах; шаблон описывает, какие регистры можно менять для получения нужной яркости каналов, отслеживать нажатия на кнопки диммера и получать значения количества нажатий.По ссылке "Expand" можно увидеть полный код шаблона. | |||
<div class="mw-collapsible mw-collapsed" style="width:500px; overflow: hidden;" > | <div class="mw-collapsible mw-collapsed" style="width:500px; overflow: hidden;" > | ||
Строка 274: | Строка 278: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
</div> | </div> | ||
В этом шаблоне составной канал RGB задает одновременно яркости трех цветовых компонентов ленты, хранящихся в трех holding-регистрах и описывается следующим образом: | |||
<syntaxhighlight lang="JSON"> | <syntaxhighlight lang="JSON"> | ||
{ | { | ||
Строка 296: | Строка 300: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Канал белого цвета управляется отдельно, | |||
<syntaxhighlight lang="JSON"> | <syntaxhighlight lang="JSON"> | ||
{ | { | ||
Строка 306: | Строка 310: | ||
}, | }, | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Здесь указано максимальное значение, которое можно установить для ползунка яркости белого — 255:<syntaxhighlight lang="JSON">"max": 255</syntaxhighlight> | |||
<syntaxhighlight lang="JSON">"max": 255</syntaxhighlight> | |||
Серийный номер устройства (канал "Serial NO") считывается как беззнаковое 32-битное целое: <syntaxhighlight lang="JSON">"format": "u32"</syntaxhighlight> | |||
---- | ---- | ||
==== WBIO-DO-R10A-8 ==== | ==== WBIO-DO-R10A-8 ==== | ||
Устройство [[WBIO-DO-R10A-8_Relay_Module | Устройство [[WBIO-DO-R10A-8_Relay_Module|WBIO-DO-R10A-8]] — релейный боковой модуль, который подключается непосредственно к WBIO-разъему контроллера, и не управляется по Modbus. Но при подключении его через устройство расширения WB-MIO или WB-MIO-E становится полноценным Modbus-устройством, для которого имеется соответствующий шаблон. | ||
По ссылке "Expand" можно увидеть полный код шаблона. | |||
<div class="mw-collapsible mw-collapsed" style="width:500px; overflow: hidden;" > | <div class="mw-collapsible mw-collapsed" style="width:500px; overflow: hidden;" > | ||
Строка 421: | Строка 424: | ||
В этом шаблоне следует обратить внимание на следующие параметры устройства. | |||
<syntaxhighlight lang="JSON"> | <syntaxhighlight lang="JSON"> | ||
"protocol": "modbus_io", | "protocol": "modbus_io", | ||
Строка 430: | Строка 433: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Параметр '''"protocol": "modbus_io"''' указывает, что устройство подключается оп специальному протоколу к модулю расширения. Параметры '''"stride": 1000''' и '''"shift": 500''' задают сдвиг регистров в зависимости от того, в каком порядке подключены модули к модулю расширения. | |||
Сдвиг регистров (число, которое нужно добавить к базовому номеру регистра) вычисляется по формуле: <syntaxhighlight lang="C++">Shift = (((SlaveId.Secondary - 1) % 4) + 1) * DeviceConfig()->Stride + DeviceConfig()->Shift;</syntaxhighlight> Здесь stride — ''DeviceConfig()->Stride'', a shift — ''DeviceConfig()->Shift''. Каждое подключенное устройство имеет порядковый номер (''SlaveId.Secondary''), начинающийся с 1 для первого устройства. (Здесь знаком "%" обозначается деление по модулю.) | |||
Shift = ((( | Например, подставляя значения shift и stride в формулу, получаем: <syntaxhighlight lang="C++">Shift = ((( 1 - 1) % 4) + 1) * 500 + 1000 = (0 + 1) * 500 + 1000 = 1500</syntaxhighlight> То есть ко всем регистрам, указанным в шаблоне, надо добавить 1500. | ||
Еще один важный параметр — setup-секция, массив | |||
<syntaxhighlight lang="JSON"> | <syntaxhighlight lang="JSON"> | ||
"setup": [ { | "setup": [ { | ||
Строка 451: | Строка 449: | ||
...] | ...] | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Он описывает регистры и значения, которые однократно заносятся в эти регистры при инициализации устройства (при запуске или перезапуске wb-mqtt-serial). Его можно использовать для конфигурирования устройств для работы в каком-то определенном режиме, задавать изначальные значения яркости, положения сервоприводов, состояния реле, режима работы с входами релейных модулей и т. п. | |||
---- | ---- | ||
Строка 457: | Строка 455: | ||
==== WB-MAP3H ==== | ==== WB-MAP3H ==== | ||
[[WB-MAP3H_Power_Meter | Устройство [[WB-MAP3H_Power_Meter|WB-MAP3H]] — трехканальный счетчик электроэнергии. Он измеряет большое количество параметров электрической сети. Поскольку опрос всех регистров такого устройства может занять достаточно много времени, имеется несколько шаблонов, содержащих оптимальный набор параметров для решения текущей задачи. Мы рассмотрим базовый шаблон. По ссылке "Expand" можно увидеть полный код шаблона. | ||
<div class="mw-collapsible mw-collapsed" style="width:500px; overflow: hidden;" > | <div class="mw-collapsible mw-collapsed" style="width:500px; overflow: hidden;" > | ||
Строка 869: | Строка 867: | ||
</div> | </div> | ||
На что следует обратить внимание в этом шаблоне? В первую очередь в параметрах устройства мы указываем, что одновременно следует считывать не более 60 регистров, чтобы не останавливать надолго опрос остальных устройств: '''"max_read_registers": 60'''. | |||
Также показательным является параметр, описывающий накопленную реактивную энергию по фазе L1: | |||
<syntaxhighlight lang="JSON"> | <syntaxhighlight lang="JSON"> | ||
{ | { | ||
Строка 884: | Строка 882: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Здесь стоит обратить внимание на то, что адрес регистра может задаваться и в шестнадцатеричном виде: '''"address": "0x1224"''', вещественный коэффициент масштабирования можно задавать в экспоненциальной записи: '''"scale": 3.125e-05''', при считывании значения округлять его до нужного порядка: '''"round_to": 0.0001''', а также учитывать, что число в Modbus-регистрах хранится в порядке от младшего к старшему: '''"word_order": "little_endian"'''. | |||
Форматы хранения для 16-битных Modbus регистров описываются следующим образом: | |||
<pre> | <pre> | ||
big-endian : ( [0xAA 0xBB] [0xCC 0xDD] => 0xAABBCCDD ) | big-endian : ( [0xAA 0xBB] [0xCC 0xDD] => 0xAABBCCDD ) | ||
little-endian : ( [0xAA 0xBB] [0xCC 0xDD] => 0xCCDDAABB ) | little-endian : ( [0xAA 0xBB] [0xCC 0xDD] => 0xCCDDAABB ) | ||
</pre> | </pre> | ||
По умолчанию предполагается формат big-endian. | |||
Типы переменных, используемых в шаблонах, перечислены в следующей таблице: | |||
{| class="wikitable" | {| class="wikitable" | ||
! | ! Обозначение !! Тип | ||
|- | |- | ||
| s16 || Signed 16-bit integer | | s16 || Signed 16-bit integer | ||
Строка 930: | Строка 929: | ||
|} | |} | ||
=== | === Источники информации === | ||
В этой статье описаны основные правила создания шаблонов устройств для контроллеров Wiren Board. Информация изменяется и дополняется по мере обновления ПО и выходу новых продуктов. Самая полная и актуальная информация может быть найдена в следующих источниках: | |||
* | * в описании сервиса [https://github.com/contactless/wb-mqtt-serial/ wb-mqtt-serial] на GitHub; | ||
* | * в файлах самих шаблонов. | ||
* в файле [https://github.com/contactless/wb-mqtt-serial/blob/master/wb-mqtt-serial.schema.json wb-mqtt-serial.schema.json] на GitHub. |
Версия 16:21, 11 июня 2019
=== The general structure of the device template
===
A device template file is a JSON structure that describes device parameters. The template allows comments. The JSON structure is written inside the space between the opening and closing braces: { ... }
The general structure of the device template is as follows:
//Device template
{
"device": {
"Device1 parameter":"value",
"Device2 parameter":"value",
...
"channels": [ {channel parameters 1}, {channel parameters 2}, ...]
}
}
Device is a device connected to the controller, channel is a data source: usually it is a Modbus register with a description of the data type, polling frequency, value conversion, etc. See the following sections for a detailed description: template files are stored on the controller in a folder
/usr/share/wb-mqtt-serial/templates
You should copy the new templates you created for the new device to this directory. In our templates, we use indents of 4 spaces per level, which ensures the readability of the template code, and we recommend writing new templates with the same indentation.
Device settings
![](/wiki/images/thumb/6/68/Device_properties_mqtt_serial.png/650px-Device_properties_mqtt_serial.png)
The parameters of the device are set in the form of a set of pairs key:value at the beginning of the pattern. Required parameters are "device_type" and "device" keys.
The device_type key specifies a unique name for the device type as a string, for example:
"device_type":"WB-MAP12H",
.
The device key value is a composite structure that describes specific device parameters:
"device": {
"name": "WB-MAP12H",
"id": "wb-map12h",
"channels": [...]
}
- name — is the displayed name of the device. Published as
.../meta/name in mqtt
. The device name is used when displaying the web-interface, stored in the topic"id" + " " + "slave_id"
. Example for a device with modbus address 5 (slave_id) and value"name":"WB-MAP12H (basic)"
/devices/wb-map12h_5/meta/name WB-MAP12H (basic)
.
- id — is the unique identifier of the device to MQTT. Each item in devices must have a unique id. mqtt-topic related to this device in MQTT have a common prefix /devices/<topic ID>/... Also by default it is taken from the template with the addition of slave_id:
"id" + "_" + slave_id
- channels — is the list of device channels, is set as
[...]
, each element represents a description of a particular channel.
Other device parameters are either added to the section when the template is included in the wb-mqtt-serial general configuration, or default values are used. The full list can be found in the wb-mqtt-serial.schema.json file (a copy is also stored on the controller: /usr/share/wb-mqtt-confed/schemas/wb-mqtt-serial.schema.json
). See "device" object properties: "device" -> "properties"
.
Device channels
![](/wiki/images/thumb/d/d5/Channel_properties_mqtt_serial.png/450px-Channel_properties_mqtt_serial.png)
Channel description is a structure
"channels": [
{
"name": "Channel name1",
...
},
{
"name": "Channel name2",
...
},
...
]
The structure contains the following set of fields.
![](/wiki/images/thumb/c/c4/Vartype_properties_mqtt_serial.png/450px-Vartype_properties_mqtt_serial.png)
- name — имя канала, уникальное для устройство имя канала
- reg_type — тип Modbus-регистра, одно из "coil", "discrete", "holding", "holding_single", "holding_multi", "input", "direct"
- address — адрес Modbus-регистра, связанного с каналом.
- type — тип контрола -- виртуального элемента для представления данных в Web-интерфейсе контроллера: "switch", "pushbutton", "range", "rgb" и другие; полностью перечислены в схеме wb-mqtt-serial.schema.json.
- readonly — "true", если значения можно только считывать.
- format — тип переменной, описывающей значение, см. рис.
- name — the channel name that is unique to the device
- reg_type — type of Modbus register, one of "coil", "discrete", "holding", "holding_single", "holding_multi", "input", "direct" types
- address — the address of the Modbus register associated with the channel.
- type — type of control, a virtual element for data representation in the Web-interface of the controller: "switch", "pushbutton", "range", "rgb" and others; fully listed in the scheme wb-mqtt-serial.schema.json.
- readonly — "true" if the values can only be read.
- format — type of the variable describing the value, see figure.
In the simplest case, the fields "name", "reg_type", "address" and "type"are sufficient. Descriptions of other parameter types are fully listed in the wb-mqtt-serial.schema.json scheme.
Examples of device templates
The following are sample template files for some Wiren Board devices, covering a basic list of options used when creating templates.
WB-MS-THLS v.2
Устройство WB-MS-THLS — универсальный комбинированный Modbus-датчик температуры, влажности, освещённости и звукового давления. Устройство предоставляет доступ к данным через input-регистры Modbus. Первоначальные настройки устройства записаны в holding-регистры, но не используются для получения данных и управления устройством, поэтому в шаблон не входят. По ссылке "Expand" можно увидеть полный код шаблона.
В настройках устройства интересен параметр
"max_read_registers": 0,
Этот параметр описывает максимальное количество регистров, считываемых с устройства при запросе. Значение по умолчанию — 1, в нашем случае мы указываем считывать все регистры за один проход (bulk read).
В настройках канала "Temperature" имеются три параметра, на которые стоит обратить внимание:
"format": "s16",
"scale": 0.1,
"error_value": "0x7FFF"
Параметр "format": "s16" указывает на то, что число в регистрах представлено в виде знакового 16-битного целого, "scale": 0.1 — говорит о том, что полученное из регистров значение следует домножить на коэффициент масштабирования 0,1 для получения значения температуры, а параметр "error_value": "0x7FFF" задает значение, получаемое из регистра, указывающее на то, что при опросе датчика произошла ошибка. Такой параметр будет выделен красным цветом в Web-интерфейсе контроллера. Применять такой параметр следует, если вы знаете, какое значение выдает ваше устройство в случае ошибки.
WB-MRGBW-D
Устройство WB-MRGBW-D — четырехканальный диммер для управления светодиодными лентами. Может управлять лентой RGB+W либо независимо четырьмя одноцветными лентами. Настройки яркости хранятся в holding-регистрах; шаблон описывает, какие регистры можно менять для получения нужной яркости каналов, отслеживать нажатия на кнопки диммера и получать значения количества нажатий.По ссылке "Expand" можно увидеть полный код шаблона.
В этом шаблоне составной канал RGB задает одновременно яркости трех цветовых компонентов ленты, хранящихся в трех holding-регистрах и описывается следующим образом:
{
"name": "RGB",
"type": "rgb",
"consists_of": [
{
"reg_type": "holding",
"address": 1
},
{
"reg_type": "holding",
"address": 0
},
{
"reg_type": "holding",
"address": 2
}
]
},
Канал белого цвета управляется отдельно,
{
"name": "White",
"reg_type": "holding",
"address": 3,
"type": "range",
"max": 255
},
Здесь указано максимальное значение, которое можно установить для ползунка яркости белого — 255:
"max": 255
Серийный номер устройства (канал "Serial NO") считывается как беззнаковое 32-битное целое:
"format": "u32"
WBIO-DO-R10A-8
Устройство WBIO-DO-R10A-8 — релейный боковой модуль, который подключается непосредственно к WBIO-разъему контроллера, и не управляется по Modbus. Но при подключении его через устройство расширения WB-MIO или WB-MIO-E становится полноценным Modbus-устройством, для которого имеется соответствующий шаблон. По ссылке "Expand" можно увидеть полный код шаблона.
В этом шаблоне следует обратить внимание на следующие параметры устройства.
"protocol": "modbus_io",
"stride": 1000,
"shift": 500,
"max_read_registers": 0,
"setup": [
Параметр "protocol": "modbus_io" указывает, что устройство подключается оп специальному протоколу к модулю расширения. Параметры "stride": 1000 и "shift": 500 задают сдвиг регистров в зависимости от того, в каком порядке подключены модули к модулю расширения.
Сдвиг регистров (число, которое нужно добавить к базовому номеру регистра) вычисляется по формуле:
Shift = (((SlaveId.Secondary - 1) % 4) + 1) * DeviceConfig()->Stride + DeviceConfig()->Shift;
Здесь stride — DeviceConfig()->Stride, a shift — DeviceConfig()->Shift. Каждое подключенное устройство имеет порядковый номер (SlaveId.Secondary), начинающийся с 1 для первого устройства. (Здесь знаком "%" обозначается деление по модулю.) Например, подставляя значения shift и stride в формулу, получаем:
Shift = ((( 1 - 1) % 4) + 1) * 500 + 1000 = (0 + 1) * 500 + 1000 = 1500
То есть ко всем регистрам, указанным в шаблоне, надо добавить 1500.
Еще один важный параметр — setup-секция, массив
"setup": [ {
"title": "IODIR",
"address": 10000,
"value": "0x0000"
},
{},
...]
Он описывает регистры и значения, которые однократно заносятся в эти регистры при инициализации устройства (при запуске или перезапуске wb-mqtt-serial). Его можно использовать для конфигурирования устройств для работы в каком-то определенном режиме, задавать изначальные значения яркости, положения сервоприводов, состояния реле, режима работы с входами релейных модулей и т. п.
WB-MAP3H
Устройство WB-MAP3H — трехканальный счетчик электроэнергии. Он измеряет большое количество параметров электрической сети. Поскольку опрос всех регистров такого устройства может занять достаточно много времени, имеется несколько шаблонов, содержащих оптимальный набор параметров для решения текущей задачи. Мы рассмотрим базовый шаблон. По ссылке "Expand" можно увидеть полный код шаблона.
На что следует обратить внимание в этом шаблоне? В первую очередь в параметрах устройства мы указываем, что одновременно следует считывать не более 60 регистров, чтобы не останавливать надолго опрос остальных устройств: "max_read_registers": 60. Также показательным является параметр, описывающий накопленную реактивную энергию по фазе L1:
{
"name": "RP energy L1",
"reg_type": "input",
"address": "0x1224",
"type": "value",
"format": "u64",
"scale": 3.125e-05,
"round_to": 0.0001,
"word_order": "little_endian"
},
Здесь стоит обратить внимание на то, что адрес регистра может задаваться и в шестнадцатеричном виде: "address": "0x1224", вещественный коэффициент масштабирования можно задавать в экспоненциальной записи: "scale": 3.125e-05, при считывании значения округлять его до нужного порядка: "round_to": 0.0001, а также учитывать, что число в Modbus-регистрах хранится в порядке от младшего к старшему: "word_order": "little_endian". Форматы хранения для 16-битных Modbus регистров описываются следующим образом:
big-endian : ( [0xAA 0xBB] [0xCC 0xDD] => 0xAABBCCDD ) little-endian : ( [0xAA 0xBB] [0xCC 0xDD] => 0xCCDDAABB )
По умолчанию предполагается формат big-endian.
Типы переменных, используемых в шаблонах, перечислены в следующей таблице:
Обозначение | Тип |
---|---|
s16 | Signed 16-bit integer |
u16 | Unsigned 16-bit integer |
s8 | Signed 8-bit integer |
u8 | Unsigned 8-bit integer |
s24 | Signed 24-bit integer |
u24 | Unsigned 24-bit integer |
s32 | Signed 32-bit integer |
u32 | Unsigned 32-bit integer |
s64 | Signed 64-bit integer |
u64 | Unsigned 64-bit integer |
bcd8 | 8-bit BCD |
bcd16 | 16-bit BCD |
bcd24 | 24-bit BCD |
bcd32 | 32-bit BCD |
float | IEEE754 32-bit float |
double | IEEE754 64-bit float (double) |
char8 | 8-bit ASCII char |
Источники информации
В этой статье описаны основные правила создания шаблонов устройств для контроллеров Wiren Board. Информация изменяется и дополняется по мере обновления ПО и выходу новых продуктов. Самая полная и актуальная информация может быть найдена в следующих источниках:
- в описании сервиса wb-mqtt-serial на GitHub;
- в файлах самих шаблонов.
- в файле wb-mqtt-serial.schema.json на GitHub.