ModbusLib

一个功能完整、高性能的 Modbus 客户端库,支持 .NET 8 / 9 / 10 平台和多种 Modbus 协议变体

CI NuGet NuGet Downloads .NET License DeepSeek

📦 安装

dotnet add package Himmelt.ModbusLib

🌟 支持的协议和传输方式

协议类型

传输方式

协议与传输组合示例

✨ 功能特性

🚀 快速开始

基本用法

串口 RTU 客户端

using ModbusLib.Clients;
using ModbusLib.Models;
// 创建 RTU 客户端(串口传输,默认使用 RTU 协议)
var rtuClient = new ModbusRtuClient(new SerialConfig
{
 PortName = "COM1",
 BaudRate = 9600,
 Parity = System.IO.Ports.Parity.None,
 DataBits = 8,
 StopBits = System.IO.Ports.StopBits.One
});
// 连接并读取数据
await rtuClient.ConnectAsync();
var coils = await rtuClient.ReadCoilsAsync(unitId: 1, startAddress: 0, quantity: 10);

网络客户端(可切换协议)

using ModbusLib.Clients;
using ModbusLib.Enums;
using ModbusLib.Models;
// TCP 传输 + TCP 协议(标准 Modbus TCP)
var tcpClient = new ModbusTcpClient(new NetworkConfig
{
 RemoteHost = "192.168.1.100",
 RemotePort = 502
}, protocol: ProtocolType.Tcp); // 或省略 protocol 参数,默认为 Tcp
await tcpClient.ConnectAsync();
await tcpClient.WriteMultipleRegistersAsync(unitId: 1, startAddress: 0, new ushort[] { 100, 200, 300 });

// TCP 传输 + RTU 协议(RTU over TCP)
var rtuOverTcpClient = new ModbusTcpClient(new NetworkConfig
{
 RemoteHost = "192.168.1.100",
 RemotePort = 502
}, protocol: ProtocolType.Rtu);
await rtuOverTcpClient.ConnectAsync();
var registers = await rtuOverTcpClient.ReadHoldingRegistersAsync(unitId: 1, startAddress: 0, quantity: 10);

// UDP 传输 + RTU 协议(RTU over UDP)
var rtuOverUdpClient = new ModbusUdpClient(new NetworkConfig
{
 RemoteHost = "192.168.1.100",
 RemotePort = 502
}, protocol: ProtocolType.Rtu);
await rtuOverUdpClient.ConnectAsync();
var inputs = await rtuOverUdpClient.ReadDiscreteInputsAsync(unitId: 1, startAddress: 0, quantity: 8);

同步方法示例

// 串口 RTU 客户端(同步)
var rtuClient = new ModbusRtuClient("COM1", 9600);
rtuClient.Connect();
var coils = rtuClient.ReadCoils(unitId: 1, startAddress: 0, quantity: 10);

// TCP 客户端 + RTU 协议(同步)
var rtuOverTcpClient = new ModbusTcpClient("192.168.1.100", 502, protocol: ProtocolType.Rtu);
rtuOverTcpClient.Connect();
var registers = rtuOverTcpClient.ReadHoldingRegisters(unitId: 1, startAddress: 0, quantity: 10);

泛型方法使用示例

// 读取浮点数数组
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);

使用 Pipe 和 Channel 客户端

using ModbusLib.Clients;
using ModbusLib.Enums;
using ModbusLib.Models;
// Pipe 客户端 + TCP 协议(默认)
var pipeSession = new PipeSession();
var pipeTcpClient = new ModbusPipeClient(pipeSession, protocol: ProtocolType.Tcp);
await pipeTcpClient.ConnectAsync();
// Pipe 客户端 + RTU 协议
var pipeRtuClient = new ModbusPipeClient(pipeSession, protocol: ProtocolType.Rtu);
await pipeRtuClient.ConnectAsync();
// Channel 客户端 + TCP 协议(默认)
var channelSession = new ChannelSession();
var channelTcpClient = new ModbusChannelClient(channelSession, protocol: ProtocolType.Tcp);
await channelTcpClient.ConnectAsync();
// Channel 客户端 + RTU 协议
var channelRtuClient = new ModbusChannelClient(channelSession, protocol: ProtocolType.Rtu);
await channelRtuClient.ConnectAsync();

