# serial.py 函数文档

Modbus RTU串口通信实现模块，提供完整的Modbus串口通信功能。

## Serial 类

### 初始化
```python
def __init__(self, uart_id, baudrate=9600, data_bits=8, stop_bits=1, parity=None, pins=None, ctrl_pin=None)
```
- **功能**: 初始化串口通信
- **参数**:
  - uart_id: UART端口号
  - baudrate: 波特率（默认9600）
  - data_bits: 数据位（默认8）
  - stop_bits: 停止位（默认1）
  - parity: 校验位（默认None）
  - pins: 引脚配置
  - ctrl_pin: RS485方向控制引脚
- **特性**: 自动计算字符时间

### 核心功能

#### 读取功能

##### read_coils
```python
def read_coils(self, slave_addr, starting_addr, coil_qty)
```
- **功能**: 读取线圈状态
- **参数**:
  - slave_addr: 从机地址
  - starting_addr: 起始地址
  - coil_qty: 线圈数量
- **返回值**: 布尔值列表

##### read_discrete_inputs
```python
def read_discrete_inputs(self, slave_addr, starting_addr, input_qty)
```
- **功能**: 读取离散输入
- **参数**:
  - slave_addr: 从机地址
  - starting_addr: 起始地址
  - input_qty: 输入数量
- **返回值**: 布尔值列表

##### read_holding_registers
```python
def read_holding_registers(self, slave_addr, starting_addr, register_qty, signed=True)
```
- **功能**: 读取保持寄存器
- **参数**:
  - slave_addr: 从机地址
  - starting_addr: 起始地址
  - register_qty: 寄存器数量
  - signed: 是否有符号
- **返回值**: 整数值列表

##### read_input_registers
```python
def read_input_registers(self, slave_addr, starting_address, register_quantity, signed=True)
```
- **功能**: 读取输入寄存器
- **参数**:
  - slave_addr: 从机地址
  - starting_address: 起始地址
  - register_quantity: 寄存器数量
  - signed: 是否有符号
- **返回值**: 整数值列表

#### 写入功能

##### write_single_coil
```python
def write_single_coil(self, slave_addr, output_address, output_value)
```
- **功能**: 写入单个线圈
- **参数**:
  - slave_addr: 从机地址
  - output_address: 输出地址
  - output_value: 输出值
- **返回值**: 操作状态

##### write_single_register
```python
def write_single_register(self, slave_addr, register_address, register_value, signed=True)
```
- **功能**: 写入单个寄存器
- **参数**:
  - slave_addr: 从机地址
  - register_address: 寄存器地址
  - register_value: 寄存器值
  - signed: 是否有符号
- **返回值**: 操作状态

##### write_multiple_coils
```python
def write_multiple_coils(self, slave_addr, starting_address, output_values)
```
- **功能**: 写入多个线圈
- **参数**:
  - slave_addr: 从机地址
  - starting_address: 起始地址
  - output_values: 输出值列表
- **返回值**: 操作状态

##### write_multiple_registers
```python
def write_multiple_registers(self, slave_addr, starting_address, register_values, signed=True)
```
- **功能**: 写入多个寄存器
- **参数**:
  - slave_addr: 从机地址
  - starting_address: 起始地址
  - register_values: 寄存器值列表
  - signed: 是否有符号
- **返回值**: 操作状态

### 内部方法

#### 数据处理
```python
def _calculate_crc16(self, data)
def _bytes_to_bool(self, byte_list)
def _to_short(self, byte_array, signed=True)
```
- CRC16校验计算
- 字节转布尔值列表
- 字节数组转短整型

#### 通信控制
```python
def _send_receive(self, modbus_pdu, slave_addr, count)
def _uart_read(self)
def _validate_resp_hdr(self, response, slave_addr, function_code, count)
```
- 发送接收数据
- UART读取
- 响应头验证

## 使用示例

### 基本读取操作
```python
# 创建串口实例
serial = Serial(uart_id=2, baudrate=9600)

# 读取线圈
coil_status = serial.read_coils(slave_addr=1, starting_addr=0, coil_qty=8)

# 读取寄存器
registers = serial.read_holding_registers(slave_addr=1, starting_addr=0, register_qty=4)
```

### 基本写入操作
```python
# 写单个线圈
status = serial.write_single_coil(slave_addr=1, output_address=0, output_value=True)

# 写多个寄存器
values = [100, 200, 300]
status = serial.write_multiple_registers(slave_addr=1, starting_address=0, register_values=values)
```

### RS485控制
```python
# 使用方向控制引脚
serial = Serial(uart_id=2, baudrate=9600, ctrl_pin=15)
```

## 技术规格

### 通信参数
- 波特率: 1200-115200
- 数据位: 5-8
- 停止位: 1-2
- 校验位: None/Even/Odd

### 超时设置
- 字符时间: 根据波特率自动计算
- 响应超时: 40次轮询（约2秒）

### 缓冲区大小
- 接收缓冲区: 动态
- 发送缓冲区: 根据协议自动调整

## 错误处理

### 通信错误
- CRC校验错误
- 响应超时
- 从机异常

### 数据错误
- 地址错误
- 数值范围错误
- 响应格式错误

## 注意事项

1. 通信稳定性
   - 合适的波特率选择
   - 正确的线路连接
   - RS485方向控制时序

2. 数据处理
   - 有符号数处理
   - 字节序考虑
   - CRC校验必要性

3. 性能优化
   - 批量读写操作
   - 超时时间设置
   - 缓冲区管理

4. 错误恢复
   - 异常重试机制
   - 通信状态监控
   - 错误日志记录