Wiren Board MQTT Serial

https://github.com/wirenboard/wb-mqtt-serial
Admin
A serial device to MQTT bridge for Wiren Board devices, supporting various master-slave protocols...
Tokens:7,528
Snippets:25
Trust Score:9.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Driver Control Commands

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Commands to manage the wb-mqtt-serial driver service using systemd, including starting, stopping, and checking its status. Also includes manual execution for debugging.

```shell
systemctl start wb-mqtt-serial
```

```shell
systemctl stop wb-mqtt-serial
```

```shell
systemctl status wb-mqtt-serial
```

```shell
# service wb-mqtt-serial stop
# wb-mqtt-serial -c /etc/wb-mqtt-serial.conf -d
```

--------------------------------

### Uniel Device Templates

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Device type mappings for Uniel lighting control and automation modules, including their unique identifiers and naming prefixes.

```markdown
| Device                               | device_type | id_prefix   | name_prefix      |
|:------------------------------------:|:-----------:|:-----------:|:-----------------|
| Модуль управления освещением UCH-M111RX | UCH-M111RX  | uchm111rx   | UCH-M111RX 0808  |
| Модуль управления автоматикой UCH-M121RX| UCH-M121RX  | uchm121rx   | UCH-M121RX 0808  |
| Диммер светодиодных ламп UCH-M141RC   | UCH-M141RC  | uchm141rc   | UCH-M141RC 0808  |
```

--------------------------------

### Logical Operators and Comparisons

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/test/expressions/good.txt

Demonstrates the use of standard logical operators (AND, OR, NOT) and comparison operators (==, !=, >, <, >=, <=) in expressions. These are fundamental for defining conditions.

```DSL
a==1
(a==1)
((a==1))
1==2
1==a
a!=1
a>1
a<1
a>=1
a<=1
a||1
a&&1
(a==1)&&1
(a==1)&&b
(a==1)&&(b==2)
((a==1)&&1)
1==(a&&2)
a==1&&2
a==1&&b==3
a==1&&b==3||c<4||c>5
a==1&&b==3||(c<4||c>5)
(a==1)&&(b==3)||(c<4)
(a==1)&&(b==3)||(c<4)||(d!=5)
(a==1)&&((b==3)||(c<4))||(d!=5)
```

--------------------------------

### Milur Device Templates

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Device type mappings for Milur electricity meters, including their unique identifiers and naming prefixes.

```markdown
| Device                                   | device_type   | id_prefix | name_prefix      |
|:----------------------------------------:|:-------------:|:---------:|:-----------------|
| Счётчик электроэнергии Милур-305         | milur305      | milur305  | Milur 305        |
| Счётчик электроэнергии Милур-105 (Милур-104) | Milur 104/105 | milur105  | Milur 105        |
```

--------------------------------

### Serial Port Configuration

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Defines the configuration for a serial port, including its path, communication parameters like baud rate, parity, data bits, and stop bits. It also lists the devices connected to this port.

```json
{
    "path": "/dev/ttyUSB0",
    "baud_rate": 9600,
    "parity": "N",
    "data_bits": 8,
    "stop_bits": 1,
    "enabled": true,
    "devices": [
        // ... device configurations ...
    ]
}
```

--------------------------------

### wb-mqtt-serial Group Definitions

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Defines groups for organizing parameters and channels in the web configurator interface. Groups can be nested and include titles, IDs, and descriptions.

```JSON
{
    "title": "Group 1",
    "id": "group1",
    "group": "group2",
    "description": "Group description"
}
```

--------------------------------

### Energomera MEK 61107 Device Templates

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Device type mappings for Energomera MEK 61107 electricity meters.

```markdown
| Device                     | device_type    | id_prefix      | name_prefix           |
|:---------------------------:|:--------------:|:--------------:|:---------------------:|
```

--------------------------------

### Pulsar Device Templates

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Device type mappings for Pulsar water and heat meters, including their unique identifiers and naming prefixes.

