Oakrey.Capsule.Can 2.0.2

Oakrey.Capsule.Can

Overview

Oakrey.Capsule.Can is a .NET 10 class library for encoding and decoding CAN and CAN-FD communication data using the Oakrey Capsule binary framing protocol.

It provides three capsule types that cover the full lifecycle of a CAN channel:

Main Features

• Serialize and deserialize CAN messages to and from the Capsule binary format.
• Multi-message batching in a single CanDataCapsule using delta timestamps (CanStatus.MultiModeMessage).
• CAN-FD support signaled via CanStatus.FDEnabled.
• Extended message IDs (CanStatus.ExtendedMessage).
• Channel capability flags: terminator present, FD support, timing override, filter support (CanChannelFlags).
• Full timing configuration: arbitration and data baud rates, sample points, time quanta, sync jump width.
• Request payload generation via static GetRequestPayload() on each capsule type.

Architecture

classDiagram
    class CapsuleBase {
        +CapsuleHead Head
        +Serialize() byte[]
        #WritePayload(BinaryWriter)
    }

    class CanDataCapsule {
        +ushort Id = 0x0101
        +byte Version = 0x01
        +IList~CanMessage~ Messages
        +CanStatus Flag
        +byte ChannelIndex
        +GetRequestPayload()$ byte[]
    }

    class CanChannelInfoCapsule {
        +ushort Id = 0x0100
        +byte Version = 0x01
        +byte ChannelIndex
        +CanChannelStatus Status
        +CanChannelFlags Setting
        +uint MaxArbitrationBaudRate
        +uint MaxDataBaudRate
        +string Alias
        +GetRequestPayload()$ byte[]
    }

    class CanChannelSettingCapsule {
        +ushort Id = 0x0102
        +byte Version = 0x01
        +byte ChannelIndex
        +CanChannelSettings Setting
        +uint ArbitrationBaudRate
        +uint DataBaudRate
        +byte NominalSamplePoint
        +ushort NominalTimeQuantaCount
        +byte NominalSWJ
        +byte DataSamplePoint
        +byte DataTimeQuantaCount
        +byte DataSWJ
        +string Alias
        +GetRequestPayload()$ byte[]
    }

    class CanMessage {
        +long Id
        +long Timestamp
        +byte[] Data
        +WriteTo(BinaryWriter)
        +WriteTo(BinaryWriter, long timestamp)
    }

    class CanMessageFactory {
        +FromPayload(ReadOnlySpan~byte~, out int)$ CanMessage
        +FromPayload(ReadOnlySpan~byte~, out int, long)$ CanMessage
    }

    CapsuleBase <|-- CanDataCapsule
    CapsuleBase <|-- CanChannelInfoCapsule
    CapsuleBase <|-- CanChannelSettingCapsule
    CanDataCapsule "1" --> "*" CanMessage
    CanMessageFactory ..> CanMessage : creates

Requirements

• .NET 10 or higher
• NuGet dependency: Oakrey.Collections 2.0.0
• NuGet dependency: Oakrey.Capsule (project / package reference)

Installation

.NET CLI

dotnet add package Oakrey.Capsule.Can

Package Manager Console

Install-Package Oakrey.Capsule.Can

NuGet Package Manager

Search for Oakrey.Capsule.Can in Tools > NuGet Package Manager > Manage NuGet Packages for Solution.

Usage

Serialize a single CAN message

CanMessage message = new CanMessage(
    timestamp: DateTime.UtcNow.Ticks,
    iD: 0x1A0,
    data: new byte[] { 0x01, 0x02, 0x03, 0x04 });

CanDataCapsule capsule = new CanDataCapsule(
    record: message,
    status: CanStatus.FDEnabled,
    channel: 0,
    hwId: 1);

byte[] binary = capsule.Serialize();

Serialize multiple CAN messages (batched)

IEnumerable<CanMessage> messages = GetMessages();

CanDataCapsule capsule = new CanDataCapsule(
    records: messages,
    status: CanStatus.FDEnabled,
    channel: 0,
    hwId: 1);

// CanStatus.MultiModeMessage is set automatically when more than one message is added.
byte[] binary = capsule.Serialize();

Deserialize a CAN data capsule

byte[] binary = ReceiveBinary();

CanDataCapsule capsule = new CanDataCapsule(binary);

foreach (CanMessage msg in capsule.Messages)
{
    Console.WriteLine(msg); // timestamp; id; length; hex-data
}

Request channel information

// Build a request frame and send it to the device.
byte[] request = CanChannelInfoCapsule.GetRequestPayload();

// Parse the response.
byte[] response = SendAndReceive(request);
CanChannelInfoCapsule info = new CanChannelInfoCapsule(response);

Console.WriteLine($"Channel {info.ChannelIndex}: {info.Status}, FD={info.Setting.HasFlag(CanChannelFlags.SupportFD)}");

Configure channel settings

CanChannelSettingCapsule settings = new CanChannelSettingCapsule(
    channelIndex: 0,
    setting: CanChannelSettings.FDEnabled | CanChannelSettings.TerminatorEnabled,
    arbitrationBaudRate: 500_000,
    dataBaudRate: 2_000_000,
    nominalSamplePoint: 80,
    nominalTimeQuantaCount: 20,
    nominalSWJ: 1,
    dataSamplePoint: 75,
    dataTimeQuantaCount: 10,
    dataSWJ: 1,
    alias: "CAN0");

byte[] binary = settings.Serialize();

Capsule Protocol Reference

Development Notes

• All capsules inherit from CapsuleBase and override WritePayload(BinaryWriter), Id, and Version.
• Delta timestamps in multi-message capsules are stored as uint (max ~429 seconds at 100 ns tick resolution).
• CanMessageFactory is the low-level deserialization entry point for individual frames within a payload.
• All capsule types expose a static GetRequestPayload() for polling devices that use a request/response model.

License

MIT. Copyright (c) Oakrey 2016-present.

See the project page and repository for more information.