CosmoSerialPort 0.1.1

CosmoSerialPort

A modern, cross-platform serial port library for .NET 10 — a semantic port of serialport-rs built for industrial automation, robotics, SCADA, telemetry and other long-running, latency-sensitive workloads.

• Windows (Win32 overlapped I/O + IOCP), Linux (termios2/BOTHER, poll), macOS (termios + IOSSIOSPEED, IOKit enumeration)
• SerialPort derives from Stream: works with StreamReader, System.IO.Pipelines, etc.
• Real async: pooled IValueTaskSource operations over a poll reactor (Unix) / IOCP (Windows) — no Task.Run wrappers, zero steady-state allocations
• Deterministic disposal: Dispose() wakes blocked readers, even with infinite timeouts
• Port enumeration with USB VID/PID, serial number, manufacturer and product strings
• Modem pin control (RTS/DTR out, CTS/DSR/RI/CD in), break, buffer discard, XON/XOFF and RTS/CTS flow control
• Opt-in text layer (ReadLine/WriteLine, NewLine, Encoding) and a race-free DataReceived event — the binary hot path stays untouched until you use them
• Nullable, analyzer-clean, AOT- and trimming-compatible
• Targets net10.0 and netstandard2.0 — usable from .NET Framework 4.7.2+, validated on .NET Framework 4.8 (see samples/CosmoSerialPort.Probe48). The ns2.0 build uses classic DllImport interop and a small polyfill layer; behavior is identical, though async continuations there always dispatch via the thread pool

Quick start

using CosmoSerialPort;

// Discover ports
foreach (SerialPortInfo info in SerialPort.GetPortInfos())
    Console.WriteLine($"{info.PortName} [{info.PortType}] {info.UsbInfo?.Product}");

// Open with the builder (an immutable record — share and reconfigure freely)
using SerialPort port = SerialPort.Create("/dev/ttyUSB0", 115200)
    .WithParity(Parity.None)
    .WithStopBits(StopBits.One)
    .WithFlowControl(FlowControl.None)
    .WithReadTimeout(TimeSpan.FromSeconds(2))
    .Open();

// Sync: returns as soon as at least one byte is available,
// throws SerialPortTimeoutException after ReadTimeout.
byte[] buffer = new byte[256];
int read = port.Read(buffer);

// Async with cancellation
int n = await port.ReadAsync(buffer.AsMemory(), cancellationToken);
await port.WriteAsync("AT\r\n"u8.ToArray());

// Pipelines for protocol parsing
var reader = port.CreatePipeReader();

// Control surface
port.SetRts(true);
ModemPins pins = port.GetModemPins();
port.DiscardBuffers(ClearBuffer.Input);

// Text layer (opt-in; UTF-8 and "\n" by default)
port.WriteLine("AT");
string? reply = port.ReadLine();
string? reply2 = await port.ReadLineAsync(cancellationToken);

// DataReceived: a background watcher owns the receive side while subscribed,
// so reading inside the handler is safe (unlike System.IO.Ports).
port.DataReceived += (_, e) =>
{
    if (!e.IsEndOfStream && port.ReadLine() is { } line)
        Console.WriteLine($"got: {line}");
};

Timeouts

SerialPortTimeoutException derives from TimeoutException for System.IO.Ports compatibility; all other errors derive from SerialPortException (an IOException) with the native error code preserved.

Thread safety

One thread may read while another writes on the same instance. Multiple concurrent readers (or writers) are rejected. Control operations are individually thread-safe.

CosmoSerialPort vs System.IO.Ports

How this library compares to the classic System.IO.Ports.SerialPort:

Migration notes. Most call sites map one-to-one: IsOpen → CanRead/CanWrite, Close() → Dispose(), DiscardInBuffer()/DiscardOutBuffer() → DiscardBuffers(ClearBuffer.…), DtrEnable/RtsEnable → WithDtrOnOpen(…)/SetRts(…). Two things have no direct equivalent: Write(string) (encode explicitly and write the bytes — the old default was ASCII) and ReadExisting() (check BytesToRead, then Read that many bytes — or better, use ReadLine/ReadAsync). Ports open at construction time via the builder, so code that configured a closed port and opened it later should defer creation to the point of first use.

Repository layout

dotnet build -c Release        # warning-clean, analyzers on
dotnet test  -c Release        # 31 tests; PTY loopback suite on macOS/Linux
dotnet run --project samples/CosmoSerialPort.Probe -c Release -- COM1   # against an echo peer