CSoft.Protocol.Modbus 10.100.0

Modbus 协议库

一个简洁易用的 Modbus 通信库：主站 + 从站，Attribute 驱动的泛型数据映射、完整功能码支持、类型化异常。

• 主站 + 从站：ModBusMaster 发起读写，ModBusSlave 应答请求，同一套 [CHProtocol] 模型
• 报文格式与物理传输解耦：RTU / TCP 报文可跑在串口、TCP、命名管道任一传输上
• 泛型映射：[CHProtocol] 标注模型属性，一行代码读写整个数据块
• 功能码齐全：FC01 / 02 / 03 / 04 / 05 / 06 / 15 / 16
• 快速分帧：按帧长驱动解析，帧完整即处理，无静默等待；噪声与残留自动恢复
• 现场友好：四种字序（ABCD / DCBA / BADC / CDAB）、字符串编码可配
• 现代 API：类型化异常、CancellationToken、自动拆包与合并

安装

dotnet add package CSoft.Protocol.Modbus

快速开始

1. 定义数据模型

public class SensorData
{
    [CHProtocol(1)]              // 寄存器地址 1（float 占 1、2 两个寄存器）
    public float Temperature { get; set; }

    [CHProtocol(3)]
    public ushort Humidity { get; set; }

    [CHProtocol(5)]
    public float Pressure { get; set; }

    [CHProtocol(7, count: 4)]    // string 必须声明寄存器个数（4 寄存器 = 8 字节）
    public string DeviceName { get; set; } = string.Empty;

    [CHProtocol(11)]             // bool 映射为单寄存器 0 / 1
    public bool Running { get; set; }
}

2. 建立连接

Builder 方式（推荐）：

// 串口 + RTU（默认）
var master = ModBusMaster.UseSerial("COM2", baudRate: 9600).Build();
await master.OpenAsync();

// 网络 + TCP 报文格式
var master = ModBusMaster.UseTcp("192.168.1.100", 502)
    .Protocol(ModbusType.TCP)
    .Timeout(3000)               // 可选：请求超时（毫秒）
    .Build();

构造函数方式：

using Communication.Bus.PhysicalPort;

var master = new ModBusMaster(new TcpClient("192.168.1.100", 502), ModbusType.TCP);
await master.OpenAsync();

ModbusType 指的是报文格式，与物理链路无关：串口上可以跑 TCP 报文，网络上也可以跑 RTU 报文，按设备实际协议选择即可。

3. 读写数据

byte address = 0x01;

// 读：自动按地址合并相邻寄存器，通常一次请求拿回全部字段
var data = await master.GetAsync<SensorData>(address);
Console.WriteLine($"{data.Temperature}, {data.Humidity}, {data.DeviceName}");

// 写：连续地址的字段自动合并为一帧
await master.SetAsync(address, new SensorData
{
    Temperature = 25.5f,
    Humidity = 60,
    DeviceName = "PUMP-A",
    Running = true
});

地址支持字符串形式："1"、"01"、"0x01" 均可。

功能码 API

除泛型模型外，也提供寄存器 / 线圈的原始读写：

var regs = await master.ReadHoldingRegistersAsync(0x01, start: 100, count: 10);
var coils = await master.ReadCoilsAsync(0x01, start: 0, count: 16);

await master.WriteRegisterAsync(0x01, register: 0x0064, value: 123);
await master.WriteCoilsAsync(0x01, start: 0, values: [true, false, true]);

超出单帧上限（读 125 / 写 123 个寄存器，读 2000 / 写 1968 个线圈）时自动拆分成多帧。

支持的数据类型

字节序

多寄存器数值（float / int32 / double）的字节排列按设备现场情况选择，默认 ABCD（Modbus 标准大端）：

master.ReqWordOrder = WordOrder.CDAB;   // 请求方向：交换 16 位字（常见于国产仪表的 float）
master.RspWordOrder = WordOrder.CDAB;   // 响应方向

单个属性也可用 [CHProtocol] 通道级覆盖（Channel.IsHighByteBefore）。

字符串编码

master.StringEncoding = Encoding.GetEncoding("GB2312");   // 默认 ASCII

写入时不足 count * 2 字节自动补 0x00；读取时自动截断尾部 \0。