```markdown
| Device                         | device_type    | id_prefix      | name_prefix           |
|:------------------------------:|:--------------:|:--------------:|:---------------------:|
| Счётчик воды "Пульсар"         | pulsar-water   | pulsar-water   |  Pulsar Water Meter   |
| Счётчик воды многоструйный "Пульсар-М" | pulsar-m-water | pulsar-m-water |  Pulsar-M Water Meter |
| Счётчик тепла "Пульсар"        | pulsar-heat    | pulsar-heat    |  Pulsar Heat Meter    |
```

--------------------------------

### Wirenboard wb-mqtt-serial Configuration

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

This JSON configuration defines parameters for the wb-mqtt-serial service, including port settings, device configurations, and Modbus-specific options. It allows customization of communication timeouts, device enablement, and read/write behavior for Modbus devices.

```json
{
    "guard_interval_us": 1000,
    "connection_timeout_ms": 5000,
    "connection_max_fail_cycles": 2,
    "enabled": true,
    "devices": [
        {
            "device_type": "MSU34+TLP",
            "name": "MSU34+TLP",
            "id": "msu34tlp",
            "slave_id": 2,
            "enabled": true,
            "protocol": "modbus",
            "enable_wb_continuous_read": true,
            "max_reg_hole": 10,
            "max_bit_hole": 80,
            "max_read_registers": 10,
            "min_read_registers": 1
        }
    ]
}
```

--------------------------------

### wb-mqtt-serial Parameter Configuration

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Defines the properties for individual parameters within the wb-mqtt-serial configuration. This includes data types, addresses, scaling, default values, and conditional visibility.

```JSON
{
    "address": 9992,
    "write_address": 9995,
    "fw": "1.2.3",
    "reg_type": "input",
    "format": "s8",
    "enum": [
        1,
        2,
        3
    ],
    "enum_titles": [
        "one",
        "two",
        "three"
    ],
    "default": 2,
    "min": 1,
    "max": 3,
    "scale": 2,
    "offset": 10,
    "required": true,
    "order": 1,
    "group": "group1",
    "condition": "isDefined(param1)&&(param2==1)||(param3>5)",
    "readonly": true
}
```

--------------------------------

### wb-mqtt-serial Channel Definitions

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Describes how to define channels, which represent data from device registers. Includes mapping to registers, data formats, and conditional availability.

```JSON
{
    "name": "Temperature",
    "reg_type": "input",
    "format": "s32",
    "address": "0x0504",
    "group": "group1",
    "condition": "(param2==1)||(param3==5)"
}
```

--------------------------------

### Channel Configuration

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Defines a specific channel for a device, including its name, Modbus register type (coil, input, holding, etc.), address, and data type (e.g., switch). Custom values like 'on_value' can also be specified.

```json
{
    "name": "Relay 1",
    "reg_type": "coil",
    "address": 0,
    "type": "switch"
},
{
    "name": "Input 2",
    "reg_type": "input",
    "address": 1,
    "type": "switch",
    "on_value": 101
}
```

--------------------------------

### Device Configuration

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Specifies a connected device, including its name, unique ID, enabled status, and Modbus slave ID. It also lists the channels associated with this device.

```json
{
    "name": "tM-P3R3",
    "id": "tmp3r3",
    "enabled": true,
    "slave_id": 1,
    "channels": [
        // ... channel configurations ...
    ]
}
```

--------------------------------

### Modbus-RTU Device Templates

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Device type mappings for Modbus-RTU devices, including their unique identifiers and naming prefixes.

