简介NModbus4 C# 源码是一套面向 .NET 开发者的开源 Modbus 协议实现库适合从事工业自动化、设备通信与上位机开发的初中级工程师学习与二次开发。它解决了在 C# 项目中快速集成 Modbus TCP、ASCII、RTU 等通信模式的问题可用于工厂自动化、能源管理、远程监控等场景主站与从站功能均有对应实现。资源包共 223 个文件以 104 个 cs 源码文件和 103 个 html 文档为主另含 csproj 工程文件、config 配置、sln 解决方案、chm 帮助文档及 nuspec 打包描述压缩包约 719KB结构完整便于直接编译研究。目前已有 402 人学习下载。通过阅读源码读者可掌握线圈、离散输入、保持寄存器与输入寄存器的读写 API 调用方式理解异步通信与异常诊断机制的设计思路并借助示例工程与帮助文档快速上手为构建响应快、可扩展的工业控制系统提供参考。1. 工控上位机通信的硬骨头NModbus4 C# 源码能帮你省掉哪些造轮子的时间做上位机或者设备通信网关的兄弟大概率都经历过这个场景PLC 那边数据点表已经给过来了领导催着三天内把采集程序跑通结果你打开工程发现从站地址、功能码、寄存器大小端、CRC 校验这些底层细节全得自己撸。Modbus 协议本身不复杂但真要用 C# 写一个稳定能跑的轮子没个两三天调不通。NModbus4 C# 源码就是来解决这个问题的——它是一套完整的 Modbus 协议栈实现覆盖了 RTU、ASCII、TCP、UDP 四种传输方式主站从站都支持拿来就能嵌到自己的工控项目里。适合谁做设备数据采集、SCADA 上位机、边缘网关的 C# 开发者尤其是那些不想在协议层反复踩坑、想把精力放在业务逻辑上的人。这套源码不是玩具它把串口和网络两种链路的超时、重试、异常响应都处理过了你拿到手第一件事应该是跑通一个读写保持寄存器的 Demo而不是从头读协议文档。2. 拆开 NModbus4 的骨架四种传输链路与主从站模型怎么选2.1 先搞清楚你的设备走的是哪条链路NModbus4 把传输层抽象得很干净核心接口是IModbusMaster和IModbusSlave底下挂ModbusSerialMaster、ModbusTcpMaster、ModbusUdpMaster这几个实现。选型第一步不是看代码是看你的物理接口。串口设备RS485/RS232走ModbusSerialMaster.CreateRtu(serialPort)或者CreateAscii网口设备走ModbusTcpMaster.CreateIp(ipAddress)或者CreateUdp。这里有个新手容易翻车的地方RTU 和 ASCII 的区别不只是编码ASCII 模式下每个字节要转成两个 ASCII 字符帧头是冒号、帧尾是 CRLF传输效率低但抗干扰调试直观。我一般建议除非设备手册明确写了 ASCII否则一律用 RTU现场 90% 的 485 设备都是 RTU。主从站模型的选择更直接你的程序主动去读别人就当主站你的程序等着别人来读你就当从站。NModbus4 的从站实现需要你自己提供一个IDataStore或者继承SlaveStorage把寄存器映射到内存数组里。很多兄弟第一次用从站模式发现主站读上来的全是 0原因就是没把数据写进DataStore的对应地址段。记住一个原则主站是“请求-响应”的发起方从站是被动应答方从站代码里你只需要管数据怎么存、怎么取帧的解析和 CRC 校验框架会帮你做。2.2 用代码把主站读保持寄存器跑通下面这段代码是我在模拟项目里最常用的最小可运行片段串口 RTU 主站读 10 个保持寄存器。注意SerialPort的参数必须和设备手册严格一致尤其是停止位和校验位错一个就是超时。using Modbus.Device; using System.IO.Ports; // 配置串口参数COM3、9600、8数据位、无校验、1停止位 var port new SerialPort(COM3, 9600, Parity.None, 8, StopBits.One); port.ReadTimeout 1000; // 读超时单位毫秒 port.WriteTimeout 1000; // 写超时单位毫秒 port.Open(); // 创建 RTU 主站实例 var master ModbusSerialMaster.CreateRtu(port); // 从站地址 1起始地址 0读取 10 个保持寄存器 ushort startAddress 0; ushort numRegisters 10; byte slaveId 1; try { ushort[] registers master.ReadHoldingRegisters(slaveId, startAddress, numRegisters); for (int i 0; i registers.Length; i) { Console.WriteLine($寄存器[{startAddress i}] {registers[i]}); } } catch (Exception ex) { Console.WriteLine($读取失败{ex.Message}); } finally { port.Close(); }逻辑说明CreateRtu内部会构造 RTU 帧自动加 CRC16 校验你不需要手动算。ReadHoldingRegisters对应功能码 03读的是保持寄存器可读可写如果你要读输入寄存器只读就用ReadInputRegisters功能码 04。参数上slaveId是设备地址startAddress是从 0 开始的寄存器偏移不是手册上写的 40001 那种地址需要自己减 40001。numRegisters一次别读太多RTU 帧最大 256 字节读 125 个寄存器就到顶了超了会抛异常。2.3 从站模式的数据存储与地址映射从站模式在工控网关里很常见比如你把本地采集的数据模拟成一个 Modbus 从站让上位机来读。NModbus4 的从站需要你实现ISlaveDataStore最简单的方式是用SlaveStorage类它内部用数组存四类数据线圈、离散输入、保持寄存器、输入寄存器。using Modbus.Data; using Modbus.Device; // 创建从站数据存储100 个线圈、100 个离散输入、100 个保持寄存器、100 个输入寄存器 var dataStore new SlaveStorage(); dataStore.CoilDiscretes new ModbusDataCollectionbool(new bool[100]); dataStore.CoilInputs new ModbusDataCollectionbool(new bool[100]); dataStore.HoldingRegisters new ModbusDataCollectionushort(new ushort[100]); dataStore.InputRegisters new ModbusDataCollectionushort(new ushort[100]); // 往保持寄存器地址 0 写入 1234 dataStore.HoldingRegisters[0] 1234; // 创建 RTU 从站绑定串口和存储 var port new SerialPort(COM4, 9600, Parity.None, 8, StopBits.One); port.Open(); var slave ModbusSerialSlave.CreateRtu(1, port); // 从站地址 1 slave.DataStore dataStore; slave.Listen(); // 开始监听这里的关键是ModbusDataCollection的索引就是寄存器地址主站读地址 0 拿到的就是HoldingRegisters[0]的值。注意从站的Listen()是阻塞的实际项目里要放到独立线程或者 Task 里跑。另外从站地址必须和主站请求的slaveId一致否则从站不会应答主站那边就是超时。3. 避坑与排查串口超时、CRC 错误、地址偏移的五个血泪经验3.1 现象主站一直超时从站毫无反应原因串口参数不匹配是最常见的尤其是校验位和停止位。有些 USB 转 485 模块默认校验位是 Even但设备手册写的是 None你代码里配 None 就永远通不上。另一个原因是 RS485 收发方向控制没做好半双工 485 需要手动控制 DE/RE 引脚NModbus4 默认不帮你管这个你得用port.RtsEnable或者额外的 GPIO 来控制。解决先用串口调试助手手动发一帧 03 功能码的报文确认设备有回复再回来查代码。如果调试助手能通、代码不通那就是参数或方向控制问题。3.2 现象偶尔能读上来但频繁抛 CRC 校验错误原因波特率太高、线缆太长、没有终端电阻或者现场变频器干扰。RTU 模式下 CRC 是逐字节算的任何一个位翻转都会导致校验失败。解决先把波特率降到 9600 甚至 4800 测试确认是干扰问题还是代码问题。如果是干扰加 120 欧终端电阻、用屏蔽双绞线、把 485 的 A/B 线远离动力线。代码层面可以在ReadHoldingRegisters外面包一层重试NModbus4 本身不自动重试你得自己写。3.3 现象读上来的数据全是 0 或者明显不对原因地址偏移搞错了。设备手册上写“保持寄存器 40001”你代码里startAddress填了 40001实际应该填 0。Modbus 的地址有“协议地址”和“PLC 地址”两套体系40001 是 PLC 地址协议地址是 0。另外32 位浮点数或者整型数在寄存器里是高低字交换的你读两个寄存器拼成一个 float 时字序搞反了就是乱码。解决先读单个寄存器确认数值和手册能对上再处理多寄存器拼接。字序问题用BitConverter配合数组反转多试两次就能确定。3.4 现象TCP 连接正常但读数据报异常原因Modbus TCP 的端口默认是 502但有些设备改成了别的端口你代码里没改。另一个坑是单元标识符Unit IDTCP 模式下虽然走的是网络但帧里还有一个 Unit ID 字段有些网关要求这个字段必须和从站地址一致有些又忽略它。解决用 Wireshark 抓包看请求帧的 Unit ID 和端口和设备的实际配置对比。NModbus4 的ModbusTcpMaster.CreateIp默认端口 502要改端口得用CreateIp(ip, port)重载。3.5 现象从站模式下主站读不到我写入的数据原因你写数据的时候直接操作了dataStore.HoldingRegisters但 NModbus4 的从站内部可能有一层缓存或者事件机制尤其是多线程环境下主站读的时候拿到的还是旧值。解决确保写入和读取在同一个DataStore实例上不要在从站启动后重新 new 一个SlaveStorage替换掉。如果多线程写加锁或者用Interlocked保证可见性。另外从站的DataStore属性必须在Listen()之前赋值启动后再改不生效。4. 把 NModbus4 嵌进真实项目批量采集、异常重试与性能调优4.1 批量采集的轮询策略与超时设置真实项目里你不会只读一个寄存器通常是几十个设备、几百个点位轮询。NModbus4 的每次ReadHoldingRegisters都是一次完整的请求-响应频繁调用小批量读会浪费带宽。我一般会把连续地址合并成一次读比如地址 0 到 49 的 50 个寄存器一次读完再在内存里拆分。但要注意 RTU 帧上限读 125 个寄存器是极限实际建议一次不超过 100 个留点余量。超时设置上串口ReadTimeout设 1000ms 是保守值现场如果设备响应快可以降到 300ms但别低于 200ms否则误判超时。TCP 的ReadTimeout可以设 2000ms网络抖动比串口大。// 批量读取优化合并连续地址减少请求次数 ushort[] ReadBatch(IModbusMaster master, byte slaveId, ushort start, ushort count) { const int maxBatch 100; // 单次最大读取量 var result new Listushort(); while (count 0) { ushort batch Math.Min(count, (ushort)maxBatch); ushort[] data master.ReadHoldingRegisters(slaveId, start, batch); result.AddRange(data); start batch; count - batch; } return result.ToArray(); }这段代码解决的是“一次读不完”的问题逻辑很简单把大范围拆成多个不超过 100 的批次依次读完再拼接。参数maxBatch可以根据你的设备响应速度调整响应慢的设备降到 50 更稳。4.2 异常重试与连接恢复NModbus4 抛异常的时候串口可能已经处于半死状态直接重试往往还是失败。我的做法是捕获异常后先关闭串口延时 200ms重新打开再重试。重试次数设 3 次3 次都失败就标记设备离线等下一轮轮询再试。TCP 类似但不需要关端口直接重新Connect就行。bool TryReadWithRetry(IModbusMaster master, byte slaveId, ushort addr, ushort count, out ushort[] data) { data null; for (int i 0; i 3; i) { try { data master.ReadHoldingRegisters(slaveId, addr, count); return true; } catch { Thread.Sleep(200); } } return false; }注意重试之间一定要加延时立刻重试大概率还是撞上同样的干扰窗口。200ms 是个经验值现场干扰周期如果更长可以加到 500ms。4.3 性能调优轮询周期与线程模型如果你用ModbusSerialMaster它是线程安全的但多个线程同时读同一个串口会互相排队反而降低效率。我一般用一个独立的采集线程按设备顺序串行轮询每个设备读完后Thread.Sleep一小段时间让出串口。TCP 主站可以并发但要注意设备端的连接数限制有些 PLC 只允许 4 个 TCP 连接你开 10 个线程去读后面的全被拒绝。轮询周期根据点位数量算假设 10 个设备每个设备读 50 个寄存器耗时 50ms一轮就是 500ms加上延时1 秒一轮是合理值。别追求 100ms 一轮现场设备扛不住。5. 进阶技巧用 NModbus4 做协议转换网关与数据校验5.1 把 RTU 从站数据映射到 TCP 主站一个很实用的场景现场设备是 485 接口但上位机只认 Modbus TCP。你可以用 NModbus4 做一个协议转换网关——一边用ModbusSerialMaster读 485 设备一边用ModbusTcpSlave把数据暴露成 TCP 从站。核心代码如下// 创建 TCP 从站监听 502 端口 var tcpListener new TcpListener(IPAddress.Any, 502); tcpListener.Start(); var tcpSlave ModbusTcpSlave.CreateTcp(1, tcpListener); tcpSlave.DataStore dataStore; // 复用同一个数据存储 tcpSlave.Listen(); // 独立线程轮询 RTU 设备更新 dataStore Task.Run(() { while (true) { ushort[] values rtuMaster.ReadHoldingRegisters(1, 0, 10); for (int i 0; i values.Length; i) { dataStore.HoldingRegisters[i] values[i]; } Thread.Sleep(500); } });这个模式的关键是dataStore共享RTU 主站写进去TCP 从站读出来。注意线程安全ModbusDataCollection本身不是线程安全的高并发下要加锁。我一般用lock (dataStore)包住读写操作简单有效。5.2 数据校验用 CRC 和异常码定位问题NModbus4 抛出的异常里包含了 Modbus 异常码比如功能码 03 的异常响应会带一个字节的错误码01 表示非法功能02 表示非法数据地址03 表示非法数据值。捕获异常时把SlaveException的SlaveExceptionCode打出来能快速定位是地址越界还是设备不支持该功能码。catch (SlaveException ex) { Console.WriteLine($Modbus 异常码{ex.SlaveExceptionCode}); // 02 通常是地址不对03 通常是写入的值超范围 }另外串口通信的原始帧可以用port.BytesToRead和port.Read抓出来配合在线 CRC 计算器验证。我习惯在调试阶段开一个日志把每次请求的帧和响应的帧都按十六进制打出来对比手册就能发现是地址错了还是字节序错了。5.3 一个我踩过的坑从站地址 0 的广播陷阱Modbus 协议里从站地址 0 是广播地址主站发地址 0 的写请求所有从站都会执行但不响应。NModbus4 的ReadHoldingRegisters如果传slaveId 0会直接超时因为读操作不支持广播。我当初调一个设备手册上写“从站地址 0”我以为是设备地址结果读了一下午都是超时。后来才发现那个 0 是广播地址实际设备地址是 1。从那以后我每次拿到新设备都先用调试助手发地址 1 的读请求确认有回复再写代码。希望帮到你。本文还有配套的精品资源点击获取