Update documentation

README.md

@@ -1,34 +1,841 @@
-# dbc parser skeleton
-
-A minimal DBC parser skeleton for the **FrameTap** project.
-
-The purpose of this module is to read a DBC file and convert it into a simple internal representation that can later be:
-
-- displayed as a tree
-- connected to `Qt Model/View`
-- used for signal selection
-- extended toward runtime CAN frame decoding
-
----
+# DBC Parser and Runtime Decode Module Documentation
 
 ## Overview
 
-The architecture is intentionally simple:
+This module provides a minimal but extensible DBC parser and runtime decode foundation for the **FrameTap** project.
 
-1. `dbc_parser` reads a DBC file
-2. parsed data is stored in `DbcDatabase`
-3. `dbc_tree_builder` converts it into a `TreeNode` hierarchy
-4. the resulting tree can later be adapted to `QAbstractItemModel`
+Its purpose is to:
 
-This keeps the parser independent from Qt and makes it easier to test and evolve.
+- parse DBC files
+- store parsed frame and signal metadata
+- build a tree for future UI integration
+- build a runtime-ready decode database
+- decode live CAN frames
+- decode CAN trace records using the same decoder
+
+The implementation follows a simple and practical design:
+
+- parser logic is separated from UI logic
+- runtime decode structures are separated from tree structures
+- Qt is not required at the parser or decoder level
+- the same decode engine can be reused for live traffic and trace replay
+
+This is **not a full production-grade DBC implementation yet**, but it is a strong architectural base.
 
 ---
 
-## Currently supported
+## High-Level Architecture
 
-### Frame definitions
+The module is divided into two main paths.
 
