From cb20f5fe55200118bf8b9a5954faba3fa04402c4 Mon Sep 17 00:00:00 2001 From: deeaitch Date: Fri, 13 Mar 2026 13:14:20 -0400 Subject: [PATCH] update readme --- README.md | 521 +++++++++++++++++++++++++++++------------------------- 1 file changed, 284 insertions(+), 237 deletions(-) diff --git a/README.md b/README.md index 8f40ee7..30cdb2d 100644 --- a/README.md +++ b/README.md @@ -1,263 +1,295 @@ -DBC Parser Documentation -Overview -This module implements a minimal DBC parser intended for use in the FrameTap project. +# DBC Parser Module Documentation + +## Overview + +This module implements a minimal DBC parser intended for use in the **FrameTap** project. Its purpose is to read a DBC file and convert it into an internal representation that can later be used for: - displaying CAN frames and signals +- displaying CAN frames and signals +- building a hierarchical structure for UI +- integrating with Qt Model/View +- selecting signals for plotting +- preparing for runtime CAN/J1939 decoding - building a hierarchical structure for UI +The implementation intentionally follows the **KISS principle**: - integrating with Qt Model/View +- simple +- readable +- easy to modify +- independent from Qt - selecting signals for plotting +This is **not a full DBC parser**, but a practical foundation that can be extended gradually. - preparing for runtime CAN/J1939 decoding +--- -The implementation intentionally follows the KISS principle: - - simple - - readable - - easy to modify - - independent from Qt - -This is not a full DBC parser, but a practical foundation that can be extended gradually. -Architecture +# Architecture The module uses a simple processing pipeline. -DBC file - ↓ -DbcParser - ↓ -DbcDatabase - ↓ -DbcTreeBuilder - ↓ -TreeNode hierarchy - ↓ -Future Qt Model/View integration +DBC file +↓ +DbcParser +↓ +DbcDatabase +↓ +DbcTreeBuilder +↓ +TreeNode hierarchy +↓ +Future Qt Model/View integration Each component has a clear responsibility. -Component Responsibility -DbcParser Reads and parses the DBC file -DbcDatabase Stores parsed frames and signals -DbcTreeBuilder Converts the database into a tree -TreeNode Represents hierarchical nodes + +| Component | Responsibility | +|-----------|---------------| +| DbcParser | Reads and parses the DBC file | +| DbcDatabase | Stores parsed frames and signals | +| DbcTreeBuilder | Converts the database into a tree | +| TreeNode | Represents hierarchical nodes | This separation allows the parser to remain independent from UI or visualization logic. -File Structure + +--- + +# File Structure The module consists of several logical parts. -Data structures + +## Data structures Files: -signal_info.h -frame_info.h -dbc_database.h +signal_info.h +frame_info.h +dbc_database.h These files define the internal representation of parsed data. -Tree representation + +## Tree representation Files: -tree_node.h -tree_node.cpp +tree_node.h +tree_node.cpp Defines a simple hierarchical structure that can later be used by UI components. -Parser + +## Parser Files: -dbc_parser.h -dbc_parser.cpp +dbc_parser.h +dbc_parser.cpp Responsible for reading the DBC file and extracting frame and signal information. -Tree builder + +## Tree builder Files: -dbc_tree_builder.h -dbc_tree_builder.cpp +dbc_tree_builder.h +dbc_tree_builder.cpp Converts the parsed database into a tree representation. -Data Structures -SignalInfo + +--- + +# Data Structures + +## SignalInfo Represents a single signal defined in a DBC file. Fields: -name -startBit -length -isLittleEndian -isSigned -factor -offset -minimum -maximum -unit -receivers -comment +- name +- startBit +- length +- isLittleEndian +- isSigned +- factor +- offset +- minimum +- maximum +- unit +- receivers +- comment Notes: - receivers may contain multiple ECUs - - comment is optional - - factor and offset define physical conversion +- receivers may contain multiple ECUs +- comment is optional +- factor and offset define physical conversion Physical value is calculated as: physical = raw * factor + offset -FrameInfo +--- + +## FrameInfo Represents a CAN frame. Fields: -name -canId -dlc -transmitter -comment -signals -pgn -hasPgn +- name +- canId +- dlc +- transmitter +- comment +- signals +- pgn +- hasPgn Notes: - signals is a vector of SignalInfo +- signals is a vector of SignalInfo +- transmitter is the ECU that sends the frame +- pgn is derived using simplified J1939 logic - transmitter is the ECU that sends the frame +--- - pgn is derived if the frame appears to follow J1939 rules - -DbcDatabase +## DbcDatabase Top level container for parsed data. -DbcDatabase - └── vector +DbcDatabase +└── vector This structure represents the entire DBC file content. -Tree Representation + +--- + +# Tree Representation The module converts the parsed data into a tree. Node types: -Root -Frame -Signal +- Root +- Frame +- Signal Example structure: -dbc - ├── EngineData - │ ├── EngineSpeed - │ ├── OilTemp - │ └── CoolantTemp - └── VehicleData - ├── VehicleSpeed - └── Odometer +dbc +├── EngineData +│ ├── EngineSpeed +│ ├── OilTemp +│ └── CoolantTemp +└── VehicleData + ├── VehicleSpeed + └── Odometer Each node stores either: - FrameInfo - - SignalInfo +- FrameInfo +- SignalInfo This tree structure is designed to integrate easily with Qt Model/View. -Parser + +--- + +# Parser The parser is implemented in: -dbc_parser.h -dbc_parser.cpp +dbc_parser.h +dbc_parser.cpp It performs line-based parsing of the DBC file. Supported elements: -BO_ -SG_ -CM_ +- BO_ +- SG_ +- CM_ -Supported DBC Syntax -Frame Definition +--- + +# Supported DBC Syntax + +## Frame Definition Example: BO_ 256 EngineData: 8 EEC1 Parsed values: -Field Meaning -256 CAN identifier -EngineData frame name -8 DLC -EEC1 transmitter ECU -Signal Definition + +| Field | Meaning | +|------|---------| +| 256 | CAN identifier | +| EngineData | frame name | +| 8 | DLC | +| EEC1 | transmitter ECU | + +--- + +## Signal Definition Example: SG_ EngineSpeed : 0|16@1+ (0.125,0) [0|8000] "rpm" ECU1,ECU2 Parsed values: -Field Meaning -EngineSpeed signal name -0 start bit -16 signal length -@1 little endian -+ unsigned -factor 0.125 -offset 0 -minimum 0 -maximum 8000 -unit rpm -receivers ECU1, ECU2 -Comments -Frame comment: +| Field | Meaning | +|------|---------| +| EngineSpeed | signal name | +| 0 | start bit | +| 16 | signal length | +| @1 | little endian | +| + | unsigned | +| factor | 0.125 | +| offset | 0 | +| minimum | 0 | +| maximum | 8000 | +| unit | rpm | +| receivers | ECU1, ECU2 | + +--- + +## Comments + +Frame comment example: CM_ BO_ 256 "Engine data frame"; -Signal comment: +Signal comment example: CM_ SG_ 256 EngineSpeed "Actual engine speed"; -These values are stored in: +Stored in: -FrameInfo::comment -SignalInfo::comment +- FrameInfo::comment +- SignalInfo::comment -PGN Extraction +--- + +# PGN Extraction PGN is derived using simplified J1939 logic. -Typical J1939 identifier layout: +Typical identifier layout: -Priority -Reserved -Data Page -PDU Format -PDU Specific -Source Address +Priority +Reserved +Data Page +PDU Format +PDU Specific +Source Address -The parser extracts PGN from the 29-bit CAN ID. +The parser extracts PGN from the 29‑bit CAN identifier. -This is a simplified approximation and should not be considered full J1939 validation. -Example Usage +This is only an approximation and not full J1939 validation. -Typical usage: +--- + +# Example Usage DbcParser parser; @@ -268,123 +300,134 @@ DbcTreeBuilder builder; std::unique_ptr root = builder.Build(database); After this step, the tree can be used by a UI or visualization system. -Example Tree -Example output structure: +--- -dbc - ├── EngineData - │ ├── EngineSpeed - │ ├── OilTemp - │ └── CoolantTemp - └── VehicleData - ├── VehicleSpeed - └── Odometer +# Example Tree -Limitations +dbc +├── EngineData +│ ├── EngineSpeed +│ ├── OilTemp +│ └── CoolantTemp +└── VehicleData + ├── VehicleSpeed + └── Odometer + +--- + +# Limitations The current implementation intentionally does not support many advanced DBC features. Not supported yet: -multiplexed signals -BA_ attributes -BA_DEF_ definitions -VAL_ value tables -signal groups -advanced comments -complex syntax variations +- multiplexed signals +- BA_ attributes +- BA_DEF_ definitions +- VAL_ value tables +- signal groups +- complex syntax variations These can be added later if required. -Design Principles -KISS -The parser is intentionally simple. +--- -It avoids complex grammar systems and tokenizers in order to keep the code easy to understand and maintain. -Separation of Concerns +# Design Principles + +## KISS + +The parser avoids complex grammar systems or tokenizers in order to keep the code easy to understand and maintain. + +## Separation of Concerns Parsing, storage, and tree building are separate components. -This makes it easier to: +This allows reuse for: - test the parser +- GUI display +- runtime decoding +- export +- filtering +- testing - change UI representation - - export data - - reuse the module elsewhere - -Qt Independence +## Qt Independence The parser itself does not depend on Qt. Qt integration should be implemented through a separate adapter layer. -Future Development + +--- + +# Future Development Recommended evolution path. -Stage 1 (current) -BO_ -SG_ -CM_ -transmitter -receivers -basic PGN extraction -tree representation +## Stage 1 (current) -Stage 2 +- BO_ +- SG_ +- CM_ +- transmitter +- receivers +- basic PGN extraction +- tree representation + +## Stage 2 Add: -extended CAN ID detection -better PGN extraction -TreeNode parent pointer -Qt Model adapter +- extended CAN ID detection +- better PGN extraction +- parent pointer in TreeNode +- Qt Model adapter -Stage 3 +## Stage 3 Add support for: -VAL_ value tables -BA_ attributes -BA_DEF_ definitions -extended comments +- VAL_ value tables +- BA_ attributes +- BA_DEF_ definitions +- extended comments -Stage 4 +## Stage 4 Advanced functionality: -multiplexing -runtime signal decoding -integration with CAN stream -drag-and-drop plotting +- multiplexing +- runtime signal decoding +- integration with CAN stream +- drag‑and‑drop plotting -Intended Usage in FrameTap +--- -This module will allow FrameTap to: +# Intended Usage in FrameTap -load DBC files -display frames and signals -select signals -search signals -display metadata -prepare runtime decoding +This module allows FrameTap to: + +- load DBC files +- display frames and signals +- select signals +- search signals +- display metadata +- prepare runtime decoding Example workflow: -Load DBC - ↓ -Browse signals - ↓ -Select signal - ↓ -Decode CAN frames - ↓ -Plot physical values +Load DBC +↓ +Browse signals +↓ +Select signal +↓ +Decode CAN frames +↓ +Plot physical values -Why Abstract Factory Is Not Used +--- + +# Why Abstract Factory Is Not Used An abstract factory is intentionally not used at this stage. @@ -392,40 +435,44 @@ The current structure already separates responsibilities clearly: parser → database → tree builder → tree -Introducing factories now would increase complexity without significant benefit. +Factories can be introduced later if multiple internal representations become necessary. -Factories can be added later if multiple internal representations are required. -Build Integration +--- + +# Build Integration The module is independent of any specific build system. It can be integrated using: -CMake -qmake -Makefile +- CMake +- qmake +- Makefile -Simply add the source files to the project. -Summary +Simply include the source files in your project. -This module provides a minimal but extensible DBC parser designed for FrameTap. +--- + +# Summary + +This module provides a minimal but extensible DBC parser designed for **FrameTap**. Key properties: -simple -modular -Qt-independent -extendable +- simple +- modular +- Qt‑independent +- extendable It converts a DBC file into an internal structure: frame → signals -with additional metadata such as: +with metadata such as: -transmitter -receivers -comments -basic PGN information +- transmitter +- receivers +- comments +- basic PGN information -This forms the foundation for future CAN signal visualization and decoding. \ No newline at end of file +This forms the foundation for future CAN signal visualization and decoding.