Zluo.ModbusMaster
0.1.0
dotnet add package Zluo.ModbusMaster --version 0.1.0
NuGet\Install-Package Zluo.ModbusMaster -Version 0.1.0
<PackageReference Include="Zluo.ModbusMaster" Version="0.1.0" />
<PackageVersion Include="Zluo.ModbusMaster" Version="0.1.0" />
<PackageReference Include="Zluo.ModbusMaster" />
paket add Zluo.ModbusMaster --version 0.1.0
#r "nuget: Zluo.ModbusMaster, 0.1.0"
#:package Zluo.ModbusMaster@0.1.0
#addin nuget:?package=Zluo.ModbusMaster&version=0.1.0
#tool nuget:?package=Zluo.ModbusMaster&version=0.1.0
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, orDCBAbyte 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:
- Chinese performance dashboard: http://127.0.0.1:5080/
- English performance dashboard: http://127.0.0.1:5080/?lang=en
- Chinese Device Studio: http://127.0.0.1:5080/devices.html
- English Device Studio: http://127.0.0.1:5080/devices.html?lang=en
Device Studio provides:
- Modbus TCP device cards with live connection state.
- Manual FC01/FC02/FC03/FC04 point configuration.
.xlsxpoint-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 | Versions 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. |
-
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.