Advanced Features of EHB-CB

Intermediate Hierarchy Filtering

This feature is sold as a separate option on request and is not part of the standard EHB-CB tool. There is the request, that the interactive ASCET model of a function only contains sub hierarchies for which an image screenshot in the documentation is also available. However, to allow a continuous model navigation, also intermediate hierarchies without documentation has to be handled and shown in an appropriate way.

Example:

White list [H1, H3]: Hierarchies whose image screenshots are present in the documentation.

Intermediate list [H2]: Hierarchies whose parent [H1] is a white listed hierarchy and whose one or more child hierarchies [H3] are also white listed. But H2 is not present in the documentation.

To allow now a model navigation from H1 to H3, H2 will be still shown, but its contents of it are filtered out to maintain minimalist information.

Without the option -ihf, only H1 will be part of the interactive model.

The ihf feature is only an emergency solution and has some limitations. The better way would be to use the build-in view mechanisms of ASCET upfront, see chapter View Concept

Known limitations:

SVG image will not be generated for filtered sub-hierarchies.
For resolving all white listed class definition paths with “ihf” the model conversion may take significantly longer. The time increases exponentially as the number of references and *.amd files increases.

If the ASCET model contains about 1000 references (Class instance entries) the time is increased by a factor of 5 and if model has more than 150 *.amd file entries the time is increased by a factor of 10.

Root Level Skipping

Typically, an ASCET, ASCET-DEVELOPER or Simulink model starts with some first wrapping hierarchies, which were of no interest to the EHB-NAV user. In addition, for the seamless function wallpaper feature, it just wastes space and makes it complex. Therefore, EHB-CB provides the flexibility to change the entry level of a model type (ASCET, ASCET-DEVELOPER, SIMULINK) by using a JSON configuration file.

Considering the example below without skipping:

Figure 1. Since level (1) and (2) does not contain any information the user can directly view level (3) of the model using this feature.

Same example with skipping of the first two root levels:

With the JSON file shown below (plain ASCII format), all ASCET models in the container are opened with its 2^nd and ASCET-DEVELOPER, SIMULINK with 1^st level.

{
	"rootLevel": {
		"ASCET": "2",
		"Simulink": "1",
		"ASCET-DEVELOPER": "1",
	}
}

Conditions for level skipping:

Level exceeds
In case the level specified in JSON file is exceeding the one available in the model, then the tool stops at the last available level in the model.
Multiple sub levels in parallel
In case of multiple expandable sub levels exist in an upper level, the tool stops at the immediate parent level, as there is a conflict of unambiguousness.

To activate this feature, the command line option -rootlevel “path_to_jsonfile\name.json” has to be provided.

A sample file is available in the examples sub folder of the EHB-CB installation directory. (..\examples\configuration\RootLevel.json)

For the C-Code models, root-level skip cannot be applied.

Container Encryption

This feature is sold as a separate option on request and is not part of the standard EHB-CB tool. Encrypted containers can be generated by using the command parameter -epwd or -epwdf. The password can be passed either in the command line e.g. -epwd "qwertz" or within a password file e.g. -epwdf ./my_password_file.txt. If using a separate password file, the password must be surrounded with % characters e.g. %my_secret% as content of the password file. The password file is deleted after container encryption.

The password should satisfy the following credentials:

Password length: minimum 4; maximum 255 characters
Password characters: alphanumeric, special characters are allowed
Password pattern: No special pattern is required

The container gets the new file extension .ehbcrypt. It can be opened in the EHB-NAV in the same way. But after section of the container file, the user will be prompted for the correct password to be typed in.

ClickPic

EHANDBOOK Container-Build is capable to generate graphics out of a model and link it with its corresponding interactive model hierarchy. In addition, these graphics are linked between each others in the Function Documentation Window in EHB-NAV, the so called ClickPic navigation feature. To visualize these graphics, some special keywords have to be added in the text source files.

RTF input files:

[ehbmodelref]
Model hierarchy path in text style of type “Caption”

AsciiDoc input files:

ehbmodelref::model_path[image_title]

ASAM input files:

In FSX, the FIGURE’s <SHORT-NAME> for the model graphic contains the model hierarchy path directly in a mandatory format i.e. “X.Y.Z”.

More details about this can be found in the separate specification documents, which are located in the sub folder ../documentation of your EHB-CB installation folder.

To allow EHB-CB generated graphics and ClickPic containers must be generated by using the command parameter -gensvg, otherwise this feature will not work!

Figure 2. Navigable blocks indicated by arrow and orange frame

NOTICE

Incomplete, wrong or differing representation of model screenshots and interactive models from source data.

During the conversion of ASCET models, Simulink/Stateflow models or C-Code to interactive models and/or SVG graphics, the generated outputs may differ from the original model visualizations. As C-Code is written in textual form while interactive models are graphical diagrams, the semantic and interpretation can differ.

The following deviations between the model and the EHANDBOOK Container content may occur:

Missing or wrong graphics
Wrong targets on linked graphics
- Wrong model links
- Wrong model hierarchy links
For C-Code visualizations, different interpretations and semantics

Possible root causes of these deviations are:

Link specification in input text does not match to model hierachy path
Referenced model/source files are missing
Matlab connection for mask generation in Simulink was broken,
EHB-CB tool error due to internal error or unsupported source content
Technical limitations, especially for representing C-Code as graphical visualization

To identify deviations:

Check the entries in the log file of the generated EHANDBOOK Container for Warnings and Errors
Check the links between SVG graphics and interactive models in the EHANDBOOK Container

It is the responsibility of the creator of the EHANDBOOK Container to check the log files generated by EHANDBOOK Container-Build and to check the outputs for wrong model references and initiate the correction in the sources.

To ensure consistency and mitigate limitations:

Check the release notes and the known issues of EHANDBOOK Container-Build as well as EHANDBOOK-NAVIGATOR.
Compare the C-Code source code with the its graphical representation in EHANDBOOK-NAVIGATOR.

View Concept

For know-how protection purposes, ASCET allows designing the models for different views, e.g. it is possible to hide some element for a defined view. EHB supports this concept. With the command line option -viewtype “ViewName” you are setting, for which view the model and its screenshots should be generated. The command line option -ascetview “config-file.xml” locates the file, where for every view name the corresponding model appearance is configured in a given format.

You can export a view file from ASCET:

Tools (ASCET Main Window) Views → Select the view names to be exported (multiple selection allowed) → Click Export button and choose destination and name of the file.

The following elements are supported in EHB for the views:

ASCET View contents	Support in EHB
BDE Settings Show Unused Sequence Calls Show Used Sequence Calls Show Graphical Comments Show Process Name Locals	All settings supported
Default settings for Elements As Line Invisible Contour Hide Contents	Element properties of type ‘Implementation Cast’ is supported only
Documentation Settings	Not Implemented

ASCET View contents

Support in EHB

BDE Settings

Show Unused Sequence Calls

Show Used Sequence Calls

Show Graphical Comments

Show Process Name Locals

All settings supported

Default settings for Elements

As Line
Invisible

Contour
Hide Contents

Element properties of type ‘Implementation Cast’ is supported only

Documentation Settings

Not Implemented

In ASAM-CCX, you can also define a view name in the tag <SD GID="view">Name</SD>. It supersedes the command line option -viewtype. For details, please refer to the document ASAM Format Specification for EHB, which is located in the sub folder ../documentation of your EHB-CB installation folder.

The view name provided by -viewtype has to match to the view name specified in corresponding view file, otherwise no view is applied.

For c-code the same method is used with the parameter -ccodeview “config-file.xml”. Here the same xml format as for ASCET is used, but you can only specify, if process sequence calls are visible in the interactive model or not. These calls are showing the computation order of the c-code.

Sample files are available in the examples sub folder of the EHB-CB installation directory. (..\examples\configuration\AscetFiguresView.xml, CCodeViews.xml)

Configuration of details shown for Simulink subsystem-based blocks

For know-how protection reasons or for a better readability, Simulink blocks that are based on subsystems can be specified as non-expandable for interactive models in EHANDBOOK-NAVIGATOR during EHANDBOOK Container generation. To enable the global configuration feature, the command line option -simulinkview that takes “path_to_jsonfile\name.json” as argument is used. The JSON file specifies the behavior of the blocks then, see samples below.

Makes referenced blocks with masks non-expandable (e.g. libraries):

{
	"GlobalView": {
		"HideContents": [
			{
				"BlockType": "Reference",
				"Simulink.Mask": "true"
			}
		]
	}
}

Makes all subsystems with masks non-expandable:

{
	"GlobalView": {
		"HideContents": [
			{
				"BlockType": "SubSystem",
				"Simulink.Mask": "true"
			}
		]
	}
}

Makes any masked Simulink block non-expandable:

{
	"GlobalView": {
		"HideContents": [
			{
				"Simulink.Mask": "true"
			}
		]
	}
}

Makes any subsystem non-expandable:

{
	"GlobalView": {
		"HideContents": [
			{
				"BlockType": "SubSystem"
			}
		]
	}
}

A sample file is available in the examples sub folder of the EHB-CB installation directory. (..\examples\configuration\SimulinkGlobalView.json)

The feature above works only if the key word Simulink.Mask is used inside the model file. This is the case for MATLAB 2012b onwards. For older versions (2012a and below) the key word MaskDisplay is used, which is currently not supported.

Model Depth Skip

Model depth skip can be used to convert all Simulink models till a particular model hierarchy level starting from the root level. This may be useful, to hide know-sensitive information in deeper model hierarchies.

For this feature, the same command line parameter -simulinkview and JSON file as for the feature above is used. In this JSON file, an additional section “ModelDepth” with the required level can be provided:

{
	"GlobalView": {
		"ModelDepth" : 5
	}
}

“ModelDepth” value must be in integers.

In this example, all Simulink models within a container will be converted up to 5 levels from the root level.

Label Amendment

Several features of EHANDBOOK-NAVIGATOR are based on the notion that the label names visible in interactive models correspond to label names in an A2L file. Also the function overview in NAV works purely name based. This means, the variable name from an exporting function has to match to the name of the importing function.

There can be cases, however, where the strings that are visible in an ASCET or Simulink model do not directly correspond to an A2L label name or match between functions. In this case, features like label pop-up, INCA visualization or function overview will not work in EHB-NAV.

By means of amending the names of labels in interactive models and the generated screenshots, models and screenshots can be "patched" such that the visible strings do match the expected A2L label names. It works in such a way that during the generation of an interactive model from a source ASCET or Simulink model the strings resembling label names are analyzed and transformed according to a specific set of rules. The rules are specified in a JSON file and passed via an argument to EHB-CB or UGG. The command line parameter is

-labelamendment with “path_to_json_file/name.json” as argument.

The rules for renaming are specified in a JSON file format:

Exact Replacements

Exact replacements are specified as key-value pairs of strings in rule groups marked with the key word "exact". They work straight-forward - the string in the key is replaced by the string in the value:

“Original_Name” : “New_Name”

Here’s an example for a set of exact replacement rules:

{
	"exact": {
		"Epm_rpmEngSpd_Sim_changed" : "Epm_rpmEngSpd_Sim"
		"Two-point-controller_changed" : "Two-point-controller",
		"Lamsoni_Sim_changed" : "Lamsoni_Sim"
	}
}

Pattern-based Replacements

Pattern-based replacement are specified as key value pairs of strings in rule groups marked with the key word "pattern". The keys make use of regular expressions to match strings that shall be amended. The values denote replacement strings. The latter can make use of the match groups defined in the regular expression.

“Target_Pattern” : “Substitude_Pattern”

Here’s an example for a set of pattern based replacement rules:

{
	"pattern": {
		"(.*)_write": "$1",
		"read_(.*)": "$1",
		"read_(.*)_write": "$1",
		"(.*)_middle_(.*)": "$1_$2"
	}
}

If the single character ‘.’ is used for a regular expression it must be escaped by ‘\\’

"prefix_(.*)\\.postfix" : "$1_postfix",

Here a sample Internet page with further information about regular expressions in general and online testing possibilities: https://freeformatter.com/regex-tester.html

Order in which replacements are applied

The order of rules as well as rule groups is of relevance. Rules within a rule group are applied in sequence. The same applies to rule groups; they are also applied in the sequence specified in the JSON file. Through this, even multiple rules can be applied during a transformation.

A sample file is available in the examples sub folder of the EHB-CB installation directory. (..\examples\configuration\LabelAmendment.json)

On application of label amendment to model hierarchies, clickPic for backward navigation and “open interactive model” does not work!

Passing Simulink library paths to EHB-CB

Two command line parameters could be used to provide SIMULINK library paths as input for the container generation.

simlib

Provide folder paths enclosed within double quotes separated by commas. Example:

-simlib "path1,path2,path3"

simlibfile

Provide path to json file containing paths to all libraries required. Example:

-simlibfile "path_to_json_file"

The key property in the json file used is "libraryPaths". Here’s an example of the JSON file:

{
	"libraryPaths": [
		"path1",
		"path2",
		"path3"
	]
}

Function Overview Diagram

EHB-CB is capable to generate a Function Overview Diagram with all input- and output signals automatically. Besides one single function, there are also multiple functions possible, showing the dependency and relation between them.

The generated Function Overview diagram will appear in EHB-NAV in the Function Documentation Window with a new navigation button named “Open function overview”. On click of this button, the model explorer tab opens with combined Function Overview of the functions appearing the image.

The separate chapters Function Overview Diagram in the TOC of EHB-NAV are generated by default without any additional configurations during container generation, independent of this feature.

Required changes to achieve this functionality are described in the separate documents RTF format Specification and AsciiDoc format Specification for directory based EHB-CB and in ASAM format Specification for the ASAM based EHB-CB. These documents are located in the sub folder ../documentation of your EHB-CB installation folder.

Creating function overviews with > 30 functions is not advised as all the functions might not fit into canvas.

Structure Data Type Support

EHANDBOOK supports configuration of structure data types for Simulink. Structures are mapped to Simulink buses. Structures can be defined in MDX following the MDX specification. For details please refer to the document ASAM Format Specification for EHB-CB, which is located in the sub folder ../documentation of your EHB-CB installation folder.

Configuration for C-Code Visualization

The visualization of C-Code as block diagram can be customized through several configurations. These can be adapted in such a way that the program logic is represented more precisely and that the graphical visualization can be understood more easily.

The configuration options are provided through a central configuration file in XML format. The configuration file is to be passed using the command-line option -ccodemeta with

“path_to_meta_file/name.xml” as argument.

The following shows the XML template for the C-Code configuration options.

<?xml version="1.0" encoding="UTF-8"?>
<functionmetadata:FunctionMetadataRoot
	xmi:version="2.0"
	xmlns:functionmetadata="http://www.etas.com/ehandbook/functionmetadata"
	xmlns:xmi="http://www.omg.org/XMI">

	<globalConfiguration
		libraryPath="../lib"
		inlineFunctions="true"
		simplifyDiagram="true"
		generateHierarchies="true"
		maxIterationForDataflowAnalysis="50000"/>

</functionmetadata:FunctionMetadataRoot>

The configuration options are described in the following:

libraryPath

For a given ECU function, having a set of C-files with implementations, the C-functions call other C-functions as sub-routines or service routines.

A suitable way to arrange such ECU specific C-files and global sub-routines is to configure where C-files for ECU functions are placed, and where the global sub-routines are placed.

This configuration specifies the location of all such global sub-routines or other C functions which could be present in a true either .c files or .h files.

These files typically contain helper or utility functions for the ECU specific C-files.

inlineFunctions

This configuration can be set to true/false in order to enable/disable the graphical inlining of called C-functions into the context of the calling C-functions.

Default setting: inlineFunctions=false

If set to true, the model visualizes the called function (e.g. global sub-routine/other C functions) as an expandable block within the block of the calling function.

For clearness, the Inlined C-functions are removed from the top level. Therefore, no model screenshots for these functions can created via -gensvg.

Example: The C-function mul is called from C-function main.

If set to false, the model visualizes the called function (e.g. global sub-routine/other C functions) as non-expandable block within the block of the calling function. Note that the called functions are visualized as top-level expandable blocks.

This configuration can be used to obtain visualizations of C-libraries, for example.

Example:

simplifyDiagram

This configuration takes in a true/false to enable/disable simplification of C-Code model. When enabled, unused variables and code from visualization are omitted, thereby decluttering and consequently simplifying the model visualization. However, the simplification can be disabled to view the actual model aiding in verifying the correctness of the model in comparison to the original source code, if required.

Default setting: simplifyDiagram=true

generateHierarchies

