Asynchronous (as in python async/await) modbus python 3 client library. A thin layer on on top of the venerable umodbus library providing an object oriented client API.
async_modbus is async library agnostic. You should be able to use it with asyncio, curio, trio or anyio.
It expects an object with the same interface as StreamReader and StreamWriter so you may need to write a thin wrapper if you are not using asyncio. The examples below show how to use it with curio.
Note: the modbus_for_url()
relies on the
connio library which relies on
the asyncio event loop so you it's usage is limited to asyncio applications.
This library is not a re-implementation of the ModBus communication protocol. You can view it instead as a complement to the umodbus library.
Here is what async_modbus provides on top of umodbus:
modbus_for_url()
helper function. Type an URL and you're ready
to go.From within your favorite python environment type:
$ pip install async_modbus
Numpy will be used if installed. You can install it yourself, or include the optional dependency:
$ pip install async_modbus[numpy]
The core of the async_modbus library consists of a modbus_for_url()
function
and the two classes AsyncTCPClient
and AsyncRTUClient
.
Here are some examples:
simple TCP client
import asyncio
import numpy
from async_modbus import modbus_for_url
async def main():
client = modbus_for_url("tcp://localhost:15020")
values = numpy.array([1, 0, 1, 1]) # would also work with list<bool or int>
reply = await client.write_coils(slave_id=1, starting_address=1, values=values)
assert reply is len(values)
reply = await client.read_coils(slave_id=1, starting_address=1, quantity=len(values))
assert (reply == values).all()
asyncio.run(main())
RTU on local serial line with custom serial options
import asyncio
from async_modbus import modbus_for_url
async def main():
client = modbus_for_url("serial:///dev/ttyS0", {"baudrate":19200, "parity":"E"})
values = [1, 0, 1, 1]
reply = await client.write_coils(slave_id=1, starting_address=1, values=values)
assert reply is len(values)
reply = await client.read_discrete_inputs(slave_id=1, starting_address=1, quantity=len(values))
assert (reply == values).all()
asyncio.run(main())
RTU over remote serial line using RFC2217
import asyncio
from async_modbus import modbus_for_url
async def main():
client = modbus_for_url("rfc2217://moxa.acme.org:6610")
values = [1, 0, 1, 1]
reply = await client.write_coils(slave_id=1, starting_address=1, values=values)
assert reply is len(values)
reply = await client.read_discrete_inputs(slave_id=1, starting_address=1, quantity=len(values))
assert (reply == values).all()
asyncio.run(main())
asyncio TCP streams
import asyncio
import numpy
from async_modbus import AsyncTCPClient
async def main():
reader, writer = await asyncio.open_connection('localhost', 15020)
client = AsyncTCPClient((reader, writer))
values = numpy.array([0, 2**15 - 1, 10, 3, 32766])
reply = await client.write_registers(slave_id=1, starting_address=1, values=values)
assert reply is len(values)
reply = await client.read_holding_registers(slave_id=1, starting_address=1, quantity=len(values))
assert (reply == values).all()
writer.close()
await writer.wait_closed()
asyncio.run(main())
async serial line RTU using remote raw TCP
import asyncio
import numpy
from async_modbus import AsyncRTUClient
from serial_asyncio import open_serial_connection
async def main():
reader, writer = await open_serial_connection(url="socket://moxa.acme.org:6610")
client = AsyncRTUClient((reader, writer))
values = [0, 2**15 - 1, 10, 3, 32766]
reply = await client.write_registers(slave_id=1, starting_address=1, values=values)
assert reply is len(values)
reply = await client.read_input_registers(slave_id=1, starting_address=1, quantity=len(values))
assert (reply == values).all()
writer.close()
await writer.wait_closed()
asyncio.run(main())
curio TCP streams
import curio
from async_modbus import AsyncTCPClient
async def main():
sock = await curio.open_connection("0", 15020)
client = AsyncTCPClient(sock.as_stream())
values = [1, 0, 1, 1]
reply = await client.write_coils(slave_id=1, starting_address=1, values=values)
assert reply is len(values)
reply = await client.read_coils(slave_id=1, starting_address=1, quantity=len(values))
assert (reply == values).all()
await sock.close()
None yet. Why not be the first?