Zluo.ModbusMaster 0.1.0

dotnet add package Zluo.ModbusMaster --version 0.1.0
                    
NuGet\Install-Package Zluo.ModbusMaster -Version 0.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Zluo.ModbusMaster" Version="0.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Zluo.ModbusMaster" Version="0.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Zluo.ModbusMaster" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Zluo.ModbusMaster --version 0.1.0
                    
#r "nuget: Zluo.ModbusMaster, 0.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Zluo.ModbusMaster@0.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Zluo.ModbusMaster&version=0.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Zluo.ModbusMaster&version=0.1.0
                    
Install as a Cake Tool

Async Modbus Master for .NET 10

简体中文 | English

A high-performance Modbus Master library implemented entirely in C# and .NET 10. It connects to Modbus TCP or Modbus Security (TLS) servers/slaves and is designed for thousands of long-lived device connections.

The SDK is fully asynchronous from the public API down to socket I/O. It does not dedicate a thread to each connection. Every device owns a bounded Channel and a single asynchronous consumer, so callers may submit work concurrently while the SDK guarantees that requests for the same physical connection are sent strictly in order: the next request is not transmitted until the current response has been fully received and validated.

Highlights

  • Pure C# / .NET 10 with no third-party runtime dependencies in the core library.
  • Fully asynchronous networking using Socket, NetworkStream, SslStream, async/await, and cancellation tokens.
  • Per-device ordered queue implemented with a bounded Channel; exactly one Modbus transaction is in flight on each connection.
  • High connection density verified with 2,001 simultaneous TCP connections without one thread per connection.
  • Modbus TCP and Modbus Security with optional TLS 1.2/1.3 and mutual certificate authentication.
  • Strict MBAP validation for transaction ID, protocol ID, length, unit ID, and function code.
  • Automatic reconnect and fault isolation after timeout, broken transport, or protocol corruption.
  • Typed register reads for homogeneous and heterogeneous .NET data types.
  • Configurable data layout: zero- or one-based addresses and ABCD, CDAB, BADC, BACD, or DCBA byte order.
  • All standard point-read functions: FC01, FC02, FC03, and FC04.
  • Write functions: FC05, FC06, and FC16 (0x10).
  • ASP.NET Core operations UI with a bilingual Chinese/English dashboard, device cards, live values, Excel point import, connect/disconnect controls, and optimized polling plans.

Why the queue matters

Many Modbus devices cannot safely handle pipelined requests. If request B is sent before the response to request A arrives, the device may ignore B, close the connection, or return a response whose transaction ID no longer matches the expected request.

ModbusDeviceClient solves this inside the SDK:

flowchart LR
    A[Concurrent application tasks] --> Q[Bounded Channel per device]
    Q --> W[Single async consumer]
    W --> S[Send one request]
    S --> R[Await and validate response]
    R --> W

Waiting for network I/O does not occupy a worker thread. Different devices run concurrently, while requests sharing one physical connection remain strictly serialized.

Supported functions

Function Operation Core API
FC01 Read Coils ReadCoilsAsync
FC02 Read Discrete Inputs ReadDiscreteInputsAsync
FC03 Read Holding Registers ReadHoldingRegistersAsync
FC04 Read Input Registers ReadInputRegistersAsync
FC05 Write Single Coil WriteSingleCoilAsync
FC06 Write Single Register WriteSingleRegisterAsync
FC16 / 0x10 Write Multiple Registers WriteMultipleRegistersAsync

Other function codes can be sent as raw PDUs through ExecuteAsync.

Quick start

Requirements:

  • .NET SDK 10.0.300 or newer compatible patch
  • Windows or Linux

Install from NuGet:

dotnet add package Zluo.ModbusMaster --version 0.1.0
dotnet build ModbusMaster.slnx -c Release

Create one client per physical Modbus TCP connection:

using ModbusMaster;

await using var client = new ModbusDeviceClient(new ModbusDeviceOptions
{
    DeviceId = "plc-001",
    Host = "10.0.0.20",
    Port = 502,
    UnitId = 1,
    QueueCapacity = 256,
    ConnectTimeout = TimeSpan.FromSeconds(5),
    RequestTimeout = TimeSpan.FromSeconds(3),
    MaxConnectAttempts = 3,
    Tls = new ModbusTlsOptions { Enabled = false }
});

// Multiple application tasks may call this client concurrently.
// The SDK queues and serializes requests on plc-001 automatically.
ushort[] registers = await client.ReadHoldingRegistersAsync(
    startAddress: 0,
    quantity: 10,
    cancellationToken);

ConnectAsync opens the TCP/TLS transport without sending a dummy Modbus request:

await client.ConnectAsync(cancellationToken);
Console.WriteLine(client.IsConnected);

Typed register reads

One .NET type for every value

var layout = new ModbusDataLayout
{
    AddressBase = ModbusAddressBase.One,
    ByteOrder = ModbusByteOrder.CDAB
};

