Oakrey.Guru.Base 5.0.0

Oakrey.Guru.Base

Base device library for Oakrey Guru USB hardware adapters. Provides the core abstractions and default implementations used by all Guru protocol adapters (CAN, LIN, and others).

Main features

• IDevice - common contract for Guru adapters: connect, ping, firmware update, bootloader reset
• ILicense - multi-slot license key retrieval (GetLicenseKey, GetAllLicenseKeys, GetBootLicense)
• DeviceBase - abstract base class that wires together an ITransceiver and a handler pipeline; extend this to build a concrete adapter
• FirmwareUpdater - async firmware update from an Intel HEX file; handles bootloader entry, waits for the device to re-enumerate as a mass-storage drive, copies the file, and triggers reboot
• FirmwareUpdateException - specific exception type for firmware update failures, with a built-in file-existence guard
• DeviceExtensions.VerifyConnection - runs N ping round-trips, logs average latency, and throws on mismatch
• HardwareTimeStamp<T> - generic value type that pairs a hardware-reported timestamp with the host DateTime

Architecture

classDiagram
    class IDevice {
        +Connect(ct)
        +Ping(data, ct)
        +GetFwVersion(ct)
        +RestartToBootloader(ct)
        +UpdateFirmware(path, ct)
        +FwUpdateInProgress IObservable~bool~
    }
    class ILicense {
        +GetLicenseKey(id, ct)
        +GetAllLicenseKeys(ct)
        +GetBootLicense(ct)
    }
    class DeviceBase {
        #transceiver ITransceiver
        #commandsManager HandlerCollection
        #deviceLock SemaphoreSlim
    }
    IDevice <|.. DeviceBase
    ILicense <|.. DeviceBase
    DeviceBase <|-- ConcreteAdapter

DeviceBase subscribes to ITransceiver.Received and dispatches each incoming packet to the matching handler via HandlerCollection. Concrete adapters (e.g. CanGuruAdapter, LinGuruAdapter) inherit from DeviceBase, register their own handlers, and expose a protocol-specific API.

Key types

Requirements

• .NET 10 (Windows only � System.Management / WMI is used to detect the bootloader drive)
• The Guru adapter must support the Guru packet protocol

Installation

.NET CLI

dotnet add package Oakrey.Guru.Base

Package Manager Console

Install-Package Oakrey.Guru.Base

NuGet Package Manager

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

Example usage

Connect and ping

// adapter is a concrete DeviceBase implementation supplied by e.g. Oakrey.Guru.Can
using MyGuruAdapter adapter = new(transceiver);

await adapter.Connect(cancellationToken);

uint echo = await adapter.Ping(0xDEADBEEF, cancellationToken);

Read firmware version and license keys

string version = await adapter.GetFwVersion(cancellationToken);
List<string> keys = await adapter.GetAllLicenseKeys(cancellationToken);

Firmware update

adapter.FwUpdateInProgress.Subscribe(inProgress =>
    Console.WriteLine(inProgress ? "Update started" : "Update finished"));

await adapter.UpdateFirmware(@"C:\firmware\v2.hex", cancellationToken);

The updater:

1. Sends the bootloader-entry command to the device.
2. Waits (up to 5 s) for the device to re-enumerate as a removable drive using WMI Win32_VolumeChangeEvent.
3. Copies the .hex file to that drive.
4. Writes a reboot trigger file to complete the update.

Development notes

• All async methods accept a CancellationToken and propagate it through the call chain.
• deviceLock (a SemaphoreSlim(1,1)) serialises all handler executions; do not bypass it in subclasses.
• FwUpdateInProgress is a BehaviorSubject-backed IObservable<bool>; subscribe before calling UpdateFirmware to observe the full lifecycle.
• System.Management is consumed with PrivateAssets="All" so it is not exposed as a transitive dependency to consumers.

Project information

License

MIT. See the LICENSE file for details.