¶ Руководство пользователя. Драйвер Modbus2mqtt
Modbus2mqtt — это приложение, которое предназначено для взаимодействия с устройствами Modbus RTU/ Modbus RTU-over-TCP / Modbus TCP. Оно позволяет собирать данные от Modbusустройств и публиковать их в брокере MQTT, форматировать полученные данные.
Приложение предназначено для использования в системах, где необходима интеграция различных устройств Modbus с брокером MQTT для обработки данных в реальном времени.
¶ Назначение
Modbus2mqtt решает следующие задачи:
- Автоматический сбор данных с устройств по протоколу Modbus;
- Публикация данных в локальный брокер MQTT для дальнейшего анализа и мониторинга;
- Управление через подписку на топики MQTT.
¶ Основные функции
- Опрос устройств по протоколам Modbus RTU / Modbus RTU-over-TCP / Modbus TCP: Приложение позволяет подключаться как к Modbus RTU-устройствам через COM-порты, так и к Modbus TCP-устройствам через сеть (IP-адреса). Это обеспечивает возможность интеграции разных типов Modbus-устройств.
- Публикация данных в MQTT: Автоматическая отправка данных с Modbus-устройств в заданные топики локального брокера MQTT, что делает данные доступными для анализа в реальном времени.
- Гибкая настройка через YAML-файлы: Пользователи могут легко настраивать COM-порты, параметры устройств и регистров через YAML- файлы конфигурации. Это позволяет быстро адаптировать приложение под различные системы.
- Поддержка повторных запросов и подключений: В случае сетевых ошибок или сбоев подключения к устройствам Modbus, приложение автоматически пытается повторить попытку подключения через заданные интервалы времени.
- Логирование и диагностика: Приложение ведет подробные логи, позволяя пользователям отслеживать процессы подключения, публикации данных и возникающие ошибки. Это помогает в диагностике проблем и мониторинге системы.
¶ Функционал и реализация
¶ Типы данных
| YAML-ключ | Описание | Диапазон | Размер (байт) | Код функции для чтения | Код функции для записи |
|---|---|---|---|---|---|
| u16 / word / uint16 | 16-разрядное беззнаковое целое число | 0 до 65535 | 2 | 03, 04 | 06, 16, 22 |
| s16 / shortInt / int16 | 16-разрядное знаковое целое число | -32768 до 32767 | 2 | 03, 04 | 06, 16 |
| u32 / dword / uint32 | 32-разрядное беззнаковое целое число | 0 до 4294967295 | 4 | 03, 04 | 16 |
| s32 / integer / int32 | 32-разрядное знаковое целое число | -2147483648 до 2147483647 | 4 | 03, 04 | 16 |
| u64 / uint64 | 64-разрядное беззнаковое целое число | 0 до 18446744073709551615 | 8 | 03, 04 | 16 |
| s64 / int64 | 64-разрядное знаковое целое число | -9223372036854775808 до 9223372036854775807 | 8 | 03, 04 | 16 |
| f32 / float | 32-разрядное число с плавающей запятой | 4 | 03, 04 | 16 | |
| f64 / double | 64-разрядное число с плавающей запятой | 8 | 03, 04 | 16 | |
| boolean / bool | Булева переменная (0 или 1) | 1-0 | 1 | 01, 02 |
¶ Modbus порядок байт/порядок слов
Порядок байт выставляется в параметре byteorder
Для 16 битных типов данных:
- B1 B2 big;
- B1 B2 => B2 B1 little.
- B1 B2 => B2 B1 middle
Для 32 битных типов данных:
- B1 B2 B3 B4 big;
- B1 B2 B3 B4 => B2 B1 B4 B3 bigswap;
- B1 B2 B3 B4 => B2 B1 B4 B3 middle
- B1 B2 B3 B4 => B4 B3 B2 B1 little;
- B1 B2 B3 B4 => B3 B4 B1 B2 littleswap.
Для 64 битных типов данных:
- B1 B2 B3 B4 B5 B6 B7 B8 big;
- B1 B2 B3 B4 B5 B6 B7 B8 => B2 B1 B4 B3 B6 B5 B8 B7 bigswap;
- B1 B2 B3 B4 B5 B6 B7 B8 => B2 B1 B4 B3 B6 B5 B8 B7 middle
- B1 B2 B3 B4 B5 B6 B7 B8 => B8 B7 B6 B5 B4 B3 B2 B1 little;
- B1 B2 B3 B4 B5 B6 B7 B8 => B7 B8 B5 B6 B3 B4 B1 B2 littleswap.
Порядок слов выставляется в параметре wordorder
Для 64 битных типов данных:
- B1 B2 B3 B4 B5 B6 B7 B8 high;
- B1 B2 B3 B4 B5 B6 B7 B8 => B5 B6 B7 B8 B1 B2 B3 B4 low.
¶ Modbus функции чтения-записи
| Описание в YAMl | Название | Описание |
|---|---|---|
| coil | Read Coil 0x01 | Чтение состояния дискретных выводов(катушек) |
| discrete | Read Discrete Inputs 0x02 | Чтение состояния дискретных выходов |
| holding | Read Holding Registers 0x03 | Чтение регистров хранения |
| input | Read Input Registers 0x04 | Чтение входных регистров |
| 5 | Write Single Coil 0x05 | Запись одного дискретного вывода |
| 6 | Write Single Register 0x06 | Запись одного регистра хранения |
| 16 | Write Multiple Registers 0x10 | Запись нескольких регистров хранения |
| 22 | Mask Write Register (0x16) | Запись битовой маски |
¶ Настройки MQTT
| YAML-ключ | Описание | Допустимые значения | Обязательный/Необязательный | Значение по умолчанию |
|---|---|---|---|---|
| broker | URL брокера | ip:port, tcp://ip:port, ssl://ip:port, unix://path/to/file. Для TCP/SSL допускается IPv4 или localhost | Необязательный | tcp://127.0.0.1:1883 |
| client_id | Идентификатор клиента | Строка | Необязательный | smartgate.modbus2mqtt |
| max_retries | Максимальное количество попыток подключения к брокеру | 0–2000; 0 — бесконечные попытки до успешного подключения или остановки сервиса | Необязательный | 0 |
| retry_interval | Интервал между попытками подключения/переподключения, с | 1–300 | Необязательный | 30 |
| clean_session | MQTT clean session | true / false | Необязательный | true |
| autoreconnect | Автоматическое переподключение клиента MQTT | true / false | Необязательный | true |
| keepalive | Параметр keepalive в секундах | 1–240 | Необязательный | 60 |
| ping_timeout | Тайм-аут ожидания MQTT ping, с | 1–60 | Необязательный | 10 |
| connect_timeout | Тайм-аут подключения к брокеру, с | 1–60 | Необязательный | 30 |
| pub_qos | QoS для публикаций данных в MQTT | 0, 1, 2 | Необязательный | 0 |
| retained | Retained-флаг MQTT-сообщений | true / false | Необязательный | false |
| username | Логин для аутентификации | Строка; обязательно при использовании password | Необязательный | — |
| password | Пароль для аутентификации | Строка; обязательно при использовании username | Необязательный | — |
¶ Настройки mqtt.tls
| YAML-ключ | Описание | Допустимые значения | Обязательный/Необязательный | Значение по умолчанию |
|---|---|---|---|---|
| ca_cert_file | Путь к CA-сертификату брокера | Путь к PEM-файлу | Обязательный, если insecure_skip_verify=false | — |
| cert_file | Путь к клиентскому сертификату | Путь к PEM-файлу | Необязательный; обязателен при использовании key_file | — |
| key_file | Путь к клиентскому ключу | Путь к PEM-файлу | Необязательный; обязателен при использовании cert_file | — |
| insecure_skip_verify | Отключение проверки сертификата сервера | true / false | Необязательный | true, если задан хотя бы один TLS-файл; иначе TLS не используется |
¶ Настройка metadata
| Описание в YAMl | Название | Описание / Допустимые значения |
|---|---|---|
| enabled | Опция активации и деактивации метаинформации в payload; по умолчанию true | true - payload в формате json с метаин-формацией false - payload только с value |
¶ Настройка логирования
| YAML-ключ | Описание | Допустимые значения | Обязательный/Необязательный | Значение по умолчанию |
|---|---|---|---|---|
| level_log | Уровень логирования | 1–6 (см. уровни логирования) | Необязательный | 1 |
| path_log | Путь к лог-файлу | mnt/data/etc/andromeda_embedded/log/modbus2mqtt.log | Необязательный | — |
| path_json_log | Путь к JSON-лог-файлу | Путь до 255 символов | Необязательный | — |
| max_size_log | Максимальный размер файла в мегабайтах | 1–5 | Необязательный | 2 |
| max_backups_log | Максимальное количество резервных копий | 0–300 | Необязательный | 10 |
| max_age_log | Максимальный возраст файлов в днях | 0–30 | Необязательный | 1 |
¶ Уровни логирования
| level_log | Будут выводиться сообщения уровня: |
|---|---|
| 1 | INFO, WARN, ERROR |
| 2 | WARN, ERROR |
| 3 | DEBUG, INFO, WARN, ERROR |
| 4 | ERROR |
| 5 | MONITOR, DEBUG, INFO, WARN, ERROR |
| 6 | MONITOR |
INFO
Modbus2MQTT. Все права защищены.
2026-06-16 12:27:21.805 [INFO] [component:ConfigManager] Чтение конфигурационного файла [файл конфигурации:configs/modbus2mqtt/modbus.yaml]
2026-06-16 12:27:21.805 [INFO] [component:ConfigManager] Режим сборки [license_mode:FULL]
2026-06-16 12:27:21.805 [INFO] [component:ConfigManager] использовано стандартное значение: 30 [path:modbus.mqtt.connect_timeout]
2026-06-16 12:27:21.805 [INFO] [component:ConfigManager] использовано стандартное значение: 0 [path:modbus.mqtt.pub_qos]
2026-06-16 12:27:21.805 [INFO] [component:ConfigManager] использовано стандартное значение: false [path:modbus.mqtt.retained]
2026-06-16 12:27:21.805 [INFO] [component:ValidateConfig] Настройки логирования [Уровень:1 | Запись в файл:false]
2026-06-16 12:27:21.805 [INFO] [component:ValidateConfig] Успешная инициализация файлов конфигурации [Время инициализации:341.292µs]
2026-06-16 12:27:21.805 [INFO] [component:CoreApp] Modbus2MQTT успешно инициализирован 🚀 [ver:2.5.0]
DEBUG
Modbus2MQTT. Все права защищены.
2026-06-16 12:27:21.805 [INFO] [component:ConfigManager] Чтение конфигурационного файла [файл конфигурации:configs/modbus2mqtt/modbus.yaml]
2026-06-16 12:27:21.805 [INFO] [component:ConfigManager] Режим сборки [license_mode:FULL]
2026-06-16 12:27:21.805 [INFO] [component:ConfigManager] использовано стандартное значение: 30 [path:modbus.mqtt.connect_timeout]
2026-06-16 12:27:21.805 [INFO] [component:ConfigManager] использовано стандартное значение: 0 [path:modbus.mqtt.pub_qos]
2026-06-16 12:27:21.805 [INFO] [component:ConfigManager] использовано стандартное значение: false [path:modbus.mqtt.retained]
2026-06-16 12:27:21.805 [INFO] [component:ValidateConfig] Настройки логирования [Уровень:1 | Запись в файл:false]
2026-06-16 12:27:21.805 [INFO] [component:ValidateConfig] Успешная инициализация файлов конфигурации [Время инициализации:341.292µs]
2026-06-16 12:27:21.805 [INFO] [component:CoreApp] Modbus2MQTT успешно инициализирован 🚀 [ver:2.5.0]
2026-06-16 12:33:21.985 [INFO] [component:MQTTClient] Соединение с брокером установлено
2026-06-16 12:33:21.984 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Публикация сообщения [Topic:/devices/device_tcp_1/controls/level1 | Payload:27427]
2026-06-16 12:33:21.984 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Публикация сообщения [Topic:/devices/device_tcp_1/controls/level2 | Payload:27427]
2026-06-16 12:33:21.984 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Публикация сообщения [Topic:/devices/device_tcp_1/controls/level3 | Payload:27427]
2026-06-16 12:33:21.984 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Публикация сообщения [Topic:/devices/device_tcp_1/controls/level4 | Payload:27427]
2026-06-16 12:33:21.984 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Публикация сообщения [Topic:/devices/device_tcp_1/controls/level1 | Payload:27427]
MONITOR (5)
Modbus2MQTT. Все права защищены.
2025-09-30T10:49:01.094 [INFO] [component:ConfigManager] Чтение конфигурационного файла [файл конфигурации:configs/modbus2mqtt/modbus.yaml]
2025-09-30T10:49:01.094 [INFO] [component:ConfigManager] Режим сборки [license_mode:FULL]
2025-09-30T10:49:01.094 [INFO] [component:ValidateConfig] Настройки логирования [Уровень:1 | Запись в файл:false]
2025-09-30T10:49:01.095 [INFO] [component:ValidateConfig] Успешная инициализация файлов конфигурации [Время инициализации:341.292µs]
2025-09-30T10:49:01.095 [INFO] [component:CoreApp] Modbus2MQTT успешно инициализирован 🚀 [ver:2.5.0]
2026-06-16 12:33:21.985 [INFO] [component:MQTTClient] Соединение с брокером установлено
2025-09-30T10:49:01.099 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502]
2025-09-30T10:49:01.099 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Публикация MQTT с адаптивными параметрами [packSize:50 | flushInterval_ms:100]
2025-09-30T10:49:01.099 [INFO] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запуск публикации данных в MQTT
2025-09-30T10:49:01.099 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Соединение успешно установлено
2025-09-30T10:49:01.099 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Инициализация подписки на управляющие сообщения [Topic:/devices/device_tcp_1/controls/parameter_name4/on]
2025-09-30T10:49:01.100 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запрос: 00 01 00 00 00 06 01 04 00 01 00 02
2025-09-30T10:49:01.100 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Ответ: 00 01 00 00 00 07 01 04 04 46 d7 46 d8
2025-09-30T10:49:01.201 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Публикация сообщения [Topic:/devices/device_tcp_1/controls/level1 | Payload:27555]
2025-09-30T10:49:02.101 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запрос: 00 02 00 00 00 06 01 04 00 01 00 02
2025-09-30T10:49:02.102 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Ответ: 00 02 00 00 00 07 01 04 04 46 d7 46 d8
2025-09-30T10:49:02.203 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Публикация сообщения [Topic:/devices/device_tcp_1/controls/level1 | Payload:27555]
2025-09-30T10:49:03.101 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запрос: 00 03 00 00 00 06 01 04 00 01 00 02
2025-09-30T10:49:03.102 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Ответ: 00 03 00 00 00 07 01 04 04 46 d7 46 d8
2025-09-30T10:49:03.203 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Публикация сообщения [Topic:/devices/device_tcp_1/controls/level1 | Payload:27555]
2025-09-30T10:49:04.101 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запрос: 00 04 00 00 00 06 01 04 00 01 00 02
2025-09-30T10:49:04.101 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Ответ: 00 04 00 00 00 07 01 04 04 46 d7 46 d8
2025-09-30T10:49:04.203 [DEBUG] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Публикация сообщения [Topic:/devices/device_tcp_1/controls/level1 | Payload:27555]
MONITOR (6)
Modbus2MQTT. Все права защищены.
2025-09-30T10:49:01.094 [INFO] [component:ConfigManager] Чтение конфигурационного файла [файл конфигурации:configs/modbus2mqtt/modbus.yaml]
2025-09-30T10:49:01.094 [INFO] [component:ConfigManager] Режим сборки [license_mode:FULL]
2025-09-30T10:49:01.094 [INFO] [component:ValidateConfig] Настройки логирования [Уровень:1 | Запись в файл:false]
2025-09-30T10:49:01.095 [INFO] [component:ValidateConfig] Успешная инициализация файлов конфигурации [Время инициализации:341.292µs]
2025-09-30T10:49:01.095 [INFO] [component:CoreApp] Modbus2MQTT успешно инициализирован 🚀 [ver:2.5.0]
2026-06-16 12:33:21.985 [INFO] [component:MQTTClient] Соединение с брокером установлено
2025-09-30T10:50:04.233 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502]
2025-09-30T10:50:04.233 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502]
2025-09-30T10:50:04.234 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запрос: 00 01 00 00 00 06 01 04 00 01 00 02
2025-09-30T10:50:04.235 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Ответ: 00 01 00 00 00 07 01 04 04 46 d7 46 d8
2025-09-30T10:50:05.236 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запрос: 00 02 00 00 00 06 01 04 00 01 00 02
2025-09-30T10:50:05.236 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Ответ: 00 02 00 00 00 07 01 04 04 46 d7 46 d8
2025-09-30T10:50:06.235 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запрос: 00 03 00 00 00 06 01 04 00 01 00 02
2025-09-30T10:50:06.235 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Ответ: 00 03 00 00 00 07 01 04 04 46 d7 46 d8
2025-09-30T10:50:07.236 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запрос: 00 04 00 00 00 06 01 04 00 01 00 02
2025-09-30T10:50:07.236 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Ответ: 00 04 00 00 00 07 01 04 04 46 d7 46 d8
2025-09-30T10:50:08.236 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запрос: 00 05 00 00 00 06 01 04 00 01 00 02
2025-09-30T10:50:08.236 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Ответ: 00 05 00 00 00 07 01 04 04 46 d7 46 d8
2025-09-30T10:50:09.235 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Запрос: 00 06 00 00 00 06 01 04 00 01 00 02
2025-09-30T10:50:09.235 [MONITOR] [Сервер:device_tcp_1 | UnitID:1 | IP:192.168.1.172:1502] Ответ: 00 06 00 00 00 07 01 04 04 46 d7 46 d8
¶ Настройки COM-порта
| YAML-ключ | Описание | Допустимые значения | Обязательный/Необязательный | Значение по умолчанию |
|---|---|---|---|---|
| port | Путь к COM-порту | Например, /dev/ttyS1 | Обязательный | — |
| settings 9600:8:N:1 | Настройки COM (строка целиком) | Обязательный | — | |
| 9600 | Скорость порта | 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200 | Обязательный | — |
| 8 | Количество бит данных | 5, 6, 7, 8 | Обязательный | — |
| N | Тип чётности | N, E, O | Обязательный | — |
| 1 | Количество стоп-бит | 1, 2 | Обязательный | — |
| timeout | Время ожидания ответа, мс | 500–10000 | Необязательный | 500 |
¶ Настройки VCOM-порта
| YAML-ключ | Описание | Допустимые значения | Обязательный/Необязательный | Значение по умолчанию |
|---|---|---|---|---|
| ip | IP адрес | 192.168.100.1 | Обязательный | — |
| port | Порт | 1–65535 | Обязательный | — |
¶ Настройки сервера Modbus TCP
| YAML-ключ | Описание | Обязательный/Необязательный | Значение по умолчанию | Пример |
|---|---|---|---|---|
| name | Имя устройства | Обязательный | — | modbus_device_tcp1 |
| enabled | Активация/деактивация устройства true/false | Обязательный | — | true |
| root_topic_mqtt | root топик | Обязательный | — | bAf0r0_bAf0r0_0_n1_climate |
| ip | IP сервера:Port сервера | Обязательный | — | 127.0.0.1:502 |
| unit_id | ID сервера Modbus TCP | Обязательный | — | 10 |
| use_shared_connection | Использование 1 TCP соединения для группы устройств | Обязательный | — | false |
| response_timeout_ms | Максимальное время ответа устройств, мс (500–20000) | Необязательный | 500 | 2000 |
| request_timeout_ms | Задержка между запросами к серверу, мс (0–1000) | Необязательный | 0 | 5 |
| idle_timeout_s | Время без данных до закрытия TCP соединения, с (10–120) | Необязательный | 60 | 60 |
| retries | Кол-во попыток повтора соединения с тайм-аутом time_retries (1–500) | Необязательный | 10 | 100 |
| time_retries_s | Тайм-аут между попытками повтора соединения, с (1–300) | Необязательный | 10 | 10 |
| time_reconnect_s | Тайм-аут повтора соединения после retries, с (1–600) | Необязательный | 300 | 300 |
| global_publish_interval | Период гарантированной отправки данных независимо от апертур, с (0–3600). Если не указано или 0 — апертуры не работают | Необязательный | 0 | 3600 |
¶ Настройки сервера Modbus RTU
| YAML-ключ | Описание | Обязательный/Необязательный | Значение по умолчанию | Пример |
|---|---|---|---|---|
| name | Имя устройства | Обязательный | — | modbus_device_rtu1 |
| enabled | Активация/деактивация устройства true/false | Обязательный | — | true |
| root_topic_mqtt | root топик | Обязательный | — | bAf0r0_bAf0r0_0_n1_climate |
| com_port | Ссылка на com port из файла настроек modbus.yaml | Обязательный | — | com1 |
| unit_id | ID сервера Modbus RTU | Обязательный | — | 10 |
| frame_timeout_ms | Время между командами на чтение, мс (5–5000). При ошибке типа serial: timeout увеличиваем время между запросами | Необязательный | 20 | 20 |
| retries | Кол-во попыток повтора соединения с тайм-аутом time_retries (1–500) | Необязательный | 10 | 100 |
| time_retries_s | Тайм-аут между попытками повтора соединения, с (1–300) | Необязательный | 10 | 10 |
| time_reconnect_s | Тайм-аут повтора соединения после retries, с (1–600) | Необязательный | 300 | 300 |
| global_publish_interval | Период гарантированной отправки данных независимо от апертур, с (0–3600). Если не указано или 0 — апертуры не работают | Необязательный | 0 | 3600 |
¶ Настройки сервера Modbus RTUoverTCP
| YAML-ключ | Описание | Обязательный/Необязательный | Значение по умолчанию | Пример |
|---|---|---|---|---|
| name | Имя устройства | Обязательный | — | modbus_device_rtuovertcp1 |
| enabled | Активация/деактивация устройства true/false | Обязательный | — | true |
| root_topic_mqtt | root топик | Обязательный | — | bAf0r0_bAf0r0_0_n1_climate |
| vcom_port | Ссылка на vcom port из файла настроек modbus.yaml | Обязательный | — | vcom1 |
| unit_id | ID сервера Modbus RTU | Обязательный | — | 10 |
| request_timeout_ms | Задержка между запросами к серверу, мс (0–1000) | Необязательный | 0 | 5 |
| response_timeout_ms | Максимальное время ответа устройств, мс (500–20000) | Необязательный | 500 | 2000 |
| idle_timeout_s | Время без данных до закрытия TCP соединения, с (10–120) | Необязательный | 60 | 60 |
| frame_timeout_ms | Время между командами на чтение, мс (5–5000). При ошибке типа serial: timeout увеличиваем время между запросами | Необязательный | 20 | 20 |
| retries | Кол-во попыток повтора соединения с таймаутом time_retries (1–500) | Необязательный | 10 | 100 |
| time_retries_s | Тайм-аут между попытками повтора соединения, с (1–300) | Необязательный | 10 | 10 |
| time_reconnect_s | Тайм-аут повтора соединения после retries, с (1–600) | Необязательный | 300 | 300 |
| global_publish_interval | Период гарантированной отправки данных независимо от апертур, с (0–3600). Если не указано или 0 — апертуры не работают | Необязательный | 0 | 3600 |
¶ Настройки чтения параметров Modbus
| YAML-ключ | Описание | Обязательный/Необязательный | Значение по умолчанию | Пример |
|---|---|---|---|---|
| read_period_ms | Частота опроса каналов slave-устройства, мс (100–60000) | Обязательный | — | 5000 |
| publish_period_s | Период публикации данных независимо от апертуры, с (0–3600). Если 0 — публикация по этому таймеру выключена | Необязательный | 0 | 60 |
| enabled_group | Включает автоматическую группировку параметров по коду функции чтения и последовательности адресации регистров для группового запроса | Обязательный | — | true |
| max_quantity | Максимальное кол-во регистров для группового запроса (2–125) | Необязательный | 125 | 100 |
| parameter_name | Используется как /devices/${root_topic_mqtt}/controls/${parameter_name}. Если в название указан /devices/... то берётся полное имя |
Обязательный | — | TemperatureIndoor1 |
| aperture | Абсолютная апертура для этого параметра для записи данных в MQTT (0–1000) | Необязательный | 0 | 0.01 |
| transform | Формула преобразования значения y = (a*x + b); x — исходное значение, y — преобразованное | Необязательный | 1:0 | 1:0 |
| precision | Кол-во знаков после запятой (0–6) | Необязательный | 0 | 2 |
| object: address | Modbus адрес регистра в dec; если указан с разделителем : то чтение бита | Обязательный | — | 10 или 10:1 |
| object: reg_type | Формат данных Modbus. Поддерживаемые: coil, discrete, input, holding | Обязательный | — | input |
| object: data_type | Тип данных Modbus | Обязательный | — | f32 |
| object: byteorder | Порядок следования байт: big, little, middle, littleswap, bigswap | Необязательный | big | little |
| object: wordorder | Порядок следования слов "low"/"high" | Необязательный | high | low |
¶ Настройки записи параметров Modbus
| YAML-ключ | Описание | Обязательный/Необязательный | Значение по умолчанию | Пример |
|---|---|---|---|---|
| parameter_name | Используется как /devices/${root_topic_mqtt}/controls/${parameter_name}. Если в название указан /devices/... то берётся полное имя |
Обязательный | — | TemperatureIndoor1 |
| command_topic | Используется как /devices/${root_topic_mqtt}/controls/${parameter_name}/${command_topic}/ |
Необязательный | on | cmd |
| object: address | Modbus адрес регистра в dec; если указан с разделителем : то запись бита | Обязательный | — | 10 или 10:1 |
| object: func_code | Код функции записи Modbus. Поддерживаемые: 5-0х05, 6-0х06, 16-0х10, 22-0х16 | Обязательный | — | 5 |
| object: data_type | Тип данных Modbus | Обязательный | — | f32 |
| object: byteorder | Порядок следования байт: big, little, middle, littleswap, bigswap | Необязательный | big | little |
| object: wordorder | Порядок следования слов "low"/"high" | Необязательный | high | low |
¶ Метаинформация сигналов и коды ошибок
Если в конфигурации Modbus2mqtt параметр metadata включен (enable: true). В случае отсут-ствия блока metadata, по умолчанию его значение установлено в true. Тогда все сообщения, отправ-ляемые драйвером, будут представлены в формате JSON. Пример сообщения от драйвера Modbus2mqtt в формате JSON:
{
"value": "23.5", // само значение
"metadata": {
"timestamp": "2024-01-15T10:30:45.123Z", // метка времени
"status_code":{
"code": 0, // Код ошибки из драйвера/стороннего сервиса
"source": "modbus2mqtt", // Источник.
},
}
}
Расшифровка кодов ошибок Modbus2mqtt:
| Код ошибки протокола Modbus | Код ошибки в сообщении от драйвера Modbus2mqtt | Описание |
|---|---|---|
| 0x01 | 1 | Принятый код функции не может быть обработан (Ille-gal Function ) |
| 0x02 | 2 | Адрес данных, указанный в запросе, недоступен (Ille-gal Data Address) |
| 0x03 | 3 | Значение, содержащееся в поле данных запроса, является недопустимой величиной (Illegal Data Value) |
| 0x04 | 4 | Невосстанавливаемая ошибка имела место, пока ведомое устройство пыталось выполнить затребован-ное действие (Slave Device Failure) |
| 0x05 | 5 | Ведомое устройство приняло запрос и обрабатывает его, но это требует много времени (Acknowledge) |
| 0x06 | 6 | Ведомое устройство занято обработкой команды. Ведущее устройство должно повторить сообщение позже, когда ведомое освободится (Slave Device Busy) |
| 0x08 | 7 | Ведомое устройство при чтении расширенной памяти обнаружило ошибку паритета (ParityError) |
| 0x0A | 8 | Шлюз неправильно настроен или перегружен запросами (Gateway Path Unavailable) |
| 0x0B | 9 | Slave устройства нет в сети, или от него нет ответа (Gateway Target Failed to Respond) |
| — | 0 | Успешный ответ |
| — | 10 | Timeout |
| — | 11 | CRC Error |
| — | 12 | Connection Refused/Closed |
| — | 255 | Любой неизвестный Exception |
¶ Демо-режим
Демо-версия Modbus2MQTT предназначена для ознакомления с возможностями ПО. При запуске демо-версии в логах указывается режим сборки DEMO, а для конфигурации действуют следующие ограничения:
| Ограничение | Значение |
|---|---|
| Максимальное количество уникальных MQTT-топиков | 30 |
| Максимальное количество устройств суммарно | 3 |
Минимальный период чтения read_period_ms |
5000 мс |
mqtt.client_id |
Нельзя задавать в YAML-конфигурации. Используется значение по умолчанию smartgate.modbus2mqtt |
mqtt.broker |
Нельзя задавать в YAML-конфигурации. Используется значение по умолчанию tcp://127.0.0.1:1883 |
Если ограничение нарушено, драйвер завершит запуск и выведет ошибку конфигурации с префиксом demo. Например: превышен лимит уникальных топиков, превышен лимит устройств или read_period_ms ниже допустимого минимума.
¶ Инструкции по запуску
Установить deb пакет (либо загрузите скомпилированный бинарный файл для соответствующей платформы).
¶ Аргументы запуска
| Сокращённый флаг | Полный флаг | Допустимые значения | Значение по умолчанию |
|---|---|---|---|
-c |
--cfgpath |
Путь к YAML-файлу конфигурации | configs/modbus/modbus.yaml |
-v |
--version |
true / false; при указании флага выводит версию и завершает работу | false |
-l |
--level_log |
1–6 (см. п.4.6 Уровни логирования) | 1 |
-p |
--path_log |
Путь к лог-файлу | ./log/modbus2mqtt.log |
-d |
--debug |
true / false; включает периодический вывод debug-информации о памяти | false |
-m |
--mscan |
true / false; запускает режим Modbus Scan с формированием отчёта .xlsx |
false |
¶ Запуск на Wirenboard 7
Установка deb пакета через пакетный менеджер apt: apt install ./modbus2mqtt_x.x.x.x_linux_x
Директория для исполнительного файла: /mnt/data/etc/andromeda_embedded/
Директория с файлами конфигурации: /mnt/data/etc/andromeda_embedded/configs/modbus/
Файл службы: /etc/systemd/system/
[Unit]
Description=Смарт-Гейт Modbus2MQTT
Wants=mosquitto.service
After=network.target
[Service]
WorkingDirectory=/mnt/data/etc/andromeda_embedded
ExecStart=/mnt/data/etc/andromeda_embedded/modbus2mqtt \
-c configs/modbus/modbus.yaml
Restart=always
RestartSec=5s
User=sgate_user
Group=sgate_user
[Install]
WantedBy=multi-user.target
Если установка в ручном режиме, то обязательно после создания файла службы выполнить:
sudo systemctl daemon-reload
sudo systemctl enable modbus2mqtt.service sudo systemctl start modbus2mqtt.service
Так же для работы необходима установка lsof: apt install lsof
Нативный драйвер WirenBoard (wb-mqtt-serial) должен быть остановлен: systemctl stop wb-mqtt-serial
Запуск в ручном режиме:
./modbus2mqtt -cfgpath configs/modbus/modbus.yaml -loglvl x
Перед запуском в ручном режиме необходимо остановить demon, если он был запущен: systemctl stop modbus2mqtt
Запуск с выводом уровня логирования:
./modbus2mqtt -cfgpath configs/modbus/modbus.yaml -loglvl 3
Запуск с выводом логов уровня “Monitor” 6/7:
./modbus2mqtt -cfgpath configs/modbus/modbus.yaml -loglvl 6
¶ Пример настроек YAML
¶ Пример настройки файла конфигурации инициализации драйвера - modbus.yaml
enabled: true
############################################
# Описание конфигурации подключения mqtt
mqtt:
broker: "unix:///var/run/mosquitto/mosquitto.sock" # или tcp://127.0.0.1:1883
client_id: "modbus2mqtt"
keepalive: 60
username: test # Дефолт без логина/пароля
password: test123
############################################
# Описание конфигурации метаинформации
# metadata:
# enabled: true
############################################
# Описание конфигурации логирования
# logger:
# write_in_logfile: false
# level_log: 1
# path_log: configs/modbus/log/modbus2mqtt.log
# max_size_log: 2
# max_backups_log: 10
# max_age_log: 10
############################################
# Описание конфигурации COM портов
# com_ports:
# com1:
# port: /dev/ttyS1
# settings: 38400:8:N:1
# timeout: 500
############################################
# Описание конфигурации VCOM портов
# vcom_ports:
# vcom1:
# ip: 192.168.1.201
# port: 9001
############################################
# Описание конфигурации для RTU Серверов
# rtu:
# device_rtu1:
# file: config/rtu1.yaml
############################################
# Описание конфигурации для TCP Серверов
# tcp:
# device_tcp1:
# file: config/tcp1.yaml
############################################
# Описание конфигурации для RTUoverTCP Серверов
# rtuovertcp:
# device_rtuovertcp1:
# file: config/rtuovertcp1.yaml
¶ Файл конфигурации TCP сервера
device:
name: device_tcp_1
enabled: true
root_topic_mqtt: device_tcp_1
unit_id: 1
use_shared_connection: false
ip: 192.168.1.172:1502
response_timeout_ms: 2000
idle_timeout_s: 60
retries: 5
time_retries_s: 10
time_reconnect_s: 120
global_publish_interval: 300
data_model:
read:
- read_period_ms: 1000
enabled_group: false
parameters:
- parameter_name: level1
aperture: 2
object:
address: 1
reg_type: input
data_type: float
byteorder: big
wordorder: high
write:
- parameter_name: parameter_name4
command_topic: on
object:
address: 1
func_code: 16
data_type: float
byteorder: big
¶ MScan (режим сканирования устройств)
Для ускорения процесса пуско-наладочных работ (проверка регистров, типов данных и кодов функций) был разработан дополнительный функционал mscan, встроенный в драйвер modbus2mqtt.
Функция mscan предназначена для автоматического однократного сканирования устройств Modbus (согласно конфигурационным файлам драйвера) с целью определения корректных параметров опроса и формирования отчёта о состоянии всех устройств и их регистров.
¶ Запуск режима сканирования
Запуск сервиса в режиме mscan выполняется при помощи параметра запуска -mscan 1: ./modbus2mqtt_x.x.x.x_linux_arm64 -mscan 1
- Если параметр -mscan равен 1, запускается однократное сканирование устройств;
- Если параметр не указан или равен 0, режим mscan отключён, и приложение работает в стандартном режиме (драйвер).
¶ Алгоритм работы
Инициализация конфигурации:
- Загрузка конфигурации устройств из YAML-файлов;
- Для каждого TCP/RTU/RTUoverTCP устанавливается соединение с портом, хендлером;
- Устройства на каждом порту обрабатываются последовательно и единожды.
Опрос регистров:
Опрос каждого параметра осуществляется последовательным перебором нескольких методов:
- Для регистров типа holding и input используются функции Modbus:
- 0x03 (Read Holding Registers);
- 0x04 (Read Input Registers);
- Опрос одиночных регистров (qty = 1) производится с порядком байт big endian и типом данных s16.
- Для двойных регистров (qty = 2) проверяются комбинации:
- Порядок байт: big endian, little endian, bigswap endian, littleswap endian.
- Типы данных: s16, s32, float (s16", "shortInt", "int16", "s32", "integer", "int32", "f32", "float").
Обработка ошибок
В случае возникновения ошибок чтения (недоступность устройства, ошибка соединения) информация фиксируется в логах и итоговом отчёте.
¶ Формирование отчета
После завершения однократного опроса генерируется Excel-отчёт с названием: report_mscan_{date-time}.xlsx
Отчёт содержит таблицу с результатами опроса каждого параметра всех устройств и включает следующие данные:
- Название устройства
- Подключение (ip:port,com.vcom)
- Параметр UnitID/SlaveID
- Параметр
- Адрес регистра (из конфигурации
- Бит если указан в конфигурации, если нет то значение -1
- Использованная функция Modbus (0x01, 0x02, 0x03, 0x04)
- Доступность (Ошибка чтения, ошибка соединения, ОК- если чтение успешно)
- Порядок байт (big endian, little endian, bigswap endian, littleswap endian)
- Тип данных (coil, discrete, s16, s32, float)
ВАЖНО!
Индикатор совпадения параметра с конфигурацией (отмечается светло-зелёной заливкой ячейка с значением которая соответствует настройкам из конфигурации)
¶ Пример отчета вывода в консоль
| № | Устройство | Подключение | UnitID/SlaveID | Параметр | Регистр DEC | Бит | Функции чтения | Доступность | S16-AB (Big endian) | S16-BA (Little endian) | S32-ABCD (Big endian) | S32-DCBA (Little endian) | Float-ABCD (Big endian) | Float-DCBA (Little endian) | S32-BADC (BigSwap endian) | S32-CDAB (LittleSwap endian) | Float-BADC (BigSwap endian) | Float-CDAB (LittleSwap endian) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | device_rtu_1 | com1 | 2 | Urms L1 | 256 | -1 | Read Input Registers 0x04 | OK | 15252 | -23856 | 9.99608482e+08 | -1.563388869e+09 | 0 | 0 | -1.808031024e+09 | -7.94674284e+08 | 0 | -2.1774508032e+10 |
| 2 | device_rtu_1 | com1 | 2 | Urms L1 | 256 | -1 | Read Holding Registers 0x03 | OK | 15252 | -23856 | 9.99608482e+08 | -1.563388869e+09 | 0 | 0 | -1.808031024e+09 | -7.94674284e+08 | 0 | -2.1774508032e+10 |
| 3 | device_rtu_1 | com1 | 2 | Urms L2 | 258 | -1 | Read Holding Registers 0x03 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 4 | device_rtu_1 | com1 | 2 | Urms L2 | 258 | -1 | Read Input Registers 0x04 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 5 | device_rtu_1 | com1 | 2 | I1 | 262 | -1 | Read Input Registers 0x04 | OK | 14342 | -29562 | 9.39951756e+08 | -1.93737364e+09 | 0 | 0 | 1.04369286e+08 | -2.03763097e+09 | 0 | 0 |
| 6 | device_rtu_1 | com1 | 2 | I1 | 262 | -1 | Read Holding Registers 0x03 | OK | 14342 | -29562 | 9.39951756e+08 | -1.93737364e+09 | 0 | 0 | 1.04369286e+08 | -2.03763097e+09 | 0 | 0 |
| 7 | device_rtu_1 | com1 | 2 | I2 | 264 | -1 | Read Input Registers 0x04 | OK | 14226 | 28022 | 9.32345453e+08 | 1.836487223e+09 | 0 | 4.769379707241949e+27 | -1.841861258e+09 | 1.986869138e+09 | 0 | 1.2028334524537911e+33 |
| 8 | device_rtu_1 | com1 | 2 | I2 | 264 | -1 | Read Holding Registers 0x03 | OK | 14226 | 28022 | 9.32345453e+08 | 1.836487223e+09 | 0 | 4.769379707241949e+27 | -1.841861258e+09 | 1.986869138e+09 | 0 | 1.2028334524537911e+33 |
| 9 | device_rtu_1 | com1 | 2 | I3 | 266 | -1 | Read Holding Registers 0x03 | OK | 14999 | 26972 | 9.82998121e+08 | 1.767675706e+09 | 0 | 1.66673642228305e+25 | -1.75777962e+09 | 1.550400151e+09 | 0 | 2.625923591522222e+17 |
| 10 | device_rtu_1 | com1 | 2 | I3 | 266 | -1 | Read Input Registers 0x04 | OK | 15000 | -26858 | 9.83045783e+08 | -1.760126918e+09 | 0 | 0 | -1.740990698e+09 | 3.79009688e+08 | 0 | 0 |
| 11 | device_rtu_1 | com1 | 2 | PF1 | 268 | -1 | Read Input Registers 0x04 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 12 | device_rtu_1 | com1 | 2 | PF1 | 268 | -1 | Read Holding Registers 0x03 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 13 | device_rtu_1 | com1 | 2 | PF2 | 270 | -1 | Read Holding Registers 0x03 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 14 | device_rtu_1 | com1 | 2 | PF2 | 270 | -1 | Read Input Registers 0x04 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 15 | device_rtu_1 | com1 | 2 | PF3 | 272 | -1 | Read Input Registers 0x04 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 16 | device_rtu_1 | com1 | 2 | PF3 | 272 | -1 | Read Holding Registers 0x03 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 17 | device_rtu_1 | com1 | 2 | Ch1_Q1 | 276 | -1 | Read Holding Registers 0x03 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 18 | device_rtu_1 | com1 | 2 | Ch1_Q1 | 276 | -1 | Read Input Registers 0x04 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 19 | device_rtu_1 | com1 | 2 | Ch1_Q2 | 278 | -1 | Read Input Registers 0x04 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 20 | device_rtu_1 | com1 | 2 | Ch1_Q2 | 278 | -1 | Read Holding Registers 0x03 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 21 | device_rtu_1 | com1 | 2 | Ch1_Q3 | 280 | -1 | Read Input Registers 0x04 | OK | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
¶ Приложение. PDF версия документа
PDF-версия данного руководства пользователя доступна для скачивания и печати. Документ содержит полную информацию по установке, настройке и эксплуатации драйвера Modbus2mqtt, включая все разделы, представленные в данной HTML-версии.