comFramework Wiki

Framework for CAN communication interfaces including code generator

Brought to you by: vranken

Home

Authors:

comFramework v2.1.79 (11.12.2024)

comFramework v2.1.79 (11.12.2024)

Important Announcement, Dec 13, 2024

This project is no longer going to be maintained on SourceForge. It
transited to GitHub, see https://github.com/PeterVranken/comFramework.
The first GitHub release, 2024-12-11-comFramework_v2.1.79.zip, is at the
same time the last one, which is published here at SourceForge. It has
already been compiled at GitHub but it is still consistent with the latest
source code found here at SourceForge.

Thank you for your continued trust in SourceForge, and please continue to
visit us on GitHub!

About this project

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).

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.

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).

The CAN interface

The operational core of the CAN interface 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.

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.

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.

Any number of dispatcher objects can be instantiated in order to support
multi-threading architectures in a transparent and convenient way.

The DBC code generator

The code generator consists of an open source parser for CAN network
database files (*.dbc or DBC files) with connected general purpose code
generator. The idea is most simple and most flexible:

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 http://www.stringtemplate.org/. 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.

Just by configuring the templates, the code generator can produce
different useful representations of the information in the network files,
like:

An HTML report with all frames, signals, attributes and all the
properties of these
An Excel file with all the same (however, only as *.csv)
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
LaTeX source code for documentation of the interface
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
ASAM MCD-2 MC interface description files (*.a2l) if the target
platform shall be connected to a measurement and calibration tool like
ETAS INCA or Vector Informatik CANape
AUTOSAR specification code (*.arxml). 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

DBC parser

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 example for GNU Octave
is provided.

excelExporter as auxiliary code generator

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.

Status of the project

The project is ready for productive use.

The CAN interface with its dispatcher engine is distributed as source
code; concept and how-to-use are documented in this Wiki page
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
GitHub
The code generators are distributed as Java application. A number of
samples for the DBC code generator and for excelExporter demonstrate
how templates can look like, which do the transformations mentioned above
The download page at SourceForge provides a ZIP archive for download,
which bundles all needed tools, files and samples in a ready-to-use
folder structure. The elder revision 1.51 (r430, 02.03.2022) is still
available, too. It is the last update of the software from before the
redesign of the CAN interface
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 *.jar files. Get for example the last recent DBC code
generator by replacing the files dist/*.jar and dist/*.cmd in your
installation by the jar files and command files from
https://sourceforge.net/p/comframe/code/HEAD/tree/codeGenerator/trunk/dist/.
excelExporter files would be found here, respectively

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 *.ldf 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.

Installation

comFramework is mainly distributed as a ZIP archive. Some external tools
like a C compiler are useful. Please find the installation guide as
Installation of distributed ZIP archive.

Documentation

What's new

Latest news about the progress of the project can be found as discussion
thread What's new.

The CAN interface is mainly documented in this Wiki page. An overview of
all available documentation and of the latest changes is given in the
related readMe file.

An overview of the documentation and the latest changes of the DBC code
generator is given in the related readMe file.

An overview of the documentation and the latest changes of the auxiliary
code generator excelExporter is given in the related readMe file.

Wiki pages

A growing source of documentation are the Wiki pages of the project,
please refer to https://sourceforge.net/p/comframe/wiki/browse_pages/.
The Wiki pages shade a light at some most relevant, selected issues; a
comprehensive, self-contained (printable) manual is not planned.

As of today, October 2022, we have the following discussions in the Wiki
pages: