Oakrey.Usb 3.2.0

Oakrey.Usb

Windows .NET library for WinUSB bulk-transfer communication and real-time USB plug-and-play device monitoring.

Main features

• WinUSB bulk transfer - synchronous read/write over WinUSB pipes via UsbAdapter and the simplified send-only UsbOutStreamAdapter.
• Device monitoring - UsbNotifier raises arrival and removal events for any USB device connected to the system.
• Filtered subscriptions - UsbNotifier.RegisterUsbNotification accepts a predicate so consumers receive only the events relevant to their VID, PID, or serial number.
• Reactive Extensions - consume device changes as IObservable<UsbEventArgs> and compose them with standard System.Reactive operators.
• Safe device identity parsing - ProcessedDeviceInfo validates and extracts VID, PID, serial number, and device ID from a PnP symbolic link; TryParse handles untrusted input without exceptions.

Architecture

graph TD
    subgraph Oakrey.Usb.Adapter
        IUsbAdapter
        UsbAdapter -->|implements| IUsbAdapter
        UsbOutStreamAdapter -->|wraps| UsbAdapter
    end

    subgraph Oakrey.Usb.Notifier
        UsbNotifier
        UsbNotifierFilter -->|filters| UsbNotifier
        IUsbNotifierFilter
        UsbNotifierFilter -->|implements| IUsbNotifierFilter
    end

    UsbNotifier -->|uses| Nefarius[Nefarius.Utilities.DeviceManagement]
    UsbNotifier -->|exposes| Rx[System.Reactive]
    UsbAdapter -->|uses| WinUSBNet

Requirements

• .NET 10 (Windows only - net10.0-windows)
• The target USB device must have the WinUSB kernel driver installed (use Zadig or a custom INF).

Installation

.NET CLI

dotnet add package Oakrey.Usb

Package Manager Console

Install-Package Oakrey.Usb

NuGet Package Manager

Search for Oakrey.Usb in Visual Studio under Tools > NuGet Package Manager > Manage NuGet Packages for Solution.

Usage

Reading and writing over WinUSB

using Oakrey.Usb.Adapter;

// guid  - DeviceInterfaceGUID registered in the WinUSB INF
// serial - device serial number string
using UsbAdapter adapter = new("{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}", "MY_SERIAL");

Console.WriteLine($"Connected: {adapter.Name} ({adapter.Serial})");

// Write
byte[] command = [0x01, 0x02, 0x03];
adapter.Write(command, 0, command.Length);

// Read
byte[] response = new byte[64];
int bytesRead = adapter.Read(response, 0, response.Length);

Send-only shortcut with UsbOutStreamAdapter:

using UsbOutStreamAdapter stream = new("{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}", "MY_SERIAL");
stream.Send([0x01, 0x02, 0x03]);

Monitoring device arrival and removal

Subscribe to all USB devices:

using Oakrey.Usb.Notifier;

using IUsbNotifierFilter subscription = UsbNotifier.RegisterUsbNotification(_ => true);

subscription.UsbEvent += (sender, e) =>
{
    Console.WriteLine($"{e.UsbDeviceChangeStatus}: VID={e.DeviceInfo.VID} PID={e.DeviceInfo.PID} Serial={e.DeviceInfo.Serial}");
};

Filter by VID and PID:

using IUsbNotifierFilter subscription = UsbNotifier.RegisterUsbNotification(
    device => device.VID == "1234" && device.PID == "ABCD");

subscription.UsbEvent += (sender, e) =>
{
    if (e.UsbDeviceChangeStatus == UsbDeviceChangeStatus.Inserted)
    {
        Console.WriteLine($"Target device arrived: {e.DeviceInfo.Serial}");
    }
};

Dispose the subscription to stop receiving events:

subscription.Dispose();

Reactive USB notifications

Observe all USB device changes using Reactive Extensions:

using Oakrey.Usb.Notifier;
using System.Reactive.Linq;

using IDisposable subscription = UsbNotifier
    .ObserveUsbNotifications()
    .Where(e => e.UsbDeviceChangeStatus == UsbDeviceChangeStatus.Inserted)
    .Subscribe(e =>
        Console.WriteLine($"Connected: {e.DeviceInfo.VID}:{e.DeviceInfo.PID} ({e.DeviceInfo.Serial})"));

Filter devices before they enter the RX pipeline:

using IDisposable subscription = UsbNotifier
    .ObserveUsbNotifications(device => device.VID == "1234" && device.PID == "ABCD")
    .Subscribe(e => Console.WriteLine($"{e.UsbDeviceChangeStatus}: {e.DeviceInfo.Serial}"));

An existing UsbNotifier or IUsbNotifierFilter can be converted using ToObservable(). Disposing the RX subscription detaches its event handler.

ProcessedDeviceInfo properties

For symbolic links received from an untrusted or optional source, use the non-throwing parser:

if (ProcessedDeviceInfo.TryParse(symbolicLink, out ProcessedDeviceInfo? device))
{
    Console.WriteLine($"{device.VID}:{device.PID} ({device.Serial})");
}

Project information

License

MIT License. See LICENSE file for details.