-Supported frame lines:
+### 1. Parse and UI path
+
+Used for:
+
+- browsing frames and signals
+- later integration with Qt `Model/View`
+- displaying metadata
+
+Pipeline:
 
 ```text
-BO_ 256 EngineData: 8 EEC1
+DBC file
+   ↓
+DbcParser
+   ↓
+DbcDatabase
+   ↓
+DbcTreeBuilder
+   ↓
+TreeNode hierarchy
+   ↓
+future Qt UI
+```
+
+### 2. Runtime decode path
+
+Used for:
+
+- live CAN decoding
+- CAN trace decoding
+- fast lookup by CAN ID
+
+Pipeline:
+
+```text
+DBC file
+   ↓
+DbcParser
+   ↓
+DbcDatabase
+   ↓
+DbcDecodeBuilder
+   ↓
+DecodeDatabase
+   ↓
+DbcDecoder
+   ↓
+Decoded values
+```
+
+This separation is intentional.
+
+The tree is useful for UI, but it is **not** the main data structure for runtime decoding.
+
+---
+
+## Why the Runtime Decode Layer Exists
+
+A tree structure is convenient for browsing, but a runtime decoder needs something different:
+
+- fast lookup by CAN ID
+- direct access to signal decode definitions
+- minimal overhead during repeated decoding
+- the same logic for live frames and trace frames
+
+Because of that, the design uses a dedicated runtime-ready structure:
+
+- `DecodeDatabase`
+- `DecodeFrame`
+- `DecodeSignal`
+
+This avoids forcing UI-oriented structures into a decode role they were not meant for.
+
+---
+
+## Module Layout
+
+### Parsed DBC structures
+
+Files:
+
+- `signal_info.h`
+- `frame_info.h`
+- `dbc_database.h`
+
+These store a readable representation of the parsed DBC file.
+
+### UI tree structures
+
+Files:
+
+- `tree_node.h`
+- `tree_node.cpp`
+- `dbc_tree_builder.h`
+- `dbc_tree_builder.cpp`
+
+These convert parsed DBC content into a tree hierarchy suitable for UI and model/view usage later.
+
+### Runtime decode structures
+
+Files:
+
+- `decode_database.h`
+- `dbc_decode_builder.h`
+- `dbc_decode_builder.cpp`
+
+These convert parsed DBC content into a structure optimized for decoding.
+
+### Runtime decoder
+
+Files:
+
+- `dbc_decoder.h`
+- `dbc_decoder.cpp`
+
+These perform actual decoding of raw CAN frames using `DecodeDatabase`.
+
+### Parser
+
+Files:
+
+- `dbc_parser.h`
+- `dbc_parser.cpp`
+
+These parse the DBC file itself.
+
+### Demo
+
+File:
+
+- `main.cpp`
+
+Used as a small integration example.
+
+---
+
+## Parsed Data Structures
+
+## `SignalInfo`
+
+Represents one signal as parsed from the DBC file.
+
+Fields:
+
+- `name`
+- `startBit`
+- `length`
+- `isLittleEndian`
+- `isSigned`
+- `factor`
+- `offset`
+- `minimum`
+- `maximum`
+- `unit`
+- `receivers`
+- `comment`
+
+Notes:
+
+- `receivers` is a list because a signal may have more than one receiver ECU
+- `factor` and `offset` define physical conversion
+- this structure is close to DBC content and easy to inspect
+
+Physical value rule:
+
+```text
+physical = raw * factor + offset
+```
+
+---
+
+## `FrameInfo`
+
+Represents one frame as parsed from the DBC file.
+
+Fields:
+
+- `name`
+- `canId`
+- `isExtended`
+- `pgn`
+- `hasPgn`
+- `dlc`
+- `transmitter`
+- `comment`
+- `signals`
+
+Notes:
+
+- `signals` is a list of `SignalInfo`
+- `isExtended` is determined during CAN ID normalization
+- `pgn` is derived using simplified J1939 logic when applicable
+
+---
+
+## `DbcDatabase`
+
+Top-level parsed DBC container.
+
+Conceptually:
+
+```text
+DbcDatabase
+ └── vector<FrameInfo>
+```
+
+This is the central structure produced by `DbcParser`.
+
+---
+
+## UI Tree Layer
+
+## `TreeNode`
+
+The UI tree contains three node types:
+
+- `Root`
+- `Frame`
+- `Signal`
+
+Example hierarchy:
+
+```text
+dbc
+ ├── EngineData
+ │    ├── EngineSpeed
+ │    ├── OilTemp
+ │    └── CoolantTemp
+ └── VehicleData
+      ├── VehicleSpeed
+      └── Odometer
+```
+
+Each node stores either:
+
+- `FrameInfo`
+- `SignalInfo`
+
+The tree is intended for browsing and later Qt model integration.
+
+It is **not** the primary runtime decode structure.
+
+---
+
+## Runtime Decode Layer
+
+## Purpose
+
+The decode layer exists so that decoding can be fast and independent from UI concerns.
+
+Instead of searching a tree, the decoder uses a prepared database with direct lookup.
+
+---
+
+## `ByteOrder`
+
+Runtime byte order enum:
+
+- `Intel`
+- `Motorola`
+
+This is better for decode code than passing around raw DBC characters.
+
+---
+
+## `ValueType`
+
+Numeric type enum:
+
+- `Unsigned`
+- `Signed`
+
+This is clearer than combining multiple boolean flags during runtime logic.
+
+---
+
+## `DecodeSignal`
+
+Represents one runtime-ready signal definition.
+
+Fields:
+
+- `name`
+- `startBit`
+- `length`
+- `byteOrder`
+- `valueType`
+- `factor`
+- `offset`
+- `minimum`
+- `maximum`
+- `unit`
+- `receivers`
+- `comment`
+
+This structure contains all information required for extracting and converting a signal value from raw frame data.
+
+---
+
+## `DecodeFrame`
+
+Represents one runtime-ready frame definition.
+
+Fields:
+
+- `name`
+- `canId`
+- `isExtended`
+- `dlc`
+- `pgn`
+- `hasPgn`
+- `transmitter`
+- `comment`
+- `signals`
+
+This structure is used directly by the decoder.
+
+---
+
+## `FrameKey`
+
+Fast lookup key for runtime frame matching.
+
+Fields:
+
+- `canId`
+- `isExtended`
+
+This matters because the same numeric identifier must not be confused between standard and extended frames.
+
+---
+
+## `DecodeDatabase`
+
+Top-level runtime decode container.
+
+Fields:
+
+- `frames`
+- `frameIndexByKey`
+
+Conceptually:
+
+```text
+DecodeDatabase
+ ├── vector<DecodeFrame>
+ └── unordered_map<FrameKey, index>
+```
+
+This gives the decoder fast access to a frame definition using CAN ID and frame type.
+
+---
+
+## Decoder Layer
+
+## `RawCanFrame`
+
+Represents a raw CAN frame to decode.
+
+Fields:
+
+- `canId`
+- `isExtended`
+- `data`
+
+This same structure can be used for:
+
+- live CAN bus input
+- replayed trace records
+- unit tests
+
+---
+
+## `DecodedSignalValue`
+
+Represents one decoded signal result.
+
+Fields:
+
+- `definition`
+- `rawValue`
+- `physicalValue`
+- `valid`
+
+---
+
+## `DecodedFrameValue`
+
+Represents one decoded frame result.
+
+Fields:
+
+- `definition`
+- `signals`
+- `valid`
+
+This is the decoder output for one raw frame.
+
+---
+
+## `DbcDecoder`
+
+Main runtime decoder class.
+
+Responsibilities:
+
+- find a frame definition by CAN ID
+- decode all signals in a frame
+- extract raw values
+- sign-extend signed values
+- convert raw values into physical values
+
+Main methods:
+
+- `FindFrame(...)`
+- `Decode(...)`
+
+---
+
+## Parser Support
+
+The current parser supports the following DBC elements:
+
+- `BO_`
+- `SG_`
+- `CM_ BO_`
+- `CM_ SG_`
+
+---
+
+## Supported DBC Syntax
+
+## Frame definition
+
+Example:
+
+```text
+BO_ 256 EngineData: 8 EEC1
+```
+
+Parsed fields:
+
+- frame CAN ID
+- frame name
+- DLC
+- transmitter ECU
+
+---
+
+## Signal definition
+
+Example:
+
+```text
+SG_ EngineSpeed : 0|16@1+ (0.125,0) [0|8000] "rpm" ECU1,ECU2
+```
+
+Parsed fields:
+
+- signal name
+- start bit
+- signal length
+- byte order
+- signedness
+- factor
+- offset
+- minimum
+- maximum
+- unit
+- receivers
+
+---
+
+## Comments
+
+Frame comment example:
+
+```text
+CM_ BO_ 256 "Engine data frame";
+```
+
+Signal comment example:
+
+```text
+CM_ SG_ 256 EngineSpeed "Actual engine speed";
+```
+
+Stored in:
+
+- `FrameInfo::comment`
+- `SignalInfo::comment`
+
+---
+
+## CAN ID Normalization
+
+The parser normalizes frame identifiers.
+
+Common DBC behavior:
+
+- extended identifiers may be stored with bit 31 set
+- the actual 29-bit identifier must be extracted from that value
+
+The parser therefore stores:
+
+- normalized `canId`
+- separate `isExtended` flag
+
+This is important both for correct lookup and for future interoperability with live CAN APIs.
+
+---
+
+## PGN Extraction
+
+PGN is derived only when the frame is treated as extended.
+
+The current logic is simplified J1939 extraction:
+
+- `pf`
+- `ps`
+- `dp`
+
+This is enough for a practical start but should not be treated as full J1939 validation.
+
+---
+
+## Decode Flow
+
+Typical runtime decode flow:
+
+```text
+RawCanFrame
+   ↓
+Find frame in DecodeDatabase
+   ↓
+For each signal:
+    extract raw bits
+    apply sign extension if needed
+    convert to physical value
+   ↓
+DecodedFrameValue
+```
+
+---
+
+## Intel and Motorola Extraction
+
+The decoder currently has separate extraction paths:
+
+- `ExtractIntel(...)`
+- `ExtractMotorola(...)`
+
+This is important because byte order is not just metadata once decoding starts.
+
+Intel and Motorola require different bit extraction logic.
+
+This is one of the main reasons why the runtime decode layer should be explicit and prepared in advance.
+
+---
+
+## Example Usage
+
+## Parse DBC
+
+```cpp
+DbcParser parser;
+DbcDatabase database = parser.ParseFile("example.dbc");
+```
+
+## Build UI tree
+
+```cpp
+DbcTreeBuilder treeBuilder;
+std::unique_ptr<TreeNode> root = treeBuilder.Build(database);
+```
+
+## Build runtime decode database
+
+```cpp
+DbcDecodeBuilder decodeBuilder;
+DecodeDatabase decodeDatabase = decodeBuilder.Build(database);
+```
+
+## Decode a raw frame
+
+```cpp
+RawCanFrame rawFrame;
+rawFrame.canId = 0x123;
+rawFrame.isExtended = false;
+rawFrame.data = {0x01, 0x02, 0x03, 0x04};
+
+DbcDecoder decoder;
+DecodedFrameValue decoded = decoder.Decode(decodeDatabase, rawFrame);
+```
+
+---
+
+## Unified Decode Strategy
+
+A key design goal is that the same decoder should work for both:
+
+- live CAN frames
+- trace replay frames
+
+That means this architecture supports:
+
+### live path
+
+```text
+live CAN input
+   ↓
+RawCanFrame
+   ↓
+DbcDecoder
+   ↓
+decoded signal values
+```
+
+### trace path
+
+```text
+trace reader
+   ↓
+RawCanFrame
+   ↓
+DbcDecoder
+   ↓
+decoded signal values
+```
+
+This avoids duplicating decode logic in two separate parts of the application.
+
+---
+
+## Intended Use in FrameTap
+
+This module is meant to support at least the following FrameTap workflows:
+
+- load a DBC file
+- browse frames and signals
+- search signals
+- drag a signal into a plot later
+- decode live CAN traffic
+- decode recorded traces
+- convert raw values into physical values
+- show metadata like units, comments, transmitter, receivers, and PGN
+
+Example combined workflow:
+
+```text
+Load DBC
+   ↓
+Parse into DbcDatabase
+   ↓
+Build UI tree
+   ↓
+Build DecodeDatabase
+   ↓
+Use same decode engine for:
+    - live frames
+    - trace replay
+```
+
+---
+
+## Why the Tree Is Not Enough
+
+The tree exists for browsing.
+
+However, runtime decode should not rely on tree traversal because that would introduce unnecessary coupling and inefficiency.
+
+A runtime decoder needs:
+
+- fast key-based access
+- minimal interpretation at decode time
+- direct signal definitions already prepared
+
+That is why `DecodeDatabase` is a separate layer.
+
+---
+
+## Why No Abstract Factory Is Used
+
+At the current stage, abstract factory is intentionally avoided.
+
+The current design is already clean:
+
+```text
+parser → parsed database → decode database
+                      ↘ tree builder → UI tree
+```
+
+Introducing factory layers now would increase complexity without solving an immediate problem.
+
+If later the project requires multiple output representations or multiple build strategies, that can be added then.
+
+---
+
+## Current Limitations
+
+This is still a minimal implementation.
+
+Not supported yet:
+
+- multiplexed signals
+- `VAL_` tables
+- `BA_` attributes
+- `BA_DEF_` definitions
+- advanced comment handling
+- full DBC grammar coverage
+- full J1939 validation
+- extensive edge-case handling for unusual DBC formatting
+
+Motorola extraction is implemented, but it should still be verified carefully against real-world DBC files and expected values.
+
+---
+
+## Recommended Next Steps
+
+A practical development order would be:
+
+### Stage 1 - already implemented
+
+- `BO_`
+- `SG_`
+- `CM_`
+- normalized CAN ID
+- `isExtended`
+- transmitter
+- receivers
+- comments
+- tree representation
+- runtime decode database
+- runtime decoder
+
+### Stage 2
+
+Recommended additions:
+
+- parent pointer in `TreeNode`
+- Qt model adapter
+- `VAL_` support for enum-style signals
+- better display strings for UI
+- selective decoding of only chosen signals
+
+### Stage 3
+
+Recommended additions:
+
+- multiplexing support
+- attribute parsing
+- richer J1939 support
+- CSV export of decoded traces
+- optimized filtering and signal selection
+
+### Stage 4
+
+Advanced functionality:
+
+- live plot integration
+- signal subscriptions
+- per-signal trace decode pipelines
+- decoder-assisted export formats
+
+---
+
+## Build Integration
+
+The module does not depend on any specific build system.
+
+It can be integrated with:
+
+- CMake
+- qmake
+- Makefile
+
+Just add the source files to the project.
+
+---
+
+## Summary
+
+This module is now split into two intentionally separate layers:
+
+### Parsed representation
+
+Used for:
+
+- storing parsed DBC content
+- browsing
+- UI tree generation
+
+### Runtime decode representation
+
+Used for:
+
+- fast frame lookup
+- live CAN decode
+- trace decode
+- physical value conversion
+
+That separation is the main architectural improvement.
+
+In short, the system now looks like this:
+
+```text
+DBC parser → DbcDatabase → DecodeDatabase → DbcDecoder
+                         ↘ TreeNode → future UI
+```
+
+This gives FrameTap a much better foundation for real use, because both browsing and decoding are supported without forcing one representation to do the other's job.

