-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathreadMe.html
394 lines (393 loc) · 18.6 KB
/
readMe.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang xml:lang>
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>readMe</title>
<style>
html {
font-family: Segoe UI;
color: #1a1a1a;
background-color: #fdfdfd;
}
body {
margin: 0 auto;
max-width: 36em;
padding-left: 50px;
padding-right: 50px;
padding-top: 50px;
padding-bottom: 50px;
hyphens: auto;
overflow-wrap: break-word;
text-rendering: optimizeLegibility;
font-kerning: normal;
}
@media (max-width: 600px) {
body {
font-size: 0.9em;
padding: 12px;
}
h1 {
font-size: 1.8em;
}
}
@media print {
html {
background-color: white;
}
body {
background-color: transparent;
color: black;
font-size: 12pt;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3, h4 {
page-break-after: avoid;
}
}
p {
margin: 1em 0;
}
a {
color: #1a1a1a;
}
a:visited {
color: #1a1a1a;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
margin-top: 1.4em;
}
h5, h6 {
font-size: 1em;
font-style: italic;
}
h6 {
font-weight: normal;
}
ol, ul {
padding-left: 1.7em;
margin-top: 1em;
}
li > ol, li > ul {
margin-top: 0;
}
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
color: #606060;
}
code {
font-family: Menlo, Monaco, Consolas, 'Lucida Console', monospace;
font-size: 85%;
margin: 0;
hyphens: manual;
}
pre {
margin: 1em 0;
overflow: auto;
}
pre code {
padding: 0;
overflow: visible;
overflow-wrap: normal;
}
.sourceCode {
background-color: transparent;
overflow: visible;
}
hr {
background-color: #1a1a1a;
border: none;
height: 1px;
margin: 1em 0;
}
table {
margin: 1em 0;
border-collapse: collapse;
width: 100%;
overflow-x: auto;
display: block;
font-variant-numeric: lining-nums tabular-nums;
}
table caption {
margin-bottom: 0.75em;
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
}
th {
border-top: 1px solid #1a1a1a;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
padding: 0.125em 0.5em 0.25em 0.5em;
}
header {
margin-bottom: 4em;
text-align: center;
}
#TOC li {
list-style: none;
}
#TOC ul {
padding-left: 1.3em;
}
#TOC > ul {
padding-left: 0;
}
#TOC a:not(:hover) {
text-decoration: none;
}
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list[class]{list-style: none;}
ul.task-list li input[type="checkbox"] {
font-size: inherit;
width: 0.8em;
margin: 0 0.8em 0.2em -1.6em;
vertical-align: middle;
}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<nav id="TOC" role="doc-toc">
<ul>
<li><a href="#comframework-21" id="toc-comframework-21"><span class="toc-section-number">1</span> comFramework 2.1</a>
<ul>
<li><a href="#about-this-project" id="toc-about-this-project"><span class="toc-section-number">1.1</span> About this project</a>
<ul>
<li><a href="#the-can-interface" id="toc-the-can-interface"><span class="toc-section-number">1.1.1</span> The CAN interface</a></li>
<li><a href="#the-dbc-code-generator" id="toc-the-dbc-code-generator"><span class="toc-section-number">1.1.2</span> The DBC code generator</a></li>
<li><a href="#dbc-parser" id="toc-dbc-parser"><span class="toc-section-number">1.1.3</span> DBC parser</a></li>
<li><a href="#excelexporter-as-auxiliary-code-generator" id="toc-excelexporter-as-auxiliary-code-generator"><span class="toc-section-number">1.1.4</span> excelExporter as auxiliary code
generator</a></li>
</ul></li>
<li><a href="#status-of-the-project" id="toc-status-of-the-project"><span class="toc-section-number">1.2</span> Status of the project</a></li>
<li><a href="#installation" id="toc-installation"><span class="toc-section-number">1.3</span> Installation</a></li>
<li><a href="#documentation" id="toc-documentation"><span class="toc-section-number">1.4</span> Documentation</a>
<ul>
<li><a href="#whats-new" id="toc-whats-new"><span class="toc-section-number">1.4.1</span> What's new</a></li>
<li><a href="#wiki-pages" id="toc-wiki-pages"><span class="toc-section-number">1.4.2</span> Wiki pages</a></li>
</ul></li>
</ul></li>
</ul>
</nav>
<h1 data-number="1" id="comframework-21"><span class="header-section-number">1</span> comFramework 2.1</h1>
<h2 data-number="1.1" id="about-this-project"><span class="header-section-number">1.1</span> About this project</h2>
<p>This project presents a flexible, widely customizable CAN
communication interface for embedded applications. It binds signal based
application code to the frame based hardware layer. It covers the CAN
stack from the application layer down to the hardware driver layer (not
including).</p>
<p>The interface implementation is code generator supported; the
dedicated API with the application software and the unpack/pack
functions for message (de)composition can be generated from information
in the network databases. A sample integration demonstrates, how to
generate much more: Setting initial signal values, DLC check, checksum
generation/validation, sequence counter generation/validation and the
implementation of different timing patterns is generated in a fully
automated fashion. Attributes defined in the DBC file(s) support the
automation.</p>
<p>We call this project a framework since the interface should be
considered a suggestion only; the high flexibility of the code
generation process makes it easy to design different interface
architectures, which can reach a similar degree of automation with
respect to changes of the network database(s).</p>
<h3 data-number="1.1.1" id="the-can-interface"><span class="header-section-number">1.1.1</span> The CAN interface</h3>
<p>The operational core of the <a href="https://github.com/PeterVranken/comFramework/wiki/The-CAN-Interface">CAN
interface</a> is a dispatcher engine that decouples the one or more
interrupts, which are typically used by the CAN hardware driver for
notification of send or receive events, from the application task(s);
this makes the complete data processing at the application side safe,
straightforward, race condition free programming.</p>
<p>The dispatcher implements a generic concept of events and
notifications by callbacks. Among more, events can be interrupts from
the hardware layer or timer events. The callback functions use the timer
and other events to model the transmission timing patterns of the frames
and to generate timeout information.</p>
<p>The callbacks are external to the dispatcher engine. They are either
auto-coded from the DBC files or they can be hand-coded and would then
operate on data tables, which are auto-coded from the DBC files. Samples
demonstrate both techniques.</p>
<p>Any number of dispatcher objects can be instantiated in order to
support multi-threading architectures in a transparent and convenient
way.</p>
<h3 data-number="1.1.2" id="the-dbc-code-generator"><span class="header-section-number">1.1.2</span> The DBC code generator</h3>
<p>The <a href="https://petervranken.github.io/comFramework/codeGenerator/readMe.html">DBC
code generator</a> consists of an open source parser for CAN network
database files (*<em>.dbc</em> or DBC files) with connected general
purpose code generator. The idea is most simple and most flexible:</p>
<p>The parser transforms the DBC files into an internal data
representation, which holds all information about the network. This data
structure is a special form of the parse tree. The structure has been
chosen such that it is compatible with the template engine
StringTemplate V4 by Terence Parr, see <a href="http://www.stringtemplate.org/">http://www.stringtemplate.org/</a>.
This template engine is capable to render deeply nested data structures
and it can therefore transform the parse tree in nearly any kind of
textual representation. This explains the high
flexibility/customizability of the whole system.</p>
<p>Just by configuring the templates, the code generator can produce
different useful representations of the information in the network
files, like:</p>
<ul>
<li>An HTML report with all frames, signals, attributes and all the
properties of these.</li>
<li>An Excel file with all the same (however, only as
*<em>.csv</em>).</li>
<li>C source code and related header files, which implement a CAN
interface. The interface will contain the needed data structures, timing
related frame processing, validation code and pack and unpack operations
to transform signal sets to frames and vice versa. The implementation
can be made specific to a particular platform's requirements.</li>
<li>LaTeX source code for documentation of the interface.</li>
<li>Interface definition files: If code from a model based code
generation environment is linked to the CAN interface (e.g. MathWorks
MATLAB with either their Embedded Coder or with dSPACE TargetLink) then
a descripition of the signal interface is essential as these code
generators need to be aware of the signal sets and their properties,
data types and scaling in the first place. Our code generator can
generate the required M scripts or XML files.</li>
<li>ASAM MCD-2 MC interface description files (*<em>.a2l</em>) if the
target platform shall be connected to a measurement and calibration tool
like ETAS INCA or Vector Informatik CANape.</li>
<li>AUTOSAR specification code (*<em>.arxml</em>). The DBC file contents
can be rendered as an AUTOSAR software component, which connects to the
ISignals of the COM stack, including all required application data types
with scaling and more information.</li>
</ul>
<h3 data-number="1.1.3" id="dbc-parser"><span class="header-section-number">1.1.3</span> DBC parser</h3>
<p>In most automation environments our code generator can be used as raw
DBC parser for whatever purpose, too. Typically, interpreted languages
like Perl, Python or Octave's M script are applied in software
automation environments. If you use any interpreted language then you
can configure the code generator to render the information in the syntax
of your scripting language. Run the code generator, run the generated
script and have the information in the context of your automation
environment. The configuration of the code generation can be tailored;
you will just render those parts of the information you really need. No
need to develop the most complex all embracing data structure. A simple
<a href="https://github.com/PeterVranken/comFramework/wiki/Reusage-of-Code,-Standalone-Use-of-DBC-Parser-and-Compatibility/#example-the-code-generator-as-dbc-parser-for-gnu-octave-m">example
for GNU Octave</a> is provided.</p>
<h3 data-number="1.1.4" id="excelexporter-as-auxiliary-code-generator"><span class="header-section-number">1.1.4</span> excelExporter as auxiliary
code generator</h3>
<p>A second, auxiliary code generator is part of the framework. This is
the Java application excelExporter. The idea is nearly the same as for
the main code generator but the input is a set of Excel workbooks
instead of DBC files. The parse tree can be as simple as a linear list
of rows from a flat table or a as complex as a deeply nested tree of
interrelated data items. The concrete data structure depends on the
definition of the input. The parse tree is rendered by the
StringTemplate V4 template engine, identical to what has been said for
the DBC code generator. The intented use case of the auxiliary code
generator excelExporter is to support the handling of interfaces. Excel
files serve as data dictionary of signals, variables, diagnostic
interface items, etc. and can be translated into C/C++ interface
implementations, documentation, ASAM MCD-2 MC or AUTOSAR interface
specifications, etc.</p>
<h2 data-number="1.2" id="status-of-the-project"><span class="header-section-number">1.2</span> Status of the project</h2>
<p>The project is ready for productive use.</p>
<ul>
<li>The CAN interface with its dispatcher engine is distributed as
source code; concept and how-to-use are documented in this <a href="https://github.com/PeterVranken/comFramework/wiki/The-CAN-Interface">Wiki
page</a>.</li>
<li>Several compilable and runnable sample integrations of the CAN
interface are distributed with source code and makefiles together with
the dispatcher engine. There are integrations for Windows, there's an
Arduino ATmega 2560 real time integration and an integration with the
MathWorks Embedded Coder. A complete runnable real-time application for
MPC5748G with CAN driver and integrated CAN interface can be found at <a href="https://github.com/PeterVranken/DEVKIT-MPC5748G/tree/master/samples/CAN">GitHub</a>.</li>
<li>The code generators are distributed as Java application. A number of
samples for the <a href="https://github.com/PeterVranken/comFramework/tree/main/codeGenerator/samples">DBC
code generator</a> and for <a href="https://github.com/PeterVranken/comFramework/tree/main/excelExporter/samples">excelExporter</a>
demonstrate how templates can look like, which do the transformations
mentioned above.</li>
<li><a href="https://github.com/PeterVranken/comFramework/releases">GitHub
Releases</a> provide ZIP archives for download, which bundle all needed
tools, files and samples in a ready-to-use folder structure.</li>
<li>More recent revisions of the software are distributed as source code
in this repository and, as far as the code generation tools are
concerned, as compiled Java *<em>.jar</em> files. Get for example the
last recent DBC code generator by replacing the files <em>dist/</em>* in
your installation by the files from <a href="https://github.com/PeterVranken/comFramework/tree/main/codeGenerator/dist/">https://github.com/PeterVranken/comFramework/tree/main/codeGenerator/dist/</a>.
excelExporter files would be found <a href="https://github.com/PeterVranken/comFramework/tree/main/excelExporter/dist">here</a>,
respectively.</li>
</ul>
<p>Support of the project is appreciated to support more kinds of
network databases. For now, we are restricted to the DBC format.
However, this format looses importance. New formats like arxml or FIBEX
will probably supersede DBC in the future. Furthermore, different
physical bus systems have different network database files, like
*<em>.ldf</em> for LIN communication. Parsers for these input formats
are required and - what's more difficult - a common data model for all
of these buses and network files needs to be developed so that the
parser becomes a configurable choice but the templates can be kept
widely independent of the input format.</p>
<h2 data-number="1.3" id="installation"><span class="header-section-number">1.3</span> Installation</h2>
<p>comFramework is distributed as a ZIP archive. The installation means
extracting the archive, providing a Java JRE and setting a few
environment variables.</p>
<p>Please find the installation guide <a href="https://github.com/PeterVranken/comFramework/wiki/Installation/">online
in GitHub</a> or as file <a href="doc/installation.html"><em>comFramework/doc/installation.html</em></a>
after extracting the archive.</p>
<h2 data-number="1.4" id="documentation"><span class="header-section-number">1.4</span> Documentation</h2>
<h3 data-number="1.4.1" id="whats-new"><span class="header-section-number">1.4.1</span> What's new</h3>
<p>CAN Interface: An overview of all available documentation and of the
latest changes is given in the related <a href="https://petervranken.github.io/comFramework/canInterface/readMe.html"><code>readMe</code></a>
file.</p>
<p>DBC Code Generator: An overview of the documentation and the latest
changes is given in the related <a href="https://petervranken.github.io/comFramework/codeGenerator/readMe.html"><code>readMe</code></a>
file.</p>
<p>Excel Exporter: An overview of the documentation and the latest
changes is given in the related <a href="https://petervranken.github.io/comFramework/excelExporter/readMe.html"><code>readMe</code></a>
file.</p>
<h3 data-number="1.4.2" id="wiki-pages"><span class="header-section-number">1.4.2</span> Wiki pages</h3>
<p>A growing source of documentation are the <a href="https://github.com/PeterVranken/comFramework/wiki" title="comFramework - About this Project">Wiki pages</a> of the project.
The Wiki pages shade a light at some most relevant, selected issues; a
comprehensive, self-contained (printable) manual is not planned.</p>
<p>As of today, December 2024, we have the following discussions in the
Wiki pages:</p>
<ul>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/Installation/">Installation
of distributed ZIP archive</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/The-CAN-Interface">The
CAN interface - concept and usage</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/The-DBC-Code-Generator">The
DBC code generator</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/The-Command-Line-of-the-comFramework-DBC-Code-Generator" title="Usage of DBC code generator">The command line of the DBC code
generator</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/Reusage-of-Code,-Standalone-Use-of-DBC-Parser-and-Compatibility#Compatibility">Compatibility
of the DBC parser with real *<em>.dbc</em> files</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/Prerequisites,-Limitations-and-Pitfalls" title="Java version, known issues">Prerequisites, limitations and
pitfalls</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/Reusage-of-Code,-Standalone-Use-of-DBC-Parser-and-Compatibility" title="Reusage of code, standalone use of DBC parser and compatibility">Reusability
of the DBC file parser in other contexts/applications</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/Conditional-Code-Generation-vs-Generation-of-Conditional-Code" title="Conditional code generation versus generation of conditional code">Options
for conditional code generation</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/How-to-access-Attributes-in-the-Network-Database" title="How to access attributes in the network database?">The use of
attributes</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/How-to-access-Attributes-in-the-Network-Database#typical-code-architecture" title="Typical code architecture">A common pattern how to combine
handwritten code with auto-generated code in a beneficial way</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/Sugar-on-Top-of-Inheritance-or-how-to-change-the-Copyright-Notice" title="Terence Parr: 'Sugar on top of inheritance'">Sugar on top
of inheritance or how to change the copyright notice</a></li>
<li><a href="https://github.com/PeterVranken/comFramework/wiki/Home/" title="excelExporter's Wiki Home Page">Concept of
excelExporter</a></li>
</ul>
</body>
</html>