```markdown
| Device                                                     | device_type    | id_prefix      | name_prefix      |
|:-----------------------------------------------------------:|:--------------:|:--------------:|:-----------------|
| "Разумный дом" четырёхканальный диммер светодиодов DDL4     |    DDL24       |   ddl24        |    DDL24         |
| "Разумный дом" релейный модуль DRB88                      |    DRB88       |   drb88        |    DRB88         |
| RD DDL04R LED Strip Dimmer                                 |    DDL04R      |   ddl04r       |    DDL04R        |
| "ICP DAS" модуль управления освещением LC-103              |    LC-103      |   lc-103       |    LC-103        |
| "Разумный дом" MSU24                                     |    MSU24       |   msu24        |    MSU24         |
| "Разумный дом" MSU21                                     |    MSU21       |   msu21        |    MSU21         |
| "Разумный дом" MSU34+TLP                                 |    MSU34       |   msu34tlp     |  MSU34+TLP       |
| "Разумный дом" MSU34+TLHP                                | MSU34TLHP      | msu34tlhp      |  MSU34+TLHP      |
| "ICP DAS" модуль ввода-вывода TM-P3R3                      |   TM-P3R3      |  TM-P3R3       |    tmp3r3        |
| "Kvadro" модуль подключения термометров 1-wire           |kvadro-1wire    |kvadro-1wire    | Kvadro 1-Wire    |
| PD561Z-9SY счётчик электроэнергии                          |    PD561Z      |  pd561z        | pd561z           |
| SDM220 счётчик электроэнергии                              |    SDM220      |  sdm220        |  sdm220          |
| SDM120 счётчик электроэнергии                              |    SDM120      |  sdm120        |  sdm120          |
| WELLPRO WP8028ADAM (8DI/8DO)                               | WP8028ADAM     | wp8028adam     |   WP8028ADAM     |
| Wiren Board RGB-диммер WB-MRGB                             |   WB-MRGB      |  WB-MRGB       |   wb-mrgb        |
| Wiren Board Релейный модуль WB-MRM2                        |   WB-MRM2      |  WB-MRM2       |   wb-mrm2        |
| Wiren Board Релейный модуль WB-MR11                        |   WB-MR11      |  WB-MR11       |   wb-mr11        |
| Wiren Board Релейный модуль WB-MR14                        |   WB-MR14      |  WB-MR14       |   wb-mr14        |
| Wiren Board модуль дискретных/счётных входов WB-MCM16      |   WB-MCM16     |  WB-MCM16      |   wb-mcm16       |
| Wiren Board Датчик WB-MS-THLS / WB-MSW-THLS                |  WB-MS-THLS    | wb-ms-thls     | WB-MS-THLS       |
| Wiren Board Датчик WB-MS-THLS / WB-MSW-THLS  (fw. v.2)      |  WB-MS-THLS v.2| wb-ms-thls     | WB-MS-THLS       |
| Peacefair PZEM-016                                         |  PZEM-016      | pzem           | PZEM             |
```

--------------------------------

### Modbus Byte and Word Order

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Specifies the byte and word ordering for multi-register data types. 'word_order' defines the sequence of 16-bit words, while 'byte_order' defines the sequence of bytes within a word.

```json
{
    "word_order": "big_endian" // [0xAA 0xBB] [0xCC 0xDD] => 0xAABBCCDD
}
{
    "word_order": "little_endian" // [0xAA 0xBB] [0xCC 0xDD] => 0xCCDDAABB
}
{
    "byte_order": "big_endian" // [0x12 0x34] => 0x1234
}
{
    "byte_order": "little_endian" // [0x12 0x34] => 0x3412
}
```

--------------------------------

### isDefined Function Usage

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/test/expressions/good.txt

Illustrates the usage of the 'isDefined' function, which likely checks if a variable or parameter is set or has a value. It can be used in conjunction with logical operators.

```DSL
isDefined(a)
isDefined(a)&&isDefined(b)
a==1&&isDefined(a)
a==1&&(isDefined(a))
a==1&&isDefined(a)||b==3&&isDefined(b)
a==1&&(isDefined(a)||b==3&&isDefined(b))
```

--------------------------------

### IVTM Device Templates

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Device type mappings for IVTM temperature and humidity sensors, including their unique identifiers and naming prefixes.

```markdown
| Device                     | device_type | id_prefix | name_prefix   |
|:---------------------------:|:-----------:|:---------:|:-------------:|
| Термогигрометр ИВТМ-7 М 3   | IVTM-7M-3   | ivtm7m3   | IVTM-7M-3     |
```

--------------------------------

### Modbus Register Configuration

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Defines parameters for configuring Modbus registers, including register type, addresses for reading and writing, and data formatting. It supports various data types like integers, floats, and strings, with options for byte and word ordering.

```json
{
    "reg_type": "input",
    "address": "109:1:2",
    "write_address": 10,
    "type": "temperature",
    "format": "s8",
    "word_order": "big_endian",
    "byte_order": "big_endian",
    "string_data_size": 10
}
```

--------------------------------

### Conditional Expression with isDefined and Comparison

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/test/expressions/good.txt

Shows a more complex conditional expression involving checking if a variable's value is equal to a specific number (0) and then negating that result. This pattern is common for boolean logic.

```DSL
(isDefined(in1_mode)==0||in1_mode==0)==0
```

--------------------------------

### Modbus Data Format Options

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Lists the supported data formats for Modbus registers, specifying how data is interpreted. This includes various integer sizes (u16, s16, u32, s32, s64, u64), floating-point numbers (float, double), characters, BCD codes, and strings.

```json
{
    "format": "u16" // Unsigned 16-bit integer (default)
}
{
    "format": "s16" // Signed 16-bit integer
}
{
    "format": "u8"  // Unsigned 8-bit integer
}
{
    "format": "s8"  // Signed 8-bit integer
}
{
    "format": "u32" // Unsigned 32-bit integer (2 registers)
}
{
    "format": "s32" // Signed 32-bit integer (2 registers)
}
{
    "format": "s64" // Signed 64-bit integer (4 registers)
}
{
    "format": "u64" // Unsigned 64-bit integer (4 registers)
}
{
    "format": "float" // IEEE 754 float, 32-bit (2 registers)
}
{
    "format": "double" // IEEE 754 double, 64-bit (4 registers)
}
{
    "format": "char8" // Single-byte ASCII character
}
{
    "format": "bcd8"  // 8-bit BCD
}
{
    "format": "bcd16" // 16-bit BCD
}
{
    "format": "bcd24" // 24-bit BCD
}
{
    "format": "bcd32" // 32-bit BCD
}
{
    "format": "string" // String with configurable size, byte order dependent
}
{
    "format": "string8" // String, 2 chars per register, byte order dependent
}
```

--------------------------------

### Modbus Register Type Specifics

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Details specific behaviors for different Modbus register types. 'holding_multi' writes registers using code 16, while 'press_counter' (type 'input') resets to 0 after reboot and only publishes non-zero values.

```json
{
    "reg_type": "holding_multi" // Same as "holding", but registers are always written with code 16
}
{
    "reg_type": "input" // Same as "input", for registers that reset to 0 after reboot (0 is not published, next non-zero value is)
}
```

--------------------------------

### Mercury 230 Device Templates

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Device type mappings for Mercury 230 electricity meters, including their unique identifiers and naming prefixes.

```markdown
| Device                     | device_type | id_prefix      | name_prefix      |
|:---------------------------:|:-----------:|:--------------:|:-----------------|
| Счётчик электроэнергии Меркурий-230 | mercury230  | mercury230ar02 | Mercury 230AR-02 |
```

--------------------------------

### Scan Devices via Modbus RPC

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Initiates a device scan using Fast Modbus via an MQTT RPC request. The request can target a serial port or a network IP address. The response contains details of discovered devices or any errors encountered during the scan.

```APIDOC
MQTT RPC Request for Device Scan:

Topic: wb-mqtt-serial/port/Scan/client_id

Request Payload (Serial Port Scan):
```json
{
    "path": "/dev/ttyRS485-1",
    "baud_rate": 115200,
    "parity": "N",
    "data_bits": 8,
    "stop_bits": 2,
    "command": 70
}
```

Request Payload (Network Scan):
```json
{
    "ip": "1.1.1.1",
    "port": 1234,
    "command": 70
}
```

Parameters:
- `path` (string, optional): The serial port path for scanning (e.g., "/dev/ttyRS485-1"). Required for serial scans.
- `ip` (string, optional): The IP address of the gateway for network scanning (e.g., "1.1.1.1"). Required for network scans.
- `port` (integer, optional): The port number of the gateway for network scanning (e.g., 1234). Required for network scans.
- `baud_rate` (integer, optional): The serial port baud rate (e.g., 115200). Used for serial scans.
- `parity` (string, optional): The serial port parity ('N', 'O', or 'E'). Used for serial scans.
- `data_bits` (integer, optional): The number of data bits for the serial port (e.g., 8). Used for serial scans.
- `stop_bits` (integer, optional): The number of stop bits for the serial port (e.g., 2). Used for serial scans.
- `command` (integer, optional): The Fast Modbus command to use for scanning. Defaults to 70 (0x46). 96 (0x60) is an older command.

Response Payload (Success):
```json
{
    "devices": [
        {
            "sn": "13453ghh",
            "device_signature": "WBMR6C",
            "fw_signature": "mr6cG",
            "configured_device_type": "WB-MR6C",
            "errors": [
                {
                    "id": "com.wb.device_manager.device.read_device_signature_error",
                    "message": "Failed to read device signature."
                }
            ],
            "cfg": {
                "slave_id": 100,
                "baud_rate": 9600,
                "parity": "N",
                "data_bits": 8,
                "stop_bits": 2
            },
            "fw": {
                "version": "1.2.3"
            }
        }
    ],
    "error": null
}
```

Response Payload (Error):
```json
{
    "devices": [
        {
            "sn": "13453ghh",
            "device_signature": "WBMR6C",
            "fw_signature": "mr6cG",
            "configured_device_type": "WB-MR6C",
            "errors": [
                {
                    "id": "com.wb.device_manager.device.read_device_signature_error",
                    "message": "Failed to read device signature."
                }
            ],
            "cfg": {
                "slave_id": 100,
                "baud_rate": 9600,
                "parity": "N",
                "data_bits": 8,
                "stop_bits": 2
            },
            "fw": {
                "version": "1.2.3"
            }
        }
    ],
    "error": "Serial timeout error"
}
```

Response Parameters:
- `devices` (array of objects): A list of discovered devices. Each device object may contain:
    - `sn` (string): Serial number of the device.
    - `device_signature` (string): Signature of the device.
    - `fw_signature` (string): Signature of the device's firmware.
    - `configured_device_type` (string, optional): The device type configured in wb-mqtt-serial.
    - `errors` (array of objects, optional): List of errors encountered for this specific device.
    - `cfg` (object, optional): Current configuration settings of the device.
    - `fw` (object, optional): Firmware details of the device.
- `error` (string, optional): An error message if the scan process failed. If an error occurs, the `devices` array may still contain partially discovered devices.
```

--------------------------------

### Modbus Register Address Format

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Explains the custom format for specifying Modbus register addresses, including register offset, bit shift, and width. This format allows precise targeting of specific bits within registers.

```json
//   "address": "reg:shift:width", где
//     reg — адрес первого регистра,
//     shift — смещение от младшего бита первого регистра,
//     width — количество записываемых битов
// Например, "address": "109:1:2" — записать второй и третий биты регистра, расположенного по адресу 109.
"address": "109:1:2"
```

--------------------------------

### Modbus Register Types and Formats

Source: https://github.com/wirenboard/wb-mqtt-serial/blob/master/README.md

Illustrates the use of 'reg_type' for Modbus operations and 'format' for data interpretation. Common 'reg_type' values include 'holding', 'coil', 'input'. 'format' can specify data types like 'u16', 's8'.

```json
{
    "name": "Example Channel",
    "reg_type": "holding",
    "address": 109,
    "format": "s8"
}
```
Tokens:
Raw