dbc.pro

@@ -4,6 +4,8 @@ CONFIG -= app_bundle
 CONFIG -= qt
 
 SOURCES += \
+        dbc_decode_builder.cpp \
+        dbc_decoder.cpp \
         dbc_parser.cpp \
         dbc_tree_builder.cpp \
         main.cpp \
@@ -11,8 +13,11 @@ SOURCES += \
 
 HEADERS += \
   dbc_database.h \
+  dbc_decode_builder.h \
+  dbc_decoder.h \
   dbc_parser.h \
   dbc_tree_builder.h \
+  decode_database.h \
   frame_info.h \
   signal_info.h \
   tree_node.h

dbc_database.h

@@ -9,7 +9,7 @@
  * @brief Parsed DBC content stored in a simple internal form.
  */
 struct DbcDatabase {
-  std::vector<FrameInfo> frames; /**< All frames found in DBC file. */
+  std::vector<FrameInfo> frames; /**< All frames found in the DBC file. */
 };
 
 #endif /* DBC_DATABASE_H */

dbc_decode_builder.cpp

@@ -0,0 +1,45 @@
+#include "dbc_decode_builder.h"
+
+DecodeDatabase DbcDecodeBuilder::Build (const DbcDatabase &source) const {
+  DecodeDatabase result;
+
+  for (std::size_t frameIndex = 0U; frameIndex < source.frames.size(); ++frameIndex) {
+    const FrameInfo &sourceFrame = source.frames[frameIndex];
+    DecodeFrame targetFrame;
+
+    targetFrame.name = sourceFrame.name;
+    targetFrame.canId = sourceFrame.canId;
+    targetFrame.isExtended = sourceFrame.isExtended;
+    targetFrame.dlc = sourceFrame.dlc;
+    targetFrame.pgn = sourceFrame.pgn;
+    targetFrame.hasPgn = sourceFrame.hasPgn;
+    targetFrame.transmitter = sourceFrame.transmitter;
+    targetFrame.comment = sourceFrame.comment;
+
+    for (std::size_t signalIndex = 0U; signalIndex < sourceFrame.signals.size(); ++signalIndex) {
+      const SignalInfo &sourceSignal = sourceFrame.signals[signalIndex];
+      DecodeSignal targetSignal;
+
+      targetSignal.name = sourceSignal.name;
+      targetSignal.startBit = sourceSignal.startBit;
+      targetSignal.length = sourceSignal.length;
+      targetSignal.byteOrder = sourceSignal.isLittleEndian ? ByteOrder::Intel : ByteOrder::Motorola;
+      targetSignal.valueType = sourceSignal.isSigned ? ValueType::Signed : ValueType::Unsigned;
+      targetSignal.factor = sourceSignal.factor;
+      targetSignal.offset = sourceSignal.offset;
+      targetSignal.minimum = sourceSignal.minimum;
+      targetSignal.maximum = sourceSignal.maximum;
+      targetSignal.unit = sourceSignal.unit;
+      targetSignal.receivers = sourceSignal.receivers;
+      targetSignal.comment = sourceSignal.comment;
+
+      targetFrame.signals.push_back (targetSignal);
+    }
+
+    result.frames.push_back (targetFrame);
+    result.frameIndexByKey[FrameKey (targetFrame.canId, targetFrame.isExtended)] =
+      result.frames.size() - 1U;
+  }
+
+  return result;
+}

