Wb-mqtt-serial driver

ВНИМАНИЕ: драйвер wb-mqtt-serial ранее назывался wb-homa-modbus, а конфигурационный файл /etc/wb-mqtt-serial.conf как /etc/wb-homa-modbus.conf. Учитывайте это, если используете устаревшие прошивки.

Описание

Драйвер wb-mqtt-serial служит для работы с подключенными по шине RS-485 устройствами через систему MQTT-сообщений.

Полное описание драйвера смотрите в репозитории на Github.

Поддерживаемые устройства

Поддерживается работа с:

• Периферийными устройствами Wiren Board с интерфейсом Modbus: модули реле, диммеры, счётчики импульсов, датчики и т.п.
• Устройствами сторонних производителей, работающих по протоколу Modbus.
• Некоторыми устройствами, использующими протоколы ADICON, A-BUS, Uniel, Милур, ИВТМ, Пульсар, Меркурий 230, Энергомера ГОСТ МЭК 61107, НЕВА МТ 32х ГОСТ МЭК 61107. Полный список поддерживаемых устройств можно посмотреть в таблице Протестированные устройства сторонних производителей.

Поддержка устройств различных протоколов на одной шине

Использовать устройства с разными протоколами на одной шине возможно, но необходимо учитывать особенности конкретных протоколов.

Например, фреймы устройств Unitel начинаются с байта 0xff, а устройств ИВТМ — с байта 0x24. В случае с протоколами Modbus, Меркурий 230 и Милур первым байтом фрейма является идентификатор slave, поэтому при совмещении таких устройств нужно внимательно подходить к выбору slave id.

У устройств Милур slave id по умолчанию равен 0xff, что приведет к конфликту с устройствами Unitel. Также устройства Милур требуют дополнительных задержек при опросе и при использовании на одной шине с другими устройствами могут снизить скорость опроса.

Иногда устройства, работающие на разных протоколах могут конфликтовать между собой: устройства с поддержкой протокола A-BUS не могут работать на одной шине с устройствами Unitel.

Рекомендуем придерживаться проверенной формулы комбинации протоколов на одной шине: Modbus + Милур (slave_id != 0xff) + Uniel. Учитывайте, что сторонние производители устройств могут вносить недокументированные изменения в протокол, поэтому перед покупкой устройства желательно убедиться в работоспособности выбранного решения.

Доработка драйвера для поддержки новых устройств

Вы можете самостоятельно добавить поддержку новых modbus-устройств при помощи шаблонов.

Если у вас возникли проблемы с составлением шаблона или выбранное вами устройство имеет свой протокол обмена данными — свяжитесь с нами и мы постараемся помочь.

Управление драйвером

Обычно драйвер запускается автоматически при загрузке контроллера и перезапускается при сохранении файла конфигурации в веб-интерфейсе.

Также можно управлять драйвером в ручном режиме — это может быть полезно для поиска ошибок в конфигурационном файле или если вам нужно освободить порт для использования modbus_client.

Для выполнения команд подключитесь к контроллеру по SSH. Доступны команды:

service wb-mqtt-serial stop #остановить драйвер
service wb-mqtt-serial start #запустить драйвер
service wb-mqtt-serial restart #перезапустить драйвер
wb-mqtt-serial -c /etc/wb-mqtt-serial.conf -d #запустить драйвер в отладочном режиме с указанием пути к конфигурационному файлу

Файл конфигурации драйвера

Перед использованием драйвер нужно настроить. Конфигурация драйвера хранится в файле /etc/wb-mqtt-serial.conf.

Структура файла

Файл /etc/wb-mqtt-serial.conf имеет структуру порты (ports) → устройства (devices) → каналы (channels): в файле есть описание физических портов контроллера, внутри них — список устройств подключенных к этому порту, а внутри устройств описаны каналы.

Для каждого порта указываются настройки: скорость, четность и т.п., а также протокол: Modbus, Uniel и т.п. Для каждого устройства обязательно указывается его уникальный адрес на шине — slave_id, остальные параметры указываются по необходимости.

