1. 功能库不是多写几个类:ModBus 通信先做接口抽象的理由
把 ModBus 通信封装成一个可复用的功能库,很多人第一反应是多写几个类。我在一个模拟项目里第一次做这件事时也是这么想的,用 C# 把串口和以太网各写一套,结果现场从 RTU 换成 TCP,业务代码跟着改了两天。问题不在协议本身,在于一开始没把“通信方式”和“读写语义”分开。功能库要解决的不是“能不能通”,而是换物理层时上层要不要动。下面按我后来落地的顺序写:先定接口,再拆 RTU 和 TCP 的实现,然后跑通建连、读点、写点,最后把踩过的坑和验证方法摊开。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 功能库的骨架:IModbusClient 接口与 RTU/TCP 两种实现的职责切分
2.1 接口只留四个方法:把“通信方式”从业务语义里剥出去
接口设计的第一步不是想“要支持哪些协议”,而是想“业务层到底需要什么”。业务层要的是读一批保持寄存器、写一个寄存器、连上、断开,至于底下是串口还是 Socket,它不需要知道。所以接口只暴露高层语义,四个方法就够了:
csharp复制public interface IModbusClient
{
Task<ushort[]> ReadHoldingRegistersAsync(ushort startAddress, ushort count, CancellationToken ct = default);
Task WriteSingleRegisterAsync(ushort address, ushort value, CancellationToken ct = default);
Task<bool> ConnectAsync(CancellationToken ct = default);
void Disconnect();
}
ReadHoldingRegistersAsync 返回的是 ushort[],长度应当等于 count,下标 0 对应 startAddress,下标 i 对应 startAddress + i。WriteSingleRegisterAsync 只写一个寄存器,地址和值都是 16 位。ConnectAsync 返回布尔值而不是抛异常,是为了让上层能决定“连不上是重试还是报错”。CancellationToken 放在每个异步方法上,采集线程被取消时能尽快退出。这四个方法名里没有任何“RTU”“TCP”“串口”“Socket”字样,这就是关键:物理层的词不应该出现在业务契约里。
接口里没有从站地址参数,这是一个需要提前想清楚的设计取舍。单从站、单链路场景下,地址放在实现类的构造函数里最省事;如果一条总线上挂多个从站,就得在请求体里带站号,或者按站号拆多个 client 实例。我一般会在实现类构造函数里保留一个带默认值的站号参数,先把单站跑通,多站再扩,不急着把接口撑大。
2.2 RTU 实现类:串口五要素、CRC 与半双工时序归它管
RTU 这层要把串口参数、CRC 计算、帧拼接和半双工时序全部收进来。下面是一个能直接改用的最小实现,串口部分用 SerialPort,CRC 用标准 Modbus 多项式:
csharp复制public class ModbusRtuClient : IModbusClient
{
private readonly string _portName;
private readonly int _baudRate;
private readonly Parity _parity;
private readonly int _dataBits;
private readonly StopBits _stopBits;
private readonly byte _slaveId;
private SerialPort _port;
private readonly object _busLock = new object();
public ModbusRtuClient(string portName, int baudRate, Parity parity,
int dataBits, StopBits stopBits, byte slaveId = 1)
{
_portName = portName;
_baudRate = baudRate;
_parity = parity;
_dataBits = dataBits;
_stopBits = stopBits;
_slaveId = slaveId;
}
public Task<bool> ConnectAsync(CancellationToken ct = default)
{
_port = new SerialPort(_portName, _baudRate, _parity, _dataBits, _stopBits)
{
ReadTimeout = 1000,
WriteTimeout = 1000
};
_port.Open();
return Task.FromResult(_port.IsOpen);
}
public Task<ushort[]> ReadHoldingRegistersAsync(ushort startAddress, ushort count, CancellationToken ct = default)
{
// 0x03 请求帧:站号 + 功能码 + 起始地址(2B) + 数量(2B) + CRC(2B)
byte[] pdu = new byte[6];
pdu[0] = _slaveId;
pdu[1] = 0x03;
pdu[2] = (byte)(startAddress >> 8);
pdu[3] = (byte)(startAddress & 0xFF);
pdu[4] = (byte)(count >> 8);
pdu[5] = (byte)(count & 0xFF);
byte[] frame = AppendCrc(pdu);
lock (_busLock) // RS485 半双工,同一时刻只允许一帧在总线上
{
ct.ThrowIfCancellationRequested();
_port.Write(frame, 0, frame.Length);
// 正常响应:站号 + 0x03 + 字节数 + 数据 + CRC
int expected = 5 + count * 2;
byte[] resp = new byte[expected];
int read = 0;
while (read < expected)
read += _port.Read(resp, read, expected - read);
if ((resp[1] & 0x80) != 0)
throw new InvalidOperationException($"Modbus 异常码 0x{resp[2]:X2}");
ushort[] result = new ushort[count];
for (int i = 0; i < count; i++)
result[i] = (ushort)((resp[3 + i * 2] << 8) | resp[4 + i * 2]);
return Task.FromResult(result);
}
}
private static byte[] AppendCrc(byte[] data)
{
ushort crc = 0xFFFF;
for (int i = 0; i < data.Length; i++)
{
crc ^= data[i];
for (int b = 0; b < 8; b++)
crc = (crc & 1) != 0 ? (ushort)((crc >> 1) ^ 0xA001) : (ushort)(crc >> 1);
}
byte[] full = new byte[data.Length + 2];
Array.Copy(data, full, data.Length);
full[data.Length] = (byte)(crc & 0xFF); // CRC 低字节在前
full[data.Length + 1] = (byte)(crc >> 8);
return full;
}
}
这段代码有几个参数需要说明。_portName、_baudRate、_parity、_dataBits、_stopBits 就是串口五要素,必须和从站铭牌一致,示例里的 9600、None、8、One 只是常见组合,不是通用默认值。_slaveId 默认 1,单站场景够用。ReadTimeout 和 WriteTimeout 设成 1000 毫秒,是等待从站回帧的上限,现场总线负载重时可以放宽,但不能设成无限。_busLock 锁住的是“写请求 + 读响应”这一整段,因为 RS485 是半双工,一帧没读完就让另一帧上总线,必然串包。AppendCrc 只对站号、功能码、地址、数量这 6 个字节计算,结果低字节在前,这两点错一个从站就不会回正常帧。
2.3 TCP 实现类:MBAP 头、事务 ID 与连接池归它管
TCP 这层的麻烦不在协议解析,在报文头。Modbus TCP 在 PDU 前面加了 7 个字节的 MBAP 头:事务 ID 2 字节、协议 ID 2 字节固定为 0、长度 2 字节、单元 ID 1 字节。长度字段算的是“单元 ID + PDU”的字节数,不是整帧长度。下面这段是读保持寄存器的核心构造:
csharp复制public class ModbusTcpClient : IModbusClient
{
private readonly string _host;
private readonly int _port;
private TcpClient _client;
private NetworkStream _stream;
private ushort _transactionId;
private readonly SemaphoreSlim _gate = new SemaphoreSlim(1, 1);
public ModbusTcpClient(string host, int port)
{
_host = host;
_port = port;
}
public async Task<bool> ConnectAsync(CancellationToken ct = default)
{
_client = new TcpClient();
await _client.ConnectAsync(_host, _port, ct);
_stream = _client.GetStream();
return _client.Connected;
}
public async Task<ushort[]> ReadHoldingRegistersAsync(ushort startAddress, ushort count, CancellationToken ct = default)
{
await _gate.WaitAsync(ct);
try
{
// MBAP:事务ID(2B) + 协议ID(2B,固定0) + 长度(2B) + 单元ID(1B)
ushort tid = ++_transactionId;
byte[] mbap = new byte[7];
mbap[0] = (byte)(tid >> 8);
mbap[1] = (byte)(tid & 0xFF);
mbap[2] = 0;
mbap[3] = 0;
mbap[4] = 0;
mbap[5] = 6; // 单元ID 1B + PDU 5B
mbap[6] = 1; // 单元ID
byte[] pdu = new byte[5];
pdu[0] = 0x03;
pdu[1] = (byte)(startAddress >> 8);
pdu[2] = (byte)(startAddress & 0xFF);
pdu[3] = (byte)(count >> 8);
pdu[4] = (byte)(count & 0xFF);
byte[] frame = mbap.Concat(pdu).ToArray();
await _stream.WriteAsync(frame, ct);
// 先读 7 字节头,再按长度字段读剩余部分
byte[] header = new byte[7];
await ReadExactAsync(header, 7, ct);
ushort respTid = (ushort)((header[0] << 8) | header[1]);
if (respTid != tid)
throw new InvalidOperationException("事务 ID 不匹配,响应可能串了");
int len = (header[4] << 8) | header[5];
byte[] rest = new byte[len - 1];
await ReadExactAsync(rest, rest.Length, ct);
if ((rest[0] & 0x80) != 0)
throw new InvalidOperationException($"Modbus 异常码 0x{rest[1]:X2}");
int byteCount = rest[1];
ushort[] result = new ushort[byteCount / 2];
for (int i = 0; i < result.Length; i++)
result[i] = (ushort)((rest[2 + i * 2] << 8) | rest[3 + i * 2]);
return result;
}
finally
{
_gate.Release();
}
}
private async Task ReadExactAsync(byte[] buffer, int length, CancellationToken ct)
{
int offset = 0;
while (offset < length)
offset += await _stream.ReadAsync(buffer.AsMemory(offset, length - offset), ct);
}
}
这里每个参数都有对应关系。_host 和 _port 是 TCP 端点,示例里的 502 是 Modbus TCP 的默认端口,填错了连得上也读不到。_transactionId 每次请求自增,响应回来要跟请求的 tid 比对,对不上说明有旧响应混进来。_gate 这个信号量锁的是整段“写请求 + 读响应”,不能只锁写,否则两个线程的响应会互相读走。mbap[5] = 6 是因为 PDU 固定 5 字节、单元 ID 1 字节,合计 6,改动功能码或点数时要重新算。ReadExactAsync 必须循环读,网络流一次 Read 不保证给你完整长度。
连接池解决的是“连接复用”,不是“请求并发安全”,这两个概念别混。一个实例持有一个连接,请求仍然要串行化;要多路并发,就按设备拆多个实例。
2.4 用配置选择实现:一行 switch 完成 RTU/TCP 切换
接口和两个实现都齐了,工厂方法只剩一个配置键的事:
csharp复制string mode = ConfigurationManager.AppSettings["ModbusMode"]; // "RTU" or "TCP"
IModbusClient client = mode switch
{
"RTU" => new ModbusRtuClient("COM3", 9600, Parity.None, 8, StopBits.One),
"TCP" => new ModbusTcpClient("192.168.1.100", 502),
_ => throw new NotSupportedException()
};
await client.ConnectAsync();
ushort[] values = await client.ReadHoldingRegistersAsync(0x0000, 10);
// 后续业务逻辑完全相同,无需 if-else 判断通信类型
ModbusMode 的取值只有 RTU 和 TCP,其他值直接抛 NotSupportedException,别让拼错的配置静默跑到某个分支。COM3 和 192.168.1.100 是材料里的示例值,现场要换成实际端口和地址。业务层拿到 IModbusClient 之后不再关心通信类型,这也是前面拆接口换来的收益:把 RS485 仪表升级成以太网模块时,只改配置文件,业务代码零改动。我在一次模拟改造里把 17 台设备从串口切到以太网,只动了一个键,两小时内完成,前提就是接口早就抽干净了。
3. 功能库落地:从建连到读保持寄存器的完整调用链
3.1 连接参数怎么填:9600 8N1 与 502 端口的对应关系
参数不是拍脑袋填的,先把两条链路的必填项列清楚:
| 传输 | 配置键 | 参数 | 示例值 | 说明 |
|---|---|---|---|---|
| RTU | ModbusMode=RTU |
串口名 / 波特率 / 校验 / 数据位 / 停止位 | COM3 / 9600 / None / 8 / One |
必须与从站铭牌一致 |
| RTU | 同上 | 从站地址 | 1 |
单站默认 1,多站按实际改 |
| TCP | ModbusMode=TCP |
主机 / 端口 | 192.168.1.100 / 502 |
502 是 Modbus TCP 默认端口 |
串口这行最容易翻车的地方是“看着像 9600 8N1 就填了”,实际从站可能是 19200 或带偶校验。参数不一致时现象不一定是连不上,而是返回帧长度对、数值却乱跳,很容易误判成点位错。TCP 这边,502 填错通常表现为连接超时或连上后无响应,先把端口确认再查报文。
建连代码本身很短,但要把超时和取消带上:
csharp复制using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(3));
bool ok = await client.ConnectAsync(cts.Token);
if (!ok)
throw new InvalidOperationException("Modbus 连接失败");
CancellationTokenSource 给 3 秒上限,是防止串口被占用或 TCP 对端不回 SYN 时界面卡死。ConnectAsync 返回 false 和抛异常是两种失败语义:返回 false 偏“对端没准备好”,异常偏“参数或链路错了”,上层可以据此决定重试还是告警。
3.2 读保持寄存器:起始地址、数量与返回数组的下标对应
读点是最常用的路径,调用就一行,但下标对应关系要提前约定死:
csharp复制ushort[] values = await client.ReadHoldingRegistersAsync(0x0000, 10, cts.Token);
// values.Length == 10,values[0] 对应地址 0x0000,values[9] 对应 0x0009
for (int i = 0; i < values.Length; i++)
Console.WriteLine($"0x{0x0000 + i:X4} = {values[i]}");
startAddress 是保持寄存器的起始地址,count 是一次读多少个,示例里从 0x0000 开始读 10 个。返回数组长度必须等于 count,如果实现里因为异常码提前返回,长度对不上就说明有问题。地址在 Modbus 报文里是从 0 开始算的,而有些设备手册标的是 40001 这类“显示地址”,换算时要减掉基址,这个换算放在业务层做,不要塞进功能库,否则换一家设备又要改库。
批量读的边界也要注意:一次读太多寄存器,部分从站会回异常码,常见做法是按设备手册允许的最大连续点数分段,比如 10 个一组循环。分段逻辑放在调用方,功能库只保证单次请求正确。
3.3 写入与超时:WriteSingleRegisterAsync、CancellationToken、Disconnect
写单个寄存器的帧格式和读不同,功能码是 0x06,正常响应是请求帧原样回显:
csharp复制public Task WriteSingleRegisterAsync(ushort address, ushort value, CancellationToken ct = default)
{
byte[] pdu = new byte[6];
pdu[0] = _slaveId;
pdu[1] = 0x06;
pdu[2] = (byte)(address >> 8);
pdu[3] = (byte)(address & 0xFF);
pdu[4] = (byte)(value >> 8);
pdu[5] = (byte)(value & 0xFF);
byte[] frame = AppendCrc(pdu);
lock (_busLock)
{
ct.ThrowIfCancellationRequested();
_port.Write(frame, 0, frame.Length);
byte[] echo = new byte[8];
int read = 0;
while (read < echo.Length)
read += _port.Read(echo, read, echo.Length - read);
if (echo[1] != 0x06)
throw new InvalidOperationException($"写寄存器异常码 0x{echo[2]:X2}");
}
return Task.CompletedTask;
}
address 是目标寄存器地址,value 是要写入的 16 位值。echo 读 8 字节,因为正常响应就是 8 字节回显,少于这个长度说明帧被截断。判断异常不能只看长度,echo[1] 的最高位为 1 时才是异常响应,此时 echo[2] 是异常码。ct.ThrowIfCancellationRequested() 放在写之前,避免取消后还往总线发一帧。
调用顺序上,我一般固定成“连接 → 读 → 写 → 断开”,Disconnect 放在 finally 里:
csharp复制try
{
await client.ConnectAsync(cts.Token);
ushort[] values = await client.ReadHoldingRegistersAsync(0x0000, 10, cts.Token);
await client.WriteSingleRegisterAsync(0x0001, 0x000F, cts.Token);
}
finally
{
client.Disconnect();
}
Disconnect 里要同时关流和关连接,RTU 还要 _port.Close(),不关干净下次打开会报“端口被占用”。这一步看着琐碎,现场连续采集时最容易漏。
4. 功能库避坑:RTU 与 TCP 混用时最常见的五类翻车
4.1 五类现象先对号:超时、乱码、异常码、串包、配置失效
现场出问题,先别急着改代码,按现象对号能省一半时间:
| 现象 | 先查什么 | 对应条目 |
|---|---|---|
| 连接一直超时 | 配置的 mode 与物理链路是否一致 | 4.2 第 1 条 |
| 从站完全不回帧 | CRC 字节序、计算范围 | 4.2 第 2 条 |
| 连续读时数值串位 | MBAP 长度字段、事务 ID | 4.2 第 3 条 |
| 帧长度对但数值乱跳 | 串口五要素是否与铭牌一致 | 4.2 第 4 条 |
| 单线程正常、多线程偶发超时 | 是否共用一个 client 并发请求 | 4.2 第 5 条 |
4.2 逐条拆:从现象到原因再到解决
第 1 条:配了 TCP,现场却是 RS485 表。 现象是 ConnectAsync 一直等到超时抛异常,或者勉强连上了读点也超时。原因是 ModbusMode 配成 TCP,但物理链路根本没有 502 端点,TCP 客户端连的是一个不存在的服务。解决办法是在工厂方法里做白名单校验,非 RTU、TCP 直接抛 NotSupportedException,启动时把 mode 和端点打进日志;现场改线必须同步改配置,不能只改一边。
第 2 条:RTU 从站不响应,抓不到任何回帧。 现象是写成功但读超时,或者返回一帧长度不对的数据。原因多半在 CRC:要么高低字节写反,要么把 CRC 本身也算进了校验范围。解决是按“站号 + 功能码 + 地址 + 数量”6 个字节计算,结果低字节在前、高字节在后;用一组已知请求帧做单元测试,帧对不上就别上现场。
第 3 条:TCP 响应错位,读到的数据对不上点位。 现象是第一次读正常,连续读时数值串位,或者事务 ID 跟请求对不上。原因是 MBAP 的长度字段填错,或者多个线程共用一个 _transactionId 字段,请求和响应配错。解决是长度字段按“单元 ID + PDU”算,事务 ID 每次请求自增并在响应里比对,写请求和读响应用信号量串行化。
第 4 条:串口参数与从站不一致,数据全是乱码。 现象是返回帧长度对,但数值跳变或校验失败。原因是波特率、校验位、停止位和从站铭牌不一致,9600 8N1 只是示例,不是所有设备的默认值。解决是先按铭牌设,读不通再逐项排除,一次只改一个参数,别一边改代码一边改串口。
第 5 条:多线程共用一个 client,偶发超时和串包。 现象是单线程跑得好,放到采集线程池就偶发异常或超时。原因是 RTU 是半双工共享总线,TCP 的 NetworkStream 也不保证多请求并发安全,连接池解决的是连接复用,不是请求并发。解决是一个物理链路一个 client,请求层加锁或信号量;采集频率高时按设备拆连接,别让所有点位挤一个实例。
5. 功能库的验证与扩展:换物理层之前先做这三步回归
5.1 先用假实现跑通业务层
换物理层之前,先确认业务层真的不依赖实现。写一个假客户端,返回固定数组,业务代码原样跑:
csharp复制public class FakeModbusClient : IModbusClient
{
public Task<bool> ConnectAsync(CancellationToken ct = default) => Task.FromResult(true);
public Task<ushort[]> ReadHoldingRegistersAsync(ushort startAddress, ushort count, CancellationToken ct = default)
=> Task.FromResult(Enumerable.Range(0, count).Select(i => (ushort)i).ToArray());
public Task WriteSingleRegisterAsync(ushort address, ushort value, CancellationToken ct = default)
=> Task.CompletedTask;
public void Disconnect() { }
}
如果业务层在这个假实现下能跑通,说明它没有偷偷依赖串口或 Socket 的细节;跑不通,先改业务层,别急着接真设备。
5.2 再用配置切换做一次回归
把 ModbusMode 从 RTU 改成 TCP,业务代码一行不改,跑同一组点位,对比两次结果。重点看三件事:连接是否成功、返回数组长度是否等于 count、下标对应地址是否一致。三项都过,才说明功能库真的做到了物理层透明。
5.3 日志与抓包:把帧头和耗时打出来
我习惯在功能库里留一个开关,把 mode、端点、事务 ID、CRC、耗时打进日志。RTU 用串口助手核对请求帧和响应帧,TCP 用抓包看 MBAP 头。异常时先看日志里的 mode 和端点,再看帧,比盲猜快得多。
| 检查项 | 正常表现 | 异常时先看 |
|---|---|---|
| 连接 | 3 秒内返回 true | mode 与端点是否匹配 |
| 读点 | 数组长度等于 count | 异常码、CRC、MBAP 长度 |
| 写点 | 8 字节回显、功能码 0x06 | 地址和值的高低位 |
| 并发 | 多线程下无串包 | 是否共用 client、锁的范围 |
从那以后我每次接新设备,第一件事就是把 mode、端点、超时三个值打进启动日志,再拿一组已知点位做回归;功能库能不能复用,不取决于类写得多漂亮,取决于换物理层那天业务代码要不要动。希望帮到你。
