Skip to main content

ModBus TCP proxy

Project description

ModBus TCP proxy

ModBus proxy Python Versions Pypi status License CI

Many modbus devices support only one or very few clients. This proxy acts as a bridge between the client and the modbus device. It can be seen as a layer 7 reverse proxy. This allows multiple clients to communicate with the same modbus device.

When multiple clients are connected, cross messages are avoided by serializing communication on a first come first served REQ/REP basis.


From within your favorite python 3 environment type:

$ pip install modbus-proxy

Note: On some systems pip points to a python 2 installation. You might need to use pip3 command instead.

Additionally, if you want logging configuration:

  • YAML: pip install modbus-proxy[yaml] (see below)
  • TOML: pip install modbus-proxy[toml] (see below)

Running the server

First, you will need write a configuration file where you specify for each modbus device you which to control:

  • modbus connection (the modbus device url)
  • listen interface (to which url your clients should connect)

Configuration files can be written in YAML (.yml or .yaml) or TOML (.toml).

Suppose you have a PLC modbus device listening on and you want your clients to connect to your machine on port 9000. A YAML configuration would look like this:

- modbus:
    url:     # device url (mandatory)
    timeout: 10                # communication timeout (s) (optional, default: 10)
    connection_time: 0.1       # delay after connection (s) (optional, default: 0)
    bind: 0:9000               # listening address (mandatory)

Assuming you saved this file as modbus-config.yml, start the server with:

$ modbus-proxy -c ./modbus-config.yml

Now, instead of connecting your client(s) to you just need to tell them to connect to *machine*:9000 (where machine is the host where modbus-proxy is running).

Note that the server is capable of handling multiple modbus devices. Here is a configuration example for 2 devices:

- modbus:
    bind: 0:9000
- modbus:
    bind: 0:9001

If you have a single modbus device, you can avoid writting a configuration file by providing all arguments in the command line:

modbus-proxy -b tcp://0:9000 --modbus tcp://

(hint: run modbus-proxy --help to see all available options)

Running the examples

To run the examples you will need to have umodbus installed (do it with pip install umodbus).

Start the (this will simulate an actual modbus hardware):

$ python examples/ -b :5020

You can run the example client just to be sure direct communication works:

$ python examples/ -a 0:5020
holding registers: [1, 2, 3, 4]

Now for the real test:

Start a modbus-proxy bridge server with:

$ modbus-proxy -b tcp://:9000 --modbus tcp://:5020

Finally run a the example client but now address the proxy instead of the server (notice we are now using port 9000 and not 5020):

$ python examples/ -a 0:9000
holding registers: [1, 2, 3, 4]


This project ships with a basic Dockerfile which you can use as a base to launch modbus-proxy inside a docker container.

First, build the docker image with:

$ docker build -t modbus-proxy .

To bridge a single modbus device without needing a configuration file is straight forward:

$ docker run -d -p 5020:502 modbus-proxy -b tcp://0:502 --modbus tcp://

Now you should be able to access your modbus device through the modbus-proxy by connecting your client(s) to <your-hostname/ip>:5020.

If, instead, you want to use a configuration file, you must mount the file so it is visible by the container.

Assuming you have prepared a conf.yml in the current directory:

- modbus:
    bind: 0:502

Here is an example of how to run the container:

docker run -p 5020:502 -v $PWD/conf.yml:/src/conf.yml modbus-proxy -c /src/conf.yml

Note that for each modbus device you add in the configuration file you need to publish the corresponding bind port on the host (-p <host port>:<container port> argument).

Logging configuration

Logging configuration can be added to the configuration file by adding a new logging keyword.

The logging configuration will be passed to logging.config.dictConfig() so the file contents must obey the Configuration dictionary schema.

Here is a YAML example:

- modbus:
    bind: 0:9000
  version: 1
      format: "%(asctime)s %(levelname)8s %(name)s: %(message)s"
      class: logging.StreamHandler
      formatter: standard
    handlers: ['console']
    level: DEBUG

--log-config-file (deprecated)

Logging configuration file.

If a relative path is given, it is relative to the current working directory.

If a .conf or .ini file is given, it is passed directly to logging.config.fileConfig() so the file contents must obey the Configuration file format.

A simple logging configuration (also available at log.conf) which mimics the default configuration looks like this:




format=%(asctime)s %(levelname)8s %(name)s: %(message)s



A more verbose example logging with a rotating file handler: log-verbose.conf

The same example above (also available at log.yml) can be achieved in YAML with:

version: 1
    format: "%(asctime)s %(levelname)8s %(name)s: %(message)s"
    class: logging.StreamHandler
    formatter: standard
  handlers: ['console']
  level: DEBUG


Development Lead


None yet. Why not be the first?


0.6.1 (2021-09-29)

  • Change default command line --modbus-connection-time from 0.1 to 0
  • Add basic unit tests
  • Github actions
  • Repository cleanup

0.5.0 (2021-09-28)

  • Add support for multiple devices
  • Adapt docker to changes
  • Deprecate --log-config-file command line parameter

0.4.2 (2021-09-23)

  • Add connection time delay (fixes #4)

0.4.1 (2021-01-26)

  • Logging improvements

0.4.0 (2021-01-26)

  • Logging improvements

0.3.0 (2021-01-25)

  • More robust server (fixes #2)

0.2.0 (2021-01-23)

  • Document (README)
  • Add docker intructions (fixes #1)
  • Fix setup dependencies and meta data

0.1.1 (2020-12-02)

  • Fix project package

0.1.0 (2020-11-11)

  • First release on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

modbus-proxy-0.6.8.tar.gz (12.0 kB view hashes)

Uploaded source

Built Distribution

modbus_proxy-0.6.8-py3-none-any.whl (8.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page