Modbus TCP is a widely adopted industrial communication protocol that operates over standard Ethernet networks. Unlike its serial counterpart (Modbus RTU), it leverages TCP/IP for transport, eliminating the need for checksums while introducing new considerations around connection management, byte ordering, and message framing.

Core Architecture Principles

The client design prioritizes correctness, maintainability, and interoperability. It avoids assumptions about device behavior—such as transaction ID enforcement or unit identifier usage—while remaining lightweight and dependency-free. Key architectural decisions include:

• Stateless request handling: Each operation generates a unique transaction ID, ensuring response correlation without requiring internal request tracking.
• Strict MBAP header validation: Verifies transaction ID, protocol ID (0x0000), and unit ID to detect misrouted or malformed responses.
• Endianness-agnostic data conversion: All numeric values are explicitly serialized and deserialized in big-endian format per the Modbus specification, independent of host architecture.
• Stream-level I/O control: Implements robust full-read semantics to handle TCP packet fragmentation and avoid partial reads.

Implementation Highlights

The following example demonstrates a production-ready ModbusTcpClient class with essential functionality:

using System;
using System.IO;
using System.Net.Sockets;
using System.Threading.Tasks;

public sealed class ModbusTcpClient : IDisposable
{
    private TcpClient? _client;
    private NetworkStream? _stream;
    private ushort _nextTransactionId = 1;

    public async Task ConnectAsync(string host, int port = 502, TimeSpan timeout = default)
    {
        _client = new TcpClient();
        if (timeout != default) _client.SendTimeout = _client.ReceiveTimeout = (int)timeout.TotalMilliseconds;

        await _client.ConnectAsync(host, port);
        _stream = _client.GetStream();
    }

    public void Dispose()
    {
        _stream?.Dispose();
        _client?.Dispose();
    }

    public async Task<ushort[]> ReadHoldingRegistersAsync(
        byte unitId,
        ushort startAddress,
        ushort count,
        CancellationToken cancellationToken = default)
    {
        var pdu = BuildReadHoldingRegistersPdu(startAddress, count);
        var response = await SendAndReceiveAsync(unitId, pdu, cancellationToken);
        
        return ParseRegisterResponse(response, 2); // 2 bytes per register
    }

    public async Task WriteMultipleRegistersAsync(
        byte unitId,
        ushort startAddress,
        ReadOnlySpan<ushort> values,
        CancellationToken cancellationToken = default)
    {
        var pdu = BuildWriteMultipleRegistersPdu(startAddress, values);
        await SendAndReceiveAsync(unitId, pdu, cancellationToken);
    }

    private byte[] BuildReadHoldingRegistersPdu(ushort address, ushort count)
    {
        var buffer = new byte[5];
        buffer[0] = 0x03;
        BitConverter.TryWriteBytes(buffer.AsSpan(1), IPAddress.HostToNetworkOrder(address));
        BitConverter.TryWriteBytes(buffer.AsSpan(3), IPAddress.HostToNetworkOrder(count));
        return buffer;
    }

    private byte[] BuildWriteMultipleRegistersPdu(ushort address, ReadOnlySpan<ushort> values)
    {
        var byteCount = (byte)(values.Length * 2);
        var buffer = new byte[6 + byteCount];
        buffer[0] = 0x10;
        BitConverter.TryWriteBytes(buffer.AsSpan(1), IPAddress.HostToNetworkOrder(address));
        BitConverter.TryWriteBytes(buffer.AsSpan(3), IPAddress.HostToNetworkOrder((ushort)values.Length));
        buffer[5] = byteCount;

        for (int i = 0; i < values.Length; i++)
        {
            BitConverter.TryWriteBytes(buffer.AsSpan(6 + i * 2), IPAddress.HostToNetworkOrder(values[i]));
        }
        return buffer;
    }

    private async Task<byte[]> SendAndReceiveAsync(
        byte unitId,
        byte[] pdu,
        CancellationToken cancellationToken)
    {
        var transactionId = Interlocked.Increment(ref _nextTransactionId);
        var mbapHeader = BuildMbapHeader(transactionId, unitId, pdu.Length);

        var request = new byte[mbapHeader.Length + pdu.Length];
        Buffer.BlockCopy(mbapHeader, 0, request, 0, mbapHeader.Length);
        Buffer.BlockCopy(pdu, 0, request, mbapHeader.Length, pdu.Length);

        await _stream!.WriteAsync(request, cancellationToken);
        return await ReceiveResponseAsync(transactionId, unitId, cancellationToken);
    }

    private byte[] BuildMbapHeader(ushort transactionId, byte unitId, int pduLength)
    {
        var header = new byte[7];
        BitConverter.TryWriteBytes(header.AsSpan(0), IPAddress.HostToNetworkOrder(transactionId));
        BitConverter.TryWriteBytes(header.AsSpan(2), (ushort)0); // Protocol ID
        BitConverter.TryWriteBytes(header.AsSpan(4), IPAddress.HostToNetworkOrder((ushort)(pduLength + 1)));
        header[6] = unitId;
        return header;
    }

    private async Task<byte[]> ReceiveResponseAsync(
        ushort expectedTransactionId,
        byte expectedUnitId,
        CancellationToken cancellationToken)
    {
        var header = new byte[7];
        await ReadExactlyAsync(_stream!, header, cancellationToken);

        // Validate MBAP header
        if (BitConverter.ToUInt16(header, 0) != expectedTransactionId)
            throw new InvalidOperationException("Transaction ID mismatch");
        if (BitConverter.ToUInt16(header, 2) != 0)
            throw new InvalidOperationException("Invalid protocol identifier");
        if (header[6] != expectedUnitId)
            throw new InvalidOperationException("Unit ID mismatch");

        var pduLength = (int)(BitConverter.ToUInt16(header, 4) - 1);
        var pdu = new byte[pduLength];
        await ReadExactlyAsync(_stream!, pdu, cancellationToken);

        if ((pdu[0] & 0x80) != 0)
            throw new ModbusApplicationException(pdu[1]);

        return pdu;
    }

    private async Task ReadExactlyAsync(Stream stream, byte[] buffer, CancellationToken cancellationToken)
    {
        int offset = 0;
        int remaining = buffer.Length;

        while (remaining > 0)
        {
            int read = await stream.ReadAsync(buffer, offset, remaining, cancellationToken);
            if (read == 0) throw new IOException("Connection closed prematurely");
            offset += read;
            remaining -= read;
        }
    }

    private ushort[] ParseRegisterResponse(byte[] pdu, int bytesPerValue)
    {
        var valueCount = pdu[1] / (byte)bytesPerValue;
        var result = new ushort[valueCount];

        for (int i = 0; i < valueCount; i++)
        {
            int srcOffset = 2 + i * bytesPerValue;
            result[i] = (ushort)IPAddress.NetworkToHostOrder(BitConverter.ToInt16(pdu, srcOffset));
        }
        return result;
    }
}

public sealed class ModbusApplicationException : Exception
{
    public byte ErrorCode { get; }

    public ModbusApplicationException(byte code) : base(GetMessage(code)) => ErrorCode = code;

    private static string GetMessage(byte code) => code switch
    {
        1 => "Illegal function",
        2 => "Illegal data address",
        3 => "Illegal data value",
        4 => "Server device failure",
        5 => "Acknowledge",
        6 => "Server device busy",
        7 => "Negative acknowledge",
        8 => "Memory parity error",
        10 => "Gateway path unavailable",
        11 => "Gateway target device failed to respond",
        _ => $"Unknown exception code: 0x{code:X2}"
    };
}

Usage Examples

Reading analog inputs:

var client = new ModbusTcpClient();
await client.ConnectAsync("192.168.1.10", 502);

// Read two 16-bit registers starting at address 40001
var rawValues = await client.ReadHoldingRegistersAsync(unitId: 1, startAddress: 0, count: 2);

// Convert to IEEE 754 float (big-endian register order)
float temperature = BitConverter.ToSingle(
    BitConverter.GetBytes(IPAddress.HostToNetworkOrder((int)(rawValues[0] << 16 | rawValues[1]))),
    0
);

Writing configuration parameters:

var config = new ushort[] { 
    0x0001, // Enable flag
    0x03E8, // Timeout in milliseconds (1000)
    0x0000  // Reserved
};
await client.WriteMultipleRegistersAsync(unitId: 1, startAddress: 100, config);

Production Considerations

• Timeout Configuration: Always set TcpClient.SendTimeout and ReceiveTimeout to prevent indefinite blocking on unstable networks.
• Connection Resilience: Implement exponential backoff reconnect logic outside the client for transient failures.
• Concurrent Access: The current implementation is not thread-safe for concurrent requests. Wrap shared instances in lock or use per-request instances in high-concurrency scenarios.
• Data Validation: Device-specific register mappings and scaling factors must be applied by the application layer—not embedded in the protocol client.
• Unit Identifier Semantics: While often ignored in direct connections, always pass the correct unit ID when communicating through gateways or multi-device networks.