# EasyDeviceCommunication

**Repository Path**: yoodoo/EasyDeviceCommunication

## Basic Information

- **Project Name**: EasyDeviceCommunication
- **Description**: EasyDeviceCommunication 是一个高度可扩展的设备物联通信模块，支持多种通信协议和传输方式，特别针对工业设备通信场景进行优化。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-05-30
- **Last Updated**: 2025-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Uantek 设备物联通信模块

## 概述

Uantek.Device.Communication 是一个高度可扩展的设备物联通信模块，支持多种通信协议和传输方式，特别针对工业设备通信场景进行优化。

## 主要特性

- **多协议支持**：内置 Modbus TCP/RTU 协议，支持自定义协议扩展
- **多传输方式**：支持 TCP、UDP、串口等传输方式
- **动态加载**：支持驱动程序的动态加载和热插拔
- **高性能**：异步通信，支持高并发设备连接
- **易于扩展**：基于接口设计，便于添加新的协议和传输方式
- **完善的日志**：集成 Microsoft.Extensions.Logging，提供详细的运行日志
- **错误处理**：完善的异常处理和错误恢复机制

## 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                    应用层 (Application Layer)                │
├─────────────────────────────────────────────────────────────┤
│                   服务层 (Service Layer)                    │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│  │ 设备通信服务      │ │ 数据采集服务      │ │ MQTT发布服务     │ │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                   协议层 (Protocol Layer)                   │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│  │   Modbus协议     │ │   自定义协议1    │ │   自定义协议N    │ │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                   传输层 (Transport Layer)                  │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│  │    TCP传输      │ │   串口传输       │ │    UDP传输      │ │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                   工具层 (Utility Layer)                    │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│  │   驱动加载器     │ │ 连接字符串构建器  │ │   配置管理器     │ │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

## 核心组件

### 1. 协议层 (Protocol Layer)

#### IDeviceProtocol 接口
定义设备协议的基本功能：
- 数据解析
- 命令构建
- 数据验证

#### BaseDeviceProtocol 基类
提供协议实现的基础功能：
- 通用日志记录
- 性能监控
- 异常处理

#### ModbusProtocol 实现
完整的 Modbus 协议实现：
- 支持所有标准功能码
- 自动 CRC 校验
- 异常响应处理

### 2. 传输层 (Transport Layer)

#### ICommunicationTransport 接口
定义通信传输的基本功能：
- 连接管理
- 数据发送/接收
- 状态监控

#### 传输实现
- **TcpTransport**：TCP 网络传输
- **SerialTransport**：串口传输
- **UdpTransport**：UDP 网络传输
- **ModbusTcpTransport**：Modbus TCP 专用传输
- **ModbusRtuTransport**：Modbus RTU 专用传输

### 3. 工具层 (Utility Layer)

#### DriverLoader
动态驱动加载器：
- 运行时加载程序集
- 创建驱动实例
- 实例缓存管理

#### ConnectionStringBuilder
连接字符串构建器：
- 类型安全的参数设置
- 多种连接方式支持
- URL 格式解析

## 快速开始

### 1. 安装依赖

```xml
<PackageReference Include="Microsoft.Extensions.Logging" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.Logging.Console" Version="8.0.0" />
<PackageReference Include="System.IO.Ports" Version="8.0.0" />
```

### 2. Modbus TCP 示例

