API Reference

This section provides detailed API documentation for all ModbusLink classes and functions.

Client Module

ModbusClient

class modbuslink.client.sync_client.ModbusClient(transport: BaseTransport)[source]

Bases: object

同步Modbus客户端提供简洁、用户友好的Modbus操作接口。通过依赖注入的方式接收传输层实例，支持RTU和TCP等不同传输方式。所有方法都使用Python原生数据类型（int, list等），将底层的字节操作完全封装。

Synchronous Modbus Client Provides a concise, user-friendly Modbus operation interface. Receives transport layer instances through dependency injection, supporting different transport methods such as RTU and TCP. All methods use Python native data types (int, list, etc.), completely encapsulating underlying byte operations.

__init__(transport: BaseTransport)[source]

初始化Modbus客户端

Initialize Modbus Client

Parameters:: transport – 传输层实例（RtuTransport或TcpTransport） | Transport layer instance (RtuTransport or TcpTransport)

read_coils(slave_id: int, start_address: int, quantity: int) → List[bool][source]

读取线圈状态（功能码0x01） | Read Coil Status (Function Code 0x01)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
quantity – 读取数量（1-2000） | Quantity to read (1-2000)

Returns:

线圈状态列表，True表示ON，False表示OFF

List of coil status, True for ON, False for OFF

Example

>>> client.read_coils(1, 0, 8)
[True, False, True, False, False, False, True, False]

read_discrete_inputs(slave_id: int, start_address: int, quantity: int) → List[bool][source]

读取离散输入状态（功能码0x02） | Read Discrete Input Status (Function Code 0x02)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
quantity – 读取数量（1-2000） | Quantity to read (1-2000)

Returns:

离散输入状态列表，True表示ON，False表示OFF

List of discrete input status, True for ON, False for OFF

read_holding_registers(slave_id: int, start_address: int, quantity: int) → List[int][source]

读取保持寄存器（功能码0x03） | Read Holding Registers (Function Code 0x03)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
quantity – 读取数量（1-125） | Quantity to read (1-125)

Returns:

寄存器值列表，每个值为16位无符号整数（0-65535）

List of register values, each value is a 16-bit unsigned integer (0-65535)

Example

>>> client.read_holding_registers(1, 0, 4)
[1234, 5678, 9012, 3456]

read_input_registers(slave_id: int, start_address: int, quantity: int) → List[int][source]

读取输入寄存器（功能码0x04） | Read Input Registers (Function Code 0x04)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
quantity – 读取数量（1-125） | Quantity to read (1-125)

Returns:

寄存器值列表，每个值为16位无符号整数（0-65535）

List of register values, each value is a 16-bit unsigned integer (0-65535)

write_single_coil(slave_id: int, address: int, value: bool) → None[source]

写单个线圈（功能码0x05） | Write Single Coil (Function Code 0x05)

Parameters:

slave_id – 从站地址 | Slave address
address – 线圈地址 | Coil address
value – 线圈值，True表示ON，False表示OFF | Coil value, True for ON, False for OFF

Example

>>> client.write_single_coil(1, 0, True)  # 设置线圈0为ON | Set coil 0 to ON

write_single_register(slave_id: int, address: int, value: int) → None[source]

写单个寄存器（功能码0x06） | Write Single Register (Function Code 0x06)

Parameters:

slave_id – 从站地址 | Slave address
address – 寄存器地址 | Register address
value – 寄存器值（0-65535） | Register value (0-65535)

Example

>>> client.write_single_register(1, 0, 1234)

write_multiple_coils(slave_id: int, start_address: int, values: List[bool]) → None[source]

写多个线圈（功能码0x0F） | Write Multiple Coils (Function Code 0x0F)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
values – 线圈值列表，True表示ON，False表示OFF | List of coil values, True for ON, False for OFF

Example

>>> client.write_multiple_coils(1, 0, [True, False, True, False])

write_multiple_registers(slave_id: int, start_address: int, values: List[int]) → None[source]

写多个寄存器（功能码0x10） | Write Multiple Registers (Function Code 0x10)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
values – 寄存器值列表，每个值为0-65535 | List of register values, each value 0-65535

Example

>>> client.write_multiple_registers(1, 0, [1234, 5678, 9012])

__enter__() → ModbusClient[source]: 上下文管理器入口 | Context manager entry

__exit__(exc_type: type | None, exc_val: BaseException | None, exc_tb: Any | None) → None[source]: 上下文管理器出口 | Context manager exit

read_float32(slave_id: int, start_address: int, byte_order: str = 'big', word_order: str = 'high') → float[source]

