Oakrey.Capsule.Base 2.0.2

Oakrey.Capsule.Base

Overview

Oakrey.Capsule.Base is a .NET 10 base library for building binary protocol capsules. A capsule is a self-describing binary frame that carries a fixed header (hardware ID, protocol ID, timestamp, version) and a typed payload. The library provides span-based serialization, a protocol-ID-keyed deserialization registry, and a built-in LoggingCapsule. It is designed as the foundation for domain-specific capsule packages such as Oakrey.Capsule.Can and Oakrey.Capsule.Lin.

Main Features

Binary Header

• CapsuleHead carries HardwareId, ProtocolId, Timestamp (ticks), and Version.
• Header is parsed from a ReadOnlySpan<byte> at fixed offsets; no heap allocation for the parse step.

Serialization and Deserialization

• Serialize() writes the header and payload into a byte[] via BinaryWriter.
• CapsuleBase.Deserialize(ReadOnlySpan<byte>) reads the protocol ID from the frame and dispatches to the registered capsule type.
• Head check code ("ch") is validated on every deserialization call.

Deserialization Registry

• Call AddToCache() on a capsule instance to register its type against its protocol ID.
• Deserialize uses the registry to instantiate the correct concrete type via its ReadOnlySpan<byte> constructor.

Logging Capsule

• LoggingCapsule is a ready-to-use capsule for transporting log messages with a LogCode classification.

Helper Extensions

• SpanHelper � read ushort, uint, long, and UTF-8 strings from a ReadOnlySpan<byte> at an offset.
• BinaryWriterHelper � write UTF-8 strings via BinaryWriter.

Architecture

classDiagram
    direction TB
    class ICapsule {
        <<interface>>
        +Id: ushort
        +Name: string
        +Head: CapsuleHead
        +ContentToString: string
        +OneLineInfo: string
        +Serialize() byte[]
        +AddToCache() bool
    }
    class CapsuleBase {
        <<abstract>>
        +Deserialize(payload) ICapsule$
        #WritePayload(writer)
    }
    class CapsuleHead {
        +HardwareId: ushort
        +ProtocolId: ushort
        +Timestamp: long
        +Version: byte
    }
    class LoggingCapsule {
        +Code: LogCode
        +Message: string
        +Id: ushort = 0x0000
    }
    ICapsule <|.. CapsuleBase
    CapsuleBase --> CapsuleHead
    CapsuleBase <|-- LoggingCapsule

Binary Frame Layout

Requirements

• .NET 10 or higher
• No external NuGet dependencies

Installation

.NET CLI

dotnet add package Oakrey.Capsule.Base

Package Manager Console

Install-Package Oakrey.Capsule.Base

NuGet Package Manager

1. Open your project in Visual Studio.
2. Navigate to Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
3. Search for Oakrey.Capsule.Base and click Install.

Usage

1. Define a custom capsule

Inherit from CapsuleBase, declare a unique Id and a ReadOnlySpan<byte> constructor for deserialization:

public class TemperatureCapsule : CapsuleBase
{
    public override ushort Id => 0x0010;
    public override byte Version => 1;
    public float Temperature { get; private set; }

    private const int temperatureOffset = payloadOffset;

    // For creating a new capsule to send
    public TemperatureCapsule(float temperature, ushort hwId) : base(hwId, 1)
    {
        Temperature = temperature;
    }

    // Required for deserialization dispatch
    public TemperatureCapsule(ReadOnlySpan<byte> payload) : base(payload)
    {
        Temperature = BitConverter.ToSingle(payload.Slice(temperatureOffset, 4));
    }

    protected override void WritePayload(BinaryWriter writer)
    {
        writer.Write(Temperature);
    }

    public override string ContentToString => $"Temperature: {Temperature} C";
    public override string OneLineInfo => $"Temp: {Temperature:F1} C";
}

2. Register capsule types

Register each capsule type once at startup, before any deserialization calls:

new TemperatureCapsule(0, hwId: 0).AddToCache();
new LoggingCapsule().AddToCache();

3. Serialize

TemperatureCapsule capsule = new TemperatureCapsule(23.5f, hwId: 0x0001);
byte[] frame = capsule.Serialize();

4. Deserialize

ICapsule received = CapsuleBase.Deserialize(frame);

if (received is TemperatureCapsule temp)
{
    Console.WriteLine(temp.Temperature);
}

5. LoggingCapsule

LoggingCapsule log = new LoggingCapsule("Device started", LogCode.StartedSuccessfully, hwId: 0x0001);
byte[] frame = log.Serialize();

Development Notes

• The deserialization registry (cachedCapsules) is a static Dictionary<ushort, ICapsule> on CapsuleBase. It is process-global and not thread-safe for concurrent AddToCache calls during initialization � register all types before processing data.
• LogCode is a uint enum. Add application-specific codes by extending it in your own assembly.
• The check code "ch" is validated on deserialization; frames with a wrong prefix throw an exception before any capsule lookup.

Project Information

License

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