float[] temperatures = await client.ReadHoldingRegistersAsync<float>(
    startAddress: 1,
    valueCount: 10,
    layout,
    cancellationToken);

A type schema for heterogeneous values

Type[] schema =
[
    typeof(ushort),
    typeof(float),
    typeof(int),
    typeof(double)
];

object[] values = await client.ReadHoldingRegistersAsync(
    startAddress: 1,
    schema,
    new ModbusDataLayout
    {
        AddressBase = ModbusAddressBase.One,
        ByteOrder = ModbusByteOrder.ABCD
    },
    cancellationToken);

ModbusRegisterCodec can also decode an existing register buffer without performing network I/O.

Supported CLR types are bool, byte, sbyte, char, short, ushort, Half, int, uint, float, long, ulong, double, and enums backed by supported integer types. BACD is an explicit four-byte permutation and is therefore restricted to 32-bit values.

TLS / Modbus Security

TLS is opt-in. Plain Modbus TCP defaults to port 502; Modbus Security defaults to port 802.

var certificates = new X509CertificateCollection
{
    X509CertificateLoader.LoadPkcs12FromFile(
        "client.pfx",
        Environment.GetEnvironmentVariable("MODBUS_CLIENT_PFX_PASSWORD"))
};

var options = new ModbusDeviceOptions
{
    DeviceId = "secure-plc",
    Host = "plc.example.com",
    UnitId = 1,
    Tls = new ModbusTlsOptions
    {
        Enabled = true,
        TargetHost = "plc.example.com",
        ClientCertificates = certificates,
        EnabledProtocols = SslProtocols.Tls12 | SslProtocols.Tls13
    }
};

Do not store certificate passwords in source control. Use environment variables or a production secret manager.

Multiple devices

ModbusClientPool manages clients by DeviceId:

await using var pool = new ModbusClientPool();

var line1 = pool.Add(line1Options);
var line2 = pool.Add(line2Options);

await Task.WhenAll(
    line1.ReadHoldingRegistersAsync(0, 10).AsTask(),
    line2.ReadHoldingRegistersAsync(0, 10).AsTask());

Model clients by physical TCP connection, not only by Unit ID. If multiple Unit IDs share one gateway socket, they must also share one ordered request queue.

ASP.NET Core dashboard and Device Studio

Start the web application:

dotnet run --project src/ModbusMaster.Benchmark -c Release

Pages:

Device Studio provides:

  • Modbus TCP device cards with live connection state.
  • Manual FC01/FC02/FC03/FC04 point configuration.
  • .xlsx point-list import.
  • Live point values through Server-Sent Events.
  • Explicit connect and disconnect controls.
  • Persistent device and point definitions.
  • Friendly localized Problem Details errors.

The Excel header must contain Name, Function, Address, and DataType. Optional columns are ByteOrder and Unit. FC01/FC02 points must use Boolean.

Optimized polling

Device Studio does not issue one request per point. It groups points by function and covers the configured address range with the smallest practical number of requests:

  • FC01/FC02: up to 2,000 bits per request.
  • FC03/FC04: up to 125 registers per request.
  • The final point's CLR type determines how many registers the batch must include.

For example, addresses 0, 5, and 30 where address 30 is a 32-bit value become one FC03 request starting at 0 with a quantity of 32 registers.

Verification

Run the integration verification suite:

dotnet run --project tests/ModbusMaster.Verification -c Release -- --connections 2001

It verifies:

  • Connect-only TCP handshake without a dummy Modbus request.
  • FC01/FC02/FC03/FC04 reads.
  • Strict single-device request serialization.
  • Typed values, address bases, and byte permutations.
  • TLS 1.2+ mutual certificate authentication.
  • 2,001 simultaneous TCP connections.

The included ASP.NET Core load generator defaults to 2,000 logical slaves/connections, 1,000 points per connection, and a live dashboard for CPU, memory, application-level network traffic, aggregate throughput, and per-device throughput.

Windows and Linux port behavior

The optional ReuseUnicastPort setting applies Windows SO_REUSE_UNICASTPORT before connecting. On Linux, a normal connect() already defers automatic ephemeral-port assignment. Applications that explicitly bind a source address with port zero can use the Linux-specific IP_BIND_ADDRESS_NO_PORT; it is not the same as SO_REUSEPORT.

Port reuse never permits duplicate TCP four-tuples. Connections to the same destination IP and port still require unique local endpoints.

Project layout

src/ModbusMaster                 Core reusable SDK
src/ModbusMaster.App             JSON-configured console example
src/ModbusMaster.Benchmark       ASP.NET Core dashboard, simulator, Device Studio
tests/ModbusMaster.Verification  Protocol, TLS, serialization, and scale verification

The implementation follows the Modbus Application Protocol Specification V1.1b3, Modbus Messaging on TCP/IP Implementation Guide V1.0b, and Modbus Security Protocol V3.6.

License

This project is licensed under the MIT License.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.0 154 8/14/2026

Initial public release with fully asynchronous per-device request queues, TCP/TLS support, typed reads, and verified 2,001-connection scalability.