Oakrey.Guru.Adapter 4.0.4

Oakrey.Guru.Adapter

Base adapter library for Oakrey Guru USB hardware devices. Provides a structured packet-framing protocol with CRC16-CCITT validation, and transceiver, transmitter, and receiver abstractions over USB.

Main features

• Packet-framing protocol with a fixed preamble byte, 2-byte command ID, control byte, and variable-length data payload (up to 255 bytes)
• Optional CRC16-CCITT validation appended to each frame (CrcTransceiver / CrcTransmitter / CrcReceiver)
• Rx-based observable packet stream (IObservable<ReceivedPacket>) for non-blocking asynchronous receive
• Clean interface hierarchy (ITransmitter, IReceiver, ITransceiver) for easy substitution and testing
• Extensible base classes (TransceiverBase, Receiver, Transmitter) for custom protocol variants

Architecture

classDiagram
    direction TB

    class ITransmitter {
        +Send(id, data)
        +Reply(id, data)
    }
    class IReceiver {
        +Received IObservable~ReceivedPacket~
        +Dispose()
    }
    class ITransceiver {
        +Name string
        +Serial string
    }
    ITransceiver --|> ITransmitter
    ITransceiver --|> IReceiver

    class TransceiverBase {
        +Name string
        +Serial string
        +Send(id, data)
        +Reply(id, data)
        +Received IObservable~ReceivedPacket~
    }
    TransceiverBase ..|> ITransceiver

    class Transceiver {
        +Create(guid, serial) Transceiver
    }
    class CrcTransceiver {
        +Create(guid, serial) CrcTransceiver
    }
    Transceiver --|> TransceiverBase
    CrcTransceiver --|> TransceiverBase

    class Transmitter
    class CrcTransmitter
    CrcTransmitter --|> Transmitter

    class Receiver
    class CrcReceiver
    CrcReceiver --|> Receiver

Packet frame structure

packet-beta
    0-7: "Preamble (0x58)"
    8-15: "Control byte"
    16-31: "Command ID (LE)"
    32-39: "Data length"
    40-71: "Data (0..255 bytes)"
    72-87: "CRC16-CCITT (CRC variant only)"

Requirements

• .NET 10.0 (Windows)
• Oakrey.Log >= 2.0.0
• System.Reactive >= 6.1.0
• Oakrey USB adapter device with a known device GUID and serial number

Installation

dotnet add package Oakrey.Guru.Adapter

Or via Package Manager Console:

Install-Package Oakrey.Guru.Adapter

Usage

Basic transceiver (no CRC)

using Oakrey.Guru.Adapter;

// Create a transceiver for the device identified by its USB GUID and serial number.
using Transceiver transceiver = Transceiver.Create("{device-guid}", "device-serial");

// Subscribe to incoming packets.
using IDisposable subscription = transceiver.Received.Subscribe(packet =>
{
    Console.WriteLine($"ID: {packet.CommandId}, Control: {packet.ControlByte}, Data: {packet.DataCount} bytes");
});

// Send an action packet.
transceiver.Send(0x0001, [0xAA, 0xBB]);

// Send a reply packet.
transceiver.Reply(0x0001, [0xCC]);

CRC-validated transceiver

using Oakrey.Guru.Adapter;

// CrcTransceiver appends and validates CRC16-CCITT on every frame.
using CrcTransceiver transceiver = CrcTransceiver.Create("{device-guid}", "device-serial");

using IDisposable subscription = transceiver.Received.Subscribe(packet =>
{
    Console.WriteLine($"ID: {packet.CommandId}, Data length: {packet.DataCount}");
});

transceiver.Send(0x0002, [0x01, 0x02, 0x03]);

CRC16-CCITT utility

The Crc16CCITTCalculator extension method is public and can be used independently:

byte[] buffer = [0x58, 0x00, 0x01, 0x00, 0x02, 0xAA, 0xBB];
ushort crc = buffer.Crc16CCITT(initVal: 0, offset: 0, cnt: buffer.Length);

Development notes

• Transceiver and CrcTransceiver are sealed. Extend the protocol by subclassing TransceiverBase, Transmitter, and Receiver directly, as CrcTransceiver does.
• Receiver runs a background Task via Task.Run and cancels it on Dispose. Always dispose the transceiver when done.
• The Received stream is a Subject<ReceivedPacket>. Unhandled exceptions inside a subscriber will propagate to the TaskScheduler.UnobservedTaskException handler.
• The USB project is referenced with PrivateAssets="all", so it is bundled into this package and not exposed as a transitive dependency.

Project information

License

This project is licensed under the MIT License. See the LICENSE file for details.