This configuration takes in a true/false to enable/disable artificial hierarchies in C-Code model. When enabled, artificial hierarchies are placed to logically group the elements. However, it could be disabled to have no hierarchies and view the model as it is in the original source code.

Default setting: generateHierarchies=true

Below, is an image depicting artificial hierarchies being created in the upper part. Here “True” which is expanded to show the contents, is an artificial hierarchy. The bottom part of the image shows C-code model with hierarchy generation being disabled, hence appears flat.

maxIterationForDataflowAnalysis

C-Code is converted to a data structure, which can be visualized as block diagram.

A part of the underlying algorithm is to calculate the connections between the blocks that represent the variables and operators of the C code functions. This is referred to as “Dataflow Analysis”.

maxIterationForDataflowAnalysis is a configuration parameter to tweak the calculation of the connections through an iterative Dataflow Analysis.

A too high value can lead to high memory consumption and longer runtime than necessary in order to calculate all connections.
A too low value can result is unconnected blocks due to missing connections. The algorithm terminates before all connections have been calculated.

The value should be chosen such that it represents the minimal number of iterations even for the most complex C-code sources of a given ECU program.

Default setting: maxIterationForDataflowAnalysis=50000

A sample file is available in the examples sub folder of the EHB-CB installation directory. (..\examples\configuration\CCodeConfig.xml)

When maxIterationForDataflowAnalysis is exceeded, an "Error" will be logged in the log file.

NOTICE

Incomplete, wrong or differing representation of model screenshots and interactive models from source data.

The following deviations between the model and the EHANDBOOK Container content may occur:

Missing or wrong graphics
Wrong targets on linked graphics
- Wrong model links
- Wrong model hierarchy links
For C-Code visualizations, different interpretations and semantics

Possible root causes of these deviations are:

Link specification in input text does not match to model hierachy path
Referenced model/source files are missing
Matlab connection for mask generation in Simulink was broken,
EHB-CB tool error due to internal error or unsupported source content
Technical limitations, especially for representing C-Code as graphical visualization

To identify deviations:

Check the entries in the log file of the generated EHANDBOOK Container for Warnings and Errors
Check the links between SVG graphics and interactive models in the EHANDBOOK Container

To ensure consistency and mitigate limitations:

Check the release notes and the known issues of EHANDBOOK Container-Build as well as EHANDBOOK-NAVIGATOR.
Compare the C-Code source code with the its graphical representation in EHANDBOOK-NAVIGATOR.

Label Table Configuration

Per FC, there is always one generic chapter with the default name Systemconstant-Parameter-Variable-Classinstance-Structure. This chapter contains the tables for all the elements, which are specified in the corresponding MDX or xls-file. The name of the chapter and the appearance of the tables can be configured with the command line parameter -tableconfig “file_path\file.json”. The JSON file defines the view as follows:

{
	"chapter": "Name of the chapter in EHB-NAV",
	"tables": [
		{
			"title": "Variable",
			"filters": [
				{
					"id": "ehb_element_type",
					"value": "ehb_variable"
				}
			],
			"columns": [
				{
					"title": "Name",
					"id": "ehb_name",
					"width": "20%"
				},
				{
					"title": "Description",
					"id": "ehb_desc",
					"width": "40%"
				},
				{
					"title": "Unit",
					"id": "Unit",
					"width": "10%"
				},
				{
					"title": "Data Type",
					"id": "Type",
					"width": "10%"
				},
				{
					"title": "Mode",
					"id": "ehb_mode",
					"width": "20%"
				}
			]
		},
		{
			"title": "Calibration/Parameter",
			"filters": [
				{
					"id": "ehb_element_type",
					"value": "ehb_parameter"
				}
			],
			"columns": [
				{
					"...": "..."
				}
			]
		}
	]
}

The “tables”: [] section defines the appearance of each table.

Each table begins with a title entry: “title”: “Name of the table title in EHB-NAV”