📁 项目结构

ModbusLib/
├── Clients/ # 客户端实现
│ ├── ModbusClientBase.cs # 客户端基类
│ ├── ModbusRtuClient.cs # RTU 客户端
│ ├── ModbusTcpClient.cs # TCP 客户端
│ ├── ModbusUdpClient.cs # UDP 客户端
│ ├── ModbusPipeClient.cs # Pipe 客户端
│ └── ModbusChannelClient.cs # Channel 客户端
├── Interfaces/ # 核心接口定义
│ ├── IModbusClient.cs # Modbus 客户端接口
│ ├── IModbusProtocol.cs # 协议处理接口
│ └── IModbusTransport.cs # 传输层接口
├── Enums/ # 枚举类型
│ ├── ByteOrder.cs # 字节序枚举
│ ├── WordOrder.cs # 字序枚举
│ ├── ModbusFunction.cs # Modbus 功能码
│ ├── ModbusExceptionCode.cs # Modbus 异常码
│ └── ProtocolType.cs # 协议类型
├── Models/ # 数据模型
│ ├── ModbusRequest.cs # Modbus 请求模型
│ ├── ModbusResponse.cs # Modbus 响应模型
│ ├── SerialConfig.cs # 串口连接配置
│ ├── NetworkConfig.cs # 网络连接配置
│ ├── PipeSession.cs # Pipe 会话模型
│ └── ChannelSession.cs # Channel 会话模型
├── Transports/ # 传输层实现
│ ├── SerialTransport.cs # 串口传输实现
│ ├── TcpTransport.cs # TCP 传输实现
│ ├── UdpTransport.cs # UDP 传输实现
│ ├── PipeTransport.cs # Pipe 传输实现
│ └── ChannelTransport.cs # Channel 传输实现
├── Protocols/ # 协议处理层
│ ├── RtuProtocol.cs # RTU 协议实现
│ └── TcpProtocol.cs # TCP 协议实现
├── Exceptions/ # 异常定义
│ ├── ModbusException.cs # Modbus 异常基类
│ └── ModbusCommunicationExceptions.cs # 通信异常
└── Utils/ # 工具类
 ├── Crc16Utils.cs # CRC16 校验工具
 ├── DataConverter.cs # 数据转换工具
 └── CancelTokenExtensions.cs # 取消令牌扩展
ModbusLib.Tests/ # 单元测试
├── Clients/ # 客户端测试
├── Functional/ # 功能测试
├── Mocks/ # 模拟对象
├── Transports/ # 传输层测试
└── Utils/ # 工具类测试

🔧 构建和测试

# 构建项目
dotnet build
# 运行测试
dotnet test
# 发布 NuGet 包
dotnet pack

📖 API 参考

客户端类型

ModbusRtuClient(串口 RTU 客户端)

using ModbusLib.Clients;
using ModbusLib.Models;
// 简化构造(推荐)
var rtuClient = new ModbusRtuClient("COM1", 9600);
// 或使用完整配置
var rtuClient = new ModbusRtuClient(new SerialConfig {
 PortName = "COM1",
 BaudRate = 9600,
 Parity = Parity.None,
 DataBits = 8,
 StopBits = StopBits.One
});

ModbusTcpClient(TCP 客户端,支持协议切换)

