Class SerialPort

Namespace

Pamoja.Hal

Assembly

Pamoja.Hal.dll

One serial port, shared by the program and every driver built on it.

public sealed class SerialPort : IDisposable

Inheritance

object

SerialPort

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Open(string, SerialSettings) opens the kernel's serial device raw on a Linux board: /dev/serial0 for a Raspberry Pi's own UART, /dev/ttyUSB0 or /dev/ttyACM0 for a USB adapter. Looped(SerialSettings) is a line with TX wired to RX, Pair(SerialSettings) the two ends of a null-modem cable, and Scripted(SerialSettings, params SerialStep[]) a port that checks each write against a script.

A write returns once the bytes have left the UART, and a read once bytes have arrived or its timeout has passed. On anything but the kernel's device a read never waits: it returns at once, and the time it would have waited is added to WaitedMicros. A failure throws PamojaException with the reason, and a port is thread-safe, so one thread may read while another writes.

Properties

Kind

What is on the other end of the port.

public SerialPortKind Kind { get; }

Property Value

SerialPortKind

Received

How many bytes have been read through the port.

public long Received { get; }

Property Value

long

Remaining

How many steps a script has left, or null when the port is not scripted.

public int? Remaining { get; }

Property Value

int?

Settings

The speed and character format the port runs at.

public SerialSettings Settings { get; }

Property Value

SerialSettings

WaitedMicros

How long reads have waited without an answer, and waits have waited, in microseconds, whether or not the process slept through it.

public ulong WaitedMicros { get; }

Property Value

ulong

Written

How many bytes have been written through the port.

public long Written { get; }

Property Value

long

Methods

DiscardInput()

Drops whatever has arrived and not been read, as a client does before a request so a stale reply cannot be taken for the new one.

public void DiscardInput()

Exceptions

PamojaException

The device failed.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

FromHandle(nint)

Takes a port handle that another package's native call made, such as the port of a simulated Modbus line.

public static SerialPort FromHandle(nint port)

Parameters

port nint

The handle, which the returned port owns and releases.

Returns

SerialPort

The port.

Exceptions

PamojaException

The handle is null.

Looped(SerialSettings)

A line looped back on itself: every byte written is waiting to be read.

public static SerialPort Looped(SerialSettings settings)

Parameters

settings SerialSettings

The speed and format the line runs at.

Returns

SerialPort

The port.

Exceptions

PamojaException

The settings are not ones a port has.

Open(string, SerialSettings)

Opens the kernel's serial device raw: no echo, no line editing, no translation, just bytes. Whatever the device received before it was opened is dropped.

public static SerialPort Open(string path, SerialSettings settings)

Parameters

path string

The device file.

settings SerialSettings

The speed, a standard rate from 1200 to 921600, and the format.

Returns

SerialPort

The port, with the real line on the other end.

Exceptions

PlatformNotSupportedException

The platform is not Linux.

PamojaException

The device cannot be opened or set up.

Pair(SerialSettings)

The two ends of a null-modem pair: what one end writes, the other reads.

public static (SerialPort One, SerialPort Other) Pair(SerialSettings settings)

Parameters

settings SerialSettings

The speed and format both ends run at.

Returns

(SerialPort One, SerialPort Other)

The two ends.

Exceptions

PamojaException

The settings are not ones a port has.

Read(int, TimeSpan)

Reads up to max bytes, waiting up to timeout for the first one when nothing has arrived.

public byte[] Read(int max, TimeSpan timeout)

Parameters

max int

The most bytes to read.

timeout TimeSpan

How long to wait for the first byte.

Returns

byte[]

What arrived, empty when the timeout passed with nothing.

Exceptions

PamojaException

The device failed.

Scripted(SerialSettings, params SerialStep[])

A port that checks each write against the next step of a script, and makes the bytes the far end sends readable as the script reaches them.

public static SerialPort Scripted(SerialSettings settings, params SerialStep[] steps)

Parameters

settings SerialSettings

The speed and format the line runs at.

steps SerialStep[]

The writes and reads, in order; reads at the start are there at once.

Returns

SerialPort

The port.

Exceptions

PamojaException

The settings are not ones a port has.

Use<TResult>(Func<nint, TResult>)

Runs a native call that needs this port's handle.

public TResult Use<TResult>(Func<nint, TResult> call)

Parameters

call Func<nint, TResult>

The native call to make.

Returns

TResult

Whatever the native call returned.

Type Parameters

TResult

What the native call returns.

Remarks

A client takes the port's handle when it is built and holds its own share of the port, so this port may be disposed straight afterward.

Wait(TimeSpan)

Waits, as a protocol does to leave the line silent between frames: really on the kernel's device, and anywhere else only counted.

public void Wait(TimeSpan duration)

Parameters

duration TimeSpan

How long.

Write(ReadOnlySpan<byte>)

Writes bytes, returning once they have left the UART.

public void Write(ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The bytes, in order.

Exceptions

PamojaException

A script expected another write, or the device failed.