Part III · Chapter 11

Your First Modbus TCP Client

This is where Modbus stops being theory. A dozen lines of Python connect to the practice server, read its registers, check for an exception, and print real values, and every line maps to something you already understand.

Before you start, make sure practice_server.py from Chapter 10 is still running in its own terminal, and open a second terminal (with the modbus-lab environment activated) for the client.

The shape of a client

Almost every Modbus client, however large, has the same five-step shape: connect to the server, read or write using a function code, check whether the response was an error, use the data, and close the connection. Keep that pattern in mind and the code never feels mysterious, because each line is one of those steps. pymodbus hides all of Part II's frame-building and byte-order detail inside simple method calls: you say what you want, it handles how.

Connecting

Create a file called read_client.py. The first lines import the library and open a connection. The server runs on the same board, so the address is 127.0.0.1, the standard name for "this machine" (localhost), and the port is the 5020 chosen in Chapter 10:

from pymodbus.client import ModbusTcpClient
client = ModbusTcpClient("127.0.0.1", port=5020)
client.connect()

The ModbusTcpClient object represents the connection; connect() actually opens it. Against a real device on your network, only the address changes: its IP in place of 127.0.0.1, and usually the real port 502 in place of 5020. Everything else stays identical, which is the quiet beauty of the library: localhost practice and field work use the same code.

Reading holding registers

Now the heart of the program: one call reads four holding registers starting at address 0. That's function code 0x03 from Chapter 8, but you don't need to remember the number, because the method is named for what it does:

rr = client.read_holding_registers(0, count=4)
if rr.isError():
    print("Read error:", rr)
else:
    print("Holding 0-3:", rr.registers)

In that one call pymodbus does everything Part II described. It builds the PDU (function 0x03, start 0, quantity 4), wraps it in an MBAP header, sends the frame over TCP, waits for the reply, and unpacks the returned bytes, two per register, back into ordinary numbers.

What comes back is an object holding the result, and you ask it two questions. isError() tells you whether the server replied with an exception; registers is the plain list of integers when it didn't.

That isError() check isn't optional politeness. It's the code-level form of Chapter 3's three outcomes. Data came back: isError() is false and registers holds your values. An exception came back: isError() is true and the object describes the fault. The third outcome, silence, shows up separately as a failed connection or a timeout, handled below. Always check before you trust the data.

Reading input registers and scaling

Now read the two input registers the practice server seeded with a temperature and a humidity. read_input_registers (function 0x04) is otherwise identical. The interesting part is what happens to the raw numbers afterward. As Chapter 2 showed, devices often store a fractional value as a scaled integer: the server holds 235 to mean 23.5 degrees, so the client divides by ten to recover the reading:

ri = client.read_input_registers(0, count=2)
if not ri.isError():
    temp = ri.registers[0] / 10
    hum = ri.registers[1] / 10
    print("Temp: %.1f C" % temp)
    print("Humidity: %.1f %%" % hum)

client.close()

The last line, client.close(), releases the TCP connection cleanly. The scaling step is where Chapter 2's lesson becomes concrete: Modbus delivered a faithful integer, and you supplied the meaning, exactly as the register map dictates. The protocol moved a number; turning it into a temperature was your job.

Running it

Put the pieces together and read_client.py is complete:

from pymodbus.client import ModbusTcpClient
client = ModbusTcpClient("127.0.0.1", port=5020)
client.connect()

rr = client.read_holding_registers(0, count=4)
if rr.isError():
    print("Read error:", rr)
else:
    print("Holding 0-3:", rr.registers)

ri = client.read_input_registers(0, count=2)
if not ri.isError():
    temp = ri.registers[0] / 10
    hum = ri.registers[1] / 10
    print("Temp: %.1f C" % temp)
    print("Humidity: %.1f %%" % hum)

client.close()

Save it and run it in your second terminal, with the practice server still running in the first:

python read_client.py

Holding 0-3: [100, 200, 300, 400]
Temp: 23.5 C
Humidity: 56.7 %

Choose a run above.

Take a moment with this. Those numbers made a full round trip. Your client built a request frame and sent it across a TCP connection; the server looked up the values in its register tables and built a response frame; your client unpacked it into the list you see. Every concept from Parts I and II just executed, in milliseconds, on your desk. The 100, 200, 300, 400 are the seeded holding registers; 23.5 and 56.7 are the input registers, scaled.

Two practical notes

1. The unit address

The practice server answers regardless of unit address, but a real device, or one behind a gateway, expects you to name it. In pymodbus you pass the unit address as an extra keyword on the read call. The keyword has changed across library versions: older releases use slave=1, newer ones device_id=1. If a device ignores you, check which one your version wants. For the practice server you can simply leave it out.

rr = client.read_holding_registers(0, count=4, slave=1)

2. Failure to connect

If the server isn't running, or you aim at the wrong address, connect() returns False and reads fail instead of returning data. A sturdier client tests the connection and says so plainly instead of crashing:

if not client.connect():
    print("Could not connect — is the server up?")
    raise SystemExit

This is Chapter 3's silence outcome, caught in code: no connection means no conversation, and the friendly message points at the cause instead of leaving you a cryptic traceback. Use it in place of the bare client.connect() line. As programs grow, this kind of check is the difference between a script that works on a good day and one that tells you plainly what's wrong on a bad one.

You've written a working Modbus client and watched the protocol run end to end. Reading is only half the story. In Chapter 12 you turn the tables and build a server of your own, line by line, so you can simulate any device you need and give the writes in later chapters somewhere to land.