Инженер — это не профессия, а состояние души

Modbus TCP остаётся одним из основных протоколов для опроса промышленных контроллеров, счётчиков и датчиков — ПЛК, преобразователи частоты, приборы учёта почти всегда умеют отдавать данные по нему. В этой статье показываем, как опросить одно или несколько устройств по Modbus TCP из Python-скрипта: от минимального запроса одного регистра до рабочего цикла опроса с повторными попытками и записью результатов в CSV. Материал полезен инженерам, которым нужно быстро собрать данные с оборудования без разворачивания полноценной SCADA-системы.

Что такое Modbus TCP и когда он уместен

Modbus TCP — это Modbus RTU, перенесённый на Ethernet/IP: та же модель данных (coils, discrete inputs, holding registers, input registers), но без RS-485 и адресации по CRC — пакеты передаются по TCP, обычно на порт 502. Устройство выступает Modbus-сервером (в старой терминологии — slave/mapped device), наш скрипт — клиентом (master).

Протокол подходит, когда:

  • устройство физически в той же сети (Ethernet) или за Modbus TCP-гейтвеем, который преобразует RS-485/RTU в TCP;
  • достаточно опроса раз в несколько секунд — Modbus не рассчитан на событийную передачу данных в реальном времени;
  • не нужна аутентификация — у протокола её нет, безопасность обеспечивается изоляцией сети (см. статьи про настройку VPN и сегментацию на MikroTik).

Если устройство отдаёт данные только по RS-485 (Modbus RTU), к нему либо подключают TCP-гейтвей, либо опрашивают через последовательный порт — это другой сценарий, он не описан здесь (при необходимости можно отдельно посмотреть pymodbus.client.ModbusSerialClient).

Библиотека pymodbus: установка и выбор версии

Для примеров используется pymodbus — одна из самых распространённых Python-библиотек для Modbus (TCP, RTU, ASCII, клиент и сервер).

pip install "pymodbus==3.7.4"

Версию фиксируем намеренно: API pymodbus между мажорными и даже минорными релизами 3.x менялся не один раз (в частности, имя параметра для идентификатора устройства — slave в одних версиях, device_id в более новых; у серверного датастора аналогично менялись ModbusSlaveContext/setValues). Код ниже проверен именно на 3.7.4 и Python 3.11. Если у вас уже установлена другая версия — проверьте актуальную сигнатуру read_holding_registers в документации вашей версии перед тем, как переносить пример как есть.

Минимальный пример: один регистр с одного устройства

from pymodbus.client import ModbusTcpClient

client = ModbusTcpClient("192.168.1.50", port=502, timeout=2)

if client.connect():
    result = client.read_holding_registers(address=0, count=1, slave=1)
    if not result.isError():
        print("Значение регистра 0:", result.registers[0])
    else:
        print("Ошибка Modbus-ответа:", result)
    client.close()
else:
    print("Не удалось подключиться к устройству")

Обязательные параметры:

  • address — адрес регистра (0-based в самом запросе; в документации на устройство адреса часто даны 1-based — тогда нужно отнять 1, это частый источник ошибок);
  • count — сколько регистров читать подряд, начиная с address;
  • slave — идентификатор устройства на шине/гейтвее (Unit ID), не IP-адрес; для одиночного устройства за своим TCP-портом обычно 1.

Опрос нескольких устройств с повторными попытками и записью в CSV

Для реального сценария опроса нескольких устройств минимального примера мало: нужны таймауты, повторные попытки при сбое связи и фиксация результата, даже если устройство не ответило (чтобы в логе было видно пропуски, а не только успешные измерения).

"""Опрос нескольких Modbus TCP устройств с записью в CSV."""
import csv
import logging
import time
from dataclasses import dataclass

from pymodbus.client import ModbusTcpClient
from pymodbus.exceptions import ModbusException

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("modbus-poll")


@dataclass
class Device:
    name: str
    host: str
    port: int
    unit_id: int
    register: int  # адрес holding register
    scale: float    # множитель для перевода "сырого" значения в инженерные единицы


DEVICES = [
    # Пример — замените на реальный список опрашиваемых устройств: IP, Unit ID,
    # адрес регистра и коэффициент пересчёта для каждого прибора учёта/датчика
    Device(name="counter-1", host="192.168.1.50", port=502, unit_id=1, register=0, scale=0.1),
]

RETRIES = 3
RETRY_DELAY_S = 1.0