In the section “filters”: [ “id”: “ehb_element_type” you specify the table element type by defining one of the following key words for “value”:

Type of table	Matching key words for “value”: “…”	Corresponding entry in xls	Corresponding entry in MDX
Variables Parameters System Constants Class Instances	“ehb_variable” “ehb_parameter” “ehb_system_constant” “ehb_class_instance”	Sheet “Signal” Sheet “Calibration” N.A. N.A.	<SW-VARIABLE> <SW-CALPRMS> <SW-SYSTEMCONST> <SW-CLASS-INSTANCE>

Type of table

Matching key words for “value”: “…”

Corresponding entry in xls

Corresponding entry in MDX

Variables

Parameters

System Constants

Class Instances

“ehb_variable”

“ehb_parameter”

“ehb_system_constant”

“ehb_class_instance”

Sheet “Signal”

Sheet “Calibration”

N.A.

<SW-VARIABLE>

<SW-CALPRMS>

<SW-SYSTEMCONST>

<SW-CLASS-INSTANCE>

In the section “columns”: [ ] per column entry, a “title” & “id” pair defines the column content:

“title”: “column name” defines the name of the column in EHB-NAV

“id”: “Input source value from MDX or xls to be shown”.

“width”: Defines width of the table column that can be configured in PDF. “width” is denoted in percentage.

For the “id” values, fixed pre-defined key words are used:

Key word for “id”: “…” in JSON	Corresponds to column in xls	Corresponds to key word in MDX
“ehb_name”	“Name”	<SHORT-NAME>
“ehb_desc”	“Description”	<LONG-NAME>
“ehb_mode”	“Xref”	No tag avail.
“ehb_access”	N.A.	<SW-CALIBRATION-ACCESS>
“ehb_data_type”	“Class”	<BASE-TYPE-REF>
“ehb_reference”	N.A.	No tag avail. used for class instance table only
“ehb_category”	N.A.	Entry in <CATEGORY>

Key word for “id”: “…” in JSON

Corresponds to column in xls

Corresponds to key word in MDX

“ehb_name”

“Name”

<SHORT-NAME>

“ehb_desc”

“Description”

<LONG-NAME>

“ehb_mode”

“Xref”

No tag avail.

“ehb_access”

N.A.

<SW-CALIBRATION-ACCESS>

“ehb_data_type”

“Class”

<BASE-TYPE-REF>

“ehb_reference”

N.A.

No tag avail. used for class instance table only

“ehb_category”

N.A.

Entry in <CATEGORY>

For other element properties, defined in further column entries in the xls file, the identical name is used in the JSON file as “id” value also. The same applies for MDX entries used for properties.

You can define as many “title” & “id” pairs as you want, but you have to consider the page width in EHB-NAV and especially in PDF if printing is required.

The order of the “title” & “id” pairs in the JSON file are defining the order of the columns in EHB-NAV from left to right.

The order of the tables in the JSON file are defining the order of the tables in EHB-NAV from top to bottom.

You can divide the tables into different ones by adding additional filter attributes.

"title": "Input Variables",
"filters": [
	{
		"id": "ehb_element_type",
		"value": "ehb_variable"
	},
	{
		"id": "ehb_mode",
		"value": "import"
	},
	{
		"..." : "..."
	}
]

A filter criterion can be configured as “id” & “value” pairs

“id”: “type” defines the type for the filtering

“value”: “value of type” defines the content of type, which should match the filter criteria

For “type” and “value” fixed pre-defined key words are used:

Key word for “id”: “…”	Matching key words for “value”: “…”	Corresponding entry in xls	Corresponding entry in MDX
“ehb_mode”	“import” “export” “local”	IN OUT LOC	<IMPORT> <EXPORT> <SW-FEATURE-OWNED-ELEMENT-SET>

Key word for “id”: “…”

Matching key words for “value”: “…”

Corresponding entry in xls

Corresponding entry in MDX

“ehb_mode”

“import”

“export”

“local”

OUT

LOC

<SW-FEATURE-OWNED-ELEMENT-SET>

For other element properties required for as filter criterion, the corresponding column entry in the xls file can be used. Here the identical column name is required in the JSON file as “id”: “type” also. In addition, the text entry in the column must be identical in the JSON “value”: “text entry”. The same applies for MDX entries used for filtering.

Multiple filter criteria can be used. They are combined as logical AND, e.g. element_type=variable & mode=exported & type=float.

You can define as many tables as you want, with any combination of filters, but limited to the pre-defined key words ehb_element_type and ehb_mode.

All key words and value entries are handled case insensitive but have to be exact. There is no error handling for wrongly spelled entries.

A sample file is available in the examples sub folder of the EHB-CB installation directory. (..\examples\configuration\TableConfiguration.json)

Label Configuration

In a model, you have multiple possibilities how to name a label. The tools ASCET 6 and ASCET-DEVELOPER provide certain options to configure the composition of an element name. E.g. the element name can be appended with their parent elements and the order of the name parts can be defined. So the name may differ from the name in the a2l file and MCD features like INCA connectivity will not work.

Therefore, EHB-CB provides the flexibility to configure the label names by using a JSON configuration file (plain ASCII, UTF8 format), so that it matches the names in A2L file. There is one single JSON file with individual configuration possibilites per model type (ASCET 6, ASCET DEVELOPER, Simulink)

See sample LabelConfig.json in the sub folder .\examples\configuration of your EHB-CB installation directory.

Please ensure, that the configuration parameters in ASCET and in the JSON file are matching. Otherwise labels from a2l-file or from INCA could not be shown in EHB-NAV.

For ASCET-DEVELOPER

The element name could be placed first or last, when appended with their parent elements or package names could be omitted.

With the JSON file shown below (plain ASCII, UTF8 format), ASCET-DEVELOPER models in the container will have the element name placed last and will not be appended with the package name. This is also the default, if no label configuration is provided.

{
	"ASCET-DEVELOPER": {
		"elementNameFirst": false,
		"includePackageName": false
	}
}

For example, a class element “signal” within class “Component”, placed inside package “components” would have the name as in the below table according to the various combinations provide in JSON file. This name is used to connect to INCA on EHANDBOOK-NAVIGATOR.

includePackageName

elementNameFirst

true

false

true

signal.Component.components

components.Component.signal

false

signal.Component

Component.signal

In the above JSON file, ‘elementNameFirst’ parameter corresponds to the ‘Model symbolic name format’ in the ASAM MCD section under the ‘ASAM’ tab in the launch configuration for ECU code generation in ASCET-DEVELOPER tool as shown below:

While the ‘includePackageName’ corresponds to the ‘Legacy code generation’ option in ‘Naming convention’ section under the ‘Options’ tab in the run configuration as shown below:

If the checkbox is selected, then ASCET Classic naming convention is used where the package names are omitted, while de-selecting it will have the package name being included in the label.

For ASCET 6

The element names could be placed first or last and their parent elements module and project names or their class instance names could be appended also.

With the JSON file shown below, models in the container will have the element name placed last and will be appended with the class instance names. This is also the default, if no label configuration is provided.

{
	"ASCET": {
		"elementNameFirst": false,
		"includeModuleName": false,
		"includeProjectName": false,
		"includeClassInstanceName": true
	}
}

For example, an instance “componentInstance” of class “Component” having a class element “signal”, placed within a module “RootModule” of project “Project” would have the name as in the below table according to the various combinations provide in JSON file. This name is used to connect to INCA on EHANDBOOK-NAVIGATOR.

includeProjectName

elementNameFirst

includeModuleName

true

false

true

signal.componentInstance.RootModule.Project

Project.RootModule.componentInstance.signal

true

false

signal.componentInstance

componentInstance.signal

false

For Simulink

EHB-CB provides the option to add a configurable and invisible unique name to blocks and buses in the Simulink model. This hidden unique name is then used for MCD features like INCA connectivity in EHB-NAV.

With the JSON file shown below, Simulink blocks of block type "Constant" will have label configured via uniqueName.

Example: Adding Unique Name for the Constant blocks

{
    "Simulink": {
        "blockRules": [
            {
                "selectors": [
                    {
                        "parameter": "BlockType",
                        "value": "Constant"
                    }
                ],
                "uniqueName": "${Value}"
            }
        ]
    }
}

JSON file path has to be given as an argument for command-line parameter "-labelconfig"

{
	"Simulink": {
		"blockRules": [
			{
				"selectors": [
	                                  				{
						"parameter": "BlockType",
						"value": "Inport"
					}
				],
				"replacements": [
					{
						"parameter": "Name",
						"regex": "(.*)",
						"replacement": "$1__TestSuffix"
					}
				],
				"uniqueName": "Test_prefix.${Name}"
			}
		],
		"nonVirtualBusRules": [
			{
				"busNameSelector": {
					"value": "signalBus"
				},
				"busElementNameSelector": {
					"regex": "signal__(.*)"
				},
				"busNameReplacement": {
					"regex": "prefix_(.*)_suffix",
					"replacement": "$1"
				},
				"busElementNameReplacement": {
					"regex": "(.*)__(.*)",
					"replacement": "$1"
				},
				"uniqueName": "${busNameReplacement}.${busElementNameReplacement}"
			}
		]
	}
}

Configuration for blockRules

BlockRules assist to configure "uniqueName" for any type of Simulink blocks based on "selectors" and "replacements" configurations. It is possible to provide list of blockRules [0…n].

selectors

"selectors" are the filters, applied to select the block based on the below key-value pairs.

Key	Value	Optional
parameter	Valid Simulink block parameter	No
value	Simulink block parameter value	Yes
regex	Simulink block parameter value regex pattern	Yes

Key

Value

Optional

parameter

Valid Simulink block parameter

value

Simulink block parameter value

Yes

regex

Simulink block parameter value regex pattern

Yes

Selectors are composed of either parameter and value combination or parameter and regex combination. It is possible to provide list of selectors [0…n]. If blockRule does not contain any selectors, then uniqueName will be created for all the blocks. To construct an uniqueName from blockRules, all the defined selectors are to satisfied.

replacements

"replacements" are optional.

Key	Value	Optional
parameter	Valid Simulink block parameter	No
regex	Simulink block parameter value regex pattern	No
replacement	Prepare an unique name using regex groups or text	No

Key

Value

Optional

parameter

Valid Simulink block parameter

regex

Simulink block parameter value regex pattern

replacement

Prepare an unique name using regex groups or text

replacement is composed of "parameter" and "regex" applied on "parameter".

"replacements": [
	{
		"parameter": "Name",
		"regex": "(.*)",
		"replacement": "$1__Suffix"
	}
]

In the above example if the "parameter" (name of Simulink block) is "Name", "regex" pattern applied on "parameter" to collect all the characters of the "parameter" and "replacement" replaces "parameter" with defined replacement (in the example "parameter" is appended by _Suffix ⇒ Name_Suffix)

"replacement" is used as expression in the uniqueName.

Unique name configuration

uniqueName is a mandatory key. "uniqueName" labels are not created if "uniqueName" is not provided in json file.

uniqueName is composed of expressions. An expression starts with "$" followed by "{" and ends with "}".

Example for uniqueName:

$\{Sample1}_$\{Sample2}_suffix
prefix_$\{Sample1}_$\{Sample2}_suffix
prefix.$\{Sample1}.midfix.$\{Sample2}.suffix

1) Sample1,Sample2 is always valid block parameter of Simulink

