Generated foxygen documentation. Closes #1
This commit is contained in:
740
docs/html/md_README.html
Normal file
740
docs/html/md_README.html
Normal file
@@ -0,0 +1,740 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
||||
<meta name="generator" content="Doxygen 1.9.4"/>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||||
<title>DBC framework: DBC Parser and Runtime Decode Module Documentation</title>
|
||||
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||||
<script type="text/javascript" src="jquery.js"></script>
|
||||
<script type="text/javascript" src="dynsections.js"></script>
|
||||
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||||
<div id="titlearea">
|
||||
<table cellspacing="0" cellpadding="0">
|
||||
<tbody>
|
||||
<tr id="projectrow">
|
||||
<td id="projectalign">
|
||||
<div id="projectname">DBC framework
|
||||
</div>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<!-- end header part -->
|
||||
<!-- Generated by Doxygen 1.9.4 -->
|
||||
<div id="navrow1" class="tabs">
|
||||
<ul class="tablist">
|
||||
<li><a href="index.html"><span>Main Page</span></a></li>
|
||||
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
|
||||
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
|
||||
<li><a href="annotated.html"><span>Classes</span></a></li>
|
||||
<li><a href="files.html"><span>Files</span></a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div><!-- top -->
|
||||
<div><div class="header">
|
||||
<div class="headertitle"><div class="title">DBC Parser and Runtime Decode Module Documentation </div></div>
|
||||
</div><!--header-->
|
||||
<div class="contents">
|
||||
<div class="textblock"><h1><a class="anchor" id="autotoc_md1"></a>
|
||||
Overview</h1>
|
||||
<p >This module provides a minimal but extensible DBC parser and runtime decode foundation for the <b>FrameTap</b> project.</p>
|
||||
<p >Its purpose is to:</p>
|
||||
<ul>
|
||||
<li>parse DBC files</li>
|
||||
<li>store parsed frame and signal metadata</li>
|
||||
<li>build a tree for future UI integration</li>
|
||||
<li>build a runtime-ready decode database</li>
|
||||
<li>decode live CAN frames</li>
|
||||
<li>decode CAN trace records using the same decoder</li>
|
||||
</ul>
|
||||
<p >The implementation follows a simple and practical design:</p>
|
||||
<ul>
|
||||
<li>parser logic is separated from UI logic</li>
|
||||
<li>runtime decode structures are separated from tree structures</li>
|
||||
<li>Qt is not required at the parser or decoder level</li>
|
||||
<li>the same decode engine can be reused for live traffic and trace replay</li>
|
||||
</ul>
|
||||
<p >This is <b>not a full production-grade DBC implementation yet</b>, but it is a strong architectural base.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md3"></a>
|
||||
High-Level Architecture</h1>
|
||||
<p >The module is divided into two main paths.</p>
|
||||
<h2><a class="anchor" id="autotoc_md4"></a>
|
||||
1. Parse and UI path</h2>
|
||||
<p >Used for:</p>
|
||||
<ul>
|
||||
<li>browsing frames and signals</li>
|
||||
<li>later integration with Qt <code>Model/View</code></li>
|
||||
<li>displaying metadata</li>
|
||||
</ul>
|
||||
<p >Pipeline:</p>
|
||||
<div class="fragment"><div class="line">DBC file</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DbcParser</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DbcDatabase</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DbcTreeBuilder</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">TreeNode hierarchy</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">future Qt UI</div>
|
||||
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md5"></a>
|
||||
2. Runtime decode path</h2>
|
||||
<p >Used for:</p>
|
||||
<ul>
|
||||
<li>live CAN decoding</li>
|
||||
<li>CAN trace decoding</li>
|
||||
<li>fast lookup by CAN ID</li>
|
||||
</ul>
|
||||
<p >Pipeline:</p>
|
||||
<div class="fragment"><div class="line">DBC file</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DbcParser</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DbcDatabase</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DbcDecodeBuilder</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DecodeDatabase</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DbcDecoder</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">Decoded values</div>
|
||||
</div><!-- fragment --><p >This separation is intentional.</p>
|
||||
<p >The tree is useful for UI, but it is <b>not</b> the main data structure for runtime decoding.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md7"></a>
|
||||
Why the Runtime Decode Layer Exists</h1>
|
||||
<p >A tree structure is convenient for browsing, but a runtime decoder needs something different:</p>
|
||||
<ul>
|
||||
<li>fast lookup by CAN ID</li>
|
||||
<li>direct access to signal decode definitions</li>
|
||||
<li>minimal overhead during repeated decoding</li>
|
||||
<li>the same logic for live frames and trace frames</li>
|
||||
</ul>
|
||||
<p >Because of that, the design uses a dedicated runtime-ready structure:</p>
|
||||
<ul>
|
||||
<li><code><a class="el" href="structDecodeDatabase.html" title="Runtime decode database with fast lookup by CAN ID.">DecodeDatabase</a></code></li>
|
||||
<li><code><a class="el" href="structDecodeFrame.html" title="Runtime-ready frame definition.">DecodeFrame</a></code></li>
|
||||
<li><code><a class="el" href="structDecodeSignal.html" title="Runtime-ready signal definition.">DecodeSignal</a></code></li>
|
||||
</ul>
|
||||
<p >This avoids forcing UI-oriented structures into a decode role they were not meant for.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md9"></a>
|
||||
Module Layout</h1>
|
||||
<h2><a class="anchor" id="autotoc_md10"></a>
|
||||
Parsed DBC structures</h2>
|
||||
<p >Files:</p>
|
||||
<ul>
|
||||
<li><code><a class="el" href="signal__info_8h.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">signal_info.h</a></code></li>
|
||||
<li><code><a class="el" href="frame__info_8h.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">frame_info.h</a></code></li>
|
||||
<li><code><a class="el" href="dbc__database_8h.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">dbc_database.h</a></code></li>
|
||||
</ul>
|
||||
<p >These store a readable representation of the parsed DBC file.</p>
|
||||
<h2><a class="anchor" id="autotoc_md11"></a>
|
||||
UI tree structures</h2>
|
||||
<p >Files:</p>
|
||||
<ul>
|
||||
<li><code><a class="el" href="tree__node_8h.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">tree_node.h</a></code></li>
|
||||
<li><code><a class="el" href="tree__node_8cpp.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">tree_node.cpp</a></code></li>
|
||||
<li><code><a class="el" href="dbc__tree__builder_8h.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">dbc_tree_builder.h</a></code></li>
|
||||
<li><code><a class="el" href="dbc__tree__builder_8cpp.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">dbc_tree_builder.cpp</a></code></li>
|
||||
</ul>
|
||||
<p >These convert parsed DBC content into a tree hierarchy suitable for UI and model/view usage later.</p>
|
||||
<h2><a class="anchor" id="autotoc_md12"></a>
|
||||
Runtime decode structures</h2>
|
||||
<p >Files:</p>
|
||||
<ul>
|
||||
<li><code><a class="el" href="decode__database_8h.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">decode_database.h</a></code></li>
|
||||
<li><code><a class="el" href="dbc__decode__builder_8h.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">dbc_decode_builder.h</a></code></li>
|
||||
<li><code><a class="el" href="dbc__decode__builder_8cpp.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">dbc_decode_builder.cpp</a></code></li>
|
||||
</ul>
|
||||
<p >These convert parsed DBC content into a structure optimized for decoding.</p>
|
||||
<h2><a class="anchor" id="autotoc_md13"></a>
|
||||
Runtime decoder</h2>
|
||||
<p >Files:</p>
|
||||
<ul>
|
||||
<li><code><a class="el" href="dbc__decoder_8h.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">dbc_decoder.h</a></code></li>
|
||||
<li><code><a class="el" href="dbc__decoder_8cpp.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">dbc_decoder.cpp</a></code></li>
|
||||
</ul>
|
||||
<p >These perform actual decoding of raw CAN frames using <code><a class="el" href="structDecodeDatabase.html" title="Runtime decode database with fast lookup by CAN ID.">DecodeDatabase</a></code>.</p>
|
||||
<h2><a class="anchor" id="autotoc_md14"></a>
|
||||
Parser</h2>
|
||||
<p >Files:</p>
|
||||
<ul>
|
||||
<li><code><a class="el" href="dbc__parser_8h.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">dbc_parser.h</a></code></li>
|
||||
<li><code><a class="el" href="dbc__parser_8cpp.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">dbc_parser.cpp</a></code></li>
|
||||
</ul>
|
||||
<p >These parse the DBC file itself.</p>
|
||||
<h2><a class="anchor" id="autotoc_md15"></a>
|
||||
Demo</h2>
|
||||
<p >File:</p>
|
||||
<ul>
|
||||
<li><code><a class="el" href="main_8cpp.html" title="Created: 2026-03-13 Author: Deeaitch (Dim. Himro)">main.cpp</a></code></li>
|
||||
</ul>
|
||||
<p >Used as a small integration example.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md17"></a>
|
||||
Parsed Data Structures</h1>
|
||||
<h1><a class="anchor" id="autotoc_md18"></a>
|
||||
<tt>SignalInfo</tt></h1>
|
||||
<p >Represents one signal as parsed from the DBC file.</p>
|
||||
<p >Fields:</p>
|
||||
<ul>
|
||||
<li><code>name</code></li>
|
||||
<li><code>startBit</code></li>
|
||||
<li><code>length</code></li>
|
||||
<li><code>isLittleEndian</code></li>
|
||||
<li><code>isSigned</code></li>
|
||||
<li><code>factor</code></li>
|
||||
<li><code>offset</code></li>
|
||||
<li><code>minimum</code></li>
|
||||
<li><code>maximum</code></li>
|
||||
<li><code>unit</code></li>
|
||||
<li><code>receivers</code></li>
|
||||
<li><code>comment</code></li>
|
||||
</ul>
|
||||
<p >Notes:</p>
|
||||
<ul>
|
||||
<li><code>receivers</code> is a list because a signal may have more than one receiver ECU</li>
|
||||
<li><code>factor</code> and <code>offset</code> define physical conversion</li>
|
||||
<li>this structure is close to DBC content and easy to inspect</li>
|
||||
</ul>
|
||||
<p >Physical value rule:</p>
|
||||
<div class="fragment"><div class="line">physical = raw * factor + offset</div>
|
||||
</div><!-- fragment --><hr />
|
||||
<h1><a class="anchor" id="autotoc_md20"></a>
|
||||
<tt>FrameInfo</tt></h1>
|
||||
<p >Represents one frame as parsed from the DBC file.</p>
|
||||
<p >Fields:</p>
|
||||
<ul>
|
||||
<li><code>name</code></li>
|
||||
<li><code>canId</code></li>
|
||||
<li><code>isExtended</code></li>
|
||||
<li><code>pgn</code></li>
|
||||
<li><code>hasPgn</code></li>
|
||||
<li><code>dlc</code></li>
|
||||
<li><code>transmitter</code></li>
|
||||
<li><code>comment</code></li>
|
||||
<li><code>signals</code></li>
|
||||
</ul>
|
||||
<p >Notes:</p>
|
||||
<ul>
|
||||
<li><code>signals</code> is a list of <code><a class="el" href="structSignalInfo.html" title="Describes one signal inside a DBC frame.">SignalInfo</a></code></li>
|
||||
<li><code>isExtended</code> is determined during CAN ID normalization</li>
|
||||
<li><code>pgn</code> is derived using simplified J1939 logic when applicable</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md22"></a>
|
||||
<tt>DbcDatabase</tt></h1>
|
||||
<p >Top-level parsed DBC container.</p>
|
||||
<p >Conceptually:</p>
|
||||
<div class="fragment"><div class="line">DbcDatabase</div>
|
||||
<div class="line"> └── vector<FrameInfo></div>
|
||||
</div><!-- fragment --><p >This is the central structure produced by <code><a class="el" href="classDbcParser.html" title="Minimal DBC parser.">DbcParser</a></code>.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md24"></a>
|
||||
UI Tree Layer</h1>
|
||||
<h1><a class="anchor" id="autotoc_md25"></a>
|
||||
<tt>TreeNode</tt></h1>
|
||||
<p >The UI tree contains three node types:</p>
|
||||
<ul>
|
||||
<li><code>Root</code></li>
|
||||
<li><code>Frame</code></li>
|
||||
<li><code>Signal</code></li>
|
||||
</ul>
|
||||
<p >Example hierarchy:</p>
|
||||
<div class="fragment"><div class="line">dbc</div>
|
||||
<div class="line"> ├── EngineData</div>
|
||||
<div class="line"> │ ├── EngineSpeed</div>
|
||||
<div class="line"> │ ├── OilTemp</div>
|
||||
<div class="line"> │ └── CoolantTemp</div>
|
||||
<div class="line"> └── VehicleData</div>
|
||||
<div class="line"> ├── VehicleSpeed</div>
|
||||
<div class="line"> └── Odometer</div>
|
||||
</div><!-- fragment --><p >Each node stores either:</p>
|
||||
<ul>
|
||||
<li><code><a class="el" href="structFrameInfo.html" title="Describes one CAN frame from a DBC file.">FrameInfo</a></code></li>
|
||||
<li><code><a class="el" href="structSignalInfo.html" title="Describes one signal inside a DBC frame.">SignalInfo</a></code></li>
|
||||
</ul>
|
||||
<p >The tree is intended for browsing and later Qt model integration.</p>
|
||||
<p >It is <b>not</b> the primary runtime decode structure.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md27"></a>
|
||||
Runtime Decode Layer</h1>
|
||||
<h1><a class="anchor" id="autotoc_md28"></a>
|
||||
Purpose</h1>
|
||||
<p >The decode layer exists so that decoding can be fast and independent from UI concerns.</p>
|
||||
<p >Instead of searching a tree, the decoder uses a prepared database with direct lookup.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md30"></a>
|
||||
<tt>ByteOrder</tt></h1>
|
||||
<p >Runtime byte order enum:</p>
|
||||
<ul>
|
||||
<li><code>Intel</code></li>
|
||||
<li><code>Motorola</code></li>
|
||||
</ul>
|
||||
<p >This is better for decode code than passing around raw DBC characters.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md32"></a>
|
||||
<tt>ValueType</tt></h1>
|
||||
<p >Numeric type enum:</p>
|
||||
<ul>
|
||||
<li><code>Unsigned</code></li>
|
||||
<li><code>Signed</code></li>
|
||||
</ul>
|
||||
<p >This is clearer than combining multiple boolean flags during runtime logic.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md34"></a>
|
||||
<tt>DecodeSignal</tt></h1>
|
||||
<p >Represents one runtime-ready signal definition.</p>
|
||||
<p >Fields:</p>
|
||||
<ul>
|
||||
<li><code>name</code></li>
|
||||
<li><code>startBit</code></li>
|
||||
<li><code>length</code></li>
|
||||
<li><code>byteOrder</code></li>
|
||||
<li><code>valueType</code></li>
|
||||
<li><code>factor</code></li>
|
||||
<li><code>offset</code></li>
|
||||
<li><code>minimum</code></li>
|
||||
<li><code>maximum</code></li>
|
||||
<li><code>unit</code></li>
|
||||
<li><code>receivers</code></li>
|
||||
<li><code>comment</code></li>
|
||||
</ul>
|
||||
<p >This structure contains all information required for extracting and converting a signal value from raw frame data.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md36"></a>
|
||||
<tt>DecodeFrame</tt></h1>
|
||||
<p >Represents one runtime-ready frame definition.</p>
|
||||
<p >Fields:</p>
|
||||
<ul>
|
||||
<li><code>name</code></li>
|
||||
<li><code>canId</code></li>
|
||||
<li><code>isExtended</code></li>
|
||||
<li><code>dlc</code></li>
|
||||
<li><code>pgn</code></li>
|
||||
<li><code>hasPgn</code></li>
|
||||
<li><code>transmitter</code></li>
|
||||
<li><code>comment</code></li>
|
||||
<li><code>signals</code></li>
|
||||
</ul>
|
||||
<p >This structure is used directly by the decoder.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md38"></a>
|
||||
<tt>FrameKey</tt></h1>
|
||||
<p >Fast lookup key for runtime frame matching.</p>
|
||||
<p >Fields:</p>
|
||||
<ul>
|
||||
<li><code>canId</code></li>
|
||||
<li><code>isExtended</code></li>
|
||||
</ul>
|
||||
<p >This matters because the same numeric identifier must not be confused between standard and extended frames.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md40"></a>
|
||||
<tt>DecodeDatabase</tt></h1>
|
||||
<p >Top-level runtime decode container.</p>
|
||||
<p >Fields:</p>
|
||||
<ul>
|
||||
<li><code>frames</code></li>
|
||||
<li><code>frameIndexByKey</code></li>
|
||||
</ul>
|
||||
<p >Conceptually:</p>
|
||||
<div class="fragment"><div class="line">DecodeDatabase</div>
|
||||
<div class="line"> ├── vector<DecodeFrame></div>
|
||||
<div class="line"> └── unordered_map<FrameKey, index></div>
|
||||
</div><!-- fragment --><p >This gives the decoder fast access to a frame definition using CAN ID and frame type.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md42"></a>
|
||||
Decoder Layer</h1>
|
||||
<h1><a class="anchor" id="autotoc_md43"></a>
|
||||
<tt>RawCanFrame</tt></h1>
|
||||
<p >Represents a raw CAN frame to decode.</p>
|
||||
<p >Fields:</p>
|
||||
<ul>
|
||||
<li><code>canId</code></li>
|
||||
<li><code>isExtended</code></li>
|
||||
<li><code>data</code></li>
|
||||
</ul>
|
||||
<p >This same structure can be used for:</p>
|
||||
<ul>
|
||||
<li>live CAN bus input</li>
|
||||
<li>replayed trace records</li>
|
||||
<li>unit tests</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md45"></a>
|
||||
<tt>DecodedSignalValue</tt></h1>
|
||||
<p >Represents one decoded signal result.</p>
|
||||
<p >Fields:</p>
|
||||
<ul>
|
||||
<li><code>definition</code></li>
|
||||
<li><code>rawValue</code></li>
|
||||
<li><code>physicalValue</code></li>
|
||||
<li><code>valid</code></li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md47"></a>
|
||||
<tt>DecodedFrameValue</tt></h1>
|
||||
<p >Represents one decoded frame result.</p>
|
||||
<p >Fields:</p>
|
||||
<ul>
|
||||
<li><code>definition</code></li>
|
||||
<li><code>signals</code></li>
|
||||
<li><code>valid</code></li>
|
||||
</ul>
|
||||
<p >This is the decoder output for one raw frame.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md49"></a>
|
||||
<tt>DbcDecoder</tt></h1>
|
||||
<p >Main runtime decoder class.</p>
|
||||
<p >Responsibilities:</p>
|
||||
<ul>
|
||||
<li>find a frame definition by CAN ID</li>
|
||||
<li>decode all signals in a frame</li>
|
||||
<li>extract raw values</li>
|
||||
<li>sign-extend signed values</li>
|
||||
<li>convert raw values into physical values</li>
|
||||
</ul>
|
||||
<p >Main methods:</p>
|
||||
<ul>
|
||||
<li><code>FindFrame(...)</code></li>
|
||||
<li><code>Decode(...)</code></li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md51"></a>
|
||||
Parser Support</h1>
|
||||
<p >The current parser supports the following DBC elements:</p>
|
||||
<ul>
|
||||
<li><code>BO_</code></li>
|
||||
<li><code>SG_</code></li>
|
||||
<li><code>CM_ BO_</code></li>
|
||||
<li><code>CM_ SG_</code></li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md53"></a>
|
||||
Supported DBC Syntax</h1>
|
||||
<h1><a class="anchor" id="autotoc_md54"></a>
|
||||
Frame definition</h1>
|
||||
<p >Example:</p>
|
||||
<div class="fragment"><div class="line">BO_ 256 EngineData: 8 EEC1</div>
|
||||
</div><!-- fragment --><p >Parsed fields:</p>
|
||||
<ul>
|
||||
<li>frame CAN ID</li>
|
||||
<li>frame name</li>
|
||||
<li>DLC</li>
|
||||
<li>transmitter ECU</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md56"></a>
|
||||
Signal definition</h1>
|
||||
<p >Example:</p>
|
||||
<div class="fragment"><div class="line">SG_ EngineSpeed : 0|16@1+ (0.125,0) [0|8000] "rpm" ECU1,ECU2</div>
|
||||
</div><!-- fragment --><p >Parsed fields:</p>
|
||||
<ul>
|
||||
<li>signal name</li>
|
||||
<li>start bit</li>
|
||||
<li>signal length</li>
|
||||
<li>byte order</li>
|
||||
<li>signedness</li>
|
||||
<li>factor</li>
|
||||
<li>offset</li>
|
||||
<li>minimum</li>
|
||||
<li>maximum</li>
|
||||
<li>unit</li>
|
||||
<li>receivers</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md58"></a>
|
||||
Comments</h1>
|
||||
<p >Frame comment example:</p>
|
||||
<div class="fragment"><div class="line">CM_ BO_ 256 "Engine data frame";</div>
|
||||
</div><!-- fragment --><p >Signal comment example:</p>
|
||||
<div class="fragment"><div class="line">CM_ SG_ 256 EngineSpeed "Actual engine speed";</div>
|
||||
</div><!-- fragment --><p >Stored in:</p>
|
||||
<ul>
|
||||
<li><code><a class="el" href="structFrameInfo.html#ace75121294f9d89b762080ab5643293c">FrameInfo::comment</a></code></li>
|
||||
<li><code><a class="el" href="structSignalInfo.html#ac99ba7563a5dad01e39c4257216953f5">SignalInfo::comment</a></code></li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md60"></a>
|
||||
CAN ID Normalization</h1>
|
||||
<p >The parser normalizes frame identifiers.</p>
|
||||
<p >Common DBC behavior:</p>
|
||||
<ul>
|
||||
<li>extended identifiers may be stored with bit 31 set</li>
|
||||
<li>the actual 29-bit identifier must be extracted from that value</li>
|
||||
</ul>
|
||||
<p >The parser therefore stores:</p>
|
||||
<ul>
|
||||
<li>normalized <code>canId</code></li>
|
||||
<li>separate <code>isExtended</code> flag</li>
|
||||
</ul>
|
||||
<p >This is important both for correct lookup and for future interoperability with live CAN APIs.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md62"></a>
|
||||
PGN Extraction</h1>
|
||||
<p >PGN is derived only when the frame is treated as extended.</p>
|
||||
<p >The current logic is simplified J1939 extraction:</p>
|
||||
<ul>
|
||||
<li><code>pf</code></li>
|
||||
<li><code>ps</code></li>
|
||||
<li><code>dp</code></li>
|
||||
</ul>
|
||||
<p >This is enough for a practical start but should not be treated as full J1939 validation.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md64"></a>
|
||||
Decode Flow</h1>
|
||||
<p >Typical runtime decode flow:</p>
|
||||
<div class="fragment"><div class="line">RawCanFrame</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">Find frame in DecodeDatabase</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">For each signal:</div>
|
||||
<div class="line"> extract raw bits</div>
|
||||
<div class="line"> apply sign extension if needed</div>
|
||||
<div class="line"> convert to physical value</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DecodedFrameValue</div>
|
||||
</div><!-- fragment --><hr />
|
||||
<h1><a class="anchor" id="autotoc_md66"></a>
|
||||
Intel and Motorola Extraction</h1>
|
||||
<p >The decoder currently has separate extraction paths:</p>
|
||||
<ul>
|
||||
<li><code>ExtractIntel(...)</code></li>
|
||||
<li><code>ExtractMotorola(...)</code></li>
|
||||
</ul>
|
||||
<p >This is important because byte order is not just metadata once decoding starts.</p>
|
||||
<p >Intel and Motorola require different bit extraction logic.</p>
|
||||
<p >This is one of the main reasons why the runtime decode layer should be explicit and prepared in advance.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md68"></a>
|
||||
Example Usage</h1>
|
||||
<h1><a class="anchor" id="autotoc_md69"></a>
|
||||
Parse DBC</h1>
|
||||
<div class="fragment"><div class="line"><a class="code hl_class" href="classDbcParser.html">DbcParser</a> parser;</div>
|
||||
<div class="line"><a class="code hl_struct" href="structDbcDatabase.html">DbcDatabase</a> database = parser.<a class="code hl_function" href="classDbcParser.html#aef72826942c9095d653fafa435855e56">ParseFile</a>(<span class="stringliteral">"example.dbc"</span>);</div>
|
||||
<div class="ttc" id="aclassDbcParser_html"><div class="ttname"><a href="classDbcParser.html">DbcParser</a></div><div class="ttdoc">Minimal DBC parser.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__parser_8h_source.html#l00035">dbc_parser.h:35</a></div></div>
|
||||
<div class="ttc" id="aclassDbcParser_html_aef72826942c9095d653fafa435855e56"><div class="ttname"><a href="classDbcParser.html#aef72826942c9095d653fafa435855e56">DbcParser::ParseFile</a></div><div class="ttdeci">DbcDatabase ParseFile(const std::string &filePath) const</div><div class="ttdoc">Parse DBC file.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__parser_8cpp_source.html#l00040">dbc_parser.cpp:40</a></div></div>
|
||||
<div class="ttc" id="astructDbcDatabase_html"><div class="ttname"><a href="structDbcDatabase.html">DbcDatabase</a></div><div class="ttdoc">Parsed DBC content stored in a simple internal form.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__database_8h_source.html#l00022">dbc_database.h:22</a></div></div>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md70"></a>
|
||||
Build UI tree</h1>
|
||||
<div class="fragment"><div class="line"><a class="code hl_class" href="classDbcTreeBuilder.html">DbcTreeBuilder</a> treeBuilder;</div>
|
||||
<div class="line">std::unique_ptr<TreeNode> root = treeBuilder.<a class="code hl_function" href="classDbcTreeBuilder.html#a7e57d067d831b14b383947fd125edd4b">Build</a>(database);</div>
|
||||
<div class="ttc" id="aclassDbcTreeBuilder_html"><div class="ttname"><a href="classDbcTreeBuilder.html">DbcTreeBuilder</a></div><div class="ttdoc">Builds a simple tree from parsed DBC database.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__tree__builder_8h_source.html#l00023">dbc_tree_builder.h:23</a></div></div>
|
||||
<div class="ttc" id="aclassDbcTreeBuilder_html_a7e57d067d831b14b383947fd125edd4b"><div class="ttname"><a href="classDbcTreeBuilder.html#a7e57d067d831b14b383947fd125edd4b">DbcTreeBuilder::Build</a></div><div class="ttdeci">std::unique_ptr< TreeNode > Build(const DbcDatabase &database) const</div><div class="ttdoc">Build tree representation of parsed DBC data.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__tree__builder_8cpp_source.html#l00014">dbc_tree_builder.cpp:14</a></div></div>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md71"></a>
|
||||
Build runtime decode database</h1>
|
||||
<div class="fragment"><div class="line"><a class="code hl_class" href="classDbcDecodeBuilder.html">DbcDecodeBuilder</a> decodeBuilder;</div>
|
||||
<div class="line"><a class="code hl_struct" href="structDecodeDatabase.html">DecodeDatabase</a> decodeDatabase = decodeBuilder.<a class="code hl_function" href="classDbcDecodeBuilder.html#a2bc6386dfb5e58976c42e22c19ec471b">Build</a>(database);</div>
|
||||
<div class="ttc" id="aclassDbcDecodeBuilder_html"><div class="ttname"><a href="classDbcDecodeBuilder.html">DbcDecodeBuilder</a></div><div class="ttdoc">Converts parsed DBC data into runtime decode database.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__decode__builder_8h_source.html#l00021">dbc_decode_builder.h:21</a></div></div>
|
||||
<div class="ttc" id="aclassDbcDecodeBuilder_html_a2bc6386dfb5e58976c42e22c19ec471b"><div class="ttname"><a href="classDbcDecodeBuilder.html#a2bc6386dfb5e58976c42e22c19ec471b">DbcDecodeBuilder::Build</a></div><div class="ttdeci">DecodeDatabase Build(const DbcDatabase &source) const</div><div class="ttdoc">Build runtime decode database.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__decode__builder_8cpp_source.html#l00014">dbc_decode_builder.cpp:14</a></div></div>
|
||||
<div class="ttc" id="astructDecodeDatabase_html"><div class="ttname"><a href="structDecodeDatabase.html">DecodeDatabase</a></div><div class="ttdoc">Runtime decode database with fast lookup by CAN ID.</div><div class="ttdef"><b>Definition:</b> <a href="decode__database_8h_source.html#l00132">decode_database.h:132</a></div></div>
|
||||
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md72"></a>
|
||||
Decode a raw frame</h1>
|
||||
<div class="fragment"><div class="line"><a class="code hl_struct" href="structRawCanFrame.html">RawCanFrame</a> rawFrame;</div>
|
||||
<div class="line">rawFrame.<a class="code hl_variable" href="structRawCanFrame.html#a2d0e7fa0e3d5c20bbed55ed8f7888ff4">canId</a> = 0x123;</div>
|
||||
<div class="line">rawFrame.<a class="code hl_variable" href="structRawCanFrame.html#a462193d275adc1dba8bd18ffa0e36bb7">isExtended</a> = <span class="keyword">false</span>;</div>
|
||||
<div class="line">rawFrame.<a class="code hl_variable" href="structRawCanFrame.html#a0acb487612104c99c9907344c035df83">data</a> = {0x01, 0x02, 0x03, 0x04};</div>
|
||||
<div class="line"> </div>
|
||||
<div class="line"><a class="code hl_class" href="classDbcDecoder.html">DbcDecoder</a> decoder;</div>
|
||||
<div class="line"><a class="code hl_struct" href="structDecodedFrameValue.html">DecodedFrameValue</a> decoded = decoder.<a class="code hl_function" href="classDbcDecoder.html#a345951ffe5d943a70d3a1ea1f39e74f7">Decode</a>(decodeDatabase, rawFrame);</div>
|
||||
<div class="ttc" id="aclassDbcDecoder_html"><div class="ttname"><a href="classDbcDecoder.html">DbcDecoder</a></div><div class="ttdoc">Runtime CAN decoder using prebuilt decode database.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__decoder_8h_source.html#l00070">dbc_decoder.h:70</a></div></div>
|
||||
<div class="ttc" id="aclassDbcDecoder_html_a345951ffe5d943a70d3a1ea1f39e74f7"><div class="ttname"><a href="classDbcDecoder.html#a345951ffe5d943a70d3a1ea1f39e74f7">DbcDecoder::Decode</a></div><div class="ttdeci">DecodedFrameValue Decode(const DecodeDatabase &database, const RawCanFrame &frame) const</div><div class="ttdoc">Decode one raw CAN frame.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__decoder_8cpp_source.html#l00031">dbc_decoder.cpp:31</a></div></div>
|
||||
<div class="ttc" id="astructDecodedFrameValue_html"><div class="ttname"><a href="structDecodedFrameValue.html">DecodedFrameValue</a></div><div class="ttdoc">Fully decoded frame.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__decoder_8h_source.html#l00055">dbc_decoder.h:55</a></div></div>
|
||||
<div class="ttc" id="astructRawCanFrame_html"><div class="ttname"><a href="structRawCanFrame.html">RawCanFrame</a></div><div class="ttdoc">Raw CAN frame used for runtime or trace decoding.</div><div class="ttdef"><b>Definition:</b> <a href="dbc__decoder_8h_source.html#l00023">dbc_decoder.h:23</a></div></div>
|
||||
<div class="ttc" id="astructRawCanFrame_html_a0acb487612104c99c9907344c035df83"><div class="ttname"><a href="structRawCanFrame.html#a0acb487612104c99c9907344c035df83">RawCanFrame::data</a></div><div class="ttdeci">std::vector< std::uint8_t > data</div><div class="ttdef"><b>Definition:</b> <a href="dbc__decoder_8h_source.html#l00026">dbc_decoder.h:26</a></div></div>
|
||||
<div class="ttc" id="astructRawCanFrame_html_a2d0e7fa0e3d5c20bbed55ed8f7888ff4"><div class="ttname"><a href="structRawCanFrame.html#a2d0e7fa0e3d5c20bbed55ed8f7888ff4">RawCanFrame::canId</a></div><div class="ttdeci">std::uint32_t canId</div><div class="ttdef"><b>Definition:</b> <a href="dbc__decoder_8h_source.html#l00024">dbc_decoder.h:24</a></div></div>
|
||||
<div class="ttc" id="astructRawCanFrame_html_a462193d275adc1dba8bd18ffa0e36bb7"><div class="ttname"><a href="structRawCanFrame.html#a462193d275adc1dba8bd18ffa0e36bb7">RawCanFrame::isExtended</a></div><div class="ttdeci">bool isExtended</div><div class="ttdef"><b>Definition:</b> <a href="dbc__decoder_8h_source.html#l00025">dbc_decoder.h:25</a></div></div>
|
||||
</div><!-- fragment --><hr />
|
||||
<h1><a class="anchor" id="autotoc_md74"></a>
|
||||
Unified Decode Strategy</h1>
|
||||
<p >A key design goal is that the same decoder should work for both:</p>
|
||||
<ul>
|
||||
<li>live CAN frames</li>
|
||||
<li>trace replay frames</li>
|
||||
</ul>
|
||||
<p >That means this architecture supports:</p>
|
||||
<h2><a class="anchor" id="autotoc_md75"></a>
|
||||
live path</h2>
|
||||
<div class="fragment"><div class="line">live CAN input</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">RawCanFrame</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DbcDecoder</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">decoded signal values</div>
|
||||
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md76"></a>
|
||||
trace path</h2>
|
||||
<div class="fragment"><div class="line">trace reader</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">RawCanFrame</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">DbcDecoder</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">decoded signal values</div>
|
||||
</div><!-- fragment --><p >This avoids duplicating decode logic in two separate parts of the application.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md78"></a>
|
||||
Intended Use in FrameTap</h1>
|
||||
<p >This module is meant to support at least the following FrameTap workflows:</p>
|
||||
<ul>
|
||||
<li>load a DBC file</li>
|
||||
<li>browse frames and signals</li>
|
||||
<li>search signals</li>
|
||||
<li>drag a signal into a plot later</li>
|
||||
<li>decode live CAN traffic</li>
|
||||
<li>decode recorded traces</li>
|
||||
<li>convert raw values into physical values</li>
|
||||
<li>show metadata like units, comments, transmitter, receivers, and PGN</li>
|
||||
</ul>
|
||||
<p >Example combined workflow:</p>
|
||||
<div class="fragment"><div class="line">Load DBC</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">Parse into DbcDatabase</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">Build UI tree</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">Build DecodeDatabase</div>
|
||||
<div class="line"> ↓</div>
|
||||
<div class="line">Use same decode engine for:</div>
|
||||
<div class="line"> - live frames</div>
|
||||
<div class="line"> - trace replay</div>
|
||||
</div><!-- fragment --><hr />
|
||||
<h1><a class="anchor" id="autotoc_md80"></a>
|
||||
Why the Tree Is Not Enough</h1>
|
||||
<p >The tree exists for browsing.</p>
|
||||
<p >However, runtime decode should not rely on tree traversal because that would introduce unnecessary coupling and inefficiency.</p>
|
||||
<p >A runtime decoder needs:</p>
|
||||
<ul>
|
||||
<li>fast key-based access</li>
|
||||
<li>minimal interpretation at decode time</li>
|
||||
<li>direct signal definitions already prepared</li>
|
||||
</ul>
|
||||
<p >That is why <code><a class="el" href="structDecodeDatabase.html" title="Runtime decode database with fast lookup by CAN ID.">DecodeDatabase</a></code> is a separate layer.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md82"></a>
|
||||
Why No Abstract Factory Is Used</h1>
|
||||
<p >At the current stage, abstract factory is intentionally avoided.</p>
|
||||
<p >The current design is already clean:</p>
|
||||
<div class="fragment"><div class="line">parser → parsed database → decode database</div>
|
||||
<div class="line"> ↘ tree builder → UI tree</div>
|
||||
</div><!-- fragment --><p >Introducing factory layers now would increase complexity without solving an immediate problem.</p>
|
||||
<p >If later the project requires multiple output representations or multiple build strategies, that can be added then.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md84"></a>
|
||||
Current Limitations</h1>
|
||||
<p >This is still a minimal implementation.</p>
|
||||
<p >Not supported yet:</p>
|
||||
<ul>
|
||||
<li>multiplexed signals</li>
|
||||
<li><code>VAL_</code> tables</li>
|
||||
<li><code>BA_</code> attributes</li>
|
||||
<li><code>BA_DEF_</code> definitions</li>
|
||||
<li>advanced comment handling</li>
|
||||
<li>full DBC grammar coverage</li>
|
||||
<li>full J1939 validation</li>
|
||||
<li>extensive edge-case handling for unusual DBC formatting</li>
|
||||
</ul>
|
||||
<p >Motorola extraction is implemented, but it should still be verified carefully against real-world DBC files and expected values.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md86"></a>
|
||||
Recommended Next Steps</h1>
|
||||
<p >A practical development order would be:</p>
|
||||
<h2><a class="anchor" id="autotoc_md87"></a>
|
||||
Stage 1 - already implemented</h2>
|
||||
<ul>
|
||||
<li><code>BO_</code></li>
|
||||
<li><code>SG_</code></li>
|
||||
<li><code>CM_</code></li>
|
||||
<li>normalized CAN ID</li>
|
||||
<li><code>isExtended</code></li>
|
||||
<li>transmitter</li>
|
||||
<li>receivers</li>
|
||||
<li>comments</li>
|
||||
<li>tree representation</li>
|
||||
<li>runtime decode database</li>
|
||||
<li>runtime decoder</li>
|
||||
</ul>
|
||||
<h2><a class="anchor" id="autotoc_md88"></a>
|
||||
Stage 2</h2>
|
||||
<p >Recommended additions:</p>
|
||||
<ul>
|
||||
<li>parent pointer in <code><a class="el" href="classTreeNode.html" title="Tree node for later use in model/view or other hierarchy consumers.">TreeNode</a></code></li>
|
||||
<li>Qt model adapter</li>
|
||||
<li><code>VAL_</code> support for enum-style signals</li>
|
||||
<li>better display strings for UI</li>
|
||||
<li>selective decoding of only chosen signals</li>
|
||||
</ul>
|
||||
<h2><a class="anchor" id="autotoc_md89"></a>
|
||||
Stage 3</h2>
|
||||
<p >Recommended additions:</p>
|
||||
<ul>
|
||||
<li>multiplexing support</li>
|
||||
<li>attribute parsing</li>
|
||||
<li>richer J1939 support</li>
|
||||
<li>CSV export of decoded traces</li>
|
||||
<li>optimized filtering and signal selection</li>
|
||||
</ul>
|
||||
<h2><a class="anchor" id="autotoc_md90"></a>
|
||||
Stage 4</h2>
|
||||
<p >Advanced functionality:</p>
|
||||
<ul>
|
||||
<li>live plot integration</li>
|
||||
<li>signal subscriptions</li>
|
||||
<li>per-signal trace decode pipelines</li>
|
||||
<li>decoder-assisted export formats</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md92"></a>
|
||||
Build Integration</h1>
|
||||
<p >The module does not depend on any specific build system.</p>
|
||||
<p >It can be integrated with:</p>
|
||||
<ul>
|
||||
<li>CMake</li>
|
||||
<li>qmake</li>
|
||||
<li>Makefile</li>
|
||||
</ul>
|
||||
<p >Just add the source files to the project.</p>
|
||||
<hr />
|
||||
<h1><a class="anchor" id="autotoc_md94"></a>
|
||||
Summary</h1>
|
||||
<p >This module is now split into two intentionally separate layers:</p>
|
||||
<h2><a class="anchor" id="autotoc_md95"></a>
|
||||
Parsed representation</h2>
|
||||
<p >Used for:</p>
|
||||
<ul>
|
||||
<li>storing parsed DBC content</li>
|
||||
<li>browsing</li>
|
||||
<li>UI tree generation</li>
|
||||
</ul>
|
||||
<h2><a class="anchor" id="autotoc_md96"></a>
|
||||
Runtime decode representation</h2>
|
||||
<p >Used for:</p>
|
||||
<ul>
|
||||
<li>fast frame lookup</li>
|
||||
<li>live CAN decode</li>
|
||||
<li>trace decode</li>
|
||||
<li>physical value conversion</li>
|
||||
</ul>
|
||||
<p >That separation is the main architectural improvement.</p>
|
||||
<p >In short, the system now looks like this:</p>
|
||||
<div class="fragment"><div class="line">DBC parser → DbcDatabase → DecodeDatabase → DbcDecoder</div>
|
||||
<div class="line"> ↘ TreeNode → future UI</div>
|
||||
</div><!-- fragment --><p >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. </p>
|
||||
</div></div><!-- contents -->
|
||||
</div><!-- PageDoc -->
|
||||
<!-- start footer part -->
|
||||
<hr class="footer"/><address class="footer"><small>
|
||||
Generated on Sun Jun 14 2026 20:49:34 for DBC framework by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
|
||||
</small></address>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user