
Quick answer: a reliable Modbus TCP poller needs more than an IP address. Confirm unit ID, function code, zero-based protocol address, register count, byte/word order, data type, timeout and permitted poll rate from the device map. Start read-only on an isolated test network.
Protocol facts that prevent mistakes
The Modbus Application Protocol V1.1b3 defines request/reply services using function codes. Modbus TCP normally uses TCP port 502. Function 03 reads holding registers and Function 04 reads input registers; they are not interchangeable simply because both return 16-bit words.
Documentation may show “40001” while a software library expects offset 0. Never subtract one blindly: identify whether the vendor map uses reference numbers, decimal protocol offsets or hexadecimal offsets.
Minimal read-only example
from pymodbus.client import ModbusTcpClient
client = ModbusTcpClient(
host="192.0.2.25",
port=502,
timeout=2.0,
retries=1,
)
try:
if not client.connect():
raise ConnectionError("Modbus server unavailable")
result = client.read_holding_registers(
address=0,
count=2,
slave=1,
)
if result.isError():
raise RuntimeError(f"Modbus exception: {result}")
words = result.registers
print(words)
finally:
client.close() Library APIs change. The current PyModbus documentation may use device_id rather than slave in newer versions, so pin the tested package version and follow its official client reference.
Decoding a 32-bit value
Two adjacent 16-bit registers may hold one IEEE-754 float. If words are 0x4148 and 0x0000 in big-endian word order, they represent 12.5. Some devices reverse the two words while keeping bytes inside each word unchanged. Treat byte order and word order as separate configuration fields.
import struct
raw = struct.pack(">HH", words[0], words[1])
value = struct.unpack(">f", raw)[0]
Validate decoding against a known value on the local HMI. A plausible but wrong temperature is more dangerous than a clear communication failure.
Timeout and retry design
PyModbus exposes request timeout and retry parameters. A short timeout detects failures quickly but can create false alarms on loaded gateways. Multiple immediate retries can amplify congestion. For a 1-second process scan, a practical starting design might use a 1.5-second timeout, one retry and exponential reconnect delay, then tune from packet captures and device performance.
Poll-group example
Instead of reading ten single registers, group contiguous read-only values within device limits. If one request reads 20 registers every second and the round trip is 30 ms, network occupancy is modest. Ten separate requests add transaction overhead and may overload a serial gateway behind the TCP server.
Safe commissioning checklist
- Use a lab device or approved maintenance window.
- Disable all write functions in the first build.
- Restrict access with firewall rules; traditional Modbus TCP has no inherent authentication.
- Confirm unit IDs on gateways.
- Log timestamps, transaction result, exception code and raw words.
- Rate-limit reconnects and alarms.
- Test cable loss, server restart, delayed response and malformed data.
- Do not expose port 502 directly to the internet.
FAQ
Why do I get illegal data address?
Common causes are the wrong function code, one-based versus zero-based addressing, crossing a valid block boundary or requesting too many registers.
Why is the value byte-swapped?
Modbus defines 16-bit registers but not one universal 32-bit word order. Follow the device map.
Should a poller write a watchdog register?
Only when the control philosophy explicitly requires it and the write behavior has been risk-assessed and tested.
Related: zero-trust segmentation for ICS and Networks. Sources: Modbus Organization specifications and PyModbus client documentation. Photo: Bayu Syaits via Unsplash.



