Examples
Examples are divided in 2 parts:
The first part are some simple client examples which can be copied and run directly. These examples show the basic functionality of the library.
The second part are more advanced examples, but in order to not duplicate code, this requires you to download the examples directory and run the examples in the directory.
Ready to run examples:
These examples are very basic examples, showing how a client can communicate with a server.
You need to modify the code to adapt it to your situation.
Simple asynchronous client
Source: examples/simple_async_client.py
#!/usr/bin/env python3
"""Pymodbus asynchronous client example.
An example of a single threaded synchronous client.
usage: simple_async_client.py
All options must be adapted in the code
The corresponding server must be started before e.g. as:
python3 server_sync.py
"""
import asyncio
import pymodbus.client as ModbusClient
from pymodbus import (
FramerType,
ModbusException,
pymodbus_apply_logging_config,
)
async def run_async_simple_client(comm, host, port, framer=FramerType.SOCKET):
"""Run async client."""
# activate debugging
pymodbus_apply_logging_config("DEBUG")
print("get client")
client: ModbusClient.ModbusBaseClient
if comm == "tcp":
client = ModbusClient.AsyncModbusTcpClient(
host,
port=port,
framer=framer,
# timeout=10,
# retries=3,
# source_address=("localhost", 0),
)
elif comm == "udp":
client = ModbusClient.AsyncModbusUdpClient(
host,
port=port,
framer=framer,
# timeout=10,
# retries=3,
# source_address=None,
)
elif comm == "serial": # pragma: no cover
client = ModbusClient.AsyncModbusSerialClient(
port,
framer=framer,
# timeout=10,
# retries=3,
baudrate=9600,
bytesize=8,
parity="N",
stopbits=1,
# handle_local_echo=False,
)
else: # pragma: no cover
print(f"Unknown client {comm} selected")
return
print("connect to server")
await client.connect()
# test client is connected
assert client.connected
print("get and verify data")
try:
# See all calls in client_calls.py
rr = await client.read_coils(1, count=1, device_id=1)
except ModbusException as exc: # pragma: no cover
print(f"Received ModbusException({exc}) from library")
client.close()
return
if rr.isError(): # pragma: no cover
print(f"Received exception from device ({rr})")
# THIS IS NOT A PYTHON EXCEPTION, but a valid modbus message
client.close()
return
try:
# See all calls in client_calls.py
rr = await client.read_holding_registers(10, count=2, device_id=1)
except ModbusException as exc: # pragma: no cover
print(f"Received ModbusException({exc}) from library")
client.close()
return
if rr.isError(): # pragma: no cover
print(f"Received exception from device ({rr})")
# THIS IS NOT A PYTHON EXCEPTION, but a valid modbus message
client.close()
return
value_int32 = client.convert_from_registers(rr.registers, data_type=client.DATATYPE.INT32)
print(f"Got int32: {value_int32}")
print("close connection")
client.close()
if __name__ == "__main__":
asyncio.run(
run_async_simple_client("tcp", "127.0.0.1", 5020), debug=True
)
Simple synchronous client
Source: examples/simple_sync_client.py
#!/usr/bin/env python3
"""Pymodbus synchronous client example.
An example of a single threaded synchronous client.
usage: simple_sync_client.py
All options must be adapted in the code
The corresponding server must be started before e.g. as:
python3 server_sync.py
"""
# --------------------------------------------------------------------------- #
# import the various client implementations
# --------------------------------------------------------------------------- #
import pymodbus.client as ModbusClient
from pymodbus import (
FramerType,
ModbusException,
pymodbus_apply_logging_config,
)
def run_sync_simple_client(comm, host, port, framer=FramerType.SOCKET):
"""Run sync client."""
# activate debugging
pymodbus_apply_logging_config("DEBUG")
print("get client")
client: ModbusClient.ModbusBaseSyncClient
if comm == "tcp":
client = ModbusClient.ModbusTcpClient(
host,
port=port,
framer=framer,
# timeout=10,
# retries=3,
# source_address=("localhost", 0),
)
elif comm == "udp":
client = ModbusClient.ModbusUdpClient(
host,
port=port,
framer=framer,
# timeout=10,
# retries=3,
# source_address=None,
)
elif comm == "serial": # pragma: no cover
client = ModbusClient.ModbusSerialClient(
port,
framer=framer,
# timeout=10,
# retries=3,
baudrate=9600,
bytesize=8,
parity="N",
stopbits=1,
# handle_local_echo=False,
)
else: # pragma: no cover
print(f"Unknown client {comm} selected")
return
print("connect to server")
client.connect()
print("get and verify data")
try:
rr = client.read_coils(1, count=1, device_id=1)
except ModbusException as exc: # pragma: no cover
print(f"Received ModbusException({exc}) from library")
client.close()
return
if rr.isError(): # pragma: no cover
print(f"Received exception from device ({rr})")
# THIS IS NOT A PYTHON EXCEPTION, but a valid modbus message
client.close()
return
try:
# See all calls in client_calls.py
rr = client.read_holding_registers(10, count=2, device_id=1)
except ModbusException as exc: # pragma: no cover
print(f"Received ModbusException({exc}) from library")
client.close()
return
if rr.isError(): # pragma: no cover
print(f"Received exception from device ({rr})")
# THIS IS NOT A PYTHON EXCEPTION, but a valid modbus message
client.close()
return
value_int32 = client.convert_from_registers(rr.registers, data_type=client.DATATYPE.INT32)
print(f"Got int32: {value_int32}")
print("close connection")
client.close()
if __name__ == "__main__":
run_sync_simple_client("tcp", "127.0.0.1", "5020")
Advanced examples
These examples are considered essential usage examples, and are guaranteed to work, because they are tested automatilly with each dev branch commit using CI.
Tip
The examples needs to be run from within the examples directory, unless you modify them. Most examples use helper.py and client_*.py or server_*.py. This is done to avoid maintaining the same code in multiple files.
Client asynchronous calls
Source: examples/client_async_calls.py
Pymodbus Client modbus async all calls example.
Please see method async_template_call for a template on how to make modbus calls and check for different error conditions.
The handle* functions each handle a set of modbus calls with the same register type (e.g. coils).
All available modbus calls are present.
If you are performing a request that is not available in the client mixin, you have to perform the request like this instead:
from pymodbus.pdu.diag_message import ClearCountersRequest
from pymodbus.pdu.diag_message import ClearCountersResponse
request = ClearCountersRequest()
response = client.execute(request)
if isinstance(response, ClearCountersResponse):
... do something with the response
This example uses client_async.py and client_sync.py to handle connection, and have the same options.
The corresponding server must be started before e.g. as:
./server_async.py
Client asynchronous
Source: examples/client_async.py
Pymodbus asynchronous client example.
usage:
client_async.py [-h] [-c {tcp,udp,serial,tls}]
[-f {ascii,rtu,socket,tls}]
[-l {critical,error,warning,info,debug}] [-p PORT]
[--baudrate BAUDRATE] [--host HOST]
-h, --help
show this help message and exit
-c, -comm {tcp,udp,serial,tls}
set communication, default is tcp
-f, --framer {ascii,rtu,socket,tls}
set framer, default depends on --comm
-l, --log {critical,error,warning,info,debug}
set log level, default is info
-p, --port PORT
set port
--baudrate BAUDRATE
set serial device baud rate
--host HOST
set host, default is 127.0.0.1
- The corresponding server must be started before e.g. as:
python3 server_sync.py
Client calls
Source: examples/client_calls.py
Pymodbus Client modbus all calls example.
Please see method template_call for a template on how to make modbus calls and check for different error conditions.
The handle* functions each handle a set of modbus calls with the same register type (e.g. coils).
All available modbus calls are present.
If you are performing a request that is not available in the client mixin, you have to perform the request like this instead:
from pymodbus.pdu.diag_message import ClearCountersRequest
from pymodbus.pdu.diag_message import ClearCountersResponse
request = ClearCountersRequest()
response = client.execute(request)
if isinstance(response, ClearCountersResponse):
... do something with the response
This example uses client_async.py and client_sync.py to handle connection, and have the same options.
The corresponding server must be started before e.g. as:
./server_async.py
Custom message
Source: examples/custom_msg.py
Pymodbus Synchronous Client Examples.
The following is an example of how to use the synchronous modbus client implementation from pymodbus:
with ModbusClient("127.0.0.1") as client:
result = client.read_coils(1,10)
print result
Client synchronous
Source: examples/client_sync.py
Pymodbus Synchronous Client Example.
An example of a single threaded synchronous client.
usage:
client_sync.py [-h] [-c {tcp,udp,serial,tls}]
[-f {ascii,rtu,socket,tls}]
[-l {critical,error,warning,info,debug}] [-p PORT]
[--baudrate BAUDRATE] [--host HOST]
-h, --help
show this help message and exit
-c, --comm {tcp,udp,serial,tls}
set communication, default is tcp
-f, --framer {ascii,rtu,socket,tls}
set framer, default depends on --comm
-l, --log {critical,error,warning,info,debug}
set log level, default is info
-p, --port PORT
set port
--baudrate BAUDRATE
set serial device baud rate
--host HOST
set host, default is 127.0.0.1
The corresponding server must be started before e.g. as:
python3 server_sync.py
Server asynchronous
Source: examples/server_async.py
Pymodbus asynchronous Server Example.
An example of a multi threaded asynchronous server.
usage:
server_async.py [-h] [--comm {tcp,udp,serial,tls}]
[--framer {ascii,rtu,socket,tls}]
[--log {critical,error,warning,info,debug}]
[--port PORT]
[--baudrate BAUDRATE]
[--device_ids DEVICE_IDS]
-h, --help
show this help message and exit
-c, --comm {tcp,udp,serial,tls}
set communication, default is tcp
-f, --framer {ascii,rtu,socket,tls}
set framer, default depends on --comm
-l, --log {critical,error,warning,info,debug}
set log level, default is info
-p, --port PORT
set port
--baudrate BAUDRATE
set serial device baud rate
--device_ids DEVICE IDs
set list of devices to respond to
The corresponding client can be started as:
python3 client_sync.py
Server tracer
Source: examples/server_hook.py
Pymodbus Server With request/response manipulator.
This is an example of using the builtin request/response tracer to manipulate the messages to/from the modbus server
Server synchronous
Source: examples/server_sync.py
Pymodbus Synchronous Server Example.
An example of a single threaded synchronous server.
usage:
server_sync.py [-h] [--comm {tcp,udp,serial,tls}]
[--framer {ascii,rtu,socket,tls}]
[--log {critical,error,warning,info,debug}]
[--port PORT]
[--baudrate BAUDRATE]
[--device_ids DEVICE_IDS]
-h, --help
show this help message and exit
-c, --comm {tcp,udp,serial,tls}
set communication, default is tcp
-f, --framer {ascii,rtu,socket,tls}
set framer, default depends on --comm
-l, --log {critical,error,warning,info,debug}
set log level, default is info
-p, --port PORT
set port
--baudrate BAUDRATE
set serial device baud rate
--device_ids DEVICE_IDS
set list of devices to respond to
- The corresponding client can be started as:
python3 client_sync.py
REMARK It is recommended to use the async server! The sync server is just a thin cover on top of the async server and is in some aspects a lot slower.
Server updating
Source: examples/server_updating.py
Pymodbus asynchronous Server with updating task Example.
An example of an asynchronous server and a task that runs continuously alongside the server and updates values.
A real world example controlling a heatpump can be found at
examples/heatpump.py
usage:
server_updating.py [-h]
[--log {critical,error,warning,info,debug}]
[--port PORT]
[--baudrate BAUDRATE]
[--host HOST]
-h, --help
show this help message and exit
-l, --log {critical,error,warning,info,debug}
set log level, default is info
-p, --port PORT
set port
--baudrate BAUDRATE
set serial device baud rate
--host HOST
set HOST
- The corresponding client can be started as:
python3 client_sync.py
Simulator example
Source: examples/simulator.py
Pymodbus simulator server/client Example.
An example of how to use the simulator (server) with a client.
for usage see documentation of simulator
Tip
pymodbus.simulator starts the server directly from the commandline
Message Parser
Source: examples/message_parser.py
Modbus Message Parser.
The following is an example of how to parse modbus messages using the supplied framers.
Examples contributions
These examples are supplied by users of pymodbus. The pymodbus team thanks for sharing the examples.
Solar
Source: examples/contrib/solar.py
Pymodbus Synchronous Client Example.
Modified to test long term connection.
Modified to actually work with Huawei SUN2000 inverters, that better support async Modbus operations so errors will occur Configure HOST (the IP address of the inverter as a string), PORT and CYCLES to fit your needs