0
# PyModbus
1
2
A comprehensive Python library providing both client and server implementations of the Modbus protocol. PyModbus supports multiple transport layers (TCP, UDP, Serial, TLS), various framing formats (RTU, ASCII, Socket), and offers both synchronous and asynchronous APIs for industrial automation, SCADA systems, and IoT applications.
3
4
## Package Information
5
6
- **Package Name**: pymodbus
7
- **Language**: Python
8
- **Installation**: `pip install pymodbus`
9
- **Optional dependencies**: `pip install pymodbus[serial]` for serial support, `pip install pymodbus[all]` for full features
10
- **Python Requirements**: Python >= 3.10
11
12
## Core Imports
13
14
```python
15
import pymodbus.client as ModbusClient
16
from pymodbus import FramerType, ModbusException, pymodbus_apply_logging_config
17
```
18
19
Common client imports:
20
21
```python
22
from pymodbus.client import ModbusTcpClient, AsyncModbusTcpClient
23
from pymodbus.client import ModbusSerialClient, AsyncModbusSerialClient
24
```
25
26
Server imports:
27
28
```python
29
from pymodbus.server import ModbusTcpServer, StartTcpServer
30
from pymodbus.datastore import ModbusServerContext, ModbusDeviceContext
31
from pymodbus.datastore import ModbusSequentialDataBlock
32
```
33
34
Transport and utility imports:
35
36
```python
37
from pymodbus.transport import CommType, CommParams, ModbusProtocol, NULLMODEM_HOST
38
from pymodbus.exceptions import (
39
ConnectionException, ModbusIOException, ParameterException,
40
NoSuchIdException, NotImplementedException, MessageRegisterException
41
)
42
```
43
44
## Basic Usage
45
46
### Synchronous TCP Client
47
48
```python
49
from pymodbus.client import ModbusTcpClient
50
from pymodbus import FramerType, ModbusException
51
52
# Create and connect client
53
client = ModbusTcpClient('127.0.0.1', port=502, framer=FramerType.SOCKET)
54
client.connect()
55
56
try:
57
# Read holding registers
58
result = client.read_holding_registers(0, count=10, device_id=1)
59
if not result.isError():
60
print(f"Register values: {result.registers}")
61
62
# Write single register
63
client.write_register(0, 123, device_id=1)
64
65
# Read coils
66
result = client.read_coils(0, count=8, device_id=1)
67
if not result.isError():
68
print(f"Coil values: {result.bits}")
69
70
except ModbusException as e:
71
print(f"Modbus error: {e}")
72
finally:
73
client.close()
74
```
75
76
### Asynchronous TCP Client
77
78
```python
79
import asyncio
80
from pymodbus.client import AsyncModbusTcpClient
81
82
async def run_async_client():
83
client = AsyncModbusTcpClient('127.0.0.1', port=502)
84
await client.connect()
85
86
try:
87
# Read input registers
88
result = await client.read_input_registers(0, count=5, device_id=1)
89
if not result.isError():
90
print(f"Input registers: {result.registers}")
91
finally:
92
client.close()
93
94
# Run the async client
95
asyncio.run(run_async_client())
96
```
97
98
### Simple TCP Server
99
100
```python
101
from pymodbus.server import StartTcpServer
102
from pymodbus.datastore import ModbusSequentialDataBlock, ModbusServerContext, ModbusDeviceContext
103
104
# Create datastore with some initial values
105
store = ModbusSequentialDataBlock(0, [0] * 100)
106
context = ModbusDeviceContext(
107
co=store, # coils
108
di=store, # discrete inputs
109
hr=store, # holding registers
110
ir=store # input registers
111
)
112
server_context = ModbusServerContext(device_default=context, single=True)
113
114
# Start server
115
StartTcpServer(context=server_context, address=('127.0.0.1', 5020))
116
```
117
118
## Architecture
119
120
PyModbus uses a layered architecture:
121
122
- **Transport Layer**: Handles TCP, UDP, Serial, and TLS communication
123
- **Framer Layer**: Manages different Modbus frame formats (RTU, ASCII, Socket, TLS)
124
- **PDU Layer**: Implements Modbus Protocol Data Units (function codes and messages)
125
- **Application Layer**: Provides client/server APIs and data management
126
127
The library supports both synchronous and asynchronous operations, allowing integration with various Python frameworks and applications.
128
129
## Capabilities
130
131
### Client Operations
132
133
Comprehensive client implementations supporting all standard Modbus function codes with both synchronous and asynchronous APIs across multiple transport protocols.
134
135
```python { .api }
136
# Synchronous clients
137
class ModbusTcpClient: ...
138
class ModbusUdpClient: ...
139
class ModbusSerialClient: ...
140
class ModbusTlsClient: ...
141
142
# Asynchronous clients
143
class AsyncModbusTcpClient: ...
144
class AsyncModbusUdpClient: ...
145
class AsyncModbusSerialClient: ...
146
class AsyncModbusTlsClient: ...
147
```
148
149
[Client Operations](./client.md)
150
151
### Server Operations
152
153
Full-featured Modbus server implementations with configurable data stores, custom function handlers, and simulator capabilities for testing and development.
154
155
```python { .api }
156
# Server classes
157
class ModbusTcpServer: ...
158
class ModbusUdpServer: ...
159
class ModbusSerialServer: ...
160
class ModbusTlsServer: ...
161
162
# Server start functions
163
def StartTcpServer(context, **kwargs): ...
164
def StartAsyncTcpServer(context, **kwargs): ...
165
```
166
167
[Server Operations](./server.md)
168
169
### Protocol Data Units (PDUs)
170
171
Complete implementation of all standard Modbus function codes including bit operations, register operations, file operations, and diagnostic functions.
172
173
```python { .api }
174
# Bit access messages
175
class ReadCoilsRequest: ...
176
class ReadDiscreteInputsRequest: ...
177
class WriteSingleCoilRequest: ...
178
class WriteMultipleCoilsRequest: ...
179
180
# Register access messages
181
class ReadHoldingRegistersRequest: ...
182
class ReadInputRegistersRequest: ...
183
class WriteSingleRegisterRequest: ...
184
class WriteMultipleRegistersRequest: ...
185
```
186
187
[PDU Messages](./pdu.md)
188
189
### Data Store Management
190
191
Flexible data storage implementations supporting both sequential and sparse memory layouts with full customization capabilities.
192
193
```python { .api }
194
class ModbusServerContext: ...
195
class ModbusDeviceContext: ...
196
class ModbusSequentialDataBlock: ...
197
class ModbusSparseDataBlock: ...
198
class ModbusSimulatorContext: ...
199
```
200
201
[Data Store](./datastore.md)
202
203
### Transport and Protocol Management
204
205
Low-level transport classes for custom protocol implementations and advanced connection handling.
206
207
```python { .api }
208
class CommType(int, Enum):
209
TCP = 1
210
TLS = 2
211
UDP = 3
212
SERIAL = 4
213
214
class CommParams:
215
def __init__(self, comm_name=None, comm_type=None, reconnect_delay=None,
216
reconnect_delay_max=0.0, timeout_connect=0.0, host="localhost",
217
port=0, source_address=None, handle_local_echo=False,
218
sslctx=None, baudrate=-1, bytesize=-1, parity='', stopbits=-1): ...
219
220
class ModbusProtocol:
221
def __init__(self, params, is_server=False): ...
222
async def transport_connect(self): ...
223
def transport_close(self): ...
224
225
# Special testing constant for nullmodem connections
226
NULLMODEM_HOST = "__pymodbus_nullmodem"
227
```
228
229
### Exception Handling
230
231
Specific exception classes for different types of Modbus errors and connection issues.
232
233
```python { .api }
234
class ModbusException(Exception):
235
def __init__(self, string): ...
236
def isError(self) -> bool: ...
237
238
class ConnectionException(ModbusException):
239
"""Error resulting from a bad connection."""
240
def __init__(self, string=""): ...
241
242
class ModbusIOException(ModbusException):
243
"""Error resulting from data i/o."""
244
def __init__(self, string="", function_code=None): ...
245
246
class ParameterException(ModbusException):
247
"""Error resulting from invalid parameter."""
248
def __init__(self, string=""): ...
249
250
class NoSuchIdException(ModbusException):
251
"""Error resulting from making a request to a id that does not exist."""
252
def __init__(self, string=""): ...
253
254
class NotImplementedException(ModbusException):
255
"""Error resulting from not implemented function."""
256
def __init__(self, string=""): ...
257
258
class MessageRegisterException(ModbusException):
259
"""Error resulting from failing to register a custom message request/response."""
260
def __init__(self, string=""): ...
261
```
262
263
### Debugging and Logging Utilities
264
265
Tools for debugging Modbus communications and configuring logging output.
266
267
```python { .api }
268
def pymodbus_apply_logging_config(level=logging.DEBUG, log_file_name=None):
269
"""
270
Apply basic logging configuration used by default by Pymodbus maintainers.
271
272
Parameters:
273
- level: Set log level (str or int)
274
- log_file_name: Optional log file name for file output
275
"""
276
277
def pymodbus_get_last_frames() -> str:
278
"""
279
Prepare and return last frames for automatic debugging.
280
281
Returns:
282
str: Formatted string of recent frame data for debugging
283
"""
284
```
285
286
### Simulator Functionality
287
288
Web-based Modbus server simulator with REST API and browser interface for testing and development.
289
290
```python { .api }
291
class ModbusSimulatorServer:
292
"""HTTP server for modbus simulator with web interface."""
293
def __init__(self, json_file="setup.json", custom_actions_module=None, http_host="localhost", http_port=8080): ...
294
async def start_server(self, modbus_server=None, modbus_device=None): ...
295
def stop_server(self): ...
296
297
def get_simulator_commandline():
298
"""Get command line interface for simulator."""
299
```
300
301
## Core Types
302
303
```python { .api }
304
# Frame types
305
class FramerType(str, Enum):
306
ASCII = "ascii"
307
RTU = "rtu"
308
SOCKET = "socket"
309
TLS = "tls"
310
311
# Status codes
312
class ModbusStatus(int, Enum):
313
WAITING = 0xFFFF
314
READY = 0x0000
315
ON = 0xFF00
316
OFF = 0x0000
317
318
# Exception codes
319
class ExcCodes(int, Enum):
320
ILLEGAL_FUNCTION = 0x01
321
ILLEGAL_ADDRESS = 0x02
322
ILLEGAL_VALUE = 0x03
323
DEVICE_FAILURE = 0x04
324
ACKNOWLEDGE = 0x05
325
DEVICE_BUSY = 0x06
326
MEMORY_PARITY_ERROR = 0x08
327
GATEWAY_PATH_UNAVIABLE = 0x0A
328
GATEWAY_NO_RESPONSE = 0x0B
329
330
# Device information types
331
class DeviceInformation(int, Enum):
332
BASIC = 0x01
333
REGULAR = 0x02
334
EXTENDED = 0x03
335
SPECIFIC = 0x04
336
337
# More data indicators
338
class MoreData(int, Enum):
339
NOTHING = 0x00
340
KEEP_READING = 0xFF
341
342
# Modbus Plus operations
343
class ModbusPlusOperation(int, Enum):
344
GET_STATISTICS = 0x03
345
CLEAR_STATISTICS = 0x04
346
347
# Base exception class
348
class ModbusException(Exception): ...
349
350
# Device identification
351
class ModbusDeviceIdentification:
352
def __init__(self, info=None): ...
353
def update(self, value): ...
354
def __getitem__(self, key): ...
355
def __setitem__(self, key, value): ...
356
357
# Logging configuration
358
def pymodbus_apply_logging_config(level=logging.DEBUG): ...
359
```