modbus-rs 0.12.0

Fast, full-featured Modbus TCP + Serial bindings for Python — powered by Rust

modbus-rs (Python)

Fast Modbus TCP + Serial bindings for Python, powered by Rust.

• PyPI package: modbus-rs
• Import name: modbus_rs

Licensing

This package is available under GNU GPL v3.0 for open-source use.

Commercial licenses are also available for proprietary/closed-source use. Contact: [e-mail]

Install

pip install modbus-rs

Quick Start

Synchronous TCP client

import modbus_rs

with modbus_rs.TcpClient("192.168.1.10", port=502, unit_id=1) as client:
    client.connect()
    regs = client.read_holding_registers(0, 10)
    print(regs)

Async TCP client

import asyncio
import modbus_rs

async def main():
    async with modbus_rs.AsyncTcpClient("192.168.1.10", unit_id=1) as client:
        regs = await client.read_holding_registers(0, 10)
        print(regs)

asyncio.run(main())

Serial client (RTU)

import modbus_rs

with modbus_rs.SerialClient("/dev/ttyUSB0", baud_rate=9600, unit_id=1) as client:
    client.connect()
    regs = client.read_holding_registers(0, 5)
    print(regs)

Async TCP server

import asyncio
import modbus_rs

class MyApp(modbus_rs.ModbusApp):
    def handle_read_holding_registers(self, address, count):
        return [address + i for i in range(count)]

async def main():
    server = modbus_rs.AsyncTcpServer("0.0.0.0", MyApp(), port=5020, unit_id=1)
    await server.serve_forever()

asyncio.run(main())

Exceptions

• ModbusError
• ModbusTimeout
• ModbusConnectionError
• ModbusProtocolError
• ModbusDeviceException
• ModbusConfigError
• ModbusInvalidArgument

Build from Source

cd mbus-ffi
maturin develop --features python,full

Run Python Tests

cd mbus-ffi
maturin develop --features python,full
cd ..
pytest mbus-ffi/tests/python/ -q

Run Python Examples

The examples live in this repository under mbus-ffi/examples.

1) Build/install the extension from source

git clone https://github.com/Raghava-Ch/modbus-rs.git
cd modbus-rs/mbus-ffi
maturin develop --features python,full

2) Start the example server (terminal 1)

cd ../examples/python_server
python3 python_server.py --host 127.0.0.1 --port 5020 --unit-id 1

3) Run the sync client (terminal 2)

cd ../python_client
python3 python_client.py --host 127.0.0.1 --port 5020 --unit-id 1

4) Run the async client (terminal 2)

cd ../python_async_client
python3 async_client.py --host 127.0.0.1 --port 5020 --unit-id 1

Optional: multi-server async demo

Start 3 servers on ports 5020, 5021, and 5022, then run:

cd ../python_async_client
python3 async_client.py --host 127.0.0.1 --port 5020 --multi

Modbus TCP Gateway (python-gateway feature)

The python-gateway feature exposes a thread-safe sync gateway and an asyncio-friendly async gateway that forward inbound Modbus/TCP requests to one or more downstream Modbus/TCP servers based on a unit-id routing table.

Build with the gateway feature enabled:

cd mbus-ffi
maturin develop --features python,python-gateway,full

Sync gateway

import modbus_rs

gw = modbus_rs.TcpGateway("0.0.0.0:5020")
ch = gw.add_tcp_downstream("192.168.1.10", 502)
gw.add_unit_route(unit=1, channel=ch)
gw.serve_forever()  # blocks; call gw.stop() from another thread to exit

Async gateway

import asyncio
import modbus_rs

async def main():
    gw = modbus_rs.AsyncTcpGateway("0.0.0.0:5020")
    ch = await gw.add_tcp_downstream("192.168.1.10", 502)
    await gw.add_unit_route(unit=1, channel=ch)
    await gw.serve_forever()  # cancel the task or call gw.stop() to exit

asyncio.run(main())

Note: The optional event_handler= constructor argument accepts a GatewayEventHandler subclass to receive telemetry callbacks for routing, forwarding, and errors. See event_handler_demo.py for a complete example of logging telemetry events.

More Docs

• Project docs: documentation/python_bindings.md
• Full crate README (C/WASM/Python): mbus-ffi/README.md

License

Copyright (C) 2026 Raghava Challari

This project is licensed under GNU GPL v3.0. See LICENSE for details.

Commercial licenses for proprietary use are available via [e-mail].