Class ModbusClient

Namespace

Pamoja.Modbus

Assembly

Pamoja.Modbus.dll

A Modbus RTU client on a serial line: the gateway, the master in the specification's words, that sends each request and waits for its reply.

public sealed class ModbusClient : IDisposable

Inheritance

object

ModbusClient

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

using var client = new ModbusClient(SerialPort.Open("/dev/ttyUSB0", new SerialSettings(19_200, Parity.Even)));
ushort[] registers = client.ReadHoldingRegisters(17, 107, 3);

Remarks

Each transaction follows the Modbus over Serial Line specification. The client leaves the line silent for 3.5 characters, or 1.75 ms above 19200 baud, so the request starts a new frame; drops anything stale waiting in the port; writes the request; and reads the reply to the length the request implies, against ResponseTimeout. The reply's CRC, unit, and function are checked before a value is read out of it, and a refusal throws ModbusClientException with the device's ModbusExceptionCode. A write to Broadcast reaches every device and draws no reply, so the client waits out Turnaround instead.

On the kernel's serial device every wait is real, so each call blocks until the reply is in. On a simulated line nothing waits: the waits are counted in the port's WaitedMicros.

Constructors

ModbusClient(SerialPort)

Makes a client on a port, with a one-second response timeout and a 100 ms turnaround.

public ModbusClient(SerialPort port)

Parameters

port SerialPort

The line; the client holds its own share of it, so the port may be disposed.

Fields

Broadcast

The unit address every device acts on and none answers.

public const byte Broadcast = 0

Field Value

byte

Properties

ResponseTimeout

How long the client waits for a whole reply once a request has gone out.

public TimeSpan ResponseTimeout { get; set; }

Property Value

TimeSpan

Turnaround

How long the client leaves the line quiet after a broadcast.

public TimeSpan Turnaround { get; set; }

Property Value

TimeSpan

Methods

Dispose()

Releases the client. Its port stays open while another holder has it.

public void Dispose()

FrameGapNanos(SerialSettings)

Returns the silence that separates two frames: 3.5 characters at the line's speed and format, and a fixed 1750 microseconds above 19200 baud.

public static ulong FrameGapNanos(SerialSettings settings)

Parameters

settings SerialSettings

The line's speed and character format.

Returns

ulong

The silence, in nanoseconds, rounded up.

Exceptions

PamojaException

The settings are not ones a port has.

ReadCoils(byte, ushort, ushort)

Reads coils, function 0x01.

public bool[] ReadCoils(byte unit, ushort start, ushort quantity)

Parameters

unit byte

The device, 1 to 247.

start ushort

The first coil's address.

quantity ushort

How many, 1 to 2000.

Returns

bool[]

The coils' states, in address order.

Exceptions

ModbusClientException

The transaction failed; its kind says why.

ReadDiscreteInputs(byte, ushort, ushort)

Reads discrete inputs, function 0x02.

public bool[] ReadDiscreteInputs(byte unit, ushort start, ushort quantity)

Parameters

unit byte

The device, 1 to 247.

start ushort

The first input's address.

quantity ushort

How many, 1 to 2000.

Returns

bool[]

The inputs' states, in address order.

Exceptions

ModbusClientException

The transaction failed; its kind says why.

ReadHoldingRegisters(byte, ushort, ushort)

Reads holding registers, function 0x03.

public ushort[] ReadHoldingRegisters(byte unit, ushort start, ushort quantity)

Parameters

unit byte

The device, 1 to 247.

start ushort

The first register's address.

quantity ushort

How many, 1 to 125.

Returns

ushort[]

The registers' values, in address order.

Exceptions

ModbusClientException

The transaction failed; its kind says why.

ReadInputRegisters(byte, ushort, ushort)

Reads input registers, function 0x04.

public ushort[] ReadInputRegisters(byte unit, ushort start, ushort quantity)

Parameters

unit byte

The device, 1 to 247.

start ushort

The first register's address.

quantity ushort

How many, 1 to 125.

Returns

ushort[]

The registers' values, in address order.

Exceptions

ModbusClientException

The transaction failed; its kind says why.

WriteMultipleCoils(byte, ushort, ReadOnlySpan<bool>)

Writes a run of coils, function 0x0F.

public void WriteMultipleCoils(byte unit, ushort start, ReadOnlySpan<bool> values)

Parameters

unit byte

The device, 1 to 247, or Broadcast for every device.

start ushort

The first coil's address.

values ReadOnlySpan<bool>

The states to write, 1 to 1968 of them, in address order.

Exceptions

ModbusClientException

The transaction failed; its kind says why.

WriteMultipleRegisters(byte, ushort, ReadOnlySpan<ushort>)

Writes a run of holding registers, function 0x10.

public void WriteMultipleRegisters(byte unit, ushort start, ReadOnlySpan<ushort> values)

Parameters

unit byte

The device, 1 to 247, or Broadcast for every device.

start ushort

The first register's address.

values ReadOnlySpan<ushort>

The values to write, 1 to 123 of them, in address order.

Exceptions

ModbusClientException

The transaction failed; its kind says why.

WriteSingleCoil(byte, ushort, bool)

Writes one coil, function 0x05.

public void WriteSingleCoil(byte unit, ushort address, bool on)

Parameters

unit byte

The device, 1 to 247, or Broadcast for every device.

address ushort

The coil's address.

on bool

The state to write.

Exceptions

ModbusClientException

The transaction failed; its kind says why.

WriteSingleRegister(byte, ushort, ushort)

Writes one holding register, function 0x06.

public void WriteSingleRegister(byte unit, ushort address, ushort value)

Parameters

unit byte

The device, 1 to 247, or Broadcast for every device.

address ushort

The register's address.

value ushort

The value to write.

Exceptions

ModbusClientException

The transaction failed; its kind says why.