# 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.

- `examples.zip`

- `examples.tgz`

### 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

### Simulator datastore (shared storage) example

Source: examples/datastore_simulator_share.py

Pymodbus datastore simulator Example.

An example of using simulator datastore with json interface.

Detailed description of the device definition can be found at:

> https://pymodbus.readthedocs.io/en/latest/source/library/simulator/config.html#device-entries

usage:

    datastore_simulator_share.py [-h]
                        [--log {critical,error,warning,info,debug}]
                        [--port PORT]
                        [--test_client]

    -h, --help
        show this help message and exit
    -l, --log {critical,error,warning,info,debug}
        set log level
    -p, --port PORT
        set port to use
    --test_client
        starts a client to test the configuration

The corresponding client can be started as:

  python3 client_sync.py

Tip

This is NOT the pymodbus simulator, that is started as pymodbus.simulator.

### 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