pymodbus.server
Pymodbus offers servers with transport protocols for
Serial (RS-485) typically using a dongle
TCP
TLS
UDP
possibility to add a custom transport protocol
communication in 2 versions:
synchronous server
,asynchronous server
using asyncio.
Remark All servers are implemented with asyncio, and the synchronous servers are just an interface layer allowing synchronous applications to use the server as if it was synchronous.
pymodbus.server package
Server.
import external classes, to make them easier to use:
- async pymodbus.server.ServerAsyncStop()
Terminate server.
- pymodbus.server.ServerStop()
Terminate server.
- async pymodbus.server.StartAsyncSerialServer(context=None, identity=None, custom_functions=[], defer_start=False, **kwargs)
Start and run a serial modbus server.
- Parameters
context – The ModbusServerContext datastore
identity – An optional identify structure
custom_functions – An optional list of custom function classes supported by server instance.
defer_start – if set, the server object will be returned ready to start. Otherwise, the server will be immediately spun up without the ability to shut it off
kwargs – The rest
- async pymodbus.server.StartAsyncTcpServer(context=None, identity=None, address=None, custom_functions=[], defer_start=False, **kwargs)
Start and run a tcp modbus server.
- Parameters
context – The ModbusServerContext datastore
identity – An optional identify structure
address – An optional (interface, port) to bind to.
custom_functions – An optional list of custom function classes supported by server instance.
defer_start – if set, the server object will be returned ready to start. Otherwise, the server will be immediately spun up without the ability to shut it off
kwargs – The rest
- Returns
an initialized but inactive server object coroutine
- async pymodbus.server.StartAsyncTlsServer(context=None, identity=None, address=None, sslctx=None, certfile=None, keyfile=None, password=None, reqclicert=False, allow_reuse_address=False, allow_reuse_port=False, custom_functions=[], defer_start=False, **kwargs)
Start and run a tls modbus server.
- Parameters
context – The ModbusServerContext datastore
identity – An optional identify structure
address – An optional (interface, port) to bind to.
sslctx – The SSLContext to use for TLS (default None and auto create)
certfile – The cert file path for TLS (used if sslctx is None)
keyfile – The key file path for TLS (used if sslctx is None)
password – The password for for decrypting the private key file
reqclicert – Force the sever request client”s certificate
allow_reuse_address – Whether the server will allow the reuse of an address.
allow_reuse_port – Whether the server will allow the reuse of a port.
custom_functions – An optional list of custom function classes supported by server instance.
defer_start – if set, the server object will be returned ready to start. Otherwise, the server will be immediately spun up without the ability to shut it off
kwargs – The rest
- Returns
an initialized but inactive server object coroutine
- async pymodbus.server.StartAsyncUdpServer(context=None, identity=None, address=None, custom_functions=[], defer_start=False, **kwargs)
Start and run a udp modbus server.
- Parameters
context – The ModbusServerContext datastore
identity – An optional identify structure
address – An optional (interface, port) to bind to.
custom_functions – An optional list of custom function classes supported by server instance.
defer_start – if set, the server object will be returned ready to start. Otherwise, the server will be immediately spun up without the ability to shut it off
kwargs –
- pymodbus.server.StartSerialServer(**kwargs)
Start and run a serial modbus server.
- pymodbus.server.StartTcpServer(**kwargs)
Start and run a serial modbus server.
- pymodbus.server.StartTlsServer(**kwargs)
Start and run a serial modbus server.
- pymodbus.server.StartUdpServer(**kwargs)
Start and run a serial modbus server.
Submodules
pymodbus.server module
Implementation of a Threaded Modbus Server.
- class pymodbus.server.async_io.ModbusBaseRequestHandler(owner)
Bases:
BaseProtocol
Implements modbus slave wire protocol.
This uses the asyncio.Protocol to implement the client handler.
When a connection is established, the asyncio.Protocol.connection_made callback is called. This callback will setup the connection and create and schedule an asyncio.Task and assign it to running_task.
running_task will be canceled upon connection_lost event.
- connection_lost(call_exc)
Call for socket tear down.
For streamed protocols any break in the network connection will be reported here; for datagram protocols, only a teardown of the socket itself will result in this call.
- connection_made(transport)
Call for socket establish
For streamed protocols (TCP) this will also correspond to an entire conversation; however for datagram protocols (UDP) this corresponds to the socket being opened
- execute(request, *addr)
Call with the resulting message.
- Parameters
request – The decoded request message
addr – the address
- async handle()
Return Asyncio coroutine which represents a single conversation.
between the modbus slave and master
Once the client connection is established, the data chunks will be fed to this coroutine via the asyncio.Queue object which is fed by the ModbusBaseRequestHandler class”s callback Future.
This callback future gets data from either asyncio.DatagramProtocol.datagram_received or from asyncio.BaseProtocol.data_received.
This function will execute without blocking in the while-loop and yield to the asyncio event loop when the frame is exhausted. As a result, multiple clients can be interleaved without any interference between them.
For ModbusConnectedRequestHandler, each connection will be given an instance of the handle() coroutine and this instance will be put in the active_connections dict. Calling server_close will individually cancel each running handle() task.
For ModbusDisconnectedRequestHandler, a single handle() coroutine will be started and maintained. Calling server_close will cancel that task.
- send(message, *addr, **kwargs)
Send message.
- class pymodbus.server.async_io.ModbusConnectedRequestHandler(owner)
Bases:
ModbusBaseRequestHandler
,Protocol
Implements the modbus server protocol
This uses asyncio.Protocol to implement the client handler for a connected protocol (TCP).
- connection_lost(call_exc)
Call when the connection is lost or closed.
- connection_made(transport)
Call when a connection is made.
- data_received(data)
Call when some data is received.
data is a non-empty bytes object containing the incoming data.
- class pymodbus.server.async_io.ModbusDisconnectedRequestHandler(owner)
Bases:
ModbusBaseRequestHandler
,DatagramProtocol
Implements the modbus server protocol
This uses the socketserver.BaseRequestHandler to implement the client handler for a disconnected protocol (UDP). The only difference is that we have to specify who to send the resulting packet data to.
- connection_lost(call_exc)
Handle connection lost.
- datagram_received(data, addr)
Call when a datagram is received.
data is a bytes object containing the incoming data. addr is the address of the peer sending the data; the exact format depends on the transport.
- error_received(exc)
Call when a previous send/receive raises an OSError.
exc is the OSError instance.
This method is called in rare conditions, when the transport (e.g. UDP) detects that a datagram could not be delivered to its recipient. In many conditions though, undeliverable datagrams will be silently dropped.
- class pymodbus.server.async_io.ModbusSerialServer(context, framer=<class 'pymodbus.framer.rtu_framer.ModbusRtuFramer'>, identity=None, **kwargs)
Bases:
object
A modbus threaded serial socket server.
We inherit and overload the socket server so that we can control the client threads as well as have a single server context instance.
- handler = None
- on_connection_lost()
Call on lost connection.
- async serve_forever()
Start endless loop.
- async shutdown()
Terminate server.
- async start()
Start connecting.
- class pymodbus.server.async_io.ModbusSingleRequestHandler(owner)
Bases:
ModbusBaseRequestHandler
,Protocol
Implement the modbus server protocol.
This uses asyncio.Protocol to implement the client handler for a serial connection.
- connection_lost(call_exc)
Handle connection lost.
- connection_made(transport)
Handle connect made.
- data_received(data)
Receive data.
- class pymodbus.server.async_io.ModbusTcpServer(context, framer=None, identity=None, address=None, handler=None, allow_reuse_address=False, allow_reuse_port=False, defer_start=False, backlog=20, **kwargs)
Bases:
object
A modbus threaded tcp socket server.
We inherit and overload the socket server so that we can control the client threads as well as have a single server context instance.
- async serve_forever()
Start endless loop.
- async server_close()
Close server.
- async shutdown()
Shutdown server.
- class pymodbus.server.async_io.ModbusTlsServer(context, framer=None, identity=None, address=None, sslctx=None, certfile=None, keyfile=None, password=None, reqclicert=False, handler=None, allow_reuse_address=False, allow_reuse_port=False, defer_start=False, backlog=20, **kwargs)
Bases:
ModbusTcpServer
A modbus threaded tls socket server.
We inherit and overload the socket server so that we can control the client threads as well as have a single server context instance.
- class pymodbus.server.async_io.ModbusUdpServer(context, framer=None, identity=None, address=None, handler=None, allow_reuse_port=False, defer_start=False, backlog=20, **kwargs)
Bases:
object
A modbus threaded udp socket server.
We inherit and overload the socket server so that we can control the client threads as well as have a single server context instance.
- async serve_forever()
Start endless loop.
- async server_close()
Close server.
- async shutdown()
Shutdown server.
- async pymodbus.server.async_io.ServerAsyncStop()
Terminate server.
- pymodbus.server.async_io.ServerStop()
Terminate server.
- async pymodbus.server.async_io.StartAsyncSerialServer(context=None, identity=None, custom_functions=[], defer_start=False, **kwargs)
Start and run a serial modbus server.
- Parameters
context – The ModbusServerContext datastore
identity – An optional identify structure
custom_functions – An optional list of custom function classes supported by server instance.
defer_start – if set, the server object will be returned ready to start. Otherwise, the server will be immediately spun up without the ability to shut it off
kwargs – The rest
- async pymodbus.server.async_io.StartAsyncTcpServer(context=None, identity=None, address=None, custom_functions=[], defer_start=False, **kwargs)
Start and run a tcp modbus server.
- Parameters
context – The ModbusServerContext datastore
identity – An optional identify structure
address – An optional (interface, port) to bind to.
custom_functions – An optional list of custom function classes supported by server instance.
defer_start – if set, the server object will be returned ready to start. Otherwise, the server will be immediately spun up without the ability to shut it off
kwargs – The rest
- Returns
an initialized but inactive server object coroutine
- async pymodbus.server.async_io.StartAsyncTlsServer(context=None, identity=None, address=None, sslctx=None, certfile=None, keyfile=None, password=None, reqclicert=False, allow_reuse_address=False, allow_reuse_port=False, custom_functions=[], defer_start=False, **kwargs)
Start and run a tls modbus server.
- Parameters
context – The ModbusServerContext datastore
identity – An optional identify structure
address – An optional (interface, port) to bind to.
sslctx – The SSLContext to use for TLS (default None and auto create)
certfile – The cert file path for TLS (used if sslctx is None)
keyfile – The key file path for TLS (used if sslctx is None)
password – The password for for decrypting the private key file
reqclicert – Force the sever request client”s certificate
allow_reuse_address – Whether the server will allow the reuse of an address.
allow_reuse_port – Whether the server will allow the reuse of a port.
custom_functions – An optional list of custom function classes supported by server instance.
defer_start – if set, the server object will be returned ready to start. Otherwise, the server will be immediately spun up without the ability to shut it off
kwargs – The rest
- Returns
an initialized but inactive server object coroutine
- async pymodbus.server.async_io.StartAsyncUdpServer(context=None, identity=None, address=None, custom_functions=[], defer_start=False, **kwargs)
Start and run a udp modbus server.
- Parameters
context – The ModbusServerContext datastore
identity – An optional identify structure
address – An optional (interface, port) to bind to.
custom_functions – An optional list of custom function classes supported by server instance.
defer_start – if set, the server object will be returned ready to start. Otherwise, the server will be immediately spun up without the ability to shut it off
kwargs –
- pymodbus.server.async_io.StartSerialServer(**kwargs)
Start and run a serial modbus server.
- pymodbus.server.async_io.StartTcpServer(**kwargs)
Start and run a serial modbus server.
- pymodbus.server.async_io.StartTlsServer(**kwargs)
Start and run a serial modbus server.
- pymodbus.server.async_io.StartUdpServer(**kwargs)
Start and run a serial modbus server.
- pymodbus.server.async_io.sslctx_provider(sslctx=None, certfile=None, keyfile=None, password=None, reqclicert=False)
Provide the SSLContext for ModbusTlsServer.
If the user defined SSLContext is not passed in, sslctx_provider will produce a default one.
- Parameters
sslctx – The user defined SSLContext to use for TLS (default None and auto create)
certfile – The cert file path for TLS (used if sslctx is None)
keyfile – The key file path for TLS (used if sslctx is None)
password – The password for for decrypting the private key file
reqclicert – Force the sever request client”s certificate