Структура файла:

{
// основные настройки драйвера
"параметр": "значение",
...

	// порты
    "ports": [
        {
		// настройки порта
		"параметр": "значение",
		...

            // список устройств на данном порту
            "devices" : [
                {
					// описание первого устройства на канале
                    "параметр": "значение",
					...

                    // список каналов устройства
                    "channels": [
                        {
							//описание канала 1
							"параметр": "значение",
							...							
                        },
                        {
							//описание канала 2
							"параметр": "значение",
							...							
                        },
							...
                    ]
                },
                {
                    // описание второго устройства на канале
                    "параметр": "значение",
					...

                    // секция инициализации второго устройства
                    "setup": [
                        {
                            // описание регистра настройки
		                    "параметр": "значение",
							...
                        },
                            ...
                    ],
                    // каналы второго устройства
                    "channels": [
                        {
                            //первый канал
		                    "параметр": "значение",
							...                            
                        },
                            ...
                    ]
                }
            ]
        },
        {
            // ещё один порт со своим набором устройств            
            "devices" : [
                {
                    "параметр": "значение",
					...

                    "channels": [
					    {
		                    "параметр": "значение",
							...
					   }
                    ]
                }
                ...
            ]
        }
    ]
}

Пример конфигурационного файла можете посмотреть в репозитории.

Основные настройки драйвера

• debug — опция включает отладочный режим драйвера. Доступные значения: true, false.
• max_unchanged_interval — Задаёт интервал в секундах, в течение которого не изменяющиеся значения не будут публиковаться в MQTT. По истечении интервала значение будет опубликовано, даже если оно не изменилось. Доступны специальные значения:
  • 0 — публиковать все значения;
  • -1 — публиковать только при изменении. Значение по умолчанию.

Порты (ports)

• port_type — тип порта:
  • serial — последовательные порты RS-485 или RS-232, значение по умолчанию.
  • tcp — serial over TCP/IP. Пакеты, формируемые для работы с последовательными портами, передаются без изменений через TCP/IP.
  • modbus tcp — передача по Modbus TCP. В секции устройств с таким типом порта могут использоваться только те, что поддерживают Modbus.
• path — если выбран тип serial: устройство в системе, которое соответствует порту RS-485.
• address — если выбран тип tcp или modbus tcp: IP-адрес или имя хоста.
• port — если выбран тип tcp или modbus tcp: TCP-порт.
• baud_rate — скорость порта.
• parity — четность:
  • N — none, без бита четности. Значение по умолчанию;
  • O — odd, нечетный;
  • E — even, четный.
• data_bits — количество бит данных, по умолчанию — 8.
• stop_bits — количество стоп-бит, по умолчанию — 2.
• poll_interval — минимальный интервал опроса каждого регистра в миллисекундах.
• response_timeout_ms — максимальное время ответа устройств в миллисекундах. По умолчанию — 500 мс.
• guard_interval_us — дополнительная задержка перед отправкой данных в порт, микросекунды.
• connection_timeout_ms — если выбран тип tcp или modbus tcp: таймаут соединения. Если в течение указанного времени ни по одному из устройств на порту не поступило данных и истек connection_max_fail_cycles — разорвать соединение и переподключиться.
• connection_max_fail_cycles — если выбран тип tcp или modbus tcp: количество неудачных циклов опроса.
• enabled — включает или отключает порт. Доступные значения: true, false. По умолчанию — true.

Устройства, их каналы и параметры (devices, channels и setup)

Раздел devices содержит описание устройств, подключенных к порту и имеет структуру:

"devices" : 
[
    {
		// описание устройства
		...
        "channels" : 
        [
            // описание каналов
            ...
        ]                    
    },
    {
		// описание второго устройства
		...                    
    },
    ...
]

Описание устройства device может быть задано двумя способами: вручную прописать все параметры или задать только несколько параметров, а остальные вынести в шаблон:

{
    // По DeviceType драйвер будет искать в папках с шаблонами описаний устройств
    "device_type" : "DeviceType",

    // отображаемое имя устройства. Публикуется как
    // .../meta/name в MQTT
    // По умолчанию name берется из шаблона и добавляется slave_id, т.е.
    // "name" + " " + "slave_id"
    "name" : "somename",

    // уникальный идентификатор устройства в MQTT.
    // каждый элемент в devices должен иметь уникальный id
    // topic'и, относящиеся в MQTT к данному устройству,
    // имеют общий префикс /devices/<идентификатор топика>/...
    // также по умолчанию берется из шаблона с добавлением slave_id:
    // "deviceID" + "_" + slave_id
    "id" : "deviceID",

    // идентификатор slave
    "slave_id" : slaveID,

    // включить/выключить устройство. В случае задания
    // "enabled": false опрос устройства и запись значений
    // его каналов не происходит. По умолчанию - true.
    "enabled" : true,

    // если используется шаблон устройства, определения
    // каналов совмещаются. Если имя (name) в определении
    // канала устройства совпадает с именем канала в шаблоне,
    // свойства каналов из шаблона и определения устройства
    // совмещаются, при этом значения свойств из определения
    // устройства (в файле конфигурации) имеют преимущество.
    // Это можно использовать, например, для задания индивидуальных
    // интервалов опроса каналов. Если канал с таким же
    // именем, как канал в определении устройства, отсутствует
    // в шаблоне, создаётся новый канал.
    "channels": [
        {
            // имя канала. topic'и, соответствующие каналу,
            "name" : "Temp 1",
            "poll_interval": 10000
        }
    ]
}

Подробное описание разделов device, channels и setup вы найдете в статье о шаблонах.

Редактирование через веб-интерфейс

Мы рекомендуем изменять конфигурацию драйвера через веб-интерфейс. Процедура настройки подробно описана в статье RS-485:Настройка через веб-интерфейс.

Внесение изменений вручную

Будьте внимательны при редактировании файла конфигурации вручную — в отличие от редактирования через веб-интерфейс, вы можете допустить синтаксическую ошибку и драйвер не запустится.

1. Ознакомьтесь с инструкцией Просмотр файлов контроллера с компьютера и выберите удобный для вас способ.
2. Впишите конфигурацию для портов и подключенных устройств в файл. Смотрите примеры.
3. Чтобы описанные в файле устройства появились в веб-интерфейсе, перезагрузите контроллер или выполните команду:

   service wb-mqtt-serial restart
   

Поиск ошибок

Если возникли проблемы с запуском драйвера, например, новое устройство не появилось, то можно узнать причину: выполните команду systemctl status wb-mqtt-serial и в последних двух строчках ответа будет подсказка.

В примере файл конфигурации содержит синтаксическую ошибку во второй строке на 14 позиции:

~# systemctl status wb-mqtt-serial
● wb-mqtt-serial.service - MQTT Driver for serial devices
   Loaded: loaded (/lib/systemd/system/wb-mqtt-serial.service; enabled; vendor preset: enabled)
   Active: inactive (dead) since Thu 2021-01-28 15:10:51 +04; 4s ago
  Process: 23682 ExecStart=/usr/bin/wb-mqtt-serial (code=exited, status=0/SUCCESS)
 Main PID: 23682 (code=exited, status=0/SUCCESS)

Jan 28 15:10:47 wirenboard-A6XXXT2R systemd[1]: Started MQTT Driver for serial devices.
Jan 28 15:10:51 wirenboard-A6XXXT2R wb-mqtt-serial[23682]: ERROR: [serial] Failed to parse JSON /etc/wb-mqtt-serial.conf:* Line 2, Column 14
Jan 28 15:10:51 wirenboard-A6XXXT2R wb-mqtt-serial[23682]:   Syntax error: value, object or array expected.

Примеры файла конфигурации

В примерах мы описывали устройства в самом файле конфигурации, но при их большом количестве описание устройств можно вынести в шаблоны.

Подключено одно устройство

