Smart.Modbus 2.0.0

Smart.Modbus

English | 中文

<a name="english"></a>

English

Smart.Modbus is a comprehensive Modbus protocol encapsulation library for .NET 6, 8, 9, and 10. It provides framing, response validation, parsing, and data buffering for Modbus RTU, Modbus TCP, and Modbus ASCII. It is designed to handle the protocol layer efficiently, separating protocol logic from communication logic.

Note: This library handles Protocol Processing only. It does not include the communication layer (Serial Port, TCP Client/Server). You need to implement the data transmission yourself or use a communication library like Smart.Ports.

Features

• Protocol Support: Full support for Modbus RTU, Modbus TCP, and Modbus ASCII.
• Master & Slave: Separate implementations for Master (IModbusMaster) and Slave (IModbusSlave) logic.
• Function Codes: Supports standard function codes:
  • 0x01 Read Coils
  • 0x02 Read Discrete Inputs
  • 0x03 Read Holding Registers
  • 0x04 Read Input Registers
  • 0x05 Write Single Coil
  • 0x06 Write Single Register
  • 0x08 Diagnostics
  • 0x0F Write Multiple Coils
  • 0x10 Write Multiple Registers
• Data Parsing: Built-in methods to parse response data into usable types (bools, ushorts, etc.).
• Validation: Automatic CRC16 (RTU) / LRC (ASCII) and frame validation.
• Data Buffering: Smart data buffering mechanism to handle packet fragmentation and sticking (sticky packets).

Installation

Install the package via NuGet:

dotnet add package Smart.Modbus

Usage Examples

1. Creating a Master

Use ModbusFactory to create a master instance for your desired protocol.

using Smart.Modbus;

// Create a Modbus RTU Master
IModbusMaster rtuMaster = ModbusFactory.CreateMaster(ModbusType.ModbusRTU);

// Create a Modbus TCP Master
IModbusMaster tcpMaster = ModbusFactory.CreateMaster(ModbusType.ModbusTCP);

2. Building Requests

Generate the byte array for a Modbus request.

// Build a request to read 10 Holding Registers starting at address 0 from Slave ID 1
byte[] requestFrame = rtuMaster.BuildReadHoldingRegistersRequest(slaveId: 1, startAddress: 0, quantity: 10);

// Send 'requestFrame' via your communication channel (SerialPort, TcpClient, etc.)
// stream.Write(requestFrame, 0, requestFrame.Length);

3. Processing Responses

Handle incoming data, validate it, and parse the results.

// Assume 'receivedData' is the byte array read from your communication channel
List<byte[]> validFrames = rtuMaster.FetchData(receivedData);

foreach (var frame in validFrames)
{
    // Validate the frame (CRC, structure, etc.)
    var validation = rtuMaster.ValidateResponse(frame);
    if (validation.Valid)
    {
        // Parse the data (e.g., if it was a Read Holding Registers response)
        ushort[] registers = rtuMaster.ParseRegistersResponse(frame);
        Console.WriteLine($"Register 0 Value: {registers[0]}");
    }
    else
    {
        Console.WriteLine($"Validation failed: {validation.Fail}");
    }
}

4. Creating a Slave

Use ModbusFactory to create a slave instance to handle incoming requests.

IModbusSlave rtuSlave = ModbusFactory.CreateSlave(ModbusType.ModbusRTU);

// Process incoming request data
List<byte[]> requests = rtuSlave.FetchData(receivedBytes);

foreach (var req in requests)
{
    var validation = rtuSlave.ValidateRequest(req);
    if (validation.Valid)
    {
        // Parse the request to determine action
        var (startAddress, quantity) = rtuSlave.ParseReadRequest(req);
        
        // Prepare response data (simulate reading data)
        ushort[] data = new ushort[quantity]; 
        // ... fill data ...

        // Build response frame
        byte[] response = rtuSlave.BuildReadHoldingRegistersResponse(slaveId: 1, data);
        
        // Send 'response' back to master
    }
}

<a name="chinese"></a>

中文

