Class SystemSerialPort

The serial port SerialSender transmits through: a SerialPort configured 8N1, wrapped so that opening, closing and reopening behave predictably across USB re-enumeration.

Inheritance
SystemSerialPort
Implements
Namespace: MOSAIC.Components.Manager.Serial
Assembly: MOSAIC.dll
Syntax
public sealed class SystemSerialPort : IDisposable
Remarks

Threading: used from a single writer thread, with the exception of Close() and Dispose(), which the owner may call from another thread to unblock a stalled write. Nothing here is thread-safe beyond that, and it does not need to be — closing concurrently with a Write(byte[], int, int) is expected to make that write throw, which is exactly how the block learns the link is gone.

Failure signalling: the block distinguishes two failure classes by exception type, so this wrapper must not blur them. A TimeoutException means "the peer is not draining its buffer" and leaves the port open; any other exception is treated as a broken link and triggers a close/reopen cycle. In particular, never wrap a timeout in an IOException — it would turn a merely slow receiver into a reconnect storm.

Reopen strategy: Open() always constructs a fresh SerialPort rather than reopening the previous instance. USB-CDC adapters re-enumerate when unplugged, and a SerialPort that has seen its device disappear frequently refuses to reopen or throws on close. Recreating costs nothing at reconnect frequency and avoids that whole class of bug.

Property caching: DtrEnable and WriteTimeout are stored on this wrapper and applied to each newly created port, so they can be set before the first Open() and survive reconnects.

Platform: mobile heads must bundle System.IO.Ports because shared block types refer to this wrapper while the block catalog is initialized. Bundling the package makes the type loadable on Android; access to USB-host devices still requires an Android USB serial transport rather than assuming that a desktop-style COM device is exposed to the application.

Constructors

SystemSerialPort(string, int)

Initializes a wrapper for the given port. No hardware is touched until Open().

Declaration
public SystemSerialPort(string portName, int baudRate)
Parameters
Type Name Description
string portName

Port name. A bare number is expanded to COM{n}; POSIX paths such as /dev/ttyUSB0 pass through unchanged.

int baudRate

Baud rate, e.g. 115200.

Fields

_baudRate

Baud rate applied to every port instance.

Declaration
private readonly int _baudRate
Field Value
Type Description
int

_dtrEnable

Cached DTR state, applied on each Open().

Declaration
private bool _dtrEnable
Field Value
Type Description
bool

_port

The live port, or null while closed.

Declaration
private SerialPort? _port
Field Value
Type Description
SerialPort

_portName

Port name as configured, before normalization.

Declaration
private readonly string _portName
Field Value
Type Description
string

_writeTimeout

Cached write timeout in ms, applied on each Open().

Declaration
private int _writeTimeout
Field Value
Type Description
int

Properties

AvailablePorts

Names of the serial ports currently present on this machine.

Declaration
public static string[] AvailablePorts { get; }
Property Value
Type Description
string[]

DtrEnable

Data Terminal Ready line state.

Declaration
public bool DtrEnable { get; set; }
Property Value
Type Description
bool
Remarks

Settable before Open(). On USB-CDC boards (Arduino and friends) asserting DTR resets the microcontroller, which is what the block's resetDelayMs waits out.

IsOpen

Whether the port is currently open and writable.

Declaration
public bool IsOpen { get; }
Property Value
Type Description
bool

WriteTimeout

Milliseconds a Write(byte[], int, int) may block before throwing TimeoutException.

Declaration
public int WriteTimeout { get; set; }
Property Value
Type Description
int
Remarks

Settable before Open().

Methods

Close()

Closes the port. Safe to call when already closed.

Declaration
public void Close()
Remarks

Close failures are swallowed: the port is being torn down either way, and a device that has already vanished commonly throws here.

Dispose()

Closes the port. Nothing else is held.

Declaration
public void Dispose()

NormalizePortName(string)

Expands a bare number to a Windows COM name, leaving anything else untouched.

Declaration
public static string NormalizePortName(string portName)
Parameters
Type Name Description
string portName
Returns
Type Description
string
Remarks

This lets a JSON config saying "3" and one saying "COM3" behave the same.

Open()

Opens the port, replacing any previous instance.

Declaration
public void Open()
Exceptions
Type Condition
Exception

Any failure to open (port missing, in use, access denied). The block catches all of them, records the message, and retries if auto-reconnect is enabled.

Write(byte[], int, int)

Writes count bytes from buffer.

Declaration
public void Write(byte[] buffer, int offset, int count)
Parameters
Type Name Description
byte[] buffer

Source buffer. Not retained.

int offset

Start offset within buffer.

int count

Number of bytes to write.

Exceptions
Type Condition
TimeoutException

The write did not complete within WriteTimeout. The port stays open.

Implements

IDisposable

Search documentation

Start typing to search the documentation.