Выведем среднеквадратичное значение напряжения на фазе L1 со счетчика WB-MAP3E fw2. В примере счетчик подключен к serial-порту /dev/ttyRS485-1, работает по протоколу Modbus и имеет адрес 142.

{
	// отладка выключена
    "debug" : false,
	// список портов
    "ports" : 
    [
        {
			// тип порта
            "port_type" : "serial",			
			// устройство, соответствующее порту RS-485 (если выбран тип порта serial)
            "path" : "/dev/ttyRS485-1",			
			// скорость порта
            "baud_rate" : 9600,
			// количество бит данных
            "data_bits" : 8,
			// количество стоп-бит
            "stop_bits" : 2,
			// паритет - N, O или E
            "parity" : "N",			
			// включить опрос устройства
            "enabled" : true,
			// минимальный интервал опроса каждого регистра в миллисекундах
            "poll_interval" : 10,
			// список устройств на порту /dev/ttyRS485-1
            "devices" : 
            [
                {
					// отображаемое имя устройства
					"name" : "WB-MAP3E fw2",
					// протокол передачи устройства
                    "protocol" : "modbus",
					// идентификатор устройства на шине
                    "slave_id" : "142",
					// список каналов устройства
                    "channels" : 
                    [
                        {
							// адрес регистра
                            "address" : "0x1410",
							// формат канала
                            "format" : "u32",
							// имя канала
                            "name" : "Urms L1",							
                            // тип регистра
                            "reg_type" : "input",
							// порядок, до которого будет округляться значение после всех преобразований
                            "round_to" : 0.001,
							// коэффициент, на который умножается значение регистра перед публикацией в MQTT
                            "scale" : 1.52588e-07,
							// тип элемента управления
                            "type" : "voltage"
                        }
                    ]                    
                }
            ]
        }
    ]
}

Несколько подключенных устройств

Выведем среднеквадратичное значение напряжения на фазе L1 со счетчика WB-MAP3E fw2 и температуру с датчика MSW3.

В примере устройства работают по протоколу Modbus: счетчик WB-MAP3E подключен к serial-порту /dev/ttyRS485-1 с адресом 142, а датчик MSW3 подключен к serial-порту /dev/ttyRS485-2 и имеет адрес 22.

{
	// отладка выключена
    "debug" : false,
	// список портов
    "ports" : 
    [
        {
			// тип порта
            "port_type" : "serial",			
			// устройство, соответствующее порту RS-485 (если выбран тип порта serial)
            "path" : "/dev/ttyRS485-1",			
			// скорость порта
            "baud_rate" : 9600,
			// количество бит данных
            "data_bits" : 8,
			// количество стоп-бит
            "stop_bits" : 2,
			// четность - N, O или E
            "parity" : "N",			
			// включить опрос устройства
            "enabled" : true,
			// минимальный интервал опроса каждого регистра в миллисекундах
            "poll_interval" : 10,
			// список устройств на порту /dev/ttyRS485-1
            "devices" : 
            [
                {
					// отображаемое имя устройства
					"name" : "WB-MAP3E fw2",
					// протокол передачи устройства
                    "protocol" : "modbus",
					// идентификатор устройства на шине
                    "slave_id" : "142",
					// список каналов устройства
                    "channels" : 
                    [
                        {
							// адрес регистра
                            "address" : "0x1410",
							// формат канала
                            "format" : "u32",
							// имя канала
                            "name" : "Urms L1",							
                            // тип регистра
                            "reg_type" : "input",
							// порядок, до которого будет округляться значение после всех преобразований
                            "round_to" : 0.001,
							// коэффициент, на который умножается значение регистра перед публикацией в MQTT
                            "scale" : 1.52588e-07,
							// тип элемента управления
                            "type" : "voltage"
                        }
                    ]                    
                }
            ]
        },
		{
			// тип порта
            "port_type" : "serial",			
			// устройство, соответствующее порту RS-485 (если выбран тип порта serial)
            "path" : "/dev/ttyRS485-2",			
			// скорость порта
            "baud_rate" : 9600,
			// количество бит данных
            "data_bits" : 8,
			// количество стоп-бит
            "stop_bits" : 2,
			// четность - N, O или E
            "parity" : "N",			
			// включить опрос устройства
            "enabled" : true,
			// минимальный интервал опроса каждого регистра в миллисекундах
            "poll_interval" : 10,
			// список устройств на порту /dev/ttyRS485-2
            "devices" : 
            [
                {
					// отображаемое имя устройства
					"name" : "MSW3",
					// протокол передачи устройства
                    "protocol" : "modbus",
					// идентификатор устройства на шине
                    "slave_id" : "22",
					// список каналов устройства
                    "channels" : 
                    [
                        {
							// адрес регистра
                            "address" : "0x0000",
							// формат канала
                            "format" : "s16",
							// имя канала
                            "name" : "Temp",							
                            // тип регистра
                            "reg_type" : "input",
							// порядок, до которого будет округляться значение после всех преобразований
                            "round_to" : 0.5,
							// коэффициент, на который умножается значение регистра перед публикацией в MQTT
                            "scale" : 0.1,
							// тип элемента управления
                            "type" : "temperature"
                        }
                    ]                    
                }
            ]
        }        
    ]
}