dbc_decode_builder.h

@@ -0,0 +1,20 @@
+#ifndef DBC_DECODE_BUILDER_H
+#define DBC_DECODE_BUILDER_H
+
+#include "dbc_database.h"
+#include "decode_database.h"
+
+/**
+ * @brief Converts parsed DBC data into runtime decode database.
+ */
+class DbcDecodeBuilder {
+  public:
+    /**
+     * @brief Build runtime decode database.
+     * @param source Parsed DBC database.
+     * @return Runtime-ready decode database.
+     */
+    DecodeDatabase Build (const DbcDatabase &source) const;
+};
+
+#endif /* DBC_DECODE_BUILDER_H */

dbc_decoder.cpp

@@ -0,0 +1,146 @@
+#include "dbc_decoder.h"
+
+const DecodeFrame *DbcDecoder::FindFrame (const DecodeDatabase &database,
+    std::uint32_t canId,
+    bool isExtended) const {
+  const FrameKey key (canId, isExtended);
+  const std::unordered_map<FrameKey, std::size_t, FrameKeyHasher>::const_iterator it =
+    database.frameIndexByKey.find (key);
+
+  if (it == database.frameIndexByKey.end())
+    return nullptr;
+
+  const std::size_t index = it->second;
+  if (index >= database.frames.size())
+    return nullptr;
+
+  return &database.frames[index];
+}
+
+DecodedFrameValue DbcDecoder::Decode (const DecodeDatabase &database,
+                                      const RawCanFrame &frame) const {
+  DecodedFrameValue result;
+  const DecodeFrame *definition = FindFrame (database, frame.canId, frame.isExtended);
+
+  if (definition == nullptr)
+    return result;
+
+  result.definition = definition;
+  result.valid = true;
+
+  for (std::size_t signalIndex = 0U; signalIndex < definition->signals.size(); ++signalIndex) {
+    const DecodeSignal &signal = definition->signals[signalIndex];
+    DecodedSignalValue decoded;
+    std::uint64_t unsignedValue = 0U;
+
+    decoded.definition = &signal;
+
+    if (!ExtractUnsigned (frame.data, signal, unsignedValue)) {
+      decoded.valid = false;
+      result.signals.push_back (decoded);
+      continue;
+    }
+
+    if (signal.valueType == ValueType::Signed)
+      decoded.rawValue = SignExtend (unsignedValue, signal.length);
+    else
+      decoded.rawValue = static_cast<std::int64_t> (unsignedValue);
+
+    decoded.physicalValue =
+      (static_cast<double> (decoded.rawValue) * signal.factor) + signal.offset;
+    decoded.valid = true;
+
+    result.signals.push_back (decoded);
+  }
+
+  return result;
+}
+
+bool DbcDecoder::ExtractUnsigned (const std::vector<std::uint8_t> &data,
+                                  const DecodeSignal &signal,
+                                  std::uint64_t &value) {
+  if ((signal.length == 0U) || (signal.length > 64U))
+    return false;
+
+  if (signal.byteOrder == ByteOrder::Intel)
+    return ExtractIntel (data, signal.startBit, signal.length, value);
+
+  return ExtractMotorola (data, signal.startBit, signal.length, value);
+}
+
+bool DbcDecoder::ExtractIntel (const std::vector<std::uint8_t> &data,
+                               std::uint32_t startBit,
+                               std::uint32_t length,
+                               std::uint64_t &value) {
+  value = 0U;
+
+  for (std::uint32_t bitIndex = 0U; bitIndex < length; ++bitIndex) {
+    const std::uint32_t absoluteBit = startBit + bitIndex;
+    const std::uint32_t byteIndex = absoluteBit / 8U;
+    const std::uint32_t bitInByte = absoluteBit % 8U;
+
+    if (byteIndex >= data.size())
+      return false;
+
+    const std::uint64_t bitValue =
+      (static_cast<std::uint64_t> ((data[byteIndex] >> bitInByte) & 0x01U) << bitIndex);
+
+    value |= bitValue;
+  }
+
+  return true;
+}
+
+bool DbcDecoder::ExtractMotorola (const std::vector<std::uint8_t> &data,
+                                  std::uint32_t startBit,
+                                  std::uint32_t length,
+                                  std::uint64_t &value) {
+  /*
+   * DBC Motorola bit numbering:
+   * - startBit points to the most significant bit of the signal
+   * - inside a byte, bit numbering goes 7..0
+   * - crossing byte boundary moves to the next byte, bit 7
+   */
+
+  value = 0U;
+
+  std::int32_t currentBit = static_cast<std::int32_t> (startBit);
+
+  for (std::uint32_t bitIndex = 0U; bitIndex < length; ++bitIndex) {
+    if (currentBit < 0)
+      return false;
+
+    const std::uint32_t absoluteBit = static_cast<std::uint32_t> (currentBit);
+    const std::uint32_t byteIndex = absoluteBit / 8U;
+    const std::uint32_t bitFromMsb = absoluteBit % 8U;
+    const std::uint32_t bitInByte = 7U - bitFromMsb;
+
+    if (byteIndex >= data.size())
+      return false;
+
+    value <<= 1U;
+    value |= static_cast<std::uint64_t> ((data[byteIndex] >> bitInByte) & 0x01U);
+
+    if ((absoluteBit % 8U) == 7U)
+      currentBit = static_cast<std::int32_t> ((byteIndex + 1U) * 8U);
+    else
+      --currentBit;
+  }
+
+  return true;
+}
+
+std::int64_t DbcDecoder::SignExtend (std::uint64_t value, std::uint32_t bitLength) {
+  if ((bitLength == 0U) || (bitLength >= 64U))
+    return static_cast<std::int64_t> (value);
+
+  const std::uint64_t signMask = (static_cast<std::uint64_t> (1U) << (bitLength - 1U));
+  const std::uint64_t valueMask = (static_cast<std::uint64_t> (1U) << bitLength) - 1U;
+
+  value &= valueMask;
+
+  if ((value & signMask) == 0U)
+    return static_cast<std::int64_t> (value);
+
+  return static_cast<std::int64_t> (value | (~valueMask));
+}

