automotive/dbc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
deeaitch
2026-03-13 13:14:20 -04:00
parent f2aa10cee4
commit cb20f5fe55
1 changed files with 284 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

457
README.md
View File

@@ -1,59 +1,63 @@
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: 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: # Architecture
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
The module uses a simple processing pipeline. The module uses a simple processing pipeline.
DBC file DBC file
↓ ↓
DbcParser DbcParser
↓ ↓
DbcDatabase DbcDatabase
↓ ↓
DbcTreeBuilder DbcTreeBuilder
↓ ↓
TreeNode hierarchy TreeNode hierarchy
↓ ↓
Future Qt Model/View integration Future Qt Model/View integration
Each component has a clear responsibility. Each component has a clear responsibility.
Component Responsibility
DbcParser Reads and parses the DBC file | Component | Responsibility |
DbcDatabase Stores parsed frames and signals |-----------|---------------|
DbcTreeBuilder Converts the database into a tree | DbcParser | Reads and parses the DBC file |
TreeNode Represents hierarchical nodes | 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. This separation allows the parser to remain independent from UI or visualization logic.
File Structure
---
# File Structure
The module consists of several logical parts. The module consists of several logical parts.
Data structures
## Data structures
Files: Files:
@@ -62,7 +66,8 @@ frame_info.h
dbc_database.h dbc_database.h
These files define the internal representation of parsed data. These files define the internal representation of parsed data.
Tree representation
## Tree representation
Files: Files:
@@ -70,7 +75,8 @@ tree_node.h
tree_node.cpp tree_node.cpp
Defines a simple hierarchical structure that can later be used by UI components. Defines a simple hierarchical structure that can later be used by UI components.
Parser
## Parser
Files: Files:
@@ -78,7 +84,8 @@ dbc_parser.h
dbc_parser.cpp dbc_parser.cpp
Responsible for reading the DBC file and extracting frame and signal information. Responsible for reading the DBC file and extracting frame and signal information.
Tree builder
## Tree builder
Files: Files:
@@ -86,98 +93,107 @@ dbc_tree_builder.h
dbc_tree_builder.cpp dbc_tree_builder.cpp
Converts the parsed database into a tree representation. Converts the parsed database into a tree representation.
Data Structures
SignalInfo ---
# Data Structures
## SignalInfo
Represents a single signal defined in a DBC file. Represents a single signal defined in a DBC file.
Fields: Fields:
name - name
startBit - startBit
length - length
isLittleEndian - isLittleEndian
isSigned - isSigned
factor - factor
offset - offset
minimum - minimum
maximum - maximum
unit - unit
receivers - receivers
comment - comment
Notes: Notes:
receivers may contain multiple ECUs - receivers may contain multiple ECUs
- comment is optional
comment is optional - factor and offset define physical conversion
factor and offset define physical conversion
Physical value is calculated as: Physical value is calculated as:
physical = raw * factor + offset physical = raw * factor + offset
FrameInfo ---
## FrameInfo
Represents a CAN frame. Represents a CAN frame.
Fields: Fields:
name - name
canId - canId
dlc - dlc
transmitter - transmitter
comment - comment
signals - signals
pgn - pgn
hasPgn - hasPgn
Notes: 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. Top level container for parsed data.
DbcDatabase DbcDatabase
└── vector<FrameInfo> └── vector<FrameInfo>
This structure represents the entire DBC file content. This structure represents the entire DBC file content.
Tree Representation
---
# Tree Representation
The module converts the parsed data into a tree. The module converts the parsed data into a tree.
Node types: Node types:
Root - Root
Frame - Frame
Signal - Signal
Example structure: Example structure:
dbc dbc
├── EngineData ├── EngineData
│ ├── EngineSpeed │ ├── EngineSpeed
│ ├── OilTemp │ ├── OilTemp
│ └── CoolantTemp │ └── CoolantTemp
└── VehicleData └── VehicleData
├── VehicleSpeed ├── VehicleSpeed
└── Odometer └── Odometer
Each node stores either: Each node stores either:
FrameInfo - FrameInfo
- SignalInfo
SignalInfo
This tree structure is designed to integrate easily with Qt Model/View. This tree structure is designed to integrate easily with Qt Model/View.
Parser
---
# Parser
The parser is implemented in: The parser is implemented in:
@@ -188,62 +204,77 @@ It performs line-based parsing of the DBC file.
Supported elements: Supported elements:
BO_ - BO_
SG_ - SG_
CM_ - CM_
Supported DBC Syntax ---
Frame Definition
# Supported DBC Syntax
## Frame Definition
Example: Example:
BO_ 256 EngineData: 8 EEC1 BO_ 256 EngineData: 8 EEC1
Parsed values: Parsed values:
Field Meaning
256 CAN identifier | Field | Meaning |
EngineData frame name |------|---------|
8 DLC | 256 | CAN identifier |
EEC1 transmitter ECU | EngineData | frame name |
Signal Definition | 8 | DLC |
| EEC1 | transmitter ECU |
---
## Signal Definition
Example: Example:
SG_ EngineSpeed : 0|16@1+ (0.125,0) [0|8000] "rpm" ECU1,ECU2 SG_ EngineSpeed : 0|16@1+ (0.125,0) [0|8000] "rpm" ECU1,ECU2
Parsed values: 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"; CM_ BO_ 256 "Engine data frame";
Signal comment: Signal comment example:
CM_ SG_ 256 EngineSpeed "Actual engine speed"; CM_ SG_ 256 EngineSpeed "Actual engine speed";
These values are stored in: Stored in:
FrameInfo::comment - FrameInfo::comment
SignalInfo::comment - SignalInfo::comment
PGN Extraction ---
# PGN Extraction
PGN is derived using simplified J1939 logic. PGN is derived using simplified J1939 logic.
Typical J1939 identifier layout: Typical identifier layout:
Priority Priority
Reserved Reserved
@@ -252,12 +283,13 @@ PDU Format
PDU Specific PDU Specific
Source Address 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. This is only an approximation and not full J1939 validation.
Example Usage
Typical usage: ---
# Example Usage
DbcParser parser; DbcParser parser;
@@ -268,123 +300,134 @@ DbcTreeBuilder builder;
std::unique_ptr<TreeNode> root = builder.Build(database); std::unique_ptr<TreeNode> root = builder.Build(database);
After this step, the tree can be used by a UI or visualization system. After this step, the tree can be used by a UI or visualization system.
Example Tree
Example output structure: ---
# Example Tree
dbc dbc
├── EngineData ├── EngineData
│ ├── EngineSpeed │ ├── EngineSpeed
│ ├── OilTemp │ ├── OilTemp
│ └── CoolantTemp │ └── CoolantTemp
└── VehicleData └── VehicleData
├── VehicleSpeed ├── VehicleSpeed
└── Odometer └── Odometer
Limitations ---
# Limitations
The current implementation intentionally does not support many advanced DBC features. The current implementation intentionally does not support many advanced DBC features.
Not supported yet: Not supported yet:
multiplexed signals - multiplexed signals
BA_ attributes - BA_ attributes
BA_DEF_ definitions - BA_DEF_ definitions
VAL_ value tables - VAL_ value tables
signal groups - signal groups
advanced comments - complex syntax variations
complex syntax variations
These can be added later if required. 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. # Design Principles
Separation of Concerns
## 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. 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 ## Qt Independence
export data
reuse the module elsewhere
Qt Independence
The parser itself does not depend on Qt. The parser itself does not depend on Qt.
Qt integration should be implemented through a separate adapter layer. Qt integration should be implemented through a separate adapter layer.
Future Development
---
# Future Development
Recommended evolution path. Recommended evolution path.
Stage 1 (current)
BO_ ## Stage 1 (current)
SG_
CM_
transmitter
receivers
basic PGN extraction
tree representation
Stage 2 - BO_
- SG_
- CM_
- transmitter
- receivers
- basic PGN extraction
- tree representation
## Stage 2
Add: Add:
extended CAN ID detection - extended CAN ID detection
better PGN extraction - better PGN extraction
TreeNode parent pointer - parent pointer in TreeNode
Qt Model adapter - Qt Model adapter
Stage 3 ## Stage 3
Add support for: Add support for:
VAL_ value tables - VAL_ value tables
BA_ attributes - BA_ attributes
BA_DEF_ definitions - BA_DEF_ definitions
extended comments - extended comments
Stage 4 ## Stage 4
Advanced functionality: Advanced functionality:
multiplexing - multiplexing
runtime signal decoding - runtime signal decoding
integration with CAN stream - integration with CAN stream
drag-and-drop plotting - drag‑and‑drop plotting
Intended Usage in FrameTap ---
This module will allow FrameTap to: # Intended Usage in FrameTap
load DBC files This module allows FrameTap to:
display frames and signals
select signals - load DBC files
search signals - display frames and signals
display metadata - select signals
prepare runtime decoding - search signals
- display metadata
- prepare runtime decoding
Example workflow: Example workflow:
Load DBC Load DBC
↓ ↓
Browse signals Browse signals
↓ ↓
Select signal Select signal
↓ ↓
Decode CAN frames Decode CAN frames
↓ ↓
Plot physical values 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. 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 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. The module is independent of any specific build system.
It can be integrated using: It can be integrated using:
CMake - CMake
qmake - qmake
Makefile - Makefile
Simply add the source files to the project. Simply include the source files in your project.
Summary
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: Key properties:
simple - simple
modular - modular
Qt-independent - Qt‑independent
extendable - extendable
It converts a DBC file into an internal structure: It converts a DBC file into an internal structure:
frame → signals frame → signals
with additional metadata such as: with metadata such as:
transmitter - transmitter
receivers - receivers
comments - comments
basic PGN information - basic PGN information
This forms the foundation for future CAN signal visualization and decoding. This forms the foundation for future CAN signal visualization and decoding.