DiagKit.Dbc 1.2.0-preview.1

DiagKit.Dbc

简体中文

DiagKit.Dbc is a .NET 10 DBC runtime library for diagnostic and CAN tooling. It provides DBC loading, an immutable metadata model, CAN/CAN FD signal encoding and decoding, runtime channel state, signal sample projection, and hardware-agnostic periodic transmit scheduling.

Current Capabilities

• Load DBC files with Strict or Lenient diagnostics.
• Use grouped DbcDiagnosticFormatter, Errors / Warnings, SignalPath, and simple facades for first-use and migration scenarios.
• Load immutable documents directly with DbcLoader.LoadDocumentOrThrow(...) when runtime state is not needed.
• Enumerate DbcSignalViewSnapshot values for UI binding through DbcSimpleRuntime / DbcSimpleChannel.
• Model nodes, messages, signals, environment variables, relation-attribute metadata, attributes, value tables, multiplexing, CAN identifiers, CAN FD flags, and source lines.
• Restore Vector SystemNodeLongSymbol, SystemMessageLongSymbol, SystemSignalLongSymbol, and SystemEnvVarLongSymbol as canonical names while keeping short-name aliases resolvable.
• Export normalized, reloadable DBC text with DbcWriter, write diagnostics, Vector long-symbol output, and reload semantic equivalence coverage.
• Create or semantically edit documents with DbcDocumentBuilder before export.
• Encode and decode Intel/Motorola signals, signed values, floating-point signals, raw values, and physical values.
• Use explicit write policies for range handling instead of silent correction.
• Process received frames into current snapshots and streaming SignalSample output for real-time or historical data consumers.
• Build immediate frames and poll due periodic frames without owning hardware, threads, timers, or application queues.
• Map common DBC semantics such as cycle time, send type, timeout, signal start value, and VFrameFormat.
• Keep common third-party DBC output usable in lenient mode, including Vector-explainable transport-sized message metadata, duplicate value-table warnings, and ambiguous duplicate-signal metadata.
• Run deterministic fuzz/property tests, benchmark matrix scenarios, opt-in soak runs, and real DBC corpus verification.

Scope

The package is intentionally hardware-agnostic. It does not depend on CanHub, Vector, ZLG, WPF, Excel/CSV workflows, or any hardware SDK. Host applications adapt hardware frames to DbcFrameView and consume transmit frames through IDbcFrameSink.

For Excel-based bulk editing of common DBC parameters, reference the optional DiagKit.Dbc.Workbook extension package or use the diagkit-dbc workbook template/export/import/validate commands from DiagKit.Dbc.Tool. Import reads a .xlsx DBC semantic table file by itself; it is not CAN trace data, signal samples, EOL test scripts, or source-preserving DBC editing.

J1939 is considered in the public boundaries, but the full J1939 protocol stack is not implemented in this package. Lenient loading may preserve J1939/transport payload metadata beyond 64 bytes; DbcChannelRuntime and CAN/CAN FD frame APIs only process messages where SupportsSingleFrameRuntime is true. Future protocol-specific behavior belongs in a separate extension layer.

For a fuller integration guide, see API usage guide.

Entry Points

Normalized DBC Export

DbcWriter writes stable DBC text from immutable DbcDocument metadata for newly built documents, semantic edits, and CI normalized export. The contract is reload semantic equivalence, not byte-for-byte round-trip editing: original whitespace, statement order, unknown statements, and comment placement are not preserved.

The default writer profile is ReloadEquivalent, which may emit metadata preserved by this library but not currently known-good in CANdb++, including general BA_ ... EV_ ... environment-variable attributes and BA_REL_ relation assignments. Use DbcWriterCompatibilityProfile.CanDbPlusKnownGood for CANdb++-oriented export; strict mode fails on known-unsupported statements, while lenient mode omits them and reports warnings.

var document = DbcLoader.LoadTextDocumentOrThrow(dbcText);
var result = DbcWriter.WriteText(document);
var text = result.GetTextOrThrow();

DbcDocumentBuilder can create or edit documents before export:

var builder = DbcDocumentBuilder.Create();
builder.AddNode("ECU");
builder.AddMessage(new DbcRawMessageId(256), "Status", 8, "ECU")
    .AddSignal("Speed", 0, 16)
    .WithScaling(0.1, 0);

5-Minute Path

Load a DBC and inspect messages/signals:

var dbc = DbcSimpleRuntime.LoadFile("vehicle.dbc");
Console.WriteLine(DbcDiagnosticFormatter.FormatGrouped(dbc.LoadResult.Diagnostics));

foreach (var message in dbc.Document.Messages)
{
    Console.WriteLine($"{message.Name}: {message.Signals.Count} signals");
}

Decode one received CAN frame into physical values:

var values = dbc.ProcessFrame(identifier, payload, timestamp: timestamp);
var speed = values.GetPhysicalValue("VehicleSpeed");

Set one signal and build an immediate transmit frame:

dbc.SetPhysicalValue("VehicleStatus.VehicleSpeed", 42.5);
var frame = dbc.BuildFrame("VehicleStatus", timestamp);

Poll DBC-driven periodic messages:

var session = DbcRuntimeSession.Create(dbc.Document);
var channel = session.CreateChannel("CAN1");
var start = Stopwatch.GetTimestamp();
var now = DbcTimestamp.FromElapsed(Stopwatch.GetElapsedTime(start));

var report = channel.RegisterCyclicPublishingMessagesFromDbc();
channel.PollDueFrames(now, txSink);

For hardware adapters, map receive frames to DbcFrameView and synchronously copy or forward IDbcFrameSink.OnFrame output to the hardware send API. DbcSimpleRuntime / DbcSimpleChannel are for UI, scripts, tests, and migration; hot paths should use pre-resolved handles, DbcFrameView, IDbcFrameSink, and ISignalSampleSink.

Verification

dotnet test ..\..\DiagKit.Dbc.slnx
dotnet run --project ..\..\tests\DiagKit.Dbc.Benchmarks\DiagKit.Dbc.Benchmarks.csproj -- --matrix
dotnet run --project ..\..\tests\DiagKit.Dbc.Benchmarks\DiagKit.Dbc.Benchmarks.csproj -- --soak --seconds 30
dotnet run --project ..\..\tests\DiagKit.Dbc.Benchmarks\DiagKit.Dbc.Benchmarks.csproj -- --corpus path\to\dbc-folder

Package Status

The package uses the MIT license. NuGet versions are generated by MinVer from Git tags with v as the tag prefix. The first preview tag is v1.0.0-preview; later previews use tags such as v1.0.0-preview.1. Releases follow the DiagKit family convention: CI first, then tag-driven NuGet publishing and GitHub Release creation.