Periphery.Serial 5.0.0

Periphery

A cross-platform .NET library for discovering hardware devices (USB, Bluetooth, network adapters, displays, and more) with a LINQ-friendly API. One API covers Windows, Linux, and macOS.

dotnet add package Periphery --prerelease

Every release so far is a prerelease. Before upgrading, read BREAKING-CHANGES.md.

Quick Look

// All active USB devices
var usb = await Devices.Enumerate()
    .OfCategory(DeviceCategory.Usb)
    .Active()
    .ToListAsync();

// Compose a query with LINQ
var mice = await Devices.Enumerate()
    .OfCategory(DeviceCategory.Hid)
    .ByManufacturer("Logitech")
    .OrderBy(d => d.Name)
    .ToListAsync();

// Find one device by USB VID/PID
var board = await Devices.Enumerate()
    .WithUsbId("1234", "5678")
    .FirstOrDefaultAsync();

Watch for devices arriving and leaving:

await using var watcher = Devices.Watch().OfCategory(DeviceCategory.Usb);

watcher.Appeared    += (_, e) => Console.WriteLine($"+ {e.Device.Name}");
watcher.Disappeared += (_, e) => Console.WriteLine($"- {e.Device.Name}");

await watcher.StartAsync();

Track one device by identity:

await using var watcher = Devices.Watch();

var mouse = watcher.AddTracker(
    t => t.OfCategory(DeviceCategory.Usb).WithUsbId("046D", "C52B"),
    name: "Mouse");

mouse.StateChanged += (_, _) => Console.WriteLine($"Mouse present: {mouse.IsPresent}");

await watcher.StartAsync();

Open a serial device by identity instead of by COM number. The proxy reopens the port when the device comes back, wherever the OS puts it:

var scanner = new DeviceProfile(
    f => f.OfCategory(DeviceCategory.Ports)
          .WithUsbId("0403", "6001")
          .WithSerialNumber("A9012XYZ"),
    name: "Scanner");

SerialPort? port = null;   // from the System.IO.Ports package

await using var proxy = await DeviceProxy.OpenAsync(
    scanner,
    onActivated: (info, ct) =>
    {
        port = new SerialPort(info.PortName.ToString(), 115_200);
        port.Open();
        return Task.CompletedTask;
    },
    onDeactivated: _ =>
    {
        port?.Dispose();
        return Task.CompletedTask;
    });

More in examples/.

Device categories

USB, Bluetooth, Network, Display, Monitor, HID, Keyboard, Mouse, Audio, Storage, Ports (serial), Battery, and Camera.

Devices also carry capability tags, such as Printer, Sensor, or SmartCard, that cut across categories:

var printers = await Devices.Enumerate().WithTag(DeviceTags.Printer).ToListAsync();

Packages

The core package only discovers devices. Extension packages talk to them.

Periphery.Camera, Periphery.Hid, Periphery.Monitor, and Periphery.Usb support Windows and Linux, not macOS.

Requirements

• .NET 10 or later. A best-effort net8.0 build also ships.
• Linux: libudev.so.1. Periphery.Usb also needs libusb-1.0 1.0.23 or newer.
• Windows and macOS: no native dependencies. On macOS, Bluetooth bonds are reported only to a process with Bluetooth permission (ADR-0093).

Design principles

1. Discovery in the core, I/O in extensions.
2. The same API on every platform.
3. LINQ-native. Queries compose with Where, Select, OrderBy, and the rest.
4. No third-party dependencies in the core or the I/O extensions. Integrations such as Avalonia and OpenCvSharp are separate, opt-in packages.
5. Async-first. Every entry point returns Task or IAsyncEnumerable.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md and ARCHITECTURE.md. Bugs and ideas go in GitHub issues. Report security issues through SECURITY.md.

License

PolyForm Small Business 1.0.0 - see LICENSE.md.

Source-available, not open source. Every right the licence grants - including making changes and redistributing - is granted only for a permitted purpose, and use for the benefit of a company is a permitted purpose only below the employee-count and revenue thresholds the licence sets.

LICENSE.md is the authoritative statement of the terms. This paragraph points at it and is not a summary of it.