异常处理

所有通信错误抛出 Modbus.Exceptions 下的类型化异常：

using Modbus.Exceptions;

try
{
    var data = await master.GetAsync<SensorData>(0x01);
}
catch (ModbusSlaveException ex)      // 从站返回异常响应
{
    Console.WriteLine($"异常码 {ex.ExceptionCode}，地址 0x{ex.DeviceAddress:X2}");
    // ex.ExceptionCode: IllegalFunction / IllegalDataAddress / IllegalDataValue ...
}
catch (ModbusCrcException)           // RTU CRC 校验失败
{
}
catch (ModbusFrameException)         // 帧结构非法：事务 ID / 地址 / 功能码 / 字节数不符
{
}
catch (ModbusTimeoutException)       // 超时未收到有效响应
{
}

通信语义与健壮性

解析按帧长驱动：RTU 由功能码 + 字节数域推导帧长，TCP 由 MBAP 长度域确定，帧一完整即处理，不存在静默等待；帧长无法推导时按 CRC 校验滑窗判定。每帧进入数据映射前经过完整校验链：

CRC / MBAP → 从站地址 → 功能码 → 字节数 / 写回显 → 通道边界

任何一环不符都抛类型化异常——错误停在异常层，脏数据永远进不了模型。

常见异常现场的恢复行为：

设计原则：任何单次异常只影响当次请求，不污染后续通信。

从机（ModBusSlave）

ModBusSlave 维护四个数据区（保持寄存器 / 输入寄存器 / 线圈 / 离散量输入）， 应答主站的 FC01/02/03/04/05/06/15/16 请求，越界 / 非法值 / 未知功能码自动回异常响应， 支持 RTU 地址过滤与广播（地址 0 只执行写、不响应）。

建立从站

// 点对点（串口等）
var slave = new ModBusSlave(new SerialPort("COM3"), new ModBusSlaveOptions
{
    Address = 0x01,
    HoldingRegisterCount = 100,
    CoilCount = 64
});
await slave.StartAsync();

// TCP 服务端（多客户端，响应自动发回请求来源客户端）
var server = Comm.TopServer()
    .UseTcpServer("0.0.0.0", 502)
    .WithParserFactory(ModBusSlave.CreateParser)
    .Build();
var tcpSlave = new ModBusSlave(server, new ModBusSlaveOptions { Address = 0x01, ModbusType = ModbusType.TCP });
await tcpSlave.StartAsync();

数据区与事件

slave.HoldingRegisters[0] = 0x1234;     // 直接读写元素
slave.Coils[5] = true;

slave.WriteReceived += e =>             // 主站写入（含广播）后的回调
{
    Console.WriteLine($"主站写入 FC{e.FunctionCode:X2} 起始 {e.StartAddress}");
};

模型绑定

与主站共用同一个 [CHProtocol] 模型：绑定后主站读到的就是模型的值，主站写入自动同步回模型：

var model = new SensorData { Temperature = 25.5f, DeviceName = "PUMP-A" };
slave.BindModel(model);      // 模型 → 保持寄存器

model.Temperature = 30f;
slave.SyncModelToRegisters(); // 设备逻辑改模型后发布，主站即可读到

无传输核心

HandleRequest 与传输无关，一帧进一帧出（null 表示不响应），可直接用于测试或自定义传输：

var slave = new ModBusSlave(new ModBusSlaveOptions { Address = 0x01 });
byte[]? response = slave.HandleRequest(masterRequestFrame);

高级用法

手动构建 BlockList

var blockList = BlockList.From<SensorData>();
blockList.MaxMergeGap = 2;                  // 允许 2 个寄存器的缺口合并，减少往返
var channels = await master.GetAsync(0x01, blockList);

master.MaxMergeGap 对泛型读取同样生效（默认 0，仅合并完全连续的块）。

取消令牌

所有读写方法均接受 CancellationToken：

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(2));
var data = await master.GetAsync<SensorData>(0x01, cts.Token);

事件与状态

ModBusMaster 实现 IProtocol，具备 OpenAsync / CloseAsync / IsConnect 以及 OnConnect / OnDisconnect / OnSentData / OnReceivedData 事件。

配置项