FluentModbus

The server can provide data to clients by updating its internal registers. There are two primary ways to do this:

1. Standard Form (Span<short>): Provides more flexibility using GetHoldingRegisters(). You can use extension methods like SetLittleEndian<T> to write values.
2. High Performance Form (Buffer Interpretation): Provides less flexibility but higher performance by interpreting the buffer as specific types using GetHoldingRegisterBuffer<T>(). Supported types include byte, short, and int.

Important: When updating registers in a multi-threaded environment, always wrap the update logic in a lock (server.Lock) block to prevent race conditions with client requests.

// Inside a loop or periodic task
lock (server.Lock)
{
    // Option A: Standard flexibility
    var registers = server.GetHoldingRegisters();
    registers.SetLittleEndian<int>(startingAddress: 5, 12345);

    // Option B: High performance buffer access
    var int_buffer = server.GetHoldingRegisterBuffer<int>();
    int_buffer[40] = 100;
}

To implement Modbus RTU communication, you need a ModbusRtuServer and a ModbusRtuClient connected via COM ports.

Key Requirements:

• COM Ports: You must have real or virtual COM ports available. For local testing, you can use a COM port bridge to link two ports (e.g., COM1 for the server and COM2 for the client).
• Unit Identifier: The client must use the same unitIdentifier that was assigned to the server during instantiation (e.g., 0x01).
• Server Events: You can subscribe to the RegistersChanged event on the server to detect when register addresses have been modified.

Server Modes:

• Asynchronous (Default): Client requests are answered immediately. This is easier to implement but can slow down the server under high load.
• Synchronous: Opt-in via new ModbusRtuServer(isAsynchronous: true). In this mode, you must manually call server.Update() to process accumulated client requests.

/* Create Server */
using var server = new ModbusRtuServer(unitIdentifier: 1)
{
    EnableRaisingEvents = true
};

server.RegistersChanged += (sender, registerAddresses) =>
{
    // registerAddresses contains modified register addresses
};

/* Create Client */
var client = new ModbusRtuClient();

The ModbusRtuServer provides two ways to update register data. When updating registers manually in a loop, it is recommended to use server.Lock to synchronize buffer access between your application logic and the Modbus client.

Option A: Standard (Flexible) Use GetHoldingRegisters() to get a Span<short>. This allows for more flexible data manipulation using extension methods like SetLittleEndian<T>.

Option B: High Performance (Direct Buffer Access) Use GetHoldingRegisterBuffer<T>() to interpret the buffer directly as a specific type (byte, short, int, etc.). This is faster but offers less flexibility than the standard method.

// Synchronize access using the server lock
lock (server.Lock)
{
    // Option A: Standard
    var registers = server.GetHoldingRegisters();
    registers.SetLittleEndian<int>(startingAddress: 5, value);

    // Option B: High Performance
    var int_buffer = server.GetHoldingRegisterBuffer<int>();
    int_buffer[40] = value;
}

You can implement custom business logic for validating Modbus requests by assigning a method to the RequestValidator property of a ModbusTcpServer (or an RTU server).

Key behaviors:

• The validator function is called every time a client sends a request.
• It complements rather than replaces default server checks. The server will still perform its own validation for absolute register limits and unknown function codes.
• The validator must return a ModbusExceptionCode. Returning ModbusExceptionCode.OK allows the request to proceed, while other codes will trigger a Modbus exception response to the client.
• The validator receives RequestValidatorArgs, which provides access to the Address, FunctionCode, and other request details.

var server = new ModbusTcpServer()
{
    RequestValidator = this.ModbusValidator
};

