Himmelt.ModbusLib 1.0.0-beta1

ModbusLib - .NET 9 Modbus Client Library

一个功能完整、高性能的Modbus客户端库，基于.NET 9平台，支持多种Modbus协议变体。

注意：本项目是由AI生成的，主要使用了Trae以及Qoder等工具辅助开发，主要模型是 Qwen-3-Coder。

📦 安装

dotnet add package Himmelt.ModbusLib

🌟 支持的协议

• Modbus RTU - 通过串口通信的RTU协议
• Modbus TCP - 基于TCP/IP的标准Modbus协议
• Modbus UDP - 基于UDP的Modbus协议
• Modbus RTU over TCP - 通过TCP传输的RTU协议
• Modbus RTU over UDP - 通过UDP传输的RTU协议

✨ 功能特性

• 🚀 异步编程模型，提供卓越的性能
• 🔄 同步方法支持，便于传统应用集成
• 📋 支持所有标准Modbus功能码
• ⚙️ 灵活的配置选项
• 🛡️ 完整的错误处理和重试机制
• 💾 内存优化，使用 ArrayPool 减少分配
• 🏭 工厂模式，便于创建不同类型的客户端
• 🔀 泛型支持，可直接读写基本数据类型
• 📊 字节序和字序控制，支持不同平台数据格式

🚀 快速开始

基本用法

异步方法使用示例

// 创建RTU客户端
var rtuClient = ModbusClientFactory.CreateRtuClient(new SerialConnectionConfig
{
    PortName = "COM1",
    BaudRate = 9600,
    Parity = Parity.None,
    DataBits = 8,
    StopBits = StopBits.One
});

// 连接并读取数据
await rtuClient.ConnectAsync();
var coils = await rtuClient.ReadCoilsAsync(unitId: 1, startAddress: 0, quantity: 10);

// 创建TCP客户端
var tcpClient = ModbusClientFactory.CreateTcpClient(new NetworkConnectionConfig
{
    Host = "192.168.1.100",
    Port = 502
});

// 连接并写入数据
await tcpClient.ConnectAsync();
await tcpClient.WriteMultipleRegistersAsync(unitId: 1, startAddress: 0, new ushort[] { 100, 200, 300 });

同步方法使用示例

// 创建RTU客户端
var rtuClient = ModbusClientFactory.CreateRtuClient(new SerialConnectionConfig
{
    PortName = "COM1",
    BaudRate = 9600,
    Parity = Parity.None,
    DataBits = 8,
    StopBits = StopBits.One
});

// 连接并读取数据
rtuClient.Connect();
var coils = rtuClient.ReadCoils(unitId: 1, startAddress: 0, quantity: 10);

// 创建TCP客户端
var tcpClient = ModbusClientFactory.CreateTcpClient(new NetworkConnectionConfig
{
    Host = "192.168.1.100",
    Port = 502
});

// 连接并写入数据
tcpClient.Connect();
tcpClient.WriteMultipleRegisters(unitId: 1, startAddress: 0, new ushort[] { 100, 200, 300 });

泛型方法使用示例

// 读取浮点数数组
var floatValues = await client.ReadHoldingRegistersAsync<float>(unitId: 1, startAddress: 0, count: 5);

// 读取双精度浮点数
var doubleValue = await client.ReadHoldingRegistersAsync<double>(unitId: 1, startAddress: 10, count: 1);

// 写入浮点数数组
float[] valuesToWrite = new float[] { 1.23f, 4.56f, 7.89f };
await client.WriteMultipleRegistersAsync(unitId: 1, startAddress: 0, valuesToWrite);

// 写入单个双精度浮点数
await client.WriteMultipleRegistersAsync(unitId: 1, startAddress: 10, 123.456);

字节序和字序控制

// 使用小端字节序读取寄存器
var registersLittleEndian = await client.ReadHoldingRegistersAsync(
    unitId: 1, 
    startAddress: 0, 
    quantity: 10, 
    byteOrder: ByteOrder.LittleEndian);

// 使用低字在前的字序写入寄存器
await client.WriteMultipleRegistersAsync(
    unitId: 1, 
    startAddress: 0, 
    values, 
    byteOrder: ByteOrder.BigEndian, 
    wordOrder: WordOrder.LowFirst);

