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.