Включение отладки

Веб-интерфейс. Флажок Enable debug logging установлен, отладка включена

Иногда нужно включить отладочный режим драйвера. Это можно сделать из командной строки или через веб-интерфейс.

ВНИМАНИЕ: при включенной отладке системный журнал будет быстро расти, поэтому не забудьте отключить отладку, когда необходимость в ней отпадет.

Включение отладки через веб-интерфейс:

1. Зайдите в веб-интерфейс Settings → Configs → Serial Device Driver Configuration
2. Установите флажок Enable debug logging
3. Нажмите на кнопку Save, чтобы сохранить настройки.

Теперь в системный журнал будут записываться отправленные и принятые драйвером пакеты.

Чтобы посмотреть debug-вывод драйвера, выполните в консоли контроллера команду journalctl -e -p 7, где -e — отобразить последние записи, а -p 7 задает уровень сообщений, где 7 — это debug.

Пример вывода команды:

~# journalctl -e -p 7
Jan 29 14:27:24 wirenboard-A6ZZXT2R wb-mqtt-serial[1667]: DEBUG: [serial port driver] channel 'Urms L1' of device 'wb-modbus-0-0' <-- 224.647
Jan 29 14:27:24 wirenboard-A6ZZXT2R wb-mqtt-serial[1667]: DEBUG: [modbus] read 2 input(s) @ 5136 of device modbus:142
Jan 29 14:27:24 wirenboard-A6ZZXT2R wb-mqtt-serial[1667]: DEBUG: [port] Sleep 0 us
Jan 29 14:27:24 wirenboard-A6ZZXT2R wb-mqtt-serial[1667]: DEBUG: [port] Write: 8e 04 14 10 00 02 6a c1
Jan 29 14:27:24 wirenboard-A6ZZXT2R wb-mqtt-serial[1667]: DEBUG: [port] Sleep 10000 us
Jan 29 14:27:24 wirenboard-A6ZZXT2R wb-mqtt-serial[1667]: DEBUG: [port] ReadFrame: 16 04 02 0f 3d 09 12
Jan 29 14:27:24 wirenboard-A6ZZXT2R wb-mqtt-serial[1667]: DEBUG: [register handler] new val for input @ 3 of device modbus:22: f3d
Jan 29 14:27:24 wirenboard-A6ZZXT2R wb-mqtt-serial[1667]: DEBUG: [serial port driver] register value change: input @ 3 of device modbus:22 <- 39.01

Подробнее о возможностях утилиты journalctl можете почитать в статье на Хабре.

Полезные ссылки

• Описание шаблонов и примеры
• Настройка драйвера wb-mqtt-serial в веб-интерфейсе
• Описание драйвера в репозитории на Github