📁 项目结构

ModbusLib/
├── src/
│   ├── Interfaces/          # 核心接口定义
│   │   ├── IModbusClient.cs     # Modbus客户端接口
│   │   ├── IModbusProtocol.cs   # 协议处理接口
│   │   └── IModbusTransport.cs  # 传输层接口
│   ├── Enums/              # 枚举类型
│   │   ├── ByteOrder.cs         # 字节序枚举
│   │   ├── WordOrder.cs         # 字序枚举
│   │   ├── ModbusException.cs   # Modbus异常码
│   │   └── ModbusFunction.cs    # Modbus功能码
│   ├── Models/             # 数据模型
│   │   ├── ModbusRequest.cs     # Modbus请求模型
│   │   ├── ModbusResponse.cs    # Modbus响应模型
│   │   ├── NetworkConnectionConfig.cs  # 网络连接配置
│   │   └── SerialConnectionConfig.cs   # 串口连接配置
│   ├── Transports/         # 传输层实现
│   │   ├── SerialTransport.cs  # 串口传输实现
│   │   ├── TcpTransport.cs     # TCP传输实现
│   │   └── UdpTransport.cs     # UDP传输实现
│   ├── Protocols/          # 协议处理层
│   │   ├── RtuProtocol.cs       # RTU协议实现
│   │   └── TcpProtocol.cs       # TCP协议实现
│   ├── Clients/            # 客户端实现
│   │   ├── ModbusClientBase.cs     # 客户端基类
│   │   ├── ModbusRtuClient.cs      # RTU客户端实现
│   │   ├── ModbusTcpClient.cs      # TCP客户端实现
│   │   ├── ModbusUdpClient.cs      # UDP客户端实现
│   │   ├── ModbusRtuOverTcpClient.cs  # RTU over TCP客户端实现
│   │   └── ModbusRtuOverUdpClient.cs  # RTU over UDP客户端实现
│   ├── Factories/          # 工厂模式
│   │   ├── ModbusClientFactory.cs     # 客户端工厂
│   │   └── ConfigurationBuilders.cs   # 配置构建器
│   ├── Exceptions/         # 异常定义
│   │   ├── ModbusException.cs         # Modbus异常基类
│   │   └── ModbusCommunicationExceptions.cs  # 通信异常
│   └── Utils/              # 工具类
│       ├── Crc16Utils.cs        # CRC16校验工具
│       └── DataConverter.cs     # 数据转换工具
└── ModbusLib.Tests/        # 单元测试
    ├── Functional/         # 功能测试
    ├── Mocks/              # 模拟对象
    └── Utils/              # 测试工具

🔧 构建和测试

# 构建项目
dotnet build

# 运行测试
dotnet test

# 发布 NuGet 包
dotnet pack

📖 API 参考

工厂方法

// 创建RTU客户端
IModbusClient rtuClient = ModbusClientFactory.CreateRtuClient("COM1", 9600);
// 或使用完整配置
IModbusClient rtuClient = ModbusClientFactory.CreateRtuClient(new SerialConnectionConfig {
    PortName = "COM1",
    BaudRate = 9600,
    Parity = Parity.None,
    DataBits = 8,
    StopBits = StopBits.One
});

// 创建TCP客户端
IModbusClient tcpClient = ModbusClientFactory.CreateTcpClient("192.168.1.100", 502);
// 或使用完整配置
IModbusClient tcpClient = ModbusClientFactory.CreateTcpClient(new NetworkConnectionConfig {
    Host = "192.168.1.100",
    RemotePort = 502,
    ConnectTimeout = 5000,
    ReceiveTimeout = 3000,
    SendTimeout = 3000
});

// 创建UDP客户端
IModbusClient udpClient = ModbusClientFactory.CreateUdpClient("192.168.1.100", 502);

// 创建RTU over TCP客户端
IModbusClient rtuOverTcpClient = ModbusClientFactory.CreateRtuOverTcpClient("192.168.1.100", 502);

// 创建RTU over UDP客户端
IModbusClient rtuOverUdpClient = ModbusClientFactory.CreateRtuOverUdpClient("192.168.1.100", 502);

支持的功能码

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目采用 MIT 许可证。