using ModbusLib.Clients;
using ModbusLib.Enums;
using ModbusLib.Models;
// TCP 传输 + TCP 协议(默认,标准 Modbus TCP)
var tcpClient = new ModbusTcpClient("192.168.1.100", 502);
// 或显式指定
var tcpClient = new ModbusTcpClient("192.168.1.100", 502, protocol: ProtocolType.Tcp);
// TCP 传输 + RTU 协议(RTU over TCP)
var rtuOverTcpClient = new ModbusTcpClient("192.168.1.100", 502, protocol: ProtocolType.Rtu);
// 使用完整配置
var tcpClient = new ModbusTcpClient(new NetworkConfig {
 RemoteHost = "192.168.1.100",
 RemotePort = 502,
 ConnectTimeout = 5000,
 ReceiveTimeout = 3000,
 SendTimeout = 3000
}, protocol: ProtocolType.Tcp);

ModbusUdpClient(UDP 客户端,支持协议切换)

using ModbusLib.Clients;
using ModbusLib.Enums;
// UDP 传输 + TCP 协议(默认)
var udpClient = new ModbusUdpClient("192.168.1.100", 502);
// UDP 传输 + RTU 协议(RTU over UDP)
var rtuOverUdpClient = new ModbusUdpClient("192.168.1.100", 502, protocol: ProtocolType.Rtu);

ModbusPipeClient(Pipe 客户端,支持协议切换)

using ModbusLib.Clients;
using ModbusLib.Enums;
using ModbusLib.Models;
// Pipe + TCP 协议(默认)
var pipeSession = new PipeSession();
var pipeClient = new ModbusPipeClient(pipeSession);
// Pipe + RTU 协议
var pipeRtuClient = new ModbusPipeClient(pipeSession, protocol: ProtocolType.Rtu);

ModbusChannelClient(Channel 客户端,支持协议切换)

using ModbusLib.Clients;
using ModbusLib.Enums;
using ModbusLib.Models;
// Channel + TCP 协议(默认)
var channelSession = new ChannelSession();
var channelClient = new ModbusChannelClient(channelSession);
// Channel + RTU 协议
var channelRtuClient = new ModbusChannelClient(channelSession, protocol: ProtocolType.Rtu);

ProtocolType 枚举

namespace ModbusLib.Enums;
public enum ProtocolType {
 Rtu, // RTU 协议(使用 CRC16 校验)
 Tcp // TCP 协议(使用 MBAP 报文头)
}

协议选择指南

支持的功能码

主要方法

连接管理

读取功能

写入功能

高级功能

泛型方法

配置选项

SerialConfig(串口配置)

public class SerialConfig {
 public string PortName { get; set; } // 串口名称 (如 COM1)
 public int BaudRate { get; set; } // 波特率,默认 9600
 public Parity Parity { get; set; } // 校验位,默认 None
 public int DataBits { get; set; } // 数据位,默认 8
 public StopBits StopBits { get; set; } // 停止位,默认 One
 public int ReadTimeout { get; set; } // 读取超时(毫秒)
 public int WriteTimeout { get; set; } // 写入超时(毫秒)
}

NetworkConfig(网络配置)

public class NetworkConfig {
 public string RemoteHost { get; set; } // 远程主机地址
 public int RemotePort { get; set; } // 远程端口,默认 502
 public int ConnectTimeout { get; set; } // 连接超时(毫秒)
 public int ReceiveTimeout { get; set; } // 接收超时(毫秒)
 public int SendTimeout { get; set; } // 发送超时(毫秒)
 public int ReceiveBufferSize { get; set; } // 接收缓冲区大小
 public int SendBufferSize { get; set; } // 发送缓冲区大小
 public string? LocalHost { get; set; } // 本地主机地址(可选)
 public int? LocalPort { get; set; } // 本地端口(可选)
}

超时与重试

数据类型转换

// 读取 10 个字节(占用 5 个寄存器)
var bytes = await client.ReadHoldingRegistersAsync<byte>(unitId: 1, startAddress: 0, count: 10);
// 读取 5 个整数(占用 10 个寄存器)
var ints = await client.ReadHoldingRegistersAsync<int>(unitId: 1, startAddress: 10, count: 5);
// 写入浮点数数组
float[] values = new float[] { 1.5f, 2.5f, 3.5f };
await client.WriteMultipleRegistersAsync(unitId: 1, startAddress: 0, values);

🤝 贡献

📄 许可证