private ModbusExceptionCode ModbusValidator(RequestValidatorArgs args)
{
    // Example: check if address is within valid holding register limits
    var holdingLimits = args.Address >= 50 && args.Address < 90 ||
                        args.Address >= 2000 && args.Address < 2100;

    // Example: check if address is within valid input register limits
    var inputLimits = args.Address >= 1000 && args.Address < 2000;

    return (args.FunctionCode, holdingLimits, inputLimits) switch
    {
        // holding registers
        (ModbusFunctionCode.ReadHoldingRegisters, true, _)          => ModbusExceptionCode.OK,
        (ModbusFunctionCode.ReadWriteMultipleRegisters, true, _)    => ModbusExceptionCode.OK,
        (ModbusFunctionCode.WriteMultipleRegisters, true, _)        => ModbusExceptionCode.OK,
        (ModbusFunctionCode.WriteSingleRegister, true, _)           => ModbusExceptionCode.OK,

        (ModbusFunctionCode.ReadHoldingRegisters, false, _)         => ModbusExceptionCode.IllegalDataAddress,
        (ModbusFunctionCode.ReadWriteMultipleRegisters, false, _)   => ModbusExceptionCode.IllegalDataAddress,
        (ModbusFunctionCode.WriteMultipleRegisters, false, _)       => ModbusExceptionCode.IllegalDataAddress,
        (ModbusFunctionCode.WriteSingleRegister, false, _)          => ModbusExceptionCode.IllegalDataAddress,

        // input registers
        (ModbusFunctionCode.ReadInputRegisters, _, true)            => ModbusExceptionCode.OK,
        (ModbusFunctionCode.ReadInputRegisters, _, false)           => ModbusExceptionCode.IllegalDataAddress,

        // deny other function codes
        _                                                           => ModbusExceptionCode.IllegalFunction
    };
}

The ModbusTcpClient provides methods to read and write various Modbus data types.

Data Handling Note: Most methods return data as a Span<T>. While efficient, Span<T> cannot be stored in heap-allocated objects or used across certain async boundaries easily. If you need to persist the data or move it out of the immediate scope, call .ToArray() to copy it into a standard array (e.g., var dataArray = data.ToArray();).

Common operations include:

• ReadHoldingRegisters<T>(unitIdentifier, startingAddress, count)
• WriteMultipleRegisters(unitIdentifier, startingAddress, data)
• ReadCoils(unitIdentifier, startingAddress, count)
• ReadDiscreteInputs<T>(unitIdentifier, startingAddress, count)
• ReadInputRegisters(unitIdentifier, startingAddress, count)
• WriteSingleCoil(unitIdentifier, registerAddress, value)
• WriteSingleRegister(unitIdentifier, registerAddress, value)

client.Connect();

try
{
    // Read Holding Registers (FC03)
    Span<byte> data = client.ReadHoldingRegisters<byte>(0x00, 0, 10);

    // Write Multiple Registers (FC16)
    client.WriteMultipleRegisters(0x00, 0, new byte[] { 10, 0, 20, 0, 30, 0, 255, 0, 255, 1 });

    // Write Single Coil (FC05)
    client.WriteSingleCoil(0x00, 0, true);
}
finally
{
    client.Disconnect();
}

The ModbusRtuClient provides methods to execute standard Modbus function codes.

Important Notes:

• Data Types: Most read methods return data as a Span<T>. If you need to store this data in a standard .NET array or pass it to APIs that don't support Spans, call .ToArray() on the result.
• Unit Identifier: Always pass the correct unitIdentifier (the ID assigned to the server) to every method call.

Supported Operations:

• ReadHoldingRegisters<T>(unitIdentifier, startingAddress, count) (FC03)
• WriteMultipleRegisters(unitIdentifier, startingAddress, data) (FC16)
• ReadCoils(unitIdentifier, startingAddress, count) (FC01)
• ReadDiscreteInputs(unitIdentifier, startingAddress, count) (FC02)
• ReadInputRegisters<T>(unitIdentifier, startingAddress, count) (FC04)
• WriteSingleCoil(unitIdentifier, registerAddress, value) (FC05)
• WriteSingleRegister(unitIdentifier, registerAddress, value) (FC06)

var unitIdentifier = 0x01;
var startingAddress = 0;

// Read Holding Registers
Span<byte> data = client.ReadHoldingRegisters<byte>(unitIdentifier, startingAddress, 10);

// Write Multiple Registers
client.WriteMultipleRegisters(unitIdentifier, startingAddress, new byte[] { 10, 00, 20, 00, 30, 00, 255, 00, 255, 01 });

// Read Coils
Span<byte> coilData = client.ReadCoils(unitIdentifier, startingAddress, 10);

// Write Single Coil
client.WriteSingleCoil(unitIdentifier, 0, true);