+
- Scenario
-This sample application implements a power display device for an automotive vehicle. It reads the current values of engine rotational speed and engine torque from the CAN bus and computes the current power of the engine. The power is broadcasted on the CAN bus (to whom it may concern, no specific receiver is specified). This message transfer is regular, in- and output are repeated every 10 ms.
-The power display sends a second frame. It counts all recognized error events (timeout, DLC, checksum and transmission sequence). Some of these are regularly reported by a dedicated CAN frame. However, this frame is not only sent regularly but also in the instance of a changing counter value. This is called the mixed mode.
-To make the sample more instructive some less realistic CAN messages have been invented. For whatever reasons our application can compare the computed power and the rotational speed against some user-defined limits. If a range is exceeded (or when we get into range again) then and only then an according CAN frame is broadcasted. This “functionality” has been specified for the only reason to have some purely event based frames in the system. Two frames are involved: The vehicle sends the limits and our power display sends the in-range or range violation frame.
- Involved frames
-StateEcu01, StateEcu02: Inbound frames to our power display. Origin is the engine control unit. These frames contain current values of rotational speed and torque. They are sent periodically every 10 ms.
-UserLimits: Inbound frame for our power display application. There may be a human machine interface in the vehicle, where the user can enter the current ranges for the observation of rotational speed and power. The frame is only sent when one of the settings is changed. This will happen rarely and occasionally only.
-InfoPowerDisplay: This frame is sent regularly by our power display. It contains the computed power plus a status signal. This status will indicate if the compute power is invalid or unavailable, e.g. due to recognized errors on the input frames.
-StatusPowerDisplay: The number of recognized checksum, DLC and transmission sequence errors so far. Sent by the power display, when one of the counter values alters. But no more often then every 50 ms. If no counter value has altered during the last 1000 ms then the frame is re-sent with same contents (except for the sequence counter of course). If the counter values never change than this frame becomes a regular 1000 ms frame.
-LimitsPowerDisplay: Sent by the power display in logical (not immediate) response to frame UserLimits. When the range for speed of rotation or power as defined by the last recently received frame UserLimits is violated the first time or when violation the range is over then the power display sends this frame to indicate the current in- or out-of-range status. As long as this status doesn’t change this frame won’t be sent.
- Specification of DBC file
- Attributes
-The DBC file uses some application specific attributes to specify the different behavior of the frames and signals.
+ Scenario
+This sample application implements a power display device for an
+automotive vehicle. It reads the current values of engine rotational
+speed and engine torque from the CAN bus and computes the current power
+of the engine. The power is broadcasted on the CAN bus (to whom it may
+concern, no specific receiver is specified). This message transfer is
+regular, in- and output are repeated every 10 ms.
+The power display sends a second frame. It counts all recognized
+error events (timeout, DLC, checksum and transmission sequence). Some of
+these are regularly reported by a dedicated CAN frame. However, this
+frame is not only sent regularly but also in the instance of a changing
+counter value. This is called the mixed mode.
+To make the sample more instructive some less realistic CAN messages
+have been invented. For whatever reasons our application can compare the
+computed power and the rotational speed against some user-defined
+limits. If a range is exceeded (or when we get into range again) then
+and only then an according CAN frame is broadcasted. This
+"functionality" has been specified for the only reason to have some
+purely event based frames in the system. Two frames are involved: The
+vehicle sends the limits and our power display sends the in-range or
+range violation frame.
+ Involved frames
+StateEcu01, StateEcu02: Inbound frames to our power display. Origin
+is the engine control unit. These frames contain current values of
+rotational speed and torque. They are sent periodically every 10 ms.
+UserLimits: Inbound frame for our power display application. There
+may be a human machine interface in the vehicle, where the user can
+enter the current ranges for the observation of rotational speed and
+power. The frame is only sent when one of the settings is changed. This
+will happen rarely and occasionally only.
+InfoPowerDisplay: This frame is sent regularly by our power display.
+It contains the computed power plus a status signal. This status will
+indicate if the compute power is invalid or unavailable, e.g. due to
+recognized errors on the input frames.
+StatusPowerDisplay: The number of recognized checksum, DLC and
+transmission sequence errors so far. Sent by the power display, when one
+of the counter values alters. But no more often then every 50 ms. If no
+counter value has altered during the last 1000 ms then the frame is
+re-sent with same contents (except for the sequence counter of course).
+If the counter values never change than this frame becomes a regular
+1000 ms frame.
+LimitsPowerDisplay: Sent by the power display in logical (not
+immediate) response to frame UserLimits. When the range for speed of
+rotation or power as defined by the last recently received frame
+UserLimits is violated the first time or when violation the range is
+over then the power display sends this frame to indicate the current in-
+or out-of-range status. As long as this status doesn't change this frame
+won't be sent.
+ Specification of DBC file
+ Attributes
+The DBC file uses some application specific attributes to specify the
+different behavior of the frames and signals.
The following frame related attributes have been defined:
-frameSendMode: An enumeration, which specifies the transmission/timing pattern of the frame. Known values are “regular”, “event” and “mixed”. Default value is regular
+ frameSendMode: An enumeration, which specifies the
+transmission/timing pattern of the frame. Known values are "regular",
+"event" and "mixed". Default value is regular
-regular: Purely time controlled frames. Inbound frames are expected regularly and a timeout error is raised if they stay away. Outbound frames are sent strictly regular
-event: Frames are excepted to be sent when and only when their contents change. For inbound frames it means that a timeout can’t be defined. Outbound frames are sent on data change. A minimum distance in time is defined, which limits the frequency of send events even in case of permanent content changes
-mixed: Outbound frames are send on data change but no more often as defined by the minimum distance in time. If no data change has been seen for a second specified time parameter then the frame is sent, too. Inbound frames are handled like regular frames with the only exception that the timeout is related to the specified minimum send frequency
+regular: Purely time controlled frames. Inbound frames are expected
+regularly and a timeout error is raised if they stay away. Outbound
+frames are sent strictly regular
+event: Frames are excepted to be sent when and only when their
+contents change. For inbound frames it means that a timeout can't be
+defined. Outbound frames are sent on data change. A minimum distance in
+time is defined, which limits the frequency of send events even in case
+of permanent content changes
+mixed: Outbound frames are send on data change but no more often as
+defined by the minimum distance in time. If no data change has been seen
+for a second specified time parameter then the frame is sent, too.
+Inbound frames are handled like regular frames with the only exception
+that the timeout is related to the specified minimum send frequency
sendPeriod: A numeric integer value specifying the period time of regular frames in Milliseconds. Range is [5, 10000] ms. Default value is 10 ms.
-For mixed mode frames this value specifies the maximum time span in between two transmission events.
+sendPeriod: A numeric integer value specifying the period time of
+regular frames in Milliseconds. Range is [5, 10000] ms. Default value is
+10 ms.
+For mixed mode frames this value specifies the maximum time span in
+between two transmission events.
For event mode frames this attribute is irrelevant
eventMinDistance: A numeric integer value specifying the minimum distance in time between two transmission events in Milliseconds. Range is [5, 10000] ms. Default value is 20 ms.
+eventMinDistance: A numeric integer value specifying the minimum
+distance in time between two transmission events in Milliseconds. Range
+is [5, 10000] ms. Default value is 20 ms.
For regular frames this attribute is ignored
checksumStartValue: To avoid confounding frames of different CAN IDs the checksum validation uses different checksum definitions for different frames. An individual start value of the computation is applied. The start value is specified with this attribute. It is an integer number in the range [0, 255] and the default value is 0
checksumStartValue: To avoid confounding frames of different CAN
+IDs the checksum validation uses different checksum definitions for
+different frames. An individual start value of the computation is
+applied. The start value is specified with this attribute. It is an
+integer number in the range [0, 255] and the default value is 0
The following signal related attributes have been defined:
-initialValue: A floating point number in the range [-1e99, 1e99], which specifies the inital world value of the signal. Default value is 0.
-For inbound frames, the API will show this value for the signal as long as the containing frame has never been received.
-For outbound frames, this value will be sent as long as the APSW has not updated the API value yet
initialValue: A floating point number in the range [-1e99, 1e99],
+which specifies the inital world value of the signal. Default value is
+0.
+For inbound frames, the API will show this value for the signal as
+long as the containing frame has never been received.
+For outbound frames, this value will be sent as long as the APSW has
+not updated the API value yet
- Special signals
-The sample implements a production level validation of the communication. It defines a checksum and a sequence counter signal for most frames. (Not for all however, to get more inhomogeneity and better test coverage into the code.) The code generation process is supported by specifying naming schemes for these signals:
+ Special signals
+The sample implements a production level validation of the
+communication. It defines a checksum and a sequence counter signal for
+most frames. (Not for all however, to get more inhomogeneity and better
+test coverage into the code.) The code generation process is supported
+by specifying naming schemes for these signals:
-checksum: If a signal has this name then it is considered an 8 Bit checksum. The checksum needs to allocate a complete byte of the frame; it must not go across a byte location. The checksum is defined to be the binary inverted arithmetic sum of all other frame content bytes and the frame individual start value
sequenceCounter: If a signal has this name then it is considered a cyclic sequence counter. The counter may have up to eight bit and it may go across a byte location in the frame. The counting range is defined by the min and max property of the signal. min > max is permitted; this means inverse counting direction. A counting cycle always begins with min and always ends with max
checksum: If a signal has this name then it is considered an 8
+Bit checksum. The checksum needs to allocate a complete byte of the
+frame; it must not go across a byte location. The checksum is defined to
+be the binary inverted arithmetic sum of all other frame content bytes
+and the frame individual start value
sequenceCounter: If a signal has this name then it is considered
+a cyclic sequence counter. The counter may have up to eight bit and it
+may go across a byte location in the frame. The counting range is
+defined by the min and max property of the signal. min > max is
+permitted; this means inverse counting direction. A counting cycle
+always begins with min and always ends with max
- Allocation of bits
-The positioning of signals in the frames has purposely been done in an inefficient way. This must not be considered a design error of the sample. Useless crossing of byte boundaries, useless gaps between signals and mixed byte ordering have been defined just to make the required pack and unpack code more difficult and to improve the test coverage.
+ Allocation of bits
+The positioning of signals in the frames has purposely been done in
+an inefficient way. This must not be considered a design error of the
+sample. Useless crossing of byte boundaries, useless gaps between
+signals and mixed byte ordering have been defined just to make the
+required pack and unpack code more difficult and to improve the test
+coverage.
diff --git a/canInterface/sampleIntegrations/winSampleIntegration/readMe.html b/canInterface/sampleIntegrations/winSampleIntegration/readMe.html
index f400099..83e9468 100644
--- a/canInterface/sampleIntegrations/winSampleIntegration/readMe.html
+++ b/canInterface/sampleIntegrations/winSampleIntegration/readMe.html
@@ -1,18 +1,168 @@
-
+
readMe
+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;}
+
@@ -20,49 +170,129 @@
Windows Sample Integration
Scope
-This sample application implements a power display device for an automotive vehicle as a Windows application. Although the application is entirely useless as such it contains all elements of the integration of the comFramework CAN interface into a real embedded platform. All needed code elements can be inspected and understood and the application can be run and debugged for detail investigations. Many of the code elements and particularly most of the code-generation template code will be reusable in the aimed target environment. This is proven by the second sample integration, ../arduinoSampleIntegration, which has the same functionality and shares many code elements with only minor modifications.
-The application reads the current values of engine rotational speed and engine torque from the CAN bus and computes the current power of the engine. The results are printed to the console and written in a log file.
-The sample code comes along with all source files and build scripts (makefile based). GNU GCC and GNU make 3.81 should be in the system search path, then the build command would be (Windows, other systems accordingly):
+This sample application implements a power display device for an
+automotive vehicle as a Windows application. Although the application is
+entirely useless as such it contains all elements of the integration of
+the comFramework CAN interface into a real embedded platform. All needed
+code elements can be inspected and understood and the application can be
+run and debugged for detail investigations. Many of the code elements
+and particularly most of the code-generation template code will be
+reusable in the aimed target environment. This is proven by the second
+sample integration, ../arduinoSampleIntegration, which has the same
+functionality and shares many code elements with only minor
+modifications.
+The application reads the current values of engine rotational speed
+and engine torque from the CAN bus and computes the current power of the
+engine. The results are printed to the console and written in a log
+file.
+The sample code comes along with all source files and build scripts
+(makefile based). GNU GCC and GNU make 3.82 should be in the system
+search path, then the build command would be (Windows, other systems
+accordingly):
cd <...>\comFramework\canInterface\sampleIntegrations\winSampleIntegration
make -s buildTo start the sample application you may type:
make -s runPlease try also: make help
-Note, on Windows systems you will need the MinGW port of make, not the Cygwin port. Many GCC distributions contain both variants, so it depends on your system search path, which one is run. Or consider typing mingw32-make build; in a Windows GCC distribution this should be a safe reference to the right implementation of make. The Cygwin variant uses another interface to the underlying shell and this interface is not compatible with our makefiles.
+Note, on Windows systems you will need the MinGW port of make, not
+the Cygwin port. Many GCC distributions contain both variants, so it
+depends on your system search path, which one is run. Or consider typing
+mingw32-make build; in a Windows GCC distribution this
+should be a safe reference to the right implementation of make. The
+Cygwin variant uses another interface to the underlying shell and this
+interface is not compatible with our makefiles.
Application design
-We designed this application to demonstrate how an integration into a real platform can look like. The actual capabilities of the application are secondary.
+We designed this application to demonstrate how an integration into a
+real platform can look like. The actual capabilities of the application
+are secondary.
Folder osSimulation
-The integration doesn’t support real CAN hardware and it neither builds on a real strictly priority controlled RTOS. Instead, a simulation frame has been shaped, which simulates the task scheduling and the interrupt based CAN interface of a fictive operating system. The simulation is most simple and particularly is it single-threaded. The tasks of different priorities and the interrupt notifications are executed strictly sequential and no race-conditions occur. All multi-threading related aspects of the CAN interface can in no way be tested in this environment but the code elements and structure and thus the instructive intention of the application are not affected by this fact.
-The simulation computes triangular curves of different frequencies for speed of rotation and engine torque. This leads to a dynamic but not exciting behavior of the application.
-The simulation code can inject the following kinds of CAN communication errors: Timeout, wrong data length code, bad checksum, bad sequence counter value, bus-off error (and recovery). The occurrence of the errors is random controlled; the probabilities can be adjusted by #define macros at compile time.
+The integration doesn't support real CAN hardware and it neither
+builds on a real strictly priority controlled RTOS. Instead, a
+simulation frame has been shaped, which simulates the task scheduling
+and the interrupt based CAN interface of a fictive operating system. The
+simulation is most simple and particularly is it single-threaded. The
+tasks of different priorities and the interrupt notifications are
+executed strictly sequential and no race-conditions occur. All
+multi-threading related aspects of the CAN interface can in no way be
+tested in this environment but the code elements and structure and thus
+the instructive intention of the application are not affected by this
+fact.
+The simulation computes triangular curves of different frequencies
+for speed of rotation and engine torque. This leads to a dynamic but not
+exciting behavior of the application.
+The simulation code can inject the following kinds of CAN
+communication errors: Timeout, wrong data length code, bad checksum, bad
+sequence counter value, bus-off error (and recovery). The occurrence of
+the errors is random controlled; the probabilities can be adjusted by
+#define macros at compile time.
Folder APSW
-The functional code, the application software or APSW, reads the current speed of rotation and engine torque values, computes the current engine power and prints the results. It can display a lot of program flow information and in particular the simulated and recognized CAN communication errors. The verbosity can be controlled via the command line. (Try --help first.)
-The APSW is hand-coded but in structure it is designed to resemble the code of typical model based development environments in that it simply reads required input signal values from some global variables, performs the computations and writes the results into other dedicated global variables. This design pattern was chosen in order to prove the CAN interface’s capabilities for support of data-change triggered frames. (Hand-coded software tends to be event driven by itself, which makes data-change recognition mechanisms obsolete.)
+The functional code, the application software or APSW, reads the
+current speed of rotation and engine torque values, computes the current
+engine power and prints the results. It can display a lot of program
+flow information and in particular the simulated and recognized CAN
+communication errors. The verbosity can be controlled via the command
+line. (Try --help first.)
+The APSW is hand-coded but in structure it is designed to resemble
+the code of typical model based development environments in that it
+simply reads required input signal values from some global variables,
+performs the computations and writes the results into other dedicated
+global variables. This design pattern was chosen in order to prove the
+CAN interface's capabilities for support of data-change triggered
+frames. (Hand-coded software tends to be event driven by itself, which
+makes data-change recognition mechanisms obsolete.)
The APSW code is located in folder code\APSW.
Folder integration
-More important is folder code\integration. It contains those hand-coded parts of the application, which are needed to integrate the CAN interface with any real platform (or operating system). The tasks are defined that do the initialization of the CAN interface (frame and bus registration) and the regular clocking of the interface engine instances. Moreover, the handle mapping and the checksum and sequence counter update/validation, which are external to but required by the CAN interface engine are implemented here.
-Please note: Handle mapping is always required by the CAN interface (it’ll be a trivial identity in many environments like in our Arduino integration), but checksum and sequence counter update/validation are a matter of application specific configuration only.
-The integration code contains the handling of bus errors, too. Although it strongly resembles the auto-generated code for frame handling (see below) and although it could be auto-generated, too, we decided for hand-coding. The reason simply is that the number of CAN buses is very low in comparison to the number of frames and that the CAN bus configuration typically doesn’t undergo frequent changes in the course of a software project. Maintaining this code through template programming as it would be required for auto-generated coding, won’t ever pay off.
+More important is folder code\integration. It contains those
+hand-coded parts of the application, which are needed to integrate the
+CAN interface with any real platform (or operating system). The tasks
+are defined that do the initialization of the CAN interface (frame and
+bus registration) and the regular clocking of the interface engine
+instances. Moreover, the handle mapping and the checksum and sequence
+counter update/validation, which are external to but required by the CAN
+interface engine are implemented here.
+Please note: Handle mapping is always required by the CAN interface
+(it'll be a trivial identity in many environments like in our Arduino
+integration), but checksum and sequence counter update/validation are a
+matter of application specific configuration only.
+The integration code contains the handling of bus errors, too.
+Although it strongly resembles the auto-generated code for frame
+handling (see below) and although it could be auto-generated, too, we
+decided for hand-coding. The reason simply is that the number of CAN
+buses is very low in comparison to the number of frames and that the CAN
+bus configuration typically doesn't undergo frequent changes in the
+course of a software project. Maintaining this code through template
+programming as it would be required for auto-generated coding, won't
+ever pay off.
Folder codeGen
-Most important is folder code\codeGen. It contains the configuration of the CAN interface for this application. This configuration is mainly determined by the code generation from the network database file(s). The transmission modes and all program flow for communication validation (timeouts, checksum and sequence counter support) are implemented here, controlled by the attributes in the network databases. Moreover, the global data API with the APSW, which is highly dependent on the network databases is implemented here, too.
-All C sources and related header files in this folder are generated by the code generator.
+Most important is folder code\codeGen. It contains the configuration
+of the CAN interface for this application. This configuration is mainly
+determined by the code generation from the network database file(s). The
+transmission modes and all program flow for communication validation
+(timeouts, checksum and sequence counter support) are implemented here,
+controlled by the attributes in the network databases. Moreover, the
+global data API with the APSW, which is highly dependent on the network
+databases is implemented here, too.
+All C sources and related header files in this folder are generated
+by the code generator.
Folder environment
-This folder contains a few header and stub files to satisfy the compilation and to support compilation with both, Windows GCC 32 Bit and 64 Bit, which differ in some respects.
+This folder contains a few header and stub files to satisfy the
+compilation and to support compilation with both, Windows GCC 32 Bit and
+64 Bit, which differ in some respects.
diff --git a/canInterface/sampleIntegrations/winTestMT/whichCCompilerToUse.adoc b/canInterface/sampleIntegrations/winTestMT/whichCCompilerToUse.adoc
index 2e8a99e..02b1708 100644
--- a/canInterface/sampleIntegrations/winTestMT/whichCCompilerToUse.adoc
+++ b/canInterface/sampleIntegrations/winTestMT/whichCCompilerToUse.adoc
@@ -30,4 +30,4 @@ permanently hurt, up to several hundred Milliseconds. This has the
consequence of exorbitant numbers of CAN timing errors being reported.
The differences between the two compiler's are likely because of their
-individual implementations of the pthread environment.
\ No newline at end of file
+individual implementations of the pthreads environment.
\ No newline at end of file
diff --git a/canInterface/sampleIntegrations/winTestMT/whichCCompilerToUse.html b/canInterface/sampleIntegrations/winTestMT/whichCCompilerToUse.html
index 1fb06e3..cbcf756 100644
--- a/canInterface/sampleIntegrations/winTestMT/whichCCompilerToUse.html
+++ b/canInterface/sampleIntegrations/winTestMT/whichCCompilerToUse.html
@@ -487,12 +487,12 @@ Which C Compiler to use?
The differences between the two compiler’s are likely because of their
-individual implementations of the pthread environment.
+individual implementations of the pthreads environment.