Class SerialPortTransport

Serial-port implementation of ITransport for WSS communications. Wraps System.IO.Ports.SerialPort and exposes an event-driven receive API that works well in Unity/.NET Standard 2.0.

Inheritance

object

SerialPortTransport

Implements

ITransport

Namespace: Wss.CoreModule

Assembly: WSS.Transport.Serial.dll

Syntax

public sealed class SerialPortTransport : ITransport

Remarks

Threading: BytesReceived is raised from a background task. If your app (e.g., Unity) requires main-thread processing, marshal the callback to the main thread before touching UI/GameObjects.

Chunking: Serial I/O does not preserve message boundaries. Each chunk may contain partial frames or multiple frames. Always pass chunks to a frame codec/deframer.

Timeouts: The read loop polls System.IO.Ports.SerialPort.BytesToRead and catches System.TimeoutExceptions, which are normal with short read timeouts.

Constructors

SerialPortTransport(SerialPortTransportOptions)

Creates a serial transport from a single options object.

Declaration

public SerialPortTransport(SerialPortTransportOptions options)

Parameters

Type	Name	Description
SerialPortTransportOptions	options	Serial transport configuration, including connection settings and port selection mode.

Remarks

Exactly one port selection mode must be configured: either set AutoSelectPort to true or provide a non-empty PortName.

Exceptions

Type	Condition
ArgumentNullException	Thrown when options is null.
ArgumentException	Thrown when the port selection settings specify both an explicit port and auto-selection, or neither.

Properties

IsConnected

Gets whether the transport is currently connected/open.

Declaration

public bool IsConnected { get; }

Property Value

Type	Description
bool

Methods

ConnectAsync(CancellationToken)

Opens/initializes the transport connection (e.g., open a serial port, connect a socket, start BLE session).

Declaration

public Task ConnectAsync(CancellationToken ct = default)

Parameters

Type	Name	Description
CancellationToken	ct	Optional cancellation token to abort the connect attempt.

Returns

Type	Description
Task	A task that completes when the transport is connected.

Remarks

Opens the serial port and starts a background read loop that forwards incoming data to BytesReceived.

Exceptions

Type	Condition
ObjectDisposedException	If the instance has been disposed.
OperationCanceledException	If ct is canceled.
Exception	Implementations may throw transport-specific exceptions (e.g., unauthorized port access, device not found).

DisconnectAsync(CancellationToken)

Closes the transport connection and stops any background receive loop.

Declaration

public Task DisconnectAsync(CancellationToken ct = default)

Parameters

Type	Name	Description
CancellationToken	ct	Optional cancellation token to abort a long-running disconnect.

Returns

Type	Description
Task	A task that completes when the transport is fully disconnected.

Remarks

Stops the background read loop and closes the serial port.

Exceptions

Type	Condition
ObjectDisposedException	If the instance has been disposed.
OperationCanceledException	If ct is canceled.

Dispose()

Disposes the serial port and stops the read loop.

Declaration

public void Dispose()

SendAsync(byte[], CancellationToken)

Sends a block of bytes over the transport.

Declaration

public Task SendAsync(byte[] data, CancellationToken ct = default)

Parameters

Type	Name	Description
byte[]	data	The bytes to write. Callers should provide a buffer that will not be mutated during send.
CancellationToken	ct	Optional cancellation token to cancel the send before it is written. For some transports (e.g., synchronous serial writes), cancellation may only be observed before the write starts.

Returns

Type	Description
Task	A task that completes when the bytes have been handed off to the transport.

Remarks

Writes the buffer synchronously to the underlying System.IO.Ports.SerialPort and flushes the base stream.

Exceptions

Type	Condition
ObjectDisposedException	If the instance has been disposed.
InvalidOperationException	If the transport is not connected.
OperationCanceledException	If ct is canceled.

Events

BytesReceived

Raised whenever raw bytes arrive from the underlying transport. Each invocation may represent any number of bytes (including zero, depending on implementation), and may contain partial or multiple protocol frames.

Declaration

public event Action<byte[]> BytesReceived

Event Type

Type	Description
Action<byte[]>

Remarks

Implementations should invoke this event promptly as data becomes available. Callers should treat the provided buffer as read-only and copy it if they need to retain it.

This event is typically raised on a background thread. Consumers should marshal to the main thread if required by their environment.

Implements

ITransport