def read_register(device: Device) -> float | None:
    client = ModbusTcpClient(device.host, port=device.port, timeout=2)
    try:
        if not client.connect():
            log.warning("%s: не удалось подключиться к %s:%s", device.name, device.host, device.port)
            return None

        result = client.read_holding_registers(
            address=device.register, count=1, slave=device.unit_id
        )
        if result.isError():
            log.warning("%s: ошибка Modbus-ответа: %s", device.name, result)
            return None

        raw_value = result.registers[0]
        return raw_value * device.scale
    except ModbusException as exc:
        log.warning("%s: исключение Modbus: %s", device.name, exc)
        return None
    finally:
        client.close()


def poll_with_retries(device: Device) -> float | None:
    for attempt in range(1, RETRIES + 1):
        value = read_register(device)
        if value is not None:
            return value
        log.info("%s: попытка %s/%s не удалась, пауза %.1f с", device.name, attempt, RETRIES, RETRY_DELAY_S)
        time.sleep(RETRY_DELAY_S)
    return None


def poll_once(devices: list[Device], csv_path: str) -> None:
    timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
    rows = []
    for device in devices:
        value = poll_with_retries(device)
        status = "ok" if value is not None else "no_data"
        rows.append((timestamp, device.name, value, status))
        log.info("%s: значение=%s статус=%s", device.name, value, status)

    file_exists = False
    try:
        with open(csv_path, "r", encoding="utf-8"):
            file_exists = True
    except FileNotFoundError:
        pass

    with open(csv_path, "a", newline="", encoding="utf-8") as f:
        writer = csv.writer(f)
        if not file_exists:
            writer.writerow(["timestamp", "device", "value", "status"])
        writer.writerows(rows)


if __name__ == "__main__":
    poll_once(DEVICES, "modbus_log.csv")

Для периодического опроса (например, раз в минуту) функцию poll_once оборачивают в цикл с time.sleep(POLL_INTERVAL_S) или ставят скрипт в cron/systemd-таймер — сам код опроса от этого не меняется.

Как это было проверено

Код выше запускался локально (Python 3.11.9, pymodbus 3.7.4) против тестового Modbus TCP сервера на pymodbus.server.StartTcpServer, поднятого на 127.0.0.1 с одним holding register, отдающим фиксированное значение 235 (имитация показания 23.5, при scale=0.1). Проверены оба пути:

  • устройство отвечает — скрипт корректно читает и пересчитывает значение (23.5, status=ok);
  • устройство недоступно — скрипт делает 3 попытки с паузой и пишет в CSV строку со status=no_data вместо падения с исключением.

На реальном оборудовании (конкретная модель контроллера/счётчика, карта регистров, сетевые задержки) скрипт не тестировался — только на тестовом Modbus TCP сервере, как описано выше.

Типичные грабли

  • Путаница в адресации регистров. В документации на устройство адреса часто даны 1-based (регистр «40001» означает holding register с адресом 0 в запросе Modbus TCP: вычитаем смещение типа регистра и единицу). Если данные «съезжают» на один регистр — проверяйте это первым.
  • Unit ID не равен IP. Если за одним IP (TCP-гейтвеем) несколько физических устройств на RS-485, у каждого свой slave/unit_id — ошибка в этом параметре даёт либо таймаут, либо ответ не от того устройства.
  • Многословные (multi-register) значения. float32 или 32-битные счётчики занимают 2 регистра подряд — их нужно собирать в int/float с учётом порядка байт (endianness), который различается между производителями. pymodbus для этого даёт BinaryPayloadDecoder (в более новых версиях — DecodePayload/convert_from_registers, см. документацию вашей версии).
  • Таймаут слишком короткий. На загруженной шине RS-485 за гейтвеем ответ может идти дольше 1–2 секунд; если устройство стабильно не успевает ответить — не торопитесь считать его сломанным, увеличьте timeout.
  • Версионная несовместимость pymodbus. См. раздел про установку — при обновлении библиотеки стоит сверять сигнатуры read_* методов и классов датастора сервера.

Итог

Для разового опроса одного устройства достаточно минимального примера на пять строк. Для рабочего скрипта, который должен стабильно работать без присмотра, нужны минимум таймауты, повторные попытки и явная фиксация неудачного опроса (а не тихий пропуск). Код выше проверен на тестовом сервере и корректно обрабатывает оба случая — но перед использованием на реальном оборудовании нужно подтвердить карту регистров конкретного устройства и прогнать скрипт на стенде или в тестовом контуре, а не сразу в проде. Документация: pymodbus; спецификация протокола — modbus.org.

← Все статьи раздела «Программирование»