Documentation

# functions.py 函数文档 Modbus协议的功能函数实现模块，提供各种Modbus命令的打包和验证功能。 ## Modbus读取功能 ### read_coils

python
def read_coils(starting_address, quantity)

- 功能: 生成读取线圈的Modbus命令
- 参数:
- starting_address: 起始地址
- quantity: 线圈数量 (1-2000)
- 返回值: 打包的命令字节串
- 异常: 数量超出范围时抛出ValueError ### read_discrete_inputs

python
def read_discrete_inputs(starting_address, quantity)

- 功能: 生成读取离散输入的Modbus命令
- 参数:
- starting_address: 起始地址
- quantity: 输入点数量 (1-2000)
- 返回值: 打包的命令字节串
- 异常: 数量超出范围时抛出ValueError ### read_holding_registers

python
def read_holding_registers(starting_address, quantity)

- 功能: 生成读取保持寄存器的Modbus命令
- 参数:
- starting_address: 起始地址
- quantity: 寄存器数量 (1-125)
- 返回值: 打包的命令字节串
- 异常: 数量超出范围时抛出ValueError ### read_input_registers

python
def read_input_registers(starting_address, quantity)

- 功能: 生成读取输入寄存器的Modbus命令
- 参数:
- starting_address: 起始地址
- quantity: 寄存器数量 (1-125)
- 返回值: 打包的命令字节串
- 异常: 数量超出范围时抛出ValueError ## Modbus写入功能 ### write_single_coil

python
def write_single_coil(output_address, output_value)

- 功能: 生成写单个线圈的Modbus命令
- 参数:
- output_address: 输出地址
- output_value: 输出值 (0x0000或0xFF00)
- 返回值: 打包的命令字节串
- 异常: 输出值非法时抛出ValueError ### write_single_register

python
def write_single_register(register_address, register_value, signed=True)

- 功能: 生成写单个寄存器的Modbus命令
- 参数:
- register_address: 寄存器地址
- register_value: 寄存器值
- signed: 是否有符号 (默认True)
- 返回值: 打包的命令字节串 ### write_multiple_coils

python
def write_multiple_coils(starting_address, value_list)

- 功能: 生成写多个线圈的Modbus命令
- 参数:
- starting_address: 起始地址
- value_list: 值列表
- 返回值: 打包的命令字节串
- 特性:
- 自动分段处理
- 按8位打包数据 ### write_multiple_registers

python
def write_multiple_registers(starting_address, register_values, signed=True)

- 功能: 生成写多个寄存器的Modbus命令
- 参数:
- starting_address: 起始地址
- register_values: 寄存器值列表
- signed: 是否有符号 (默认True)
- 返回值: 打包的命令字节串
- 异常: 寄存器数量超出范围(1-123)时抛出ValueError ## 响应验证 ### validate_resp_data

python
def validate_resp_data(data, function_code, address, value=None, quantity=None, signed=True)

- 功能: 验证Modbus响应数据
- 参数:
- data: 响应数据
- function_code: 功能码
- address: 地址
- value: 写入值（可选）
- quantity: 数量（可选）
- signed: 是否有符号（默认True）
- 返回值: 布尔值，表示验证是否通过
- 验证内容:
- 数据完整性
- 地址匹配
- 值/数量匹配 ## 使用示例 ### 读取操作

python
# 读取10个线圈
cmd = read_coils(0x0000, 10)

# 读取5个保持寄存器
cmd = read_holding_registers(0x0000, 5)

### 写入操作

python
# 写单个线圈
cmd = write_single_coil(0x0000, 0xFF00)  # 打开

# 写单个寄存器
cmd = write_single_register(0x0000, 100)  # 写入100

# 写多个线圈
cmd = write_multiple_coils(0x0000, [1, 0, 1, 0, 1])

# 写多个寄存器
cmd = write_multiple_registers(0x0000, [100, 200, 300])

### 响应验证

python
# 验证单个写入响应
is_valid = validate_resp_data(
    response_data,
    Const.WRITE_SINGLE_REGISTER,
    0x0000,
    value=100
)

# 验证多个写入响应
is_valid = validate_resp_data(
    response_data,
    Const.WRITE_MULTIPLE_REGISTERS,
    0x0000,
    quantity=3
)

## 技术规格 ### 数据范围
1. 线圈操作
- 读取: 1-2000个
- 写入: 无限制（自动分段） 2. 寄存器操作
- 读取: 1-125个
- 写入: 1-123个 ### 数据格式
1. 线圈值
- 0x0000: 关闭
- 0xFF00: 打开 2. 寄存器值
- 有符号: 16位整数 (-32768 到 32767)
- 无符号: 16位整数 (0 到 65535) ## 注意事项 1. 数据验证
- 始终检查返回值
- 验证响应数据完整性
- 注意地址匹配 2. 性能优化
- 合并多个操作
- 使用多寄存器写入
- 注意数据包大小 3. 错误处理
- 捕获ValueError异常
- 验证响应数据
- 处理通信超时 4. 最佳实践
- 遵循Modbus协议规范
- 正确处理字节序
- 合理使用signed参数