2) If the replacements are provided for Sample1 or Sample2 it will replace expression using "replacement" value otherwise "block parameter" value is considered.

If "${Sample1} "abc" and ${Sample2} "efg", then unique names are as follows:

$\{Sample1}_$\{Sample2}_suffix //abc_efg_suffix
prefix_$\{Sample1}_$\{Sample2}_suffix //prefix_abc_efg_suffix
prefix.$\{Sample1}.midfix.$\{Sample2}.suffix // prefix.abc.midfix.efg.suffix

Configuration for nonVirtualBusRules

nonVirtualBusRules assist to configure "uniqueName" for any type of Simulink buses based on "busNameSelector", "busElementNameSelector" and "busNameReplacement", "busElementNameReplacement" configurations. It is possible to provide list of nonVirtualBusRules [0…n].

busNameSelector "busNameSelector" is a filter, applied on the bus name, provided by value or regex configuration.
busElementNameSelector "busElementNameSelector" is a filter, applied on the bus element name (bus member), provided by value or regex configuration.

If nonVirtualBusRule does not contain any selectors, then uniqueName will be created for all the buses. To construct an uniqueName from nonVirtualBusRules, all the defined selectors are to satisfied.

busNameReplacement busNameReplacement is applied on the bus name by using regex, replacement.
busElementNameReplacement busElementNameReplacement is applied on the bus element name by using regex, replacement.

In the regex pattern, 2 fixed expressions are allowed - ${busName}, ${busElementName} These expressions are updated before processing regex and replacement

Example:

"busElementNameReplacement": {
	"regex": "${busName}_(.*)",
	"replacement": "$1"
}

In the above example if we consider busName as "Hello", the regex is updated with Hello_(.*)

uniqueName uniqueName is composed of fixed expressions and text. 4 optional fixed expressions are ${busNameReplacement}, ${busElementNameReplacement}, ${busElementName}, ${busName}

{
	"busNameSelector": {
		"value": "signalBus"
	},
	"busElementNameSelector": {
		"regex": "signal__(.*)"
	},
	"busNameReplacement": {
		"regex": "prefix_(.*)_suffix",
		"replacement": "$1"
	},
	"busElementNameReplacement": {
		"regex": "(.*)__(.*)",
		"replacement": "$1"
	},
	"uniqueName": "${busNameReplacement}.${busElementNameReplacement}"
}

where

Expression	Description
${busName}	Replaced with bus name
${busElementName}	Replaced with bus member name
${busNameReplacement}	Replacement provided in the non-virtual bus rule
${busElementNameReplacement}	Replacement provided in the non-virtual bus rule

Expression

Description

${busName}

Replaced with bus name

${busElementName}

Replaced with bus member name

${busNameReplacement}

Replacement provided in the non-virtual bus rule

${busElementNameReplacement}

Replacement provided in the non-virtual bus rule

For AUTOSAR

EHANDBOOK Container-Build provides the option to add a configurable and invisible unique name to AUTOSAR ports and its interfaces in the interface function overview. This hidden unique name is then used for MCD features like INCA connectivity in EHANDBOOK NAVIGATOR.

{
	"AUTOSAR":
		{
		"includeSwcInstanceName": true,
		"includePortName": true
		}
}

In the above JSON file, ‘includeSwcInstanceName’ parameter applies the instance name of the component to be included in the name of port and interface. 'includePortName' parameter applies the port name to be added in the name of the interface.

For example, a component instance “component” containing a port "port" having an interface "interface" would have the name as in the below table according to the various combinations provide in JSON file.

includeSwcInstanceName

includePortName

true

false

true

component.port.interface

component.interface

false

port.interface

interface

Excluding Packages for ASCET-DEVELOPER

In the workspace of an ASCET-DEVELOPER project, block diagrams are organized by means of so-called packages. When the EHANDBOOK documentation is generated for such models, the content for certain Class Instance blocks should not be included in certain cases. Typical cases are:

a Class Instance is of a library type Class where details are not required to understand the meaning of the block
a Class Instance block contains details which are subject to know-how protection

In the corresponding interactive model, such Class Instances should then be non-expandable such that no details are exposed, and subsequently the textual documentation for the sub blocks of that Class Instance block need to be excluded from documentation as well.

Excluding packages also have s significant improvement on RAM consumption and generation time during the container build.

In order to achieve this, EHANDBOOK-CONTAINER build offers an optional command line argument -ascetdeveloperexcludepackages. The CLI argument must point to the path of a configuration file in JSON format that contains the list of ASCET-DEVELOPER packages to exclude from document generation.

{
    "packages":[
        "packageX",
        "packageA.packageB"
    ]
}

See sample ExcludePackages.json in the sub folder .\examples\configuration of your EHB-CB installation directory.

In case of nested packages, fully qualified name of the package separated by “.” (DOT) needs to be provided.

Mapping signals across domain

At EHANDBOOK, it is possible to establish communication between components across domains like AUTOSAR and MSR. To visualize these connectors in the function overview of the NAVIGATOR, a mapping file is processed during the container generation.

Generate EHANDBOOK Container

To generate an EHANDBOOK Container which connects components from different domain, you have to pass the following arguments to eHandbookCB.exe

-i <path to input folder> specifies the sources that shall be converted.
-o <path to output folder> specifies where the EHANDBOOK Container shall be generated to
-n <name> name for the EHANDBOOK Container file that will be generated
-componentconnectormappingfile "<Mapping file path>" specifies the path of the mapping file

Sample Command

C:\ETAS\EHANDBOOK-Container-Build_10.0.0-Windows\eHandbookCB.exe ^
-i "<path to input folder>" ^
-o "<path to output folder>" ^
-n "<name>"^
-componentconnectormappingfile "<Mapping file path>"

The mapping file is passed via command line argument "-componentconnectormappingfile".

The mapping file is expressed in .json or .csv format and contains details of connecting signals between functions of different domains.

Mapping file specification

The following listing shows an example for the syntax of the JSON mapping file.

You can download the file from here.

[
  {
    "exported": {
      "port": "result",
      "component": "Function 1"
    },
    "imported": {
      "port": "a",
      "component": "Function 2"
    }
  }
]

In the above JSON file, "exported" and "imported" parameter points to the port and component details.

exportedPort: Name/Package path of the port which is exported from the source component.
exportedComponent: Name/Package path of the exporting component.
importedPort: Name/Package path of the port which is imported into the target component.
importedComponent: Name/Package path of the importing component.

The following listing shows an example for the syntax of the CSV mapping file. You can download the file from here.

exportedPort	exportedComponent	importedPort	importedComponent
result	Function 1	a	Function 2

exportedPort

exportedComponent

importedPort

importedComponent

result

Function 1

Function 2

Using either of the above JSON or CSV specification, functions from different domains can be connected.

Include Documentation for Nested Classed in ASCET-DEVELOPER

ASCET-DEVELOPER apps are built from a set of static entry-point classes. To re-use algorithms, these can be specified as classes and instantiated where required. When classes contain instances of other classes, this creates so-called nested classes.

Each class can be associated with some textual documentation in the form of an AsciiDoc file. Through this, the behavior of a class can be documented once.

To obtain a full documentation for a static class with EHANDBOOK Container-Build, also the textual contents associated with all instantiated and nested classes can be considered.

In order to achieve this, EHANDBOOK-CONTAINER build offers an optional command line argument -ascetdevelopernestedclasses.

Depending on the usage of nested classes, this option can lead to significant increase in EHANDBOOK generation time as each class instance gets documented at the place where it is used.

Support for Simulink Doc blocks in documentation for Simulink Addon

In Simulink Addon, the content of the Simulink doc block is extracted from the model and added as documentation(AsciiDoc) for the respective subsystem along with its screen-shot.

How to explicitly specify tables of contents (Directory-based EHANDBOOK Container-Build)

This how-to guide applies to the Directory-based EHANDBOOK Container-Build approach. For ASAM-based EHANDBOOK Container-Build approach, refer to the ASAM CCX specification and the usage of ABLOCKs for TOCs in particular.

The approach described in this how-to guide for Directory-based EHANDBOOK Container-Build approach can also be applied when generating EHANDBOOK Containers for ASCET-DEVELOPER apps.

Background

Each EHANDBOOK Container comes with one or multiple tables of contents. A table of contents provides a high-level navigation structure for the textual contents of an EHANDBOOK Container. In EHANDBOOK-NAVIGATOR, the contents of a table of contents is shown in the Document Explorer.

EHANDBOOK supports to specify multiple tables of contents such that different users of the ECU software documentation can use different navigation structures. In EHANDBOOK-NAVIGATOR, users can switch between the provided tables of contents. Through this, they can choose a navigation structure depending on their use case or personal preference.

Figure 3. Document Explorer of EHANDBOOK-NAVIGATOR, showing a table of contents

Figure 4. Button to switch to other tables of contents

Figure 5. Select a table of contents to be shown

How tables of contents are derived by default

The directory-based EHANDBOOK Conainer-Build tool-chain has a built-in feature to automatically derive two standard tables of contents:

Alphabetically list of functions: This is a flat list of ECU functions or software components in alphabetic order
Software architecture view: This is a hierarchical structure that mimics the ECU software architecture as specified by the directory structure

Benefits are:

No effort to specify a table of contents at all
Standard tables of contents are created automatically

How tables of contents can be specified explicitly

Starting with EHANDBOOK 10.2, it is possible to specify the tables of contents explicitly. Through this, the automatically generated tables of contents can be replaced with customized ones.

The format of the configuration file is YAML.

tocs.yaml - a YAML file to specify table of contents

To specify the structure of the tables of contents, a configuration file with the name tocs.yaml has to be provided in the root directory that is passed to EHANDBOOK Container-Build.

└── 📒 ECU_SW_XYZ (1)
    └── 📒 SWC_1
    ├── 📒 SWC_2
    .
    .
    .
    ├── 📒 SWC_n
    ├── 📒 Composition_1
    ├── 📒 Composition_2
    └── 📄 tocs.yaml (2)

1	Root input directory to be passed to EHANDBOOK Container-Build
2	File with explicit specification of tables of contents

For ASCET-DEVELOPER, the tocs.yaml file must be placed in the same directory as the .app file for which an EHANDBOOK Container shall be generated.

Figure 6. Placement of tocs.yaml for ASCET-DEVELOPER apps

Syntax of tocs.yaml

The following listing shows an example for the syntax of the YAML file. You can download the file from here.

docuUnits:                                  (1)
  - id: SWC_1                               (2)
    displayName: "Software Component 1"     (3)
  - id: SWC_2
    displayName: "Software Component 2"
  - id: SWC_n
    displayName: "Software Component n"
  - id: Composition_1
    displayName: "Composition 1"
  - id: Composition_2
    displayName: "Composition 2"
tocs:                                       (4)
  - displayName: Alphabetic list of software components         (5)
    contents:                               (6)
    - idRef: SWC_1                          (7)
    - idRef: SWC_2
    - idRef: SWC_n
  - displayName: Software architecture
    contents:
    - idRef: Composition_1
      contents:                             (8)
      - idRef: SWC_1
      - idRef: SWC_2
    - idRef: Composition_2
      contents:
      - idRef: SWC_n

1	docuUnits: List of documentation untis from which tables of contents can be specified.
2	id: Identifier of the documentation unit. This complies to the name of the directory that represents the software component, composition or any other documentation chapter.
3	displayName: The human-readable name that shall be displayed in the table of contents.
4	tocs: Start of YAML section where the tables of contents for the EHANDBOOK Container are specified.
5	displayName: The human-readable name that shall be displayed for a table of contents.
6	contents: Start of YAML section where entries for the tables of contents are specified.
7	idRef: Reference to a documentation unit.
8	contents: Nested YAML section with entries for sub-chapters. Useful for creating navigation hierarchies, e.g. to resemble the software architecture of an ECU.

Custom tables of contents in EHANDBOOK-NAVIGATOR

The following screenshot shows the Document Explorer after the generated EHANDBOOK Container is loaded in EHANDBOOK-NAVIGATOR. The first tables of contents - Alphabetic list of software components - is shown.

Figure 7. Document Explorer of EHANDBOOK-NAVIGATOR, showing custom table of contents for "Alphabetic list of software components"

Using the select button, users can explore and switch to another table of contents.

Figure 8. Document Explorer of EHANDBOOK-NAVIGATOR, showing selection between available tables of contents

This is how the Software architecture looks like.

Figure 9. Document Explorer of EHANDBOOK-NAVIGATOR, showing custom table of contents for "Software architecture"

Benefits

Define an arbitrary set of tables of contents (one or multiple)
Provide a custom order of the tables of contents (first table of contents will be shown when the EHANDBOOK Container is opened)
Provide custom names for the entries in the tables of contents
Provide custom ordering of entries in the tables of contents