读取32位浮点数（占用2个连续寄存器） | Read 32-bit float (occupies 2 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’

Returns:

32位浮点数值 | 32-bit float value

Example

>>> temperature = client.read_float32(1, 100)  # 读取温度传感器值 | Read temperature sensor value

write_float32(slave_id: int, start_address: int, value: float, byte_order: str = 'big', word_order: str = 'high') → None[source]

写入32位浮点数（占用2个连续寄存器） | Write 32-bit float (occupies 2 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
value – 要写入的浮点数值 | Float value to write
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’

Example

>>> client.write_float32(1, 100, 25.6)  # 写入温度设定值 | Write temperature setpoint

read_int32(slave_id: int, start_address: int, byte_order: str = 'big', word_order: str = 'high') → int[source]

读取32位有符号整数（占用2个连续寄存器） | Read 32-bit signed integer (occupies 2 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’

Returns:

32位有符号整数值 | 32-bit signed integer value

write_int32(slave_id: int, start_address: int, value: int, byte_order: str = 'big', word_order: str = 'high') → None[source]

写入32位有符号整数（占用2个连续寄存器） | Write 32-bit signed integer (occupies 2 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
value – 要写入的整数值 | Integer value to write
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’

read_uint32(slave_id: int, start_address: int, byte_order: str = 'big', word_order: str = 'high') → int[source]

读取32位无符号整数（占用2个连续寄存器） | Read 32-bit unsigned integer (occupies 2 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’

Returns:

32位无符号整数值 | 32-bit unsigned integer value

write_uint32(slave_id: int, start_address: int, value: int, byte_order: str = 'big', word_order: str = 'high') → None[source]

写入32位无符号整数（占用2个连续寄存器） | Write 32-bit unsigned integer (occupies 2 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
value – 要写入的无符号整数值 | Unsigned integer value to write
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’

read_int64(slave_id: int, start_address: int, byte_order: str = 'big', word_order: str = 'high') → int[source]

读取64位有符号整数（占用4个连续寄存器） | Read 64-bit signed integer (occupies 4 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’

Returns:

64位有符号整数值 | 64-bit signed integer value

write_int64(slave_id: int, start_address: int, value: int, byte_order: str = 'big', word_order: str = 'high') → None[source]

写入64位有符号整数（占用4个连续寄存器） | Write 64-bit signed integer (occupies 4 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
value – 要写入的整数值 | Integer value to write
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’

read_uint64(slave_id: int, start_address: int, byte_order: str = 'big', word_order: str = 'high') → int[source]

读取64位无符号整数（占用4个连续寄存器） | Read 64-bit unsigned integer (occupies 4 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’

Returns:

64位无符号整数值 | 64-bit unsigned integer value

write_uint64(slave_id: int, start_address: int, value: int, byte_order: str = 'big', word_order: str = 'high') → None[source]

写入64位无符号整数（占用4个连续寄存器） | Write 64-bit unsigned integer (occupies 4 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
value – 要写入的无符号整数值 | Unsigned integer value to write
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’

read_string(slave_id: int, start_address: int, length: int, encoding: str = 'utf-8') → str[source]

读取字符串（从连续寄存器中） | Read string (from consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
length – 字符串字节长度 | String byte length
encoding – 字符编码，默认’utf-8’ | Character encoding, default ‘utf-8’

Returns:

解码后的字符串 | Decoded string

Example

>>> device_name = client.read_string(1, 200, 16)  # 读取设备名称 | Read device name

write_string(slave_id: int, start_address: int, value: str, encoding: str = 'utf-8') → None[source]

写入字符串（到连续寄存器中） | Write string (to consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
value – 要写入的字符串 | String to write
encoding – 字符编码，默认’utf-8’ | Character encoding, default ‘utf-8’

Example

>>> client.write_string(1, 200, "ModbusLink")  # 写入设备名称 | Write device name

__repr__() → str[source]: 字符串表示 | String representation

AsyncModbusClient

class modbuslink.client.async_client.AsyncModbusClient(transport: AsyncBaseTransport)[source]

Bases: object

异步Modbus客户端提供简洁、用户友好的异步Modbus操作接口。通过依赖注入的方式接收异步传输层实例，支持异步TCP等传输方式。所有方法都使用Python原生数据类型（int, list等），将底层的字节操作完全封装，并支持回调机制。

Asynchronous Modbus Client Provides a concise, user-friendly asynchronous Modbus operation interface. Receives async transport layer instances through dependency injection, supporting async transport methods such as async TCP. All methods use Python native data types (int, list, etc.), completely encapsulating underlying byte operations, and support callback mechanisms.

__init__(transport: AsyncBaseTransport)[source]

初始化异步Modbus客户端

Initialize Async Modbus Client

Parameters:: transport – 异步传输层实例（AsyncTcpTransport等） | Async transport layer instance (AsyncTcpTransport, etc.)

async read_coils(slave_id: int, start_address: int, quantity: int, callback: Callable[[List[bool]], None] | None = None) → List[bool][source]

异步读取线圈状态（功能码0x01） | Async Read Coil Status (Function Code 0x01)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
quantity – 读取数量（1-2000） | Quantity to read (1-2000)
callback – 可选的回调函数，在收到响应后调用 | Optional callback function, called after receiving response

Returns:

线圈状态列表，True表示ON，False表示OFF

List of coil status, True for ON, False for OFF

Example

>>> coils = await client.read_coils(1, 0, 8)
[True, False, True, False, False, False, True, False]

async read_discrete_inputs(slave_id: int, start_address: int, quantity: int, callback: Callable[[List[bool]], None] | None = None) → List[bool][source]

异步读取离散输入状态（功能码0x02） | Async Read Discrete Input Status (Function Code 0x02)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
quantity – 读取数量（1-2000） | Quantity to read (1-2000)
callback – 可选的回调函数，在收到响应后调用 | Optional callback function, called after receiving response

Returns:

离散输入状态列表，True表示ON，False表示OFF

List of discrete input status, True for ON, False for OFF

async read_holding_registers(slave_id: int, start_address: int, quantity: int, callback: Callable[[List[int]], None] | None = None) → List[int][source]

异步读取保持寄存器（功能码0x03） | Async Read Holding Registers (Function Code 0x03)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
quantity – 读取数量（1-125） | Quantity to read (1-125)
callback – 可选的回调函数，在收到响应后调用 | Optional callback function, called after receiving response

Returns:

寄存器值列表，每个值为16位无符号整数（0-65535）

List of register values, each value is a 16-bit unsigned integer (0-65535)

Example

>>> registers = await client.read_holding_registers(1, 0, 4)
[1234, 5678, 9012, 3456]

async read_input_registers(slave_id: int, start_address: int, quantity: int, callback: Callable[[List[int]], None] | None = None) → List[int][source]

异步读取输入寄存器（功能码0x04） | Async Read Input Registers (Function Code 0x04)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
quantity – 读取数量（1-125） | Quantity to read (1-125)
callback – 可选的回调函数，在收到响应后调用 | Optional callback function, called after receiving response

Returns:

寄存器值列表，每个值为16位无符号整数（0-65535）

List of register values, each value is a 16-bit unsigned integer (0-65535)

async write_single_coil(slave_id: int, address: int, value: bool, callback: Callable[[], None] | None = None) → None[source]

异步写单个线圈（功能码0x05） | Async Write Single Coil (Function Code 0x05)

Parameters:

slave_id – 从站地址 | Slave address
address – 线圈地址 | Coil address
value – 线圈值，True表示ON，False表示OFF | Coil value, True for ON, False for OFF
callback – 可选的回调函数，在操作完成后调用 | Optional callback function, called after operation completes

Example

>>> await client.write_single_coil(1, 0, True)  # 设置线圈0为ON | Set coil 0 to ON

async write_single_register(slave_id: int, address: int, value: int, callback: Callable[[], None] | None = None) → None[source]

异步写单个寄存器（功能码0x06） | Async Write Single Register (Function Code 0x06)

Parameters:

slave_id – 从站地址 | Slave address
address – 寄存器地址 | Register address
value – 寄存器值（0-65535） | Register value (0-65535)
callback – 可选的回调函数，在操作完成后调用 | Optional callback function, called after operation completes

Example

>>> await client.write_single_register(1, 0, 1234)

async write_multiple_coils(slave_id: int, start_address: int, values: List[bool], callback: Callable[[], None] | None = None) → None[source]

异步写多个线圈（功能码0x0F） | Async Write Multiple Coils (Function Code 0x0F)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
values – 线圈值列表，True表示ON，False表示OFF | List of coil values, True for ON, False for OFF
callback – 可选的回调函数，在操作完成后调用 | Optional callback function, called after operation completes

Example

>>> await client.write_multiple_coils(1, 0, [True, False, True, False])

async write_multiple_registers(slave_id: int, start_address: int, values: List[int], callback: Callable[[], None] | None = None) → None[source]

异步写多个寄存器（功能码0x10） | Async Write Multiple Registers (Function Code 0x10)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始地址 | Starting address
values – 寄存器值列表，每个值为0-65535 | List of register values, each value 0-65535
callback – 可选的回调函数，在操作完成后调用 | Optional callback function, called after operation completes

Example

>>> await client.write_multiple_registers(1, 0, [1234, 5678, 9012])

async read_float32(slave_id: int, start_address: int, byte_order: str = 'big', word_order: str = 'high', callback: Callable[[float], None] | None = None) → float[source]

异步读取32位浮点数（占用2个连续寄存器） | Async Read 32-bit float (occupies 2 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’
callback – 可选的回调函数，在收到响应后调用 | Optional callback function, called after receiving response

Returns:

32位浮点数值 | 32-bit float value

async write_float32(slave_id: int, start_address: int, value: float, byte_order: str = 'big', word_order: str = 'high', callback: Callable[[], None] | None = None) → None[source]

异步写入32位浮点数（占用2个连续寄存器） | Async Write 32-bit float (occupies 2 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
value – 要写入的浮点数值 | Float value to write
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’
callback – 可选的回调函数，在操作完成后调用 | Optional callback function, called after operation completes

async read_int32(slave_id: int, start_address: int, byte_order: str = 'big', word_order: str = 'high', callback: Callable[[int], None] | None = None) → int[source]

异步读取32位有符号整数（占用2个连续寄存器） | Async Read 32-bit signed integer (occupies 2 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’
callback – 可选的回调函数，在收到响应后调用 | Optional callback function, called after receiving response

Returns:

32位有符号整数值 | 32-bit signed integer value

async write_int32(slave_id: int, start_address: int, value: int, byte_order: str = 'big', word_order: str = 'high', callback: Callable[[], None] | None = None) → None[source]

异步写入32位有符号整数（占用2个连续寄存器） | Async Write 32-bit signed integer (occupies 2 consecutive registers)

Parameters:

slave_id – 从站地址 | Slave address
start_address – 起始寄存器地址 | Starting register address
value – 要写入的整数值 | Integer value to write
byte_order – 字节序，’big’或’little’ | Byte order, ‘big’ or ‘little’
word_order – 字序，’high’或’low’ | Word order, ‘high’ or ‘low’
callback – 可选的回调函数，在操作完成后调用 | Optional callback function, called after operation completes

async __aenter__() → Self[source]: 异步上下文管理器入口 | Async context manager entry

async __aexit__(exc_type: type | None, exc_val: BaseException | None, exc_tb: Any | None) → None[source]: 异步上下文管理器出口 | Async context manager exit

Transport Module

BaseTransport

class modbuslink.transport.base.BaseTransport[source]

Bases: ABC

传输层抽象基类所有传输层实现（RTU, TCP等）都必须继承此类并实现所有抽象方法。这个设计将CRC校验、MBAP头处理等复杂性完全封装在传输层内部，为客户端提供统一、简洁的接口。

Transport Layer Abstract Base Class All transport layer implementations (RTU, TCP, etc.) must inherit from this class and implement all abstract methods. This design completely encapsulates complexities such as CRC verification and MBAP header processing within the transport layer, providing a unified and concise interface for clients.

abstract open() → None[source]

打开传输连接建立与Modbus设备的连接。对于串口是打开串口，对于TCP是建立socket连接。

Open Transport Connection Establishes connection with Modbus device. For serial port, opens the port; for TCP, establishes socket connection.

Raises:: ConnectionError – 当无法建立连接时 | When connection cannot be established

abstract close() → None[source]

关闭传输连接关闭与Modbus设备的连接并释放相关资源。

Close Transport Connection Closes connection with Modbus device and releases related resources.

abstract is_open() → bool[source]

检查连接状态

Check Connection Status

Returns:

如果连接已建立且可用返回True，否则返回False

True if connection is established and available, False otherwise

abstract send_and_receive(slave_id: int, pdu: bytes) → bytes[source]

发送PDU并接收响应这是传输层的核心方法。它接收纯净的PDU（协议数据单元），负责添加必要的传输层信息（如RTU的地址和CRC，或TCP的MBAP头），发送请求，接收响应，验证响应的完整性，然后返回响应的PDU部分。

Send PDU and Receive Response This is the core method of the transport layer. It receives pure PDU (Protocol Data Unit), is responsible for adding necessary transport layer information (such as RTU address and CRC, or TCP MBAP header), sends requests, receives responses, verifies response integrity, and then returns the PDU part of the response.

Parameters:

slave_id – 从站地址/单元标识符 | Slave address/unit identifier
pdu – 协议数据单元，包含功能码和数据，不包含地址和校验 | Protocol Data Unit, contains function code and data, excludes address and checksum

Returns:

响应的PDU部分，已去除传输层信息

PDU part of response with transport layer information removed

Raises:

ConnectionError – 连接错误 | Connection error
TimeoutError – 操作超时 | Operation timeout
CRCError – CRC校验失败（仅RTU） | CRC verification failed (RTU only)
InvalidResponseError – 响应格式无效 | Invalid response format

__enter__() → BaseTransport[source]: 上下文管理器入口 | Context Manager Entry

__exit__(exc_type: type | None, exc_val: BaseException | None, exc_tb: Any | None) → None[source]: 上下文管理器出口 | Context Manager Exit

TcpTransport

class modbuslink.transport.tcp.TcpTransport(host: str, port: int = 502, timeout: float = 10.0)[source]

Bases: BaseTransport

Modbus TCP传输层实现处理基于TCP/IP的Modbus TCP通信，包括：

Modbus TCP Transport Layer Implementation Handles Modbus TCP communication based on TCP/IP, including:

TCP socket连接管理 | TCP socket connection management
MBAP头的构建和解析 | MBAP header construction and parsing
事务标识符管理 | Transaction identifier management
错误处理和超时管理 | Error handling and timeout management

__init__(host: str, port: int = 502, timeout: float = 10.0)[source]

初始化TCP传输层

Initialize TCP transport layer

Parameters:

host – 目标主机IP地址或域名 | Target host IP address or domain name
port – 目标端口，默认502（Modbus TCP标准端口） | Target port, default 502 (Modbus TCP standard port)
timeout – 超时时间（秒），默认10.0秒 | Timeout in seconds, default 10.0 seconds

Raises:

ValueError – 当参数无效时 | When parameters are invalid
TypeError – 当参数类型错误时 | When parameter types are incorrect

open() → None[source]: 建立TCP连接 | Establish TCP connection

close() → None[source]: 关闭TCP连接 | Close TCP connection

is_open() → bool[source]: 检查TCP连接状态 | Check TCP connection status

send_and_receive(slave_id: int, pdu: bytes) → bytes[source]

发送PDU并接收响应实现TCP协议的完整通信流程：

Send PDU and receive response Implements complete TCP protocol communication flow:

构建MBAP头 | Build MBAP header
发送请求（MBAP头 + PDU） | Send request (MBAP header + PDU)
接收响应MBAP头 | Receive response MBAP header
验证MBAP头 | Validate MBAP header
接收响应PDU | Receive response PDU
返回响应PDU | Return response PDU

__repr__() → str[source]: 字符串表示 | String representation

RtuTransport

class modbuslink.transport.rtu.RtuTransport(port: str, baudrate: int = 9600, bytesize: int = 8, parity: str = 'N', stopbits: float = 1, timeout: float = 1.0)[source]

Bases: BaseTransport

Modbus RTU传输层实现处理基于串口的Modbus RTU通信，包括：

Modbus RTU Transport Layer Implementation Handles Modbus RTU communication based on serial port, including:

串口连接管理 | Serial port connection management
CRC16校验码的计算和验证 | CRC16 checksum calculation and validation
ADU（应用数据单元）的构建和解析 | ADU (Application Data Unit) construction and parsing
错误处理和超时管理 | Error handling and timeout management

__init__(port: str, baudrate: int = 9600, bytesize: int = 8, parity: str = 'N', stopbits: float = 1, timeout: float = 1.0)[source]

初始化RTU传输层

Initialize RTU transport layer

Parameters:

port – 串口名称 (如 ‘COM1’, ‘/dev/ttyUSB0’) | Serial port name (e.g. ‘COM1’, ‘/dev/ttyUSB0’)
baudrate – 波特率，默认9600 | Baud rate, default 9600
bytesize – 数据位，默认8位 | Data bits, default 8 bits
parity – 校验位，默认无校验 | Parity, default no parity
stopbits – 停止位，默认1位 | Stop bits, default 1 bit
timeout – 超时时间（秒），默认1.0秒 | Timeout in seconds, default 1.0 seconds

Raises:

ValueError – 当参数无效时 | When parameters are invalid
TypeError – 当参数类型错误时 | When parameter types are incorrect

open() → None[source]

打开串口连接

Open serial port connection

close() → None[source]

关闭串口连接

Close serial port connection

is_open() → bool[source]

检查串口连接状态

Check serial port connection status

send_and_receive(slave_id: int, pdu: bytes) → bytes[source]

发送PDU并接收响应实现RTU协议的完整通信流程：

Send PDU and receive response Implements complete RTU protocol communication flow:

构建ADU（地址 + PDU + CRC） | Build ADU (Address + PDU + CRC)
发送请求 | Send request
接收响应 | Receive response
验证CRC | Validate CRC
返回响应PDU | Return response PDU

__repr__() → str[source]: 字符串表示 | String representation

AsyncBaseTransport

class modbuslink.transport.async_base.AsyncBaseTransport[source]

Bases: ABC

异步传输层抽象基类所有异步传输层实现（AsyncTCP等）都必须继承此类并实现所有抽象方法。这个设计将CRC校验、MBAP头处理等复杂性完全封装在传输层内部，为异步客户端提供统一、简洁的接口。

Async Transport Layer Abstract Base Class All async transport layer implementations (AsyncTCP, etc.) must inherit from this class and implement all abstract methods. This design completely encapsulates complexities such as CRC verification and MBAP header processing within the transport layer, providing a unified and concise interface for async clients.

abstract async open() → None[source]

异步打开传输连接异步建立与Modbus设备的连接。对于TCP是建立异步socket连接。

Async Open Transport Connection Asynchronously establishes connection with Modbus device. For TCP, establishes async socket connection.

Raises:: ConnectionError – 当无法建立连接时 | When connection cannot be established

abstract async close() → None[source]

异步关闭传输连接异步关闭与Modbus设备的连接并释放相关资源。

Async Close Transport Connection Asynchronously closes connection with Modbus device and releases related resources.

abstract async is_open() → bool[source]

异步检查连接状态

Async Check Connection Status

Returns:

如果连接已建立且可用返回True，否则返回False

True if connection is established and available, False otherwise

abstract async send_and_receive(slave_id: int, pdu: bytes) → bytes[source]

异步发送PDU并接收响应这是异步传输层的核心方法。它接收纯净的PDU（协议数据单元），负责添加必要的传输层信息（如TCP的MBAP头），异步发送请求，接收响应，验证响应的完整性，然后返回响应的PDU部分。

Async Send PDU and Receive Response

This is the core method of the async transport layer. It receives pure PDU (Protocol Data Unit), is responsible for adding necessary transport layer information (such as TCP MBAP header), asynchronously sends requests, receives responses, verifies response integrity, and then returns the PDU part of the response.

Parameters:

slave_id – 从站地址/单元标识符 | Slave address/unit identifier
pdu – 协议数据单元，包含功能码和数据，不包含地址和校验 | Protocol Data Unit, contains function code and data, excludes address and checksum

Returns:

响应的PDU部分，已去除传输层信息

PDU part of response with transport layer information removed

Raises:

ConnectionError – 连接错误 | Connection error
TimeoutError – 操作超时 | Operation timeout
InvalidResponseError – 响应格式无效 | Invalid response format

async __aenter__() → AsyncBaseTransport[source]: 异步上下文管理器入口 | Async Context Manager Entry

async __aexit__(exc_type: type | None, exc_val: BaseException | None, exc_tb: Any | None) → None[source]: 异步上下文管理器出口 | Async Context Manager Exit

AsyncTcpTransport

class modbuslink.transport.async_tcp.AsyncTcpTransport(host: str, port: int = 502, timeout: float = 10.0)[source]

Bases: AsyncBaseTransport

异步Modbus TCP传输层实现处理基于asyncio的异步Modbus TCP通信，包括：

Async Modbus TCP Transport Layer Implementation Handles async Modbus TCP communication based on asyncio, including:

异步TCP socket连接管理 | Async TCP socket connection management
MBAP头的构建和解析 | MBAP header construction and parsing
事务标识符管理 | Transaction identifier management
异步错误处理和超时管理 | Async error handling and timeout management

__init__(host: str, port: int = 502, timeout: float = 10.0)[source]

初始化异步TCP传输层

Initialize async TCP transport layer

Parameters:

host – 目标主机IP地址或域名 | Target host IP address or domain name
port – 目标端口，默认502（Modbus TCP标准端口） | Target port, default 502 (Modbus TCP standard port)
timeout – 超时时间（秒），默认10.0秒 | Timeout in seconds, default 10.0 seconds

Raises:

ValueError – 当参数无效时 | When parameters are invalid
TypeError – 当参数类型错误时 | When parameter types are incorrect

async open() → None[source]: 异步建立TCP连接 | Async establish TCP connection

async close() → None[source]: 异步关闭TCP连接 | Async close TCP connection

async is_open() → bool[source]: 异步检查TCP连接状态 | Async check TCP connection status

async send_and_receive(slave_id: int, pdu: bytes) → bytes[source]

异步发送PDU并接收响应实现异步TCP协议的完整通信流程：

Async send PDU and receive response Implements complete async TCP protocol communication flow:

构建MBAP头 | Build MBAP header
异步发送请求（MBAP头 + PDU） | Async send request (MBAP header + PDU)
异步接收响应MBAP头 | Async receive response MBAP header
验证MBAP头 | Validate MBAP header
异步接收响应PDU | Async receive response PDU
返回响应PDU | Return response PDU

__repr__() → str[source]: 字符串表示 | String representation

AsciiTransport

class modbuslink.transport.ascii.AsciiTransport(port: str, baudrate: int = 9600, bytesize: int = 7, parity: str = 'E', stopbits: float = 1, timeout: float = 1.0)[source]

Bases: BaseTransport

Modbus ASCII传输层实现处理基于串口的Modbus ASCII通信，包括：

Modbus ASCII Transport Layer Implementation Handles Modbus ASCII communication based on serial port, including:

串口连接管理 | Serial port connection management
LRC校验码的计算和验证 | LRC checksum calculation and validation
ASCII编码和解码 | ASCII encoding and decoding
ADU（应用数据单元）的构建和解析 | ADU (Application Data Unit) construction and parsing
错误处理和超时管理 | Error handling and timeout management

__init__(port: str, baudrate: int = 9600, bytesize: int = 7, parity: str = 'E', stopbits: float = 1, timeout: float = 1.0)[source]

初始化ASCII传输层

Initialize ASCII transport layer

Parameters:

port – 串口名称 (如 ‘COM1’, ‘/dev/ttyUSB0’) | Serial port name (e.g. ‘COM1’, ‘/dev/ttyUSB0’)
baudrate – 波特率，默认9600 | Baud rate, default 9600
bytesize – 数据位，默认7位 | Data bits, default 7 bits
parity – 校验位，默认偶校验 | Parity, default even parity
stopbits – 停止位，默认1位 | Stop bits, default 1 bit
timeout – 超时时间（秒），默认1.0秒 | Timeout in seconds, default 1.0 seconds

Raises:

ValueError – 当参数无效时 | When parameters are invalid
TypeError – 当参数类型错误时 | When parameter types are incorrect

open() → None[source]

打开串口连接

Open serial port connection

close() → None[source]

关闭串口连接

Close serial port connection

is_open() → bool[source]

检查串口连接状态

Check serial port connection status

send_and_receive(slave_id: int, pdu: bytes) → bytes[source]

发送PDU并接收响应实现ASCII协议的完整通信流程：

Send PDU and receive response Implements complete ASCII protocol communication flow:

构建ASCII帧（:地址PDU LRC CR LF） | Build ASCII frame (:Address PDU LRC CR LF)
发送请求 | Send request
接收响应 | Receive response
验证LRC | Validate LRC
返回响应PDU | Return response PDU

__repr__() → str[source]

返回传输层的字符串表示

Return string representation of transport layer

AsyncRtuTransport

class modbuslink.transport.async_rtu.AsyncRtuTransport(port: str, baudrate: int = 9600, bytesize: int = 8, parity: str = 'N', stopbits: float = 1, timeout: float = 1.0)[source]

Bases: AsyncBaseTransport

异步Modbus RTU传输层实现处理基于asyncio的异步Modbus RTU通信，包括：

Async Modbus RTU Transport Layer Implementation Handles async Modbus RTU communication based on asyncio, including:

异步串口连接管理 | Async serial port connection management
CRC16校验码的计算和验证 | CRC16 checksum calculation and validation
ADU（应用数据单元）的构建和解析 | ADU (Application Data Unit) construction and parsing
异步错误处理和超时管理 | Async error handling and timeout management

__init__(port: str, baudrate: int = 9600, bytesize: int = 8, parity: str = 'N', stopbits: float = 1, timeout: float = 1.0)[source]

初始化异步RTU传输层

Initialize async RTU transport layer

Parameters:

port – 串口名称 (如 ‘COM1’, ‘/dev/ttyUSB0’) | Serial port name (e.g. ‘COM1’, ‘/dev/ttyUSB0’)
baudrate – 波特率，默认9600 | Baud rate, default 9600
bytesize – 数据位，默认8位 | Data bits, default 8 bits
parity – 校验位，默认无校验 | Parity, default no parity
stopbits – 停止位，默认1位 | Stop bits, default 1 bit
timeout – 超时时间（秒），默认1.0秒 | Timeout in seconds, default 1.0 seconds

Raises:

ValueError – 当参数无效时 | When parameters are invalid
TypeError – 当参数类型错误时 | When parameter types are incorrect

async open() → None[source]

异步打开串口连接

Async open serial port connection

async close() → None[source]

异步关闭串口连接

Async close serial port connection

async is_open() → bool[source]

异步检查串口连接状态

Async check serial port connection status

async send_and_receive(slave_id: int, pdu: bytes) → bytes[source]

异步发送PDU并接收响应实现异步RTU协议的完整通信流程：

Async send PDU and receive response Implements complete async RTU protocol communication flow:

构建ADU（地址 + PDU + CRC） | Build ADU (Address + PDU + CRC)
异步发送请求 | Async send request
异步接收响应 | Async receive response
验证CRC | Validate CRC
返回响应PDU | Return response PDU

__repr__() → str[source]

返回传输层的字符串表示

Return string representation of transport layer

AsyncAsciiTransport

class modbuslink.transport.async_ascii.AsyncAsciiTransport(port: str, baudrate: int = 9600, bytesize: int = 7, parity: str = 'E', stopbits: float = 1, timeout: float = 1.0)[source]

Bases: AsyncBaseTransport

异步Modbus ASCII传输层实现处理基于asyncio的异步Modbus ASCII通信，包括：

Async Modbus ASCII Transport Layer Implementation Handles async Modbus ASCII communication based on asyncio, including:

异步串口连接管理 | Async serial port connection management
LRC校验码的计算和验证 | LRC checksum calculation and validation
ASCII编码和解码 | ASCII encoding and decoding
ADU（应用数据单元）的构建和解析 | ADU (Application Data Unit) construction and parsing
异步错误处理和超时管理 | Async error handling and timeout management

__init__(port: str, baudrate: int = 9600, bytesize: int = 7, parity: str = 'E', stopbits: float = 1, timeout: float = 1.0)[source]

初始化异步ASCII传输层

Initialize async ASCII transport layer

Parameters:

port – 串口名称 (如 ‘COM1’, ‘/dev/ttyUSB0’) | Serial port name (e.g. ‘COM1’, ‘/dev/ttyUSB0’)
baudrate – 波特率，默认9600 | Baud rate, default 9600
bytesize – 数据位，默认7位 | Data bits, default 7 bits
parity – 校验位，默认偶校验 | Parity, default even parity
stopbits – 停止位，默认1位 | Stop bits, default 1 bit
timeout – 超时时间（秒），默认1.0秒 | Timeout in seconds, default 1.0 seconds

Raises:

ValueError – 当参数无效时 | When parameters are invalid
TypeError – 当参数类型错误时 | When parameter types are incorrect

async open() → None[source]

异步打开串口连接

Async open serial port connection

async close() → None[source]

异步关闭串口连接

Async close serial port connection

async is_open() → bool[source]

异步检查串口连接状态

Async check serial port connection status

async send_and_receive(slave_id: int, pdu: bytes) → bytes[source]

异步发送PDU并接收响应实现异步ASCII协议的完整通信流程：

Async send PDU and receive response Implements complete async ASCII protocol communication flow:

构建ASCII帧（:地址PDU LRC CR LF） | Build ASCII frame (:Address PDU LRC CR LF)
异步发送请求 | Async send request
异步接收响应 | Async receive response
验证LRC | Validate LRC
返回响应PDU | Return response PDU

__repr__() → str[source]

返回传输层的字符串表示

Return string representation of transport layer

Server Module

ModbusDataStore

class modbuslink.server.data_store.ModbusDataStore(coils_size: int = 65536, discrete_inputs_size: int = 65536, holding_registers_size: int = 65536, input_registers_size: int = 65536)[source]

Bases: object

Modbus数据存储类提供线程安全的Modbus数据存储功能，支持线圈、离散输入、保持寄存器和输入寄存器的读写操作。

Modbus Data Store Class Provides thread-safe Modbus data storage functionality, supporting read/write operations for coils, discrete inputs, holding registers, and input registers.

__init__(coils_size: int = 65536, discrete_inputs_size: int = 65536, holding_registers_size: int = 65536, input_registers_size: int = 65536)[source]

初始化数据存储

Initialize Data Store

Parameters:

coils_size – 线圈数量 | Number of coils
discrete_inputs_size – 离散输入数量 | Number of discrete inputs
holding_registers_size – 保持寄存器数量 | Number of holding registers
input_registers_size – 输入寄存器数量 | Number of input registers

read_coils(address: int, count: int) → List[bool][source]

读取线圈状态

Read Coil Status

Parameters:

address – 起始地址 | Starting address
count – 读取数量 | Number to read

Returns:

线圈状态列表 | List of coil status

Raises:

ValueError – 地址或数量无效 | Invalid address or count

write_coils(address: int, values: List[bool]) → None[source]

写入线圈状态

Write Coil Status

Parameters:

address – 起始地址 | Starting address
values – 线圈状态列表 | List of coil status

Raises:

ValueError – 地址或数据无效 | Invalid address or data

read_discrete_inputs(address: int, count: int) → List[bool][source]

读取离散输入状态

Read Discrete Input Status

Parameters:

address – 起始地址 | Starting address
count – 读取数量 | Number to read

Returns:

离散输入状态列表 | List of discrete input status

Raises:

ValueError – 地址或数量无效 | Invalid address or count

write_discrete_inputs(address: int, values: List[bool]) → None[source]

写入离散输入状态（通常用于模拟） | Write Discrete Input Status (usually for simulation)

Parameters:

address – 起始地址 | Starting address
values – 离散输入状态列表 | List of discrete input status

Raises:

ValueError – 地址或数据无效 | Invalid address or data

read_holding_registers(address: int, count: int) → List[int][source]

读取保持寄存器

Read Holding Registers

Parameters:

address – 起始地址 | Starting address
count – 读取数量 | Number to read

Returns:

保持寄存器值列表 | List of holding register values

Raises:

ValueError – 地址或数量无效 | Invalid address or count

write_holding_registers(address: int, values: List[int]) → None[source]

写入保持寄存器

Write Holding Registers

Parameters:

address – 起始地址 | Starting address
values – 保持寄存器值列表 | List of holding register values

Raises:

ValueError – 地址或数据无效 | Invalid address or data

read_input_registers(address: int, count: int) → List[int][source]

读取输入寄存器

Read Input Registers

Parameters:

address – 起始地址 | Starting address
count – 读取数量 | Number to read

Returns:

输入寄存器值列表 | List of input register values

Raises:

ValueError – 地址或数量无效 | Invalid address or count

write_input_registers(address: int, values: List[int]) → None[source]

写入输入寄存器（通常用于模拟） | Write Input Registers (usually for simulation)

Parameters:

address – 起始地址 | Starting address
values – 输入寄存器值列表 | List of input register values

Raises:

ValueError – 地址或数据无效 | Invalid address or data

get_coils_size() → int[source]: 获取线圈总数 | Get total number of coils

get_discrete_inputs_size() → int[source]: 获取离散输入总数 | Get total number of discrete inputs

get_holding_registers_size() → int[source]: 获取保持寄存器总数 | Get total number of holding registers

get_input_registers_size() → int[source]: 获取输入寄存器总数 | Get total number of input registers

reset() → None[source]

重置所有数据为默认值

Reset All Data to Default Values

AsyncBaseModbusServer

class modbuslink.server.async_base_server.AsyncBaseModbusServer(data_store: ModbusDataStore | None = None, slave_id: int = 1)[source]

Bases: ABC

异步Modbus服务器抽象基类所有异步Modbus服务器实现（AsyncTCP、AsyncRTU、AsyncASCII等）都必须继承此类并实现所有抽象方法。这个设计将协议处理、数据存储管理等复杂性封装在基类中，为具体的传输层实现提供统一、简洁的接口。

Async Modbus Server Abstract Base Class All async Modbus server implementations (AsyncTCP, AsyncRTU, AsyncASCII, etc.) must inherit from this class and implement all abstract methods. This design encapsulates complexities such as protocol processing and data store management in the base class, providing a unified and concise interface for specific transport layer implementations.

__init__(data_store: ModbusDataStore | None = None, slave_id: int = 1)[source]

初始化异步Modbus服务器

Initialize Async Modbus Server

Parameters:

data_store – 数据存储实例，如果为None则创建默认实例 | Data store instance, creates default if None
slave_id – 从站地址 | Slave address

abstract async start() → None[source]

启动异步服务器开始监听客户端连接和请求。

Start Async Server Begin listening for client connections and requests.

Raises:: ConnectionError – 当无法启动服务器时 | When server cannot be started

abstract async stop() → None[source]

停止异步服务器停止监听并关闭所有连接。

Stop Async Server Stop listening and close all connections.

abstract async is_running() → bool[source]

检查服务器运行状态

Check Server Running Status

Returns:: 如果服务器正在运行返回True，否则返回False | True if server is running, False otherwise

process_request(slave_id: int, pdu: bytes) → bytes[source]

处理Modbus请求PDU 这是服务器的核心方法，处理接收到的PDU并返回响应PDU。

Process Modbus Request PDU This is the core method of the server, processes received PDU and returns response PDU.

Parameters:

slave_id – 从站地址 | Slave address
pdu – 请求的协议数据单元 | Request Protocol Data Unit

Returns:

响应的协议数据单元 | Response Protocol Data Unit

async __aenter__() → AsyncBaseModbusServer[source]: 异步上下文管理器入口 | Async Context Manager Entry

async __aexit__(exc_type: type | None, exc_val: BaseException | None, exc_tb: Any | None) → None[source]: 异步上下文管理器出口 | Async Context Manager Exit

AsyncTcpModbusServer

class modbuslink.server.async_tcp_server.AsyncTcpModbusServer(host: str = 'localhost', port: int = 502, data_store: ModbusDataStore | None = None, slave_id: int = 1, max_connections: int = 10)[source]

Bases: AsyncBaseModbusServer

异步TCP Modbus服务器实现基于TCP的异步Modbus服务器，支持多客户端并发连接。使用MBAP（Modbus Application Protocol）头进行通信。

Async TCP Modbus Server Implements TCP-based async Modbus server with support for multiple concurrent client connections. Uses MBAP (Modbus Application Protocol) header for communication.

__init__(host: str = 'localhost', port: int = 502, data_store: ModbusDataStore | None = None, slave_id: int = 1, max_connections: int = 10)[source]

初始化异步TCP Modbus服务器

Initialize Async TCP Modbus Server

Parameters:

host – 服务器绑定地址 | Server bind address
port – 服务器端口 | Server port
data_store – 数据存储实例 | Data store instance
slave_id – 从站地址 | Slave address
max_connections – 最大并发连接数 | Maximum concurrent connections

async start() → None[source]

启动异步TCP服务器

Start Async TCP Server

Raises:: ConnectionError – 当无法启动服务器时 | When server cannot be started

async stop() → None[source]

停止异步TCP服务器

Stop Async TCP Server

async is_running() → bool[source]

检查服务器运行状态

Check Server Running Status

Returns:: 如果服务器正在运行返回True，否则返回False | True if server is running, False otherwise

get_connected_clients_count() → int[source]

获取当前连接的客户端数量

Get Current Connected Clients Count

Returns:: 当前连接的客户端数量 | Current number of connected clients

async serve_forever() → None[source]

持续运行服务器直到被停止

Run Server Forever Until Stopped

AsyncRtuModbusServer

class modbuslink.server.async_rtu_server.AsyncRtuModbusServer(port: str, baudrate: int = 9600, bytesize: int = 8, parity: str = 'N', stopbits: int = 1, timeout: float = 1.0, data_store: ModbusDataStore | None = None, slave_id: int = 1)[source]

Bases: AsyncBaseModbusServer

异步RTU Modbus服务器实现基于串口的异步Modbus RTU服务器。使用CRC16校验确保数据完整性。

Async RTU Modbus Server Implements serial port-based async Modbus RTU server. Uses CRC16 checksum to ensure data integrity.

__init__(port: str, baudrate: int = 9600, bytesize: int = 8, parity: str = 'N', stopbits: int = 1, timeout: float = 1.0, data_store: ModbusDataStore | None = None, slave_id: int = 1)[source]

初始化异步RTU Modbus服务器

Initialize Async RTU Modbus Server

Parameters:

port – 串口名称 | Serial port name
baudrate – 波特率 | Baud rate
bytesize – 数据位 | Data bits
parity – 校验位 (‘N’, ‘E’, ‘O’) | Parity (‘N’, ‘E’, ‘O’)
stopbits – 停止位 | Stop bits
timeout – 超时时间（秒） | Timeout in seconds
data_store – 数据存储实例 | Data store instance
slave_id – 从站地址 | Slave address

async start() → None[source]

启动异步RTU服务器

Start Async RTU Server

Raises:: ConnectionError – 当无法打开串口时 | When serial port cannot be opened

async stop() → None[source]

停止异步RTU服务器

Stop Async RTU Server

async is_running() → bool[source]

检查服务器运行状态

Check Server Running Status

Returns:: 如果服务器正在运行返回True，否则返回False | True if server is running, False otherwise

async serve_forever() → None[source]

持续运行服务器直到被停止

Run Server Forever Until Stopped

AsyncAsciiModbusServer

class modbuslink.server.async_ascii_server.AsyncAsciiModbusServer(port: str, baudrate: int = 9600, bytesize: int = 7, parity: str = 'E', stopbits: int = 1, timeout: float = 1.0, data_store: ModbusDataStore | None = None, slave_id: int = 1)[source]

Bases: AsyncBaseModbusServer

异步ASCII Modbus服务器实现基于串口的异步Modbus ASCII服务器。使用LRC（纵向冗余校验）确保数据完整性。

Async ASCII Modbus Server Implements serial port-based async Modbus ASCII server. Uses LRC (Longitudinal Redundancy Check) to ensure data integrity.

__init__(port: str, baudrate: int = 9600, bytesize: int = 7, parity: str = 'E', stopbits: int = 1, timeout: float = 1.0, data_store: ModbusDataStore | None = None, slave_id: int = 1)[source]

初始化异步ASCII Modbus服务器

Initialize Async ASCII Modbus Server

Parameters:

port – 串口名称 | Serial port name
baudrate – 波特率 | Baud rate
bytesize – 数据位 | Data bits
parity – 校验位 (‘N’, ‘E’, ‘O’) | Parity (‘N’, ‘E’, ‘O’)
stopbits – 停止位 | Stop bits
timeout – 超时时间（秒） | Timeout in seconds
data_store – 数据存储实例 | Data store instance
slave_id – 从站地址 | Slave address

async start() → None[source]

启动异步ASCII服务器

Start Async ASCII Server

Raises:: ConnectionError – 当无法打开串口时 | When serial port cannot be opened

async stop() → None[source]

停止异步ASCII服务器

Stop Async ASCII Server

async is_running() → bool[source]

检查服务器运行状态

Check Server Running Status

Returns:: 如果服务器正在运行返回True，否则返回False | True if server is running, False otherwise

async serve_forever() → None[source]

持续运行服务器直到被停止

Run Server Forever Until Stopped

Utility Module

CRC16Modbus

class modbuslink.utils.crc.CRC16Modbus[source]

Bases: object

Modbus CRC16校验工具类实现Modbus RTU协议中使用的CRC16校验算法。使用多项式0xA001 (反向0x8005)。

Modbus CRC16 Checksum Utility Class Implements the CRC16 checksum algorithm used in Modbus RTU protocol. Uses polynomial 0xA001 (reverse of 0x8005).

static calculate(data: bytes) → bytes[source]

计算CRC16校验码

Calculate CRC16 Checksum

Parameters:: data – 需要计算校验码的数据帧（地址+PDU） | Data frame for checksum calculation (address+PDU)
Returns:: 2字节的CRC校验码 (little-endian bytes) | 2-byte CRC checksum (little-endian bytes)

Example

>>> data = b''
>>> crc = CRC16Modbus.calculate(data)
>>> crc.hex()
'840a'

static validate(frame_with_crc: bytes) → bool[source]

验证包含CRC的完整数据帧

Validate Complete Data Frame with CRC
Args:
frame_with_crc: 包含CRC校验码的完整数据帧 | Complete data frame containing CRC checksum

Returns:
如果CRC校验正确返回True，否则返回False | True if CRC verification is correct, False otherwise

Example:
>>> frame = b'

‘

>>> CRC16Modbus.validate(frame)
True

static crc16_to_int(data: bytes) → int[source]

计算CRC16校验码并返回整数值这是一个兼容性方法，用于与旧代码保持兼容。推荐使用calculate()方法。

Calculate CRC16 Checksum and Return Integer Value This is a compatibility method for maintaining compatibility with old code. It is recommended to use the calculate() method.

Parameters:: data – 需要计算校验码的数据 | Data for checksum calculation
Returns:: CRC校验码的整数值 | Integer value of CRC checksum

PayloadCoder

Logger Functions

Exception Module

ModbusLinkError

exception modbuslink.common.exceptions.ModbusLinkError[source]

Bases: Exception

ModbusLink库的基础异常类所有ModbusLink相关的异常都继承自这个基类。

Base exception class for ModbusLink library All ModbusLink-related exceptions inherit from this base class.

ConnectionError

exception modbuslink.common.exceptions.ConnectionError[source]

Bases: ModbusLinkError

连接错误异常当无法建立或维持与Modbus设备的连接时抛出。

Connection error exception Raised when unable to establish or maintain connection with Modbus device.

TimeoutError

exception modbuslink.common.exceptions.TimeoutError[source]

Bases: ModbusLinkError

超时错误异常当操作超过指定的超时时间时抛出。

Timeout error exception Raised when operation exceeds the specified timeout period.

CRCError

exception modbuslink.common.exceptions.CRCError[source]

Bases: ModbusLinkError

CRC校验错误异常当接收到的数据帧CRC校验失败时抛出。

CRC validation error exception Raised when CRC validation of received data frame fails.

InvalidResponseError

exception modbuslink.common.exceptions.InvalidResponseError[source]

Bases: ModbusLinkError

无效响应错误异常当接收到的响应格式不正确或不符合预期时抛出。

Invalid response error exception Raised when received response format is incorrect or unexpected.

ModbusException

exception modbuslink.common.exceptions.ModbusException(exception_code: int, function_code: int, message: str | None = None)[source]

Bases: ModbusLinkError

Modbus协议异常当从站返回Modbus异常码时抛出。

Modbus protocol exception Raised when slave returns Modbus exception code.

exception_code: Modbus异常码 (如0x01, 0x02等) | Modbus exception code (e.g. 0x01, 0x02, etc.)

function_code: 原始功能码 | Original function code

__init__(exception_code: int, function_code: int, message: str | None = None)[source]

Function Code Constants

Read Function Codes

READ_COILS = 0x01
READ_DISCRETE_INPUTS = 0x02
READ_HOLDING_REGISTERS = 0x03
READ_INPUT_REGISTERS = 0x04

Write Function Codes

WRITE_SINGLE_COIL = 0x05
WRITE_SINGLE_REGISTER = 0x06
WRITE_MULTIPLE_COILS = 0x0F
WRITE_MULTIPLE_REGISTERS = 0x10

Exception Codes

ILLEGAL_FUNCTION = 0x01
ILLEGAL_DATA_ADDRESS = 0x02
ILLEGAL_DATA_VALUE = 0x03
SLAVE_DEVICE_FAILURE = 0x04
ACKNOWLEDGE = 0x05
SLAVE_DEVICE_BUSY = 0x06
MEMORY_PARITY_ERROR = 0x08
GATEWAY_PATH_UNAVAILABLE = 0x0A
GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND = 0x0B

Data Type Formats

Byte Order

'big': Big-endian (most significant byte first)
'little': Little-endian (least significant byte first)

Word Order

'big': High word first
'little': Low word first

Combined Format Codes

'>AB': Big-endian bytes, high word first
'>BA': Big-endian bytes, low word first
'<AB': Little-endian bytes, high word first
'<BA': Little-endian bytes, low word first

Type Aliases

from typing import List, Union, Optional, Callable, Any

# Common type aliases used throughout the library
RegisterList = List[int]
CoilList = List[bool]
ByteOrder = str  # 'big' or 'little'
WordOrder = str  # 'big' or 'little'
CallbackFunction = Optional[Callable[[Any], None]]

Usage Examples

Basic Client Usage

from modbuslink import ModbusClient, TcpTransport

# Create transport and client
transport = TcpTransport(host='192.168.1.100', port=502)
client = ModbusClient(transport)

# Use context manager
with client:
    # Read operations
    coils = client.read_coils(slave_id=1, start_address=0, quantity=8)
    registers = client.read_holding_registers(slave_id=1, start_address=0, quantity=10)

    # Write operations
    client.write_single_coil(slave_id=1, address=0, value=True)
    client.write_single_register(slave_id=1, address=0, value=1234)

Async Client Usage

from modbuslink import AsyncModbusClient, AsyncTcpTransport
import asyncio

async def main():
    transport = AsyncTcpTransport(host='192.168.1.100', port=502)
    client = AsyncModbusClient(transport)

    async with client:
        registers = await client.read_holding_registers(
            slave_id=1, start_address=0, quantity=10
        )
        await client.write_single_register(
            slave_id=1, address=0, value=1234
        )

asyncio.run(main())

Server Usage

from modbuslink import AsyncTcpModbusServer, ModbusDataStore
import asyncio

async def main():
    # Create and configure data store
    data_store = ModbusDataStore(
        coils_size=1000,
        discrete_inputs_size=1000,
        holding_registers_size=1000,
        input_registers_size=1000
    )

    # Set initial data
    data_store.write_holding_registers(0, [1000, 2000, 3000])
    data_store.write_coils(0, [True, False, True, False])

    # Create TCP server
    server = AsyncTcpModbusServer(
        host='localhost',
        port=5020,
        data_store=data_store,
        slave_id=1
    )

    # Start server
    await server.start()
    print("Server started")

    try:
        await server.serve_forever()
    except KeyboardInterrupt:
        print("Stopping server")
    finally:
        await server.stop()

asyncio.run(main())

RTU Server Usage

from modbuslink import AsyncRtuModbusServer, ModbusDataStore
import asyncio

async def main():
    data_store = ModbusDataStore()

    server = AsyncRtuModbusServer(
        port="COM3",
        baudrate=9600,
        data_store=data_store,
        slave_id=1,
        parity="N",
        stopbits=1,
        bytesize=8
    )

    await server.start()
    await server.serve_forever()

asyncio.run(main())

ASCII Server Usage

from modbuslink import AsyncAsciiModbusServer, ModbusDataStore
import asyncio

async def main():
    data_store = ModbusDataStore()

    server = AsyncAsciiModbusServer(
        port="COM4",
        baudrate=9600,
        data_store=data_store,
        slave_id=2,
        parity="E",
        stopbits=1,
        bytesize=7
    )

    await server.start()
    await server.serve_forever()

asyncio.run(main())

Advanced Data Types

# Float32 operations
client.write_float32(slave_id=1, start_address=100, value=3.14159)
temperature = client.read_float32(slave_id=1, start_address=100)

# Int32 operations with custom byte/word order
client.write_int32(
    slave_id=1,
    start_address=102,
    value=-123456,
    byte_order='little',
    word_order='big'
)
counter = client.read_int32(
    slave_id=1,
    start_address=102,
    byte_order='little',
    word_order='big'
)