Protocol Proxy Modbus Library

This library provides support for communication with Modbus devices to a Protocol Proxy Manager. Communication happens in a separate proxy process which holds the connections to the Modbus gateways and devices, knows the data type of every configured register, and returns decoded values to its callers. One proxy process serves any number of devices over any mix of transports (TCP, UDP, TLS, and serial).

Automatically installed dependencies

• python = ">=3.10,<4.0"
• protocol-proxy = ">=2.0.0rc2"
• pymodbus = ">=3.13,<4.0"
• psutil = ">=5.9.0,<8.0.0"

Installation

This library, along with its dependencies, can be installed using pip:

pip install protocol-proxy-modbus

Note that this is rarely necessary as this library will typically be used as a dependency of an application acting as a Protocol Proxy Manager (such as the VOLTTRON Modbus Driver Interface), and will be installed as a dependency of that application.

How it works

A Protocol Proxy Manager launches the proxy with:

python -m protocol_proxy.proxy protocol_proxy.protocol.modbus.modbus_proxy:ModbusProxy [manager options]

The Modbus proxy takes no protocol-specific launch options. Everything about a device arrives in messages:

Replies have the form {"result": ..., "error": ...}. For decoded reads, result maps register address to value and error maps the start address of any failed request to its error. For raw reads and for writes, both are lists aligned with the queries.

Register maps

A tables block maps a table name to a list of register specifications:

{
  "unit_id": 1,
  "tables": {
    "input":   [{"address": 1001, "data_type": "FLOAT32"}, {"address": 1010, "data_type": "INT16"}],
    "holding": [{"address": 1003, "data_type": ">f"}, {"address": 1005, "data_type": "string[6]"},
                {"address": 1008, "data_type": "pad", "count": 2}, {"address": 1010, "data_type": "UINT16"}],
    "coil":    [{"address": 5, "data_type": "bool"}]
  }
}

• Tables are coil, discrete_input, holding, and input.
• Data types may be spelled as pymodbus names (UINT16, FLOAT32, STRING, BITS), as the names used by the modbus_tk driver (float, uint16, string[8], bool), or as struct format strings (>f, 4H, 8s). Each specification may also carry count, word_order (big or little), and string_encoding.
• Pads are registers that are read but never decoded or returned. Two points separated by a pad are fetched in one request. max_gap lets the proxy read through short unconfigured gaps as well.

Request planning

Requests to one gateway share one connection and run one at a time, so units on a serial bus behind a TCP gateway are never polled concurrently. Different gateways are independent. Reads are merged into the fewest requests permitted by the protocol (125 registers or 2000 coils). If a merged request is rejected by the device (for example an illegal data address), its parts are retried individually so that one bad address does not fail its neighbours; a device that does not answer at all is not retried piecemeal.

Requests may queue behind other units' timeout-and-retry cycles, so the proxy allows each message 120 seconds by default before abandoning it (ModbusProxy(callback_timeout=...)). Callers should wait longer than that for a reply.

Testing

pytest tests

The tests need no network or hardware. They exercise the register map, the client against a fake pymodbus device, and every endpoint through the real IPC base class.

Development

This library is maintained by the VOLTTRON Development Team.

Please see the following guidelines for contributing to this and/or other VOLTTRON repositories.

Disclaimer Notice

This material was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights.

Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.