# VWED Modbus TCP 测试说明

## 概述

这个测试套件提供了完整的 Modbus TCP 功能测试环境，包括模拟服务器和客户端测试脚本。

## 文件说明

### 1. `test_modbus_server.py` - Modbus TCP 模拟服务器
- 提供完整的 Modbus TCP 服务器实现
- 支持所有标准 Modbus 功能码
- 动态数据更新，模拟真实设备
- 支持多个从站ID

### 2. `test_modbus_client.py` - 完整功能测试
- 测试所有 VWED Modbus 模块功能
- 包括读取、写入、批量操作等
- 自动验证测试结果

### 3. `test_modbus_example.py` - 使用示例
- 展示在线脚本中如何使用 Modbus 功能
- 包含实际应用场景示例
- 演示最佳实践

## 快速开始

### 方法1: 分离模式（推荐用于开发调试）

**终端1 - 启动模拟服务器:**
```bash
cd /mnt/d/jsw_code/project/VWED_server
python tests/test_modbus_server.py
```

**终端2 - 运行测试:**
```bash
cd /mnt/d/jsw_code/project/VWED_server
python tests/test_modbus_client.py
# 或者
python tests/test_modbus_example.py
```

### 方法2: 自动化模式

**运行完整测试:**
```bash
cd /mnt/d/jsw_code/project/VWED_server
python tests/test_modbus_client.py
```
（测试脚本会自动启动和停止服务器）

## 测试服务器配置

### 连接参数
- **主机**: localhost
- **端口**: 5020
- **从站ID**: 1, 2

### 数据布局

#### 线圈 (0x区域)
- 地址范围: 0-99
- 初始值: False
- 可读写

#### 离散输入 (1x区域)  
- 地址范围: 0-99
- 动态变化: 每秒更新
- 只读

#### 输入寄存器 (3x区域)
- 地址范围: 0-99
- 动态变化: 数值递增模式
- 只读

#### 保持寄存器 (4x区域)
- 地址范围: 0-99
- 初始值: [1000, 2000, 3000, 4000, ...]
- 可读写

## 测试功能覆盖

### 基础功能
- ✅ 读取线圈 (功能码01)
- ✅ 读取离散输入 (功能码02)
- ✅ 读取保持寄存器 (功能码03)
- ✅ 读取输入寄存器 (功能码04)
- ✅ 写入单个线圈 (功能码05)
- ✅ 写入单个保持寄存器 (功能码06)

### 批量操作
- ✅ 批量读取线圈
- ✅ 批量读取离散输入
- ✅ 批量读取保持寄存器
- ✅ 批量读取输入寄存器
- ✅ 批量写入线圈 (功能码0F)
- ✅ 批量写入保持寄存器 (功能码10)

### 高级功能
- ✅ 通用读写操作 (根据地址类型自动选择功能码)
- ✅ 实例化配置管理
- ✅ 数据类型转换 (有符号/无符号)
- ✅ 错误处理和异常管理

## 使用示例

### 在线脚本中的用法

```python
# 创建VWED对象
VWED = create_vwed_object("my_script")

# 基础读取
value = VWED.modbus.read_holding_register("192.168.1.100", 502, 1, 0, 2)
print(f"寄存器值: {value}")

# 批量操作
values = VWED.modbus.batch_read_holding_registers("192.168.1.100", 502, 1, 0, 10)
print(f"批量读取: {values}")

# 写入操作
success = VWED.modbus.write_holding_register("192.168.1.100", 502, 1, 0, 2, 12345)
print(f"写入结果: {'成功' if success else '失败'}")

# 配置实例
VWED.modbus.configure_modbus_instance("PLC1", "192.168.1.100", 502, 1, "4x")
value = VWED.modbus.read_single_modbus_value_by_instance_name("PLC1", 0)

# 通用操作
value = VWED.modbus.read_single_modbus_value("192.168.1.100", 502, 1, "4x", 0)
```

## 故障排除

### 连接问题
1. 确保服务器已启动并监听正确端口
2. 检查防火墙设置
3. 验证IP地址和端口配置

### 读写失败
1. 检查从站ID是否正确
2. 验证地址范围是否有效
3. 确认数据类型匹配

### 性能优化
1. 使用批量操作代替多次单个操作
2. 配置实例避免重复连接参数
3. 合理设置超时时间

## 扩展测试

### 自定义测试场景
可以修改测试脚本添加特定的业务逻辑测试：

```python
# 例如：模拟生产线控制
def test_production_line():
    # 读取传感器状态
    sensor_status = VWED.modbus.batch_read_input_status("localhost", 5020, 1, 0, 8)
    
    # 根据传感器状态控制执行器
    if all(sensor_status[:4]):  # 前4个传感器都激活
        VWED.modbus.write_coil_status("localhost", 5020, 1, 0, True)  # 启动机器
    else:
        VWED.modbus.write_coil_status("localhost", 5020, 1, 0, False) # 停止机器
```

## 注意事项

1. **网络延迟**: 实际网络环境中可能有延迟，建议适当调整超时设置
2. **并发访问**: 避免多个客户端同时写入同一地址
3. **数据一致性**: 读取后立即写入可能因网络延迟导致不一致
4. **错误恢复**: 实现适当的重试机制处理网络故障

## 支持的 Modbus 功能码

| 功能码 | 操作类型 | 数据类型 | 支持状态 |
|--------|----------|----------|----------|
| 01 | 读线圈 | 布尔值 | ✅ |
| 02 | 读离散输入 | 布尔值 | ✅ |
| 03 | 读保持寄存器 | 16位整数 | ✅ |
| 04 | 读输入寄存器 | 16位整数 | ✅ |
| 05 | 写单个线圈 | 布尔值 | ✅ |
| 06 | 写单个保持寄存器 | 16位整数 | ✅ |
| 0F | 写多个线圈 | 布尔值数组 | ✅ |
| 10 | 写多个保持寄存器 | 16位整数数组 | ✅ |