# SuperModbusMaster

**Repository Path**: RegoAn/super-modbus-master

## Basic Information

- **Project Name**: SuperModbusMaster
- **Description**: Modbus主站通讯组件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SuperModbusMaster

面向工业现场的 .NET 8 Modbus TCP 客户端通讯库，高可靠、长时间稳定运行、尽量减少通讯次数。

## 设计目标与能力

1. 从站上下线状态事件：`SlaveStatusChanged`（断线 / 上线）
2. 自动断线重连 + 手动重连：`ReconnectAsync`
3. 通讯参数运行中更新后重连：`UpdateConnectionOptionsAsync`
4. 端序仅在实例化时配置：`ABCD / BADC / CDAB / DCBA`
5. 单一变量注册入口：`RegisterVariable(ModbusArea, address, type, bitIndex?, tag?)`
6. 支持寄存器按位变量（如 `4x0120.14` -> `HoldingRegister + 地址 + bitIndex`）
7. 每个变量独立值变化事件：`ModbusVariable.ValueChanged`（仅返回实际值）
8. 地址可乱序注册，内部动态规划自动分块，尽量减少轮询请求次数
9. 读写长度按实际变量类型精确计算，不使用固定长度粗读粗写
10. 支持通过变量属性或标签读写：`variable.Value` / `client["Tag"]`
11. 断线或异常期间仍可本地读写：写入先进入缓存队列，通讯恢复后自动下发并刷新

## 快速示例

```csharp
using SuperModbusClient.Modbus;

var options = new ModbusConnectionOptions
{
    Host = "127.0.0.1",
    Port = 502,
    UnitId = 1,
    PollInterval = TimeSpan.FromMilliseconds(200),
    ReconnectInterval = TimeSpan.FromSeconds(2)
};

await using var client = new ModbusTcpClient(options, ModbusEndianMode.ABCD);

client.SlaveStatusChanged += (_, e) =>
{
    Console.WriteLine($"[{e.Timestamp:HH:mm:ss}] {e.PreviousStatus} -> {e.CurrentStatus} | {e.Reason}");
};

var b2 = client.RegisterVariable(ModbusArea.HoldingRegister, 0, ModbusVariableType.Bool, bitIndex: 1, tag: "B2");
var num1 = client.RegisterVariable(ModbusArea.HoldingRegister, 0, ModbusVariableType.Int16, tag: "Num1");
var pressure = client.RegisterVariable(ModbusArea.HoldingRegister, 2, ModbusVariableType.Float, tag: "Pressure");

b2.ValueChanged += value => Console.WriteLine($"B2 变化 -> {value}");
num1.ValueChanged += value => Console.WriteLine($"Num1 变化 -> {value}");
client.GetVariable("Pressure").ValueChanged += value => Console.WriteLine($"Pressure 变化 -> {value}");

await client.StartAsync();

// 属性写入
b2.Value = true;

// 标签写入
client["Num1"] = (short)1234;

// 标签读取（返回最近一次轮询值，或离线时本地缓存值）
var currentPressure = client["Pressure"];
```

## 核心文件

- `Modbus/ModbusTcpClient.cs`：通讯核心（连接、重连、轮询、写入、事件）
- `Modbus/ModbusConnectionOptions.cs`：连接参数及边界校验
- `Modbus/ModbusVariableDefinition.cs`：变量定义与类型规则
- `Modbus/ModbusValueCodec.cs`：数据编解码与端序处理
- `Modbus/ModbusVariable.cs`：变量对象（标签、属性读写、单变量变化事件）

## 说明

- 变量写入统一通过 `variable.Value = ...` 或 `client["Tag"] = ...`。
- 断线/异常期间本地可读写，恢复后自动补写到从站
- Int16/Int32/寄存器位写入长度与指令精确性
- 地址乱序注册后的自动分块与通讯效率优化
- 重连抖动场景下连续读写稳定性（恢复后自动追平最后值）