```csharp
using Microsoft.Extensions.Logging;
using Uantek.Device.Communication.Devices;
using Uantek.Device.Communication.Protocols.Modbus;
using Uantek.Device.Communication.Utilities;

// 创建日志记录器
using var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());
var logger = loggerFactory.CreateLogger<Program>();

// 创建连接字符串
var connectionBuilder = new ConnectionStringBuilder(logger)
    .SetModbusTcpParameters("192.168.1.100", 502, 1, 5000);

// 创建协议和传输实例
var protocol = new ModbusProtocol(logger);
var transport = new ModbusTcpTransport(logger);

// 创建设备实例
using var device = new ModbusDevice("Device001", "Modbus TCP设备", protocol, transport, logger);

// 连接设备
var connectionParams = connectionBuilder.GetParameters();
var connectResult = await device.ConnectAsync(connectionParams);

if (connectResult.Success)
{
    // 读取保持寄存器
    var readResult = await device.ReadHoldingRegistersAsync(0, 10);
    if (readResult.Success && readResult.Data != null)
    {
        Console.WriteLine($"读取数据: {string.Join(", ", readResult.Data)}");
    }

    // 写单个寄存器
    var writeResult = await device.WriteSingleRegisterAsync(0, 12345);
    if (writeResult.Success)
    {
        Console.WriteLine("写入成功");
    }
}
```

### 3. Modbus RTU 示例

```csharp
// 创建连接字符串
var connectionBuilder = new ConnectionStringBuilder(logger)
    .SetModbusRtuParameters("COM3", 9600, 1, 8, "One", "None", 5000);

// 创建协议和传输实例
var protocol = new ModbusProtocol(logger);
var transport = new ModbusRtuTransport(logger);

// 创建设备实例
using var device = new ModbusDevice("Device002", "Modbus RTU设备", protocol, transport, logger);

// 连接和操作设备
var connectionParams = connectionBuilder.GetParameters();
await device.ConnectAsync(connectionParams);

// 读取线圈状态
var coilsResult = await device.ReadCoilsAsync(0, 16);
if (coilsResult.Success && coilsResult.Data != null)
{
    Console.WriteLine($"线圈状态: {string.Join(", ", coilsResult.Data.Select(b => b ? "1" : "0"))}");
}
```

### 4. 动态驱动加载示例

```csharp
// 创建驱动加载器
var driverLoader = new DriverLoader(logger);

// 加载程序集
var assemblyPath = "CustomDevice.dll";
if (driverLoader.LoadAssembly(assemblyPath))
{
    // 创建自定义协议实例
    var customProtocol = driverLoader.CreateProtocolInstance(
        "CustomDevice", 
        "CustomDevice.CustomProtocol", 
        logger);

    if (customProtocol != null)
    {
        Console.WriteLine($"自定义协议加载成功: {customProtocol.ProtocolName}");
    }
}
```

## 扩展开发

### 1. 自定义协议开发

```csharp
public class CustomProtocol : BaseDeviceProtocol
{
    public override string ProtocolName => "CustomProtocol";
    public override string Version => "1.0.0";

    protected override async Task<DeviceDataModel?> ParseDataAsync(byte[] rawData)
    {
        // 实现自定义数据解析逻辑
        // ...
    }

    protected override async Task<byte[]> BuildCommandDataAsync(string command, Dictionary<string, object>? parameters)
    {
        // 实现自定义命令构建逻辑
        // ...
    }

    protected override bool ValidateDataInternal(byte[] data)
    {
        // 实现自定义数据验证逻辑
        // ...
    }

    public override IEnumerable<string> GetSupportedTransportTypes()
    {
        return new[] { "TCP", "Serial", "UDP" };
    }
}
```

### 2. 自定义传输开发

```csharp
public class CustomTransport : BaseCommunicationTransport
{
    public override string TransportType => "CustomTransport";

    protected override async Task<CommunicationResult> ConnectInternalAsync(
        Dictionary<string, object> connectionParameters, 
        CancellationToken cancellationToken)
    {
        // 实现自定义连接逻辑
        // ...
    }

    protected override async Task<CommunicationResult> DisconnectInternalAsync()
    {
        // 实现自定义断开逻辑
        // ...
    }

    protected override CommunicationResult SendDataInternal(byte[] data)
    {
        // 实现自定义数据发送逻辑
        // ...
    }

    // 实现其他抽象方法...
}
```

## 配置说明

### 连接字符串格式