dbc_decoder.h

@@ -0,0 +1,99 @@
+#ifndef DBC_DECODER_H
+#define DBC_DECODER_H
+
+#include <vector>
+#include <cstdint>
+
+#include "decode_database.h"
+
+/**
+ * @brief Raw CAN frame used for runtime or trace decoding.
+ */
+struct RawCanFrame {
+  std::uint32_t canId;           /**< Normalized CAN ID. */
+  bool isExtended;               /**< true for extended frame. */
+  std::vector<std::uint8_t> data; /**< Payload bytes. */
+
+  RawCanFrame()
+    : canId (0U)
+    , isExtended (false)
+    , data() {
+  }
+};
+
+/**
+ * @brief One decoded signal value.
+ */
+struct DecodedSignalValue {
+  const DecodeSignal *definition; /**< Signal definition. */
+  std::int64_t rawValue;          /**< Extracted raw integer value. */
+  double physicalValue;           /**< Converted physical value. */
+  bool valid;                     /**< true if decoding succeeded. */
+
+  DecodedSignalValue()
+    : definition (nullptr)
+    , rawValue (0)
+    , physicalValue (0.0)
+    , valid (false) {
+  }
+};
+
+/**
+ * @brief Fully decoded frame.
+ */
+struct DecodedFrameValue {
+  const DecodeFrame *definition;          /**< Frame definition. */
+  std::vector<DecodedSignalValue> signals; /**< Decoded signal values. */
+  bool valid;                             /**< true if frame was matched. */
+
+  DecodedFrameValue()
+    : definition (nullptr)
+    , signals()
+    , valid (false) {
+  }
+};
+
+/**
+ * @brief Runtime CAN decoder using prebuilt decode database.
+ */
+class DbcDecoder {
+  public:
+    /**
+     * @brief Find frame definition by CAN ID.
+     * @param database Runtime decode database.
+     * @param canId Normalized CAN ID.
+     * @param isExtended true for extended frame.
+     * @return Pointer to frame definition or nullptr.
+     */
+    const DecodeFrame *FindFrame (const DecodeDatabase &database,
+                                  std::uint32_t canId,
+                                  bool isExtended) const;
+
+    /**
+     * @brief Decode one raw CAN frame.
+     * @param database Runtime decode database.
+     * @param frame Raw CAN frame.
+     * @return Decoded frame value.
+     */
+    DecodedFrameValue Decode (const DecodeDatabase &database,
+                              const RawCanFrame &frame) const;
+
+  private:
+    static bool ExtractUnsigned (const std::vector<std::uint8_t> &data,
+                                 const DecodeSignal &signal,
+                                 std::uint64_t &value);
+
+    static bool ExtractIntel (const std::vector<std::uint8_t> &data,
+                              std::uint32_t startBit,
+                              std::uint32_t length,
+                              std::uint64_t &value);
+
+    static bool ExtractMotorola (const std::vector<std::uint8_t> &data,
+                                 std::uint32_t startBit,
+                                 std::uint32_t length,
+                                 std::uint64_t &value);
+
+    static std::int64_t SignExtend (std::uint64_t value, std::uint32_t bitLength);
+};
+
+#endif /* DBC_DECODER_H */

dbc_parser.cpp

