CosmoSerialPort 1.1.0

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
• RS-485 direction control (Rs485Settings: TIOCSRS485 on Linux, RTS_CONTROL_TOGGLE on Windows), inter-byte timeouts (InterByteTimeout, pySerial's inter_byte_timeout), and in-memory SerialPort.OpenLoopback() / SerialPort.OpenPair() transports for hardware-free testing on every platform
• URL-style ports, pySerial-compatible: rfc2217://host:port (Telnet COM-port control, works with ser2net), socket://host:port (raw TCP) and loop:// — just pass the URL as the port name; plus DSR/DTR flow control and 1.5 stop bits (Windows/RFC 2217), and an interactive terminal sample (samples/CosmoSerialPort.Terminal, the miniterm equivalent)
• 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

Documentation

Full guides live in docs/: getting started, configuration, reading & writing, events, signals & status, enumeration, virtual & network ports, error handling, API reference, platform notes, migration, examples, and the FAQ.

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}");
};

Feature tour

Network and URL-style ports

Port names can be URLs (pySerial's serial_for_url scheme set) — the builder and every feature above work unchanged:

// RFC 2217 / Telnet COM-port control (ser2net, terminal servers):
// line settings, RTS/DTR/break and purges are forwarded to the remote UART.
using SerialPort remote = SerialPort.Create("rfc2217://192.168.1.50:4001", 115200)
    .WithParity(Parity.Even)
    .WithReadTimeout(TimeSpan.FromSeconds(5))
    .Open();
remote.WriteLine("STATUS?");
Console.WriteLine(remote.ReadLine());
Console.WriteLine(remote.GetModemPins()); // served from NOTIFY_MODEMSTATE

// Raw TCP bridge (no control channel):
using SerialPort tcp = SerialPort.Open("socket://10.0.0.7:7777", 9600);

Hardware-free testing

// loop://—everything written comes back on the same port; RTS/DTR reflect as CTS/DSR.
using SerialPort loop = SerialPort.OpenLoopback();
loop.WriteLine("echo");
Assert.Equal("echo", loop.ReadLine());

// A cross-connected null-modem pair — drive both ends of your protocol in one process.
(SerialPort device, SerialPort host) = SerialPort.OpenPair();
device.Write(response);
host.Read(buffer);          // reads what "device" wrote
device.Dispose();           // "host" now reads end-of-stream, like a hot unplug

Status events

port.PinChanged += (_, e) =>
    Console.WriteLine($"changed: {e.ChangedPins}, now: {e.CurrentPins}");
port.ErrorReceived += (_, e) =>
    Console.WriteLine($"line errors: {e.Errors}"); // Frame | Overrun | RxParity | RxOver | Break

Both are driven by a ~50 ms sampling watcher that starts with the first subscription and stops with the last; pin pulses shorter than the interval can be missed, and ErrorReceived has no macOS source. DataReceived supports ReceivedBytesThreshold to batch notifications.

Industrial extras

// RS-485 half-duplex direction control (Linux TIOCSRS485 / Windows RTS toggle).
using SerialPort bus = SerialPort.Create("/dev/ttyS2", 19200)
    .WithRs485Mode(new Rs485Settings { DelayBeforeSend = TimeSpan.FromMilliseconds(1) })
    .Open();

// Inter-byte timeout: Read collects a burst and returns when the line goes quiet,
// instead of returning the first fragment — ideal for framed RTU-style protocols.
port.InterByteTimeout = 50;   // ms
int frame = port.Read(buffer);

// Parity beyond N/E/O, plus error-byte replacement and null stripping.
using SerialPort legacy = SerialPort.Create("COM2", 9600)
    .WithParity(Parity.Mark)              // Mark/Space: Windows & Linux
    .WithParityReplace((byte)'?')         // substitute bytes received in error
    .WithDiscardNull(true)
    .WithStopBits(StopBits.OnePointFive)  // Windows & RFC 2217
    .Open();

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(…), Handshake → FlowControl. Write(string) and ReadExisting() exist with the same semantics (mind the UTF-8 vs ASCII default Encoding). 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.

CosmoSerialPort vs pySerial

For teams coming from Python, the feature sets now largely mirror each other:

Repository layout

dotnet build -c Release        # warning-clean, analyzers on
dotnet test  -c Release        # 71 tests; PTY suite on macOS/Linux, virtual transports everywhere
dotnet run --project samples/CosmoSerialPort.Probe -c Release -- COM1        # against an echo peer
dotnet run --project samples/CosmoSerialPort.Terminal -c Release -- loop://  # try it without hardware