Smart.Modbus 是一个适用于 .NET 6、8、9 和 10 的 Modbus 协议封装库。它提供了 Modbus RTU、Modbus TCP 和 Modbus ASCII 的组帧、响应校验、解析以及数据缓冲功能。该库的设计理念是将协议逻辑与通信逻辑分离，专注于高效的协议处理。

注意：本库仅处理 协议层 逻辑。它不包含通信层（串口、TCP 客户端/服务端）的实现。你需要自行实现数据传输，或配合 Smart.Ports 等通信库使用。

功能特性

• 多协议支持: 全面支持 Modbus RTU、Modbus TCP 和 Modbus ASCII。
• 主从站支持: 分别为主站 (IModbusMaster) 和从站 (IModbusSlave) 提供了独立的逻辑实现。
• 功能码: 支持标准功能码：
  • 0x01 读取线圈
  • 0x02 读取离散输入
  • 0x03 读取保持寄存器
  • 0x04 读取输入寄存器
  • 0x05 写单个线圈
  • 0x06 写单个寄存器
  • 0x08 诊断
  • 0x0F 写多个线圈
  • 0x10 写多个寄存器
• 数据解析: 内置方法将响应数据解析为可用类型（bool, ushort 等）。
• 自动校验: 自动进行 CRC16 (RTU) / LRC (ASCII) 及帧结构校验。
• 数据缓冲: 智能的数据缓冲机制，有效处理分包和粘包问题。

安装

通过 NuGet 安装：

dotnet add package Smart.Modbus

使用示例

1. 创建主站 (Master)

使用 ModbusFactory 创建所需协议的主站实例。

using Smart.Modbus;

// 创建 Modbus RTU 主站
IModbusMaster rtuMaster = ModbusFactory.CreateMaster(ModbusType.ModbusRTU);

// 创建 Modbus TCP 主站
IModbusMaster tcpMaster = ModbusFactory.CreateMaster(ModbusType.ModbusTCP);

2. 构建请求

生成 Modbus 请求帧的字节数组。

// 构建请求：从站号 1，起始地址 0，读取 10 个保持寄存器
byte[] requestFrame = rtuMaster.BuildReadHoldingRegistersRequest(slaveId: 1, startAddress: 0, quantity: 10);

// 通过你的通信通道发送 'requestFrame' (如 SerialPort, TcpClient 等)
// stream.Write(requestFrame, 0, requestFrame.Length);

3. 处理响应

处理接收到的数据，进行校验和解析。

// 假设 'receivedData' 是从通信通道读取到的字节数组
List<byte[]> validFrames = rtuMaster.FetchData(receivedData);

foreach (var frame in validFrames)
{
    // 校验帧 (CRC, 结构等)
    var validation = rtuMaster.ValidateResponse(frame);
    if (validation.Valid)
    {
        // 解析数据 (例如：如果是读取保持寄存器的响应)
        ushort[] registers = rtuMaster.ParseRegistersResponse(frame);
        Console.WriteLine($"寄存器 0 的值: {registers[0]}");
    }
    else
    {
        Console.WriteLine($"校验失败: {validation.Fail}");
    }
}

4. 创建从站 (Slave)

使用 ModbusFactory 创建从站实例以处理传入的请求。

IModbusSlave rtuSlave = ModbusFactory.CreateSlave(ModbusType.ModbusRTU);

// 处理传入的请求数据
List<byte[]> requests = rtuSlave.FetchData(receivedBytes);

foreach (var req in requests)
{
    var validation = rtuSlave.ValidateRequest(req);
    if (validation.Valid)
    {
        // 解析请求以确定操作
        var (startAddress, quantity) = rtuSlave.ParseReadRequest(req);
        
        // 准备响应数据 (模拟读取数据)
        ushort[] data = new ushort[quantity]; 
        // ... 填充数据 ...

        // 构建响应帧
        byte[] response = rtuSlave.BuildReadHoldingRegistersResponse(slaveId: 1, data);
        
        // 将 'response' 发回给主站
    }
}

Developed by zenglei