@@ -3,7 +3,6 @@
 #include <fstream>
 #include <sstream>
 #include <stdexcept>
-#include <algorithm>
 #include <cctype>
 
 namespace {
@@ -14,11 +13,13 @@ namespace {
    */
   std::string TrimText (const std::string &text) {
     std::string::size_type begin = 0U;
-    while ((begin < text.size()) && std::isspace (static_cast<unsigned char> (text[begin])))
+    while ((begin < text.size()) &&
+           std::isspace (static_cast<unsigned char> (text[begin])))
       ++begin;
 
     std::string::size_type end = text.size();
-    while ((end > begin) && std::isspace (static_cast<unsigned char> (text[end - 1U])))
+    while ((end > begin) &&
+           std::isspace (static_cast<unsigned char> (text[end - 1U])))
       --end;
 
     return text.substr (begin, end - begin);
@@ -86,13 +87,29 @@ std::vector<std::string> DbcParser::SplitReceivers (const std::string &text) {
   return receivers;
 }
 
-std::uint32_t DbcParser::TryExtractPgn (std::uint32_t canId, bool &hasPgn) {
+void DbcParser::NormalizeCanId (std::uint32_t rawCanId,
+                                std::uint32_t &normalizedCanId,
+                                bool &isExtended) {
+  /*
+   * DBC commonly stores extended identifiers with bit 31 set.
+   * Example:
+   * raw id = 0x80000000 | actual_29_bit_id
+   */
+  if ((rawCanId & 0x80000000U) != 0U) {
+    isExtended = true;
+    normalizedCanId = (rawCanId & 0x1FFFFFFFU);
+  } else {
+    isExtended = (rawCanId > 0x7FFU);
+    normalizedCanId = rawCanId;
+  }
+}
+
+std::uint32_t DbcParser::TryExtractPgn (std::uint32_t canId, bool isExtended, bool &hasPgn) {
   hasPgn = false;
 
-  /*
-   * Very simplified J1939 PGN extraction.
-   * Assumes 29-bit identifier.
-   */
+  if (!isExtended)
+    return 0U;
+
   if ((canId & 0x1FFFFFFFU) != canId)
     return 0U;
 
@@ -114,20 +131,22 @@ std::uint32_t DbcParser::TryExtractPgn (std::uint32_t canId, bool &hasPgn) {
 FrameInfo DbcParser::ParseFrameLine (const std::string &line) {
   /*
    * Example:
-   * BO_ 256 EngineData: 8 Vector__XXX
+   * BO_ 256 EngineData: 8 EEC1
    */
 
   std::istringstream stream (line);
   std::string token;
   FrameInfo frame;
+  std::uint32_t rawCanId = 0U;
 
   stream >> token;
   if (token != "BO_")
     throw std::runtime_error ("Invalid frame line: " + line);
 
-  stream >> frame.canId;
-  stream >> token;
+  stream >> rawCanId;
+  NormalizeCanId (rawCanId, frame.canId, frame.isExtended);
 
+  stream >> token;
   if (token.empty())
     throw std::runtime_error ("Missing frame name: " + line);
 
@@ -143,7 +162,7 @@ FrameInfo DbcParser::ParseFrameLine (const std::string &line) {
   }
 
   stream >> frame.transmitter;
-  frame.pgn = TryExtractPgn (frame.canId, frame.hasPgn);
+  frame.pgn = TryExtractPgn (frame.canId, frame.isExtended, frame.hasPgn);
 
   return frame;
 }
@@ -151,7 +170,7 @@ FrameInfo DbcParser::ParseFrameLine (const std::string &line) {
 SignalInfo DbcParser::ParseSignalLine (const std::string &line) {
   /*
    * Example:
-   * SG_ EngineSpeed : 0|16@1+ (0.125,0) [0|8000] "rpm" Vector__XXX
+   * SG_ EngineSpeed : 0|16@1+ (0.125,0) [0|8000] "rpm" ECU1,ECU2
    */
 
   SignalInfo signal;
@@ -258,8 +277,12 @@ void DbcParser::ParseCommentLine (const std::string &line, DbcDatabase &database
   stream >> token;
 
   if (token == "BO_") {
+    std::uint32_t rawCanId = 0U;
     std::uint32_t canId = 0U;
-    stream >> canId;
+    bool isExtended = false;
+
+    stream >> rawCanId;
+    NormalizeCanId (rawCanId, canId, isExtended);
 
     const std::string::size_type quoteBegin = line.find ('"');
     const std::string::size_type quoteEnd = line.rfind ('"');
@@ -269,16 +292,20 @@ void DbcParser::ParseCommentLine (const std::string &line, DbcDatabase &database
         (quoteEnd <= quoteBegin))
       return;
 
-    FrameInfo *frame = FindFrameById (database, canId);
+    FrameInfo *frame = FindFrameById (database, canId, isExtended);
     if (frame != nullptr)
       frame->comment = line.substr (quoteBegin + 1U, quoteEnd - quoteBegin - 1U);
   } else if (token == "SG_") {
+    std::uint32_t rawCanId = 0U;
     std::uint32_t canId = 0U;
+    bool isExtended = false;
     std::string signalName;
 
-    stream >> canId;
+    stream >> rawCanId;
     stream >> signalName;
 
+    NormalizeCanId (rawCanId, canId, isExtended);
+
     const std::string::size_type quoteBegin = line.find ('"');
     const std::string::size_type quoteEnd = line.rfind ('"');
 
@@ -287,7 +314,7 @@ void DbcParser::ParseCommentLine (const std::string &line, DbcDatabase &database
         (quoteEnd <= quoteBegin))
       return;
 
-    FrameInfo *frame = FindFrameById (database, canId);
+    FrameInfo *frame = FindFrameById (database, canId, isExtended);
     if (frame != nullptr) {
       SignalInfo *signal = FindSignalByName (*frame, signalName);
       if (signal != nullptr)
@@ -296,9 +323,12 @@ void DbcParser::ParseCommentLine (const std::string &line, DbcDatabase &database
   }
 }
 
-FrameInfo *DbcParser::FindFrameById (DbcDatabase &database, std::uint32_t canId) {
+FrameInfo *DbcParser::FindFrameById (DbcDatabase &database,
+                                     std::uint32_t canId,
+                                     bool isExtended) {
   for (std::size_t index = 0U; index < database.frames.size(); ++index) {
-    if (database.frames[index].canId == canId)
+    if ((database.frames[index].canId == canId) &&
+        (database.frames[index].isExtended == isExtended))
       return &database.frames[index];
   }
 

dbc_parser.h

@@ -37,14 +37,21 @@ class DbcParser {
     static bool IsCommentLine (const std::string &line);
     static std::string Trim (const std::string &text);
     static std::vector<std::string> SplitReceivers (const std::string &text);
-    static std::uint32_t TryExtractPgn (std::uint32_t canId, bool &hasPgn);
+    static std::uint32_t TryExtractPgn (std::uint32_t canId, bool isExtended, bool &hasPgn);
+
+    static void NormalizeCanId (std::uint32_t rawCanId,
+                                std::uint32_t &normalizedCanId,
+                                bool &isExtended);
 
     static FrameInfo ParseFrameLine (const std::string &line);
     static SignalInfo ParseSignalLine (const std::string &line);
 
     static void ParseCommentLine (const std::string &line, DbcDatabase &database);
 
-    static FrameInfo *FindFrameById (DbcDatabase &database, std::uint32_t canId);
+    static FrameInfo *FindFrameById (DbcDatabase &database,
+                                     std::uint32_t canId,
+                                     bool isExtended);
+
     static SignalInfo *FindSignalByName (FrameInfo &frame, const std::string &signalName);
 };
 

decode_database.h

@@ -0,0 +1,126 @@
+#ifndef DECODE_DATABASE_H
+#define DECODE_DATABASE_H
+
+#include <string>
+#include <vector>
+#include <unordered_map>
+#include <cstdint>
+
+/**
+ * @brief Signal byte order used for runtime decoding.
+ */
+enum class ByteOrder {
+  Intel,
+  Motorola
+};
+
+/**
+ * @brief Signal numeric type.
+ */
+enum class ValueType {
+  Unsigned,
+  Signed
+};
+
+/**
+ * @brief Runtime-ready signal definition.
+ */
+struct DecodeSignal {
+  std::string name;                   /**< Signal name. */
+  std::uint32_t startBit;             /**< DBC start bit. */
+  std::uint32_t length;               /**< Signal length in bits. */
+  ByteOrder byteOrder;                /**< Intel or Motorola. */
+  ValueType valueType;                /**< Signed or unsigned. */
+  double factor;                      /**< Scaling factor. */
+  double offset;                      /**< Physical offset. */
+  double minimum;                     /**< Minimum physical value. */
+  double maximum;                     /**< Maximum physical value. */
+  std::string unit;                   /**< Physical unit. */
+  std::vector<std::string> receivers; /**< Receivers. */
+  std::string comment;                /**< Comment. */
+
+  DecodeSignal()
+    : name()
+    , startBit (0U)
+    , length (0U)
+    , byteOrder (ByteOrder::Intel)
+    , valueType (ValueType::Unsigned)
+    , factor (1.0)
+    , offset (0.0)
+    , minimum (0.0)
+    , maximum (0.0)
+    , unit()
+    , receivers()
+    , comment() {
+  }
+};
+
+/**
+ * @brief Runtime-ready frame definition.
+ */
+struct DecodeFrame {
+  std::string name;                /**< Frame name. */
+  std::uint32_t canId;             /**< Normalized CAN ID. */
+  bool isExtended;                 /**< true for extended frame. */
+  std::uint8_t dlc;                /**< Payload length. */
+  std::uint32_t pgn;               /**< PGN if available. */
+  bool hasPgn;                     /**< true if PGN is valid. */
+  std::string transmitter;         /**< Transmitter ECU. */
+  std::string comment;             /**< Frame comment. */
+  std::vector<DecodeSignal> signals; /**< Signal definitions. */
+
+  DecodeFrame()
+    : name()
+    , canId (0U)
+    , isExtended (false)
+    , dlc (0U)
+    , pgn (0U)
+    , hasPgn (false)
+    , transmitter()
+    , comment()
+    , signals() {
+  }
+};
+
+/**
+ * @brief Key for fast frame lookup.
+ */
+struct FrameKey {
+  std::uint32_t canId;
+  bool isExtended;
+
+  FrameKey()
+    : canId (0U)
+    , isExtended (false) {
+  }
+
+  FrameKey (std::uint32_t id, bool extended)
+    : canId (id)
+    , isExtended (extended) {
+  }
+
+  bool operator== (const FrameKey &other) const {
+    return (canId == other.canId) && (isExtended == other.isExtended);
+  }
+};
+
+/**
+ * @brief Hasher for frame key.
+ */
+struct FrameKeyHasher {
+  std::size_t operator() (const FrameKey &key) const {
+    const std::size_t a = static_cast<std::size_t> (key.canId);
+    const std::size_t b = key.isExtended ? 1U : 0U;
+    return (a * 1315423911U) ^ b;
+  }
+};
+
+/**
+ * @brief Runtime decode database with fast lookup by CAN ID.
+ */
+struct DecodeDatabase {
+  std::vector<DecodeFrame> frames;
+  std::unordered_map<FrameKey, std::size_t, FrameKeyHasher> frameIndexByKey;
+};
+
+#endif /* DECODE_DATABASE_H */

frame_info.h

@@ -11,18 +11,20 @@
  * @brief Describes one CAN frame from a DBC file.
  */
 struct FrameInfo {
-  std::string name;                  /**< Frame name. */
-  std::uint32_t canId;               /**< Raw CAN identifier from DBC. */
-  std::uint32_t pgn;                 /**< J1939 PGN if applicable. */
-  bool hasPgn;                       /**< true if PGN was derived. */
-  std::uint8_t dlc;                  /**< Frame payload length. */
-  std::string transmitter;           /**< Transmitter ECU name. */
-  std::string comment;               /**< Optional frame comment. */
-  std::vector<SignalInfo> signals;   /**< Signals contained in the frame. */
+  std::string name;                /**< Frame name. */
+  std::uint32_t canId;             /**< Normalized CAN identifier. */
+  bool isExtended;                 /**< true for extended frame. */
+  std::uint32_t pgn;               /**< J1939 PGN if applicable. */
+  bool hasPgn;                     /**< true if PGN was derived. */
+  std::uint8_t dlc;                /**< Frame payload length. */
+  std::string transmitter;         /**< Transmitter ECU name. */
+  std::string comment;             /**< Optional frame comment. */
+  std::vector<SignalInfo> signals; /**< Signals contained in the frame. */
 
   FrameInfo()
     : name()
     , canId (0U)
+    , isExtended (false)
     , pgn (0U)
     , hasPgn (false)
     , dlc (0U)

main.cpp

@@ -1,19 +1,13 @@
 #include <iostream>
+#include <iomanip>
 #include <memory>
+#include <vector>
 #include <cstddef>
 
 #include "dbc_parser.h"
 #include "dbc_tree_builder.h"
-#include "tree_node.h"
-
-static void PrintReceivers (const std::vector<std::string> &receivers) {
-  for (std::size_t index = 0U; index < receivers.size(); ++index) {
-    if (index != 0U)
-      std::cout << ",";
-
-    std::cout << receivers[index];
-  }
-}
+#include "dbc_decode_builder.h"
+#include "dbc_decoder.h"
 
 static void PrintTree (const TreeNode *node, int indent) {
   if (node == nullptr)
@@ -32,15 +26,12 @@ static void PrintTree (const TreeNode *node, int indent) {
       std::cout << "[frame] " << node->GetName();
 
       if (frame != nullptr) {
-        std::cout << " id=" << frame->canId
-                  << " dlc=" << static_cast<unsigned int> (frame->dlc)
-                  << " tx=" << frame->transmitter;
+        std::cout << " id=0x" << std::hex << frame->canId << std::dec
+                  << " ext=" << (frame->isExtended ? "yes" : "no")
+                  << " dlc=" << static_cast<unsigned int> (frame->dlc);
 
         if (frame->hasPgn)
           std::cout << " pgn=" << frame->pgn;
-
-        if (!frame->comment.empty())
-          std::cout << " comment=\"" << frame->comment << "\"";
       }
 
       std::cout << "\n";
@@ -54,13 +45,7 @@ static void PrintTree (const TreeNode *node, int indent) {
       if (signal != nullptr) {
         std::cout << " start=" << signal->startBit
                   << " len=" << signal->length
-                  << " unit=" << signal->unit
-                  << " rx=";
-
-        PrintReceivers (signal->receivers);
-
-        if (!signal->comment.empty())
-          std::cout << " comment=\"" << signal->comment << "\"";
+                  << " unit=" << signal->unit;
       }
 
       std::cout << "\n";
@@ -76,6 +61,28 @@ static void PrintTree (const TreeNode *node, int indent) {
     PrintTree (node->GetChild (i), indent + 1);
 }
 
+static void PrintDecodedFrame (const DecodedFrameValue &decoded) {
+  if (!decoded.valid || (decoded.definition == nullptr)) {
+    std::cout << "No frame definition found.\n";
+    return;
+  }
+
+  std::cout << "Decoded frame: " << decoded.definition->name << "\n";
+
+  for (std::size_t index = 0U; index < decoded.signals.size(); ++index) {
+    const DecodedSignalValue &signal = decoded.signals[index];
+
+    if ((signal.definition == nullptr) || !signal.valid)
+      continue;
+
+    std::cout << "  " << signal.definition->name
+              << " raw=" << signal.rawValue
+              << " physical=" << signal.physicalValue
+              << " " << signal.definition->unit
+              << "\n";
+  }
+}
+
 int main (int argc, char *argv[]) {
   if (argc < 2) {
     std::cerr << "Usage: dbc_demo <file.dbc>\n";
@@ -86,10 +93,29 @@ int main (int argc, char *argv[]) {
     DbcParser parser;
     DbcDatabase database = parser.ParseFile (argv[1]);
 
-    DbcTreeBuilder builder;
-    std::unique_ptr<TreeNode> root = builder.Build (database);
+    DbcTreeBuilder treeBuilder;
+    std::unique_ptr<TreeNode> root = treeBuilder.Build (database);
 
+    std::cout << "=== Parsed tree ===\n";
     PrintTree (root.get(), 0);
+
+    DbcDecodeBuilder decodeBuilder;
+    DecodeDatabase decodeDatabase = decodeBuilder.Build (database);
+
+    /*
+     * Example raw frame.
+     * Replace with live CAN frame or trace record later.
+     */
+    RawCanFrame rawFrame;
+    rawFrame.canId = decodeDatabase.frames.empty() ? 0U : decodeDatabase.frames[0].canId;
+    rawFrame.isExtended = decodeDatabase.frames.empty() ? false : decodeDatabase.frames[0].isExtended;
+    rawFrame.data.resize (8U, 0U);
+
+    DbcDecoder decoder;
+    DecodedFrameValue decoded = decoder.Decode (decodeDatabase, rawFrame);
+
+    std::cout << "\n=== Decoded frame ===\n";
+    PrintDecodedFrame (decoded);
   } catch (const std::exception &ex) {
     std::cerr << "Error: " << ex.what() << "\n";
     return 2;

signal_info.h

@@ -19,7 +19,7 @@ struct SignalInfo {
   double minimum;                     /**< Minimum physical value. */
   double maximum;                     /**< Maximum physical value. */
   std::string unit;                   /**< Physical unit. */
-  std::vector<std::string> receivers; /**< Receivers of this signal. */
+  std::vector<std::string> receivers; /**< Signal receivers. */
   std::string comment;                /**< Optional signal comment. */
 
   SignalInfo()