#### Modbus TCP
```
modbustcp://192.168.1.100:502?unit=1&timeout=5000
```

#### Modbus RTU
```
modbusrtu://COM3?baudrate=9600&databits=8&stopbits=One&parity=None&slave=1&timeout=5000
```

#### TCP
```
tcp://192.168.1.100:502?connecttimeout=5000&receivetimeout=5000&sendtimeout=5000
```

#### 串口
```
serial://COM3?baudrate=9600&databits=8&stopbits=One&parity=None&readtimeout=5000&writetimeout=5000
```

### 配置参数说明

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| Host | string | 127.0.0.1 | 主机地址 |
| Port | int | 502 | 端口号 |
| UnitId | byte | 1 | Modbus 单元标识符 |
| SlaveId | byte | 1 | Modbus 从站地址 |
| PortName | string | COM1 | 串口名称 |
| BaudRate | int | 9600 | 波特率 |
| DataBits | int | 8 | 数据位 |
| StopBits | string | One | 停止位 |
| Parity | string | None | 校验位 |
| Timeout | int | 5000 | 超时时间（毫秒） |

## 性能优化

### 1. 连接池管理
```csharp
// 使用连接池减少连接开销
var connectionPool = new ConcurrentDictionary<string, ModbusDevice>();
```

### 2. 批量操作
```csharp
// 批量读取多个寄存器
var batchResult = await device.ReadHoldingRegistersAsync(0, 100);
```

### 3. 异步并发
```csharp
// 并发处理多个设备
var tasks = devices.Select(device => device.ReadDataAsync()).ToArray();
var results = await Task.WhenAll(tasks);
```

## 错误处理

### 1. 连接错误
```csharp
var connectResult = await device.ConnectAsync(parameters);
if (!connectResult.Success)
{
    logger.LogError("连接失败: {Message}", connectResult.Message);
    // 处理连接失败逻辑
}
```

### 2. 通信错误
```csharp
try
{
    var result = await device.ReadHoldingRegistersAsync(0, 10);
}
catch (TimeoutException ex)
{
    logger.LogWarning("通信超时: {Message}", ex.Message);
    // 处理超时逻辑
}
```

### 3. 协议错误
```csharp
if (result.ErrorCode == "ModbusException")
{
    logger.LogWarning("Modbus协议异常: {Message}", result.Message);
    // 处理协议异常逻辑
}
```

## 日志配置

### 1. 控制台日志
```csharp
using var loggerFactory = LoggerFactory.Create(builder => 
    builder.AddConsole().SetMinimumLevel(LogLevel.Debug));
```

### 2. 文件日志
```csharp
using var loggerFactory = LoggerFactory.Create(builder => 
    builder.AddFile("logs/device-communication-{Date}.txt"));
```

### 3. 结构化日志
```csharp
logger.LogInformation("设备 {DeviceId} 连接状态: {IsConnected}", deviceId, isConnected);
```

## 最佳实践

### 1. 资源管理
- 始终使用 `using` 语句或手动调用 `Dispose()` 释放资源
- 及时断开不需要的设备连接
- 监控内存使用情况

### 2. 异常处理
- 捕获并处理特定的异常类型
- 记录详细的错误日志
- 实现重试机制

### 3. 性能监控
- 监控连接状态和通信延迟
- 使用性能计数器跟踪吞吐量
- 定期检查设备健康状态

### 4. 安全考虑
- 验证输入参数
- 限制网络访问权限
- 使用安全的通信协议

## 故障排除

### 1. 连接问题
- 检查网络连通性
- 验证端口是否开放
- 确认设备地址和端口配置

### 2. 通信问题
- 检查协议参数配置
- 验证数据格式
- 检查超时设置

### 3. 性能问题
- 调整连接池大小
- 优化批量操作
- 检查网络延迟

## 许可证

本模块遵循 MIT 许可证。

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个模块。

## 联系方式

如有问题或建议，请联系开发团队。