# 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参数