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.
Implements
Inherited Members
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 |
| 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 |
| int | count | Number of bytes to write. |
Exceptions
| Type | Condition |
|---|---|
| TimeoutException | The write did not complete within WriteTimeout. The port stays open. |