Oakrey.UHD 3.0.3

Oakrey.UHD

A .NET P/Invoke wrapper for the Ettus Research UHD (USRP Hardware Driver) native library. It provides TX streaming, frequency and gain tuning, stream metadata handling, and structured logging via IObservable<ILogEvent> for USRP software-defined radio devices.

Main features

• TX streaming - UhdStream extends System.IO.Stream and implements IObservable<ILogEvent>. Write raw IQ sample data directly from any .NET stream source, including files.
• Frequency and gain tuning - TuneRequest / TuneResult with configurable RF and DSP policies. Actual vs. requested values are compared and reported through the log observable.
• Sample rate control - Per-channel TX sample rate get/set via UhdWrapper.
• TX metadata - TxMetadataHandle supports time-spec, start-of-burst, and end-of-burst flags.
• RX infrastructure - RxStreamerHandle, RxMetadataHandle, MetadataRxWrapper, and StreamCommand are available for receive-side integration.
• Structured logging - ILogEvent with concrete types: InfoEventArgs, SetEventArgs, SetWarningEventArgs, ErrorEventArgs.
• Safe native handles - All UHD handles (DeviceHandle, TxStreamerHandle, RxStreamerHandle, TxMetadataHandle, RxMetadataHandle, AsyncMetadataHandle) extend SafeHandleZeroOrMinusOneIsInvalid and are disposed automatically.
• Error handling - Every native call is checked; failures throw UhdException with the UHD error code.

Architecture

graph TD
    A[Consumer code] -->|new UhdSettings| B[UhdStream]
    B -->|Init / Write| C[UhdWrapper]
    C -->|P/Invoke safe| D[UsrpSafeNativeMethods]
    C -->|P/Invoke unsafe| E[UsrpUnsafeNativeMethods]
    D --> F[uhd.dll]
    E --> F
    B -->|IObservable| G[ILogEvent stream]
    G --> H[InfoEventArgs]
    G --> I[SetEventArgs / SetWarningEventArgs]
    G --> J[ErrorEventArgs]
    B --> K[DeviceHandle]
    B --> L[TxStreamerHandle]
    B --> M[TxMetadataHandle]

Project structure

Requirements

• .NET 10 or higher
• Windows x64
• uhd.dll from the Ettus Research UHD driver placed alongside the application binary (bundled in the NuGet package)
• A supported Ettus Research / National Instruments USRP device

Installation

dotnet add package Oakrey.UHD

Or via the Visual Studio NuGet Package Manager: search for Oakrey.UHD.

Configuration

UhdSettings is a value type. All properties have defaults suitable for a single-channel TX scenario.

Example usage

Stream raw IQ samples from a file to a USRP device at GPS L1 (1575.42 MHz):

using Oakrey.UHD;
using Oakrey.UHD.Logging;

UhdSettings settings = new(frequency: 1_575_420_000.0)
{
    DeviceArgs = "addr=192.168.10.2",
    Gain = 60,
    Rate = 2_600_000
};

await using UhdStream uhdStream = new(settings);

// Subscribe to log events before initialising
IDisposable subscription = uhdStream.Subscribe(Observer.Create<ILogEvent>(
    e => Console.WriteLine(e.Message)));

uhdStream.Init();

using FileStream iqFile = File.OpenRead("samples.bin");
await uhdStream.CopyFrom(iqFile, fileBlockSize: 4096, CancellationToken.None);

subscription.Dispose();

Development notes

• uhd.dll must match the architecture of the host process (x64).
• The native UHD API reference used for P/Invoke mapping: https://files.ettus.com/manual/usrp_8h.html
• UhdStream is write-only (CanRead = false, CanSeek = false). The Read and Seek overrides throw InvalidOperationException.
• Sample buffers are managed with ArrayPool<short> to reduce GC pressure during streaming.
• UhdWrapper is a static class; handle lifetime is managed entirely by the SafeHandle subclasses.
• AllowUnsafeBlocks is required for the fixed-pointer send path in UsrpUnsafeNativeMethods.

License

MIT - Copyright (c) Oakrey 2016-present. See LICENSE or the PackageLicenseExpression field in the .csproj.