EHANDBOOK Container-Build Usage in General

EHANDBOOK Container-Build offers two modes of operation: a GUI- or a command-line mode. To simplify the first usage, the GUI-mode only provides the most important input configuration parameters. If more parameters are required or the integration in an automated build process is needed, we recommend using the command-line mode.

After container generation, check the console messages and the log file for error or warning messages and examine the container content for completeness and accuracy.

Follow the latest safety advice documents, delivered as separate documents within the EHANDBOOK Container-Build package.

EHANDBOOK Container-Build Usage in Command-line Mode

Please follow the steps for generating an EHANDBOOK container from the source data:

Step 1: Open a command-line interpreter (CMD or PowerShell under Windows; bash under Linux) and navigate to the installation directory of the EHANDBOOK Container-Build command line application (eHandbookCB.exe under Windows or eHandbookCB under Linux).

Step 2: To invoke EHANDBOOK Container-Build, appropriate command line parameters (refer the tables below) have to be provided on to the command prompt. Format: eHandbookCB.exe <Option>

List of EHANDBOOK Container-Build command line parameters:

Parameter Optional Value Type Description

-i

No

Path enclosed within double quotes

Location of ASAM catalog file (.ccx) for ASAM-based EHB-CB or top folder of input directory for Directory-based EHB-CB

-o

No

Path enclosed within double quotes

Location of output folder

-n

No

Path enclosed within double quotes

Name of the container to be generated. The file extension .ehb is added. Existing containers with the same name will be overwritten!

-styling

Yes

Path enclosed within double quotes

Location of folder containing the styling information (title page, fonts, company logo etc…​) For more details refer to the EHB-CB Styling Guide. Without this option, a default title page is created.

-gensvg

Yes

None

Option to generate SVG image screenshots out of interactive model. For more details refer to chapter Click Pic

-labelamendment

Yes

Path enclosed within double quotes

Option to provide a path and file to rename variables and parameters in Simulink models.
For more details refer to chapter Label Amendment

-lockdir

Yes

Path enclosed within double quotes

Option to provide path for locking directory (only required if multi instances of CB are used)

For more details refer to chapter Configurations in eHandbookCB.ini

-vmargs

Yes

None

Option to configure special configurations from the eHandbookCB.ini file via command line.

For more details refer to chapter Configurations in eHandbookCB.ini

-rootlevel

Yes

Path enclosed within double quotes

Option to provide path to root level file for one or more model languages. The default value for all the languages is 0.
For more details refer to chapter Root-Level Skipping

-ugg

Yes

None

Use pre-generated images and interactive models from UGG

-viewtype

Yes

Parameter enclosed within double quotes

Option to provide a view name, for which the models and their screenshots are be generated.

If this parameter is not passed, the models are generated without any views applied.

For more details refer to chapter View Concept

-tableconfig

Yes

Path enclosed within double quotes

Option to provide a path to a JSON-file to configure the appearance of the chapter for variables and parameters and their tables.
For more details refer to chapter Table Configuration

-labelconfig

Yes

Path enclosed within double quotes

Option to provide a path to a JSON-file to configure the labels for Simulink blocks and buses or element names in ASCET.
For more details refer to chapter Label Configuration

-autosarcomposition

Yes

Text enclosed within double quotes

Name of the root composition from AUTOSAR. For more details refer to chapter Model Interface & Data Description in AUTOSAR (Classic)

-ar2ehbcbinput

Yes

None

Generates EHB-CB input directory structure from ARXML files. For more details refer to chapter Generation of Input Directory Structure from AUTOSAR files

-epwd

Yes

Text enclosed within double quotes

Password to encrypt the container

For more details refer to chapter Encryption

-epwdf

Yes

Text enclosed with percentage character e.g. %my_secret%

Password to encrypt the container stored in the given text file. The password file is deleted after container encryption.

-componentconnectormappingfile

Yes

Path enclosed within double quotes

JSON file containing mapping information across domains e.g. AUTOSAR to MSR.

For more details refer to chapter Mapping signals across domain

-genxdiovr

Yes

None

Option to create MSR Diagnosis XDI overview table by aggregating the XDI information

-help

Yes

None

Show command line help documentation.

EHB-CB command line parameters, useful for debugging purposes:

Parameter Optional Value Type Description

-noclean

Yes

None

During conversion, temporary files are generated in a sub folder by name temp_ID (auto generated unique number) of the output directory, specified by the option -n. This option will not delete the temp folder after container generation

-debugreq

Yes

None

Option to print extended debug messages to log file

-nogenhtml

Yes

None

Option to avoid pre generation of html in the container

EHB-CB command line parameters, only valid if optional ASCET converter add-on is included in EHB-CB tool:

Parameter Optional Value Type Description

-ascetview

Yes/No

Path enclosed within double quotes

Location of ASCET view configuration file. Mandatory when -viewtype parameter is passed.

-splitApp

Yes

None

In ASCET-DEVELOPER projects, -splitapp is an option used to create functional components out of static class present in the app file.

Note: This option works only with directory based EHB-CB.

-ascetdeveloperexcludepackages

Yes

Path enclosed within double quotes

Path to file containing list of ASCET-DEVELOPER packages that shall be excluded from processing.

Note: This option works only with directory based EHB-CB.

-ascetdevelopernestedclasses

Yes

None

Generate documentation for nested classes in ASCET-DEVELOPER apps.

Note: This option works only with directory based EHB-CB when the ASCET-DEVELOPER .app file is passed as input argument.

-ihf

Yes

Text enclosed within double quotes

Option to trigger filtering for intermediate ASCET hierarchies. For more details refer to chapter intermediate hierarchy filtering

EHB-CB command line parameters, only valid if optional C-code converter add-on is included in EHB-CB tool:

Parameter Optional Value Type Description

-cat

Yes

None

Enable of special C-Code handling for external tools.

-ccodeview

Yes/No

Path enclosed within double quotes

Location of C-Code view configuration file. Mandatory when -viewtype parameter is passed.

-ccodemeta

Yes

Path enclosed within double quotes

Path to file with configuration information to allow the decoration of sub-routines with custom images and others. For more details refer to chapter C-Code Configuration

EHB-CB command line parameters, only valid if optional Simulink converter add-on is included in EHB-CB tool:

Parameter Optional Value Type Description

-nomatlab

Yes

None

Option not to use MATLAB for enhanced rendering of Simulink models. Container generation time gets considerable faster

-simlib

Yes

Path enclosed within double quotes

Path to root directory to all Simulink libraries. Directory may contain sub directories, too. Multiple root directories can be specified, separated by commas.

Paths to all libraries required by the Simulink model must be provided, including MATLAB Simulink system libraries.

-simlibfile

Yes

Path enclosed within double quotes

JSON file containing paths to all libraries required by the Simulink model must be provided, including MATLAB Simulink system libraries. (see chapter SIMULINK library paths support

-simulinkview

Yes

Path enclosed within double quotes

Location of Simulink view configuration file to specify non-expandable blocks (see chapter Configure Simulink Blocks as Non-Expandable)

-matlabpath

Yes

Path enclosed within double quotes

Installed MATLAB path till matlab.exe to be used for generating mask data for Simulink models.

(see also chapter Timeout for MATLAB Connection)

In order to have proper mask generation, it is recommended to connect to the same MATLAB version in which the model is generated.

-includeMatlabFunctionCode

Yes

None

Option to process and store MATLAB function code blocks during container generation and show them in the EHANDBOOK-NAVIGATOR code viewer.

List of UGG command line parameters:

Parameter Optional Value Type Description

-i

No

Path enclosed within double quotes

Input directory for UGG artifacts generation.

-o

No

Path enclosed within double quotes

Output directory for UGG artifacts generation.

-genmaps

Yes

None

Option to generate map files.

-viewtype

Yes

Parameter enclosed within double quotes

Option to provide a view name, for which the models and their screenshots are be generated.

-version

Yes

None

Option to display the version of UGG product being used.

-zip

Yes

None

Option to create a zipped file of the UGG artifacts.

-help

Yes

None

Show command line help documentation.

-labelconfig

Yes

Path enclosed within double quotes

Option to provide a path to a JSON-file to configure the labels to match A2L/MCD configuration.

-labelamendment

Yes

Path enclosed within double quotes

Option to provide a path and file to change label names.

UGG command line parameters, useful for debugging purposes:

Parameter Optional Value Type Description

-isdebugreq

Yes

None

Option to print extended debug messages to log file

UGG command line parameters, used along with ASCET model.

Parameter Optional Value Type Description

-ascetviewfile

Yes/No

Path enclosed within double quotes

Location of ASCET view configuration file. Mandatory when -viewtype parameter is passed.

UGG command line parameters, used along with Simulink model.

Parameter Optional Value Type Description

-nomatlab

Yes

None

Option not to use MATLAB for enhanced rendering of Simulink models.

-simlib

Yes

Path enclosed within double quotes

Path to root directory to all Simulink libraries. Directory may contain sub directories, too. Multiple root directories can be specified, separated by commas.

Paths to all libraries required by the Simulink model must be provided, including MATLAB Simulink system libraries.

-simlibfile

Yes

Path enclosed within double quotes

JSON file containing paths to all libraries required by the Simulink model must be provided, including MATLAB Simulink system libraries. (see chapter SIMULINK library paths support

-simulinkview

Yes

Path enclosed within double quotes

Location of Simulink view configuration file to specify non-expandable blocks (see chapter Configure Simulink Blocks as Non-Expandable)

-matlabpath

Yes

Path enclosed within double quotes

Installed MATLAB path till matlab.exe to be used for generating mask data for Simulink models.

(see also chapter Timeout for MATLAB Connection)

In order to have proper mask generation, it is recommended to connect to the same MATLAB version in which the model is generated.

-includeMatlabFunctionCode

Yes

None

Option to process and store MATLAB function code blocks during container generation and show them in the EHANDBOOK-NAVIGATOR code viewer.

UGG command line parameters, used along with C-Code Model.

Parameter Optional Value Type Description

-ccodeconfigfile

Yes

Path enclosed within double quotes

Location of configuration file used for conversion of C-Code model.

Please refer the sample below with all mandatory parameters:

eHandbookCB.exe (1)
-i "D:\TestData\Asam_Data\input\asamCC.ccx"
-o "D:\TestData\Container\output"
-n "DemoContainer"
1 On Linux use the executable eHandbookCB

Step 3: Press Enter key.

Step 4: Log information can be seen in the command prompt console.

Step 5: Once the EHANDBOOK container creation is successful, the below message can be seen on the command prompt console:

"INFO - Container creation successful! [path in which container is created]"

Now, the output folder contains an EHANDBOOK container (extension .ehb) by the name passed with -n argument

EHANDBOOK Container-Build Usage in GUI Mode

If the tool is executed without any command line parameter, just by double click on eHandbookCB.exe, a small GUI-window will appear. Here now, the major input parameters (but not all) can be specified in an interactive way. Mandatory entries are marked with a '*'. The intention of this feature is to simplify test and evaluation purposes.

ASAM based GUI Mode:

image8

To enable this GUI in the standard EHB-CB tool, -Dasam.cb=true has to be added in the ehandbookCB.ini file, located in the same folder as the eHandbookCB.exe.

Directory based GUI Mode:

image9

Type in the mandatory information:

  • Input location (Dir based): Select the top most folder, which contains the input files

  • CCX file path (ASAM based): Select the path to the ASAM CCX file

  • Output folder: Specify the output directory, where the container will
    be generated. Of course, this directory should be separated
    from the input location!

GUI Mode is supported only for Windows Operating System.

  • EHB file Name: Defines the name of the EHANDBOOK container, file extension .ehb is added

Optional arguments:

SIMLIB path: Path outside of the input folder to exactly one root directory to all Simulink libraries used by the models in the input folder.

Styling folder: Location of folder containing the styling information (title page, fonts, company logo etc…). If nothing is specified, a default title page is generated.

Generate SVG: Enables auto generated model screenshots, if text input files are configured accordingly. See Click Pic for more details.

Allow MATLAB connection: Use MATLAB for enhanced rendering of Simulink models. Matlab has to be installed on the PC. When this option is set, the container generation takes considerable more time.

For more details on the input arguments, see the command line list [cmd-list] above

Start the generation by pressing the ‘Generate’-button. After processing, the generated container is available then in the directory specified as output folder.

Container Debugging and Content Checking

If no container is generated, because of a fatal error, a log file in the output folder is written by the EHB-CB tool. In all other cases, irrespective of an error occurred or not, a log file with the name of the container (ContainerName.log) is placed inside the container. The log file can be read by unzipping the container with a standard zipping tool (e.g. 7-zip) or by opening the container in EHB-NAV and using the menu Help→Export Log Files…​ .

Configurations in eHandbookCB.ini

In addition to the command line parameters, there are also some special configurations in the eHandbookCB.ini file possible. This file is located in the same directory as the eHandbookCB.exe. It is a plain text file and can be edited with any text editor. However user can also configure this special configurations via command-line argument "-vmargs", see the command line list [cmd-list].

Running EHB-CB in Multi Instance Mode

For running EHB-CB in multi instance mode, the following have to be specified:

  1. Add the following arguments for the Java Runtime Environment into the eHandbookCB.ini file:

    • -Dosgi.instance.area=”dir path”
      (Must be different for each EHB-CB instance)

    • -Dosgi.configuration.area=”dir path”
      (Must be different for each EHB-CB instance)

    • -Djava.io.tmpdir=”dir path” (Optional)
      Handling of temporary files. This parameter is optional, if not supplied, EHB-CB handles creation of separate temp directory created for multi-instance within @user.home\AppData\Local\Temp

  1. Launch of EHB-CB with the additional command line parameter: -lockDir ”dir path” (Must be identical for all EHB-CB instances)
    Required to handle lock for PDF FLY as it support single instance only and other EHB-CB instance waits until the first EHB-CB instance completes the image conversion using PDF FLY.

Please refer to the sample below with parameters that need to be provided for running EHB-CB in multi instance mode:

eHandbookCB.exe (1)
-i "D:\TestData\Asam_Data\input\asamCC.ccx"
-o "D:\TestData\Container\output"
-n "EhcbDemoContainer"
-lockdir "D:\LockDir"
-vmargs
-Dosgi.instance.area=@user.home/EHANDBOOK-CB/instance
-Dosgi.configuration.area=@user.home/EHANDBOOK-CB/configuration
-Djava.io.tmpdir="D:\temDir"
1 On Linux use the executable eHandbookCB

All the above parameters must be used consistently in a Batch Job Server environment. Incomplete parameter supply will result in inconsistent behavior of the EHANDBOOK Container-Build. |

RAM Usage

The maximum RAM memory that EHANDBOOK Container-Build is allowed to use is specified within the -Xmx parameter in the eHandbookCB.ini file.

In this example, the memory limit is set to 8 GB:

-startup plugins/org.eclipse.equinox.launcher_1.5.100.v20180827-1352.jar
--launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.800.v20180827-1352
--launcher.appendVmargs
-vmargs
-Xms256m
-Xmx8g (1)
--add-modules=java.xml.bind
-Dorg.eclipse.update.reconcile=false
1 Set maximum RAM to 8 GB. Refer to, System Requirements

MATLAB Connection

In order to render the graphics of Simulink blocks appropriately, a connection to MATLAB is required.

By default a connection from Container-Build to MATLAB is enabled and established when converting Simulink models. In order to prevent a connection to MATLAB, the command line option -nomatlab can be used.

With an active MATLAB connection, images of Simulink block masks or block decorations are exported and are available as an overlay on the respective block when loaded in EHANDBOOK-NAVIGATOR.

Timeout for MATLAB Connection

The command line parameter -matlabpath uses MATLAB during the build process for Simulink mask generation. This happens via a MATLAB API connection. To ensure, that EHB-CB is not blocked, there is a configurable timeout, if the connection hangs for any reason. For this, the parameter -DmatlabTimeoutThreshold=value can be specified in the eHandbookCB.ini file. The value should be an integer and unit corresponds to minute.

In the following example, the timeout is set to 10 minutes:

-DmatlabTimeoutThreshold=10

Without any given timeout specification in the ini-file, the default is set to 5 minutes.

If the timeout occurs, the established MATLAB connection will be terminated immediately. The EHANDBOOK Container-Build process continues without any connection retry, therefore no more mask images are generated. An error is logged in the log file.

Caching Mechanism for Simulink Referenced Models

Performance of Simulink model conversion has been improved by introducing caching mechanism for referenced Simulink models. This is achieved by caching the libraries that are already converted. For this, the parameter -DsimulinkLibraryCacheSize=value can be specified in the eHandbookCB.ini file. The value should be an integer and unit corresponds to number of libraries.

In this example, the cached number of library modules is set to 50:

-DsimulinkLibraryCacheSize=50

Without any given specification in the eHandbookCB.ini file, the default is set to cache 100 library models.

This caching has a major impact of the overall memory consumption of EHANDBOOK Container-Build. When many and/or huge libraries are cached and only a small amount of RAM is specified for EHANDBOOK Container-Build, the tool may crash with an out of memory error! In this case you have to decrease the amount of cached libraries or increase the RAM, as described in chapter RAM Usage.

Parallelization for Simulink Mask Image Generation

Re-start MATLAB Connection for Model Count

We have realized that MATLAB becomes slower and slower the longer the API connection is established. So, the performance of Simulink mask generation has been improved by introducing restart of MATLAB connections. This is achieved by configuring -DrestartMatlabConnectionForModelCount=value which can be specified in the eHandbookCB.ini file. Value should be in integer and unit corresponds to number of models after the MATLAB connection is restated.

In this example, the MATLAB connection is restarted every 30 models:

-DrestartMatlabConnectionForModelCount=30

If no restart should happen, the value has to be set to =0

Without any given specification in the ini-file, the default is set to restart MATLAB connection for every 25 models.

Performance of Simulink mask generation has been improved by using multiple CPU threads of the used PC system. Parallelization for mask generation is based on configured number of threads running on each instance of MATLAB. This is achieved by configuring -DthreadCountForMaskGeneration=value which can be specified in the eHandbookCB.ini file or as a command line argument -vmargs -DthreadCountForMaskGeneration. Value should be in integer and unit corresponds to number of CPU threads used for parallelization during mask generation.

In this example, 4 CPU threads are used:

-DthreadCountForMaskGeneration=4

  1. Without a configuration for -DthreadCountForMaskGeneration=value, the default value is set to 2 CPU threads. If value is set to 0, negative or invalid also the default is used.

  2. Each MATLAB instance is bound to exactly one CPU core.

  3. The number should be configured carefully. Keep in mind whether your system can run as many MATLAB instances as configured (availability of RAM, CPU speed, disk access speed, etc.). Otherwise you might overload your system completely if too many threads are configured.

  4. If you configure e.g. -DthreadCountForMaskGeneration=100, but your input to Container-Build contains only one Simulink model then Container-Build will only start one MATLAB instance.

  5. If you configure e.g. -DthreadCountForMaskGeneration=100, but only one CPU core is available on the machine then Container-Build will only start one MATLAB instance.

  6. The number of effectively used MATLAB instances will be stated in the log as: threadCountForMaskGeneration is set to <SUCCESSFUL LAUNCHED NUMBER OF MATLAB INSTANCES>

Types for Simulink Mask Image Generation Caching

Performance of Simulink mask generation has been improved by introducing a caching mechanism for Simulink mask types. Types with same mask data should be considered for caching. For this, the types of masks can be configured with -DtypesForMaskGenerationCaching=type1,type2,…​ in the eHandbookCB.ini file.

Example: If a block mask data has parameter "Type" with value TL_out or TL_in which are used in many blocks, such types can be cached as

-DtypesForMaskGenerationCaching=TL_out,TL_in

If the data of the mask type is different in Simulink blocks, such types should not be cached as this results in incorrect mask generation.

Example: If two blocks has mask data has parameter "Type" with value TL_out but the mask commands are different then such types should not be cached.

Not all the mask data is currently interpreted by EHANDBOOK Container-Build. To overcome this, there is a new option which exports the Simulink Mask as an image and shows them in EHANDBOOK-NAVIGATOR. The option is enabled by default, to switch to mask interpretation add the following entry in the eHandbookCB.ini file:

-DenableSimulinkMaskInterpretation=true

By default, the option is disabled and set to false. The Simulink mask decorations as image is currently supported only for blocks which are rectangular in shape. This option requires a MATLAB connection for the build process. The earlier option -DenableSimulinkMaskDecorationsAsImage is deprecated.

With simulink mask decoration as image approach, it is possible to generate mask images for selected rectangular blocks with mask applied on them. A list of rectangular blocks with mask are identified and listed in eHandbookCB.ini file:

-DrectangularBlocksWithMask

By default, this option specifies a set of rectangular blocks with mask applied on them. This list can be further extended with additional rectangular blocks with masks on them.

Mask Icons in Simulink are not generated for Plot Commands. Display property of a masked block does not have plot information from MATLAB 2017a onwards. Hence mask icons are not generated for such blocks. Alternatively, use the option -DenableSimulinkMaskInterpretation command.

Simulink Rich Text Annotations as Text

Currently EHANDBOOK has some limitations on Simulink Annotations which contain rich text formatting. To overcome this, there is a new option which extracts the textual content from rich text annotations and shows them as text in EHANDBOOK-NAVIGATOR. The option can be enabled with the following option:

-DsimulinkAnnotationsAsText=true

Some rich text formattings like tables and images are currently not supported.

Name Matching for zipped Simulink Main Files

Typically, you will have only one Simulink file per sub directory (Directory Based EHB-CB) or per functional component (ASAM based EHB-CB). EHB-CB also supports multiple Simulink files, where one main model file is referencing other model files. To make this happen, all files must be zipped, where the zipped file name must match to the main model name (default behavior). There should not be any hierarchy within the zip folder.

If this is not the case, you can specify one or more suffixes, which will be ignored from the zip name to still allow name matching with the main model name:

-DsimulinkZipSuffix=suffix1,suffix2

This option accepts multiple suffixes with comma separated values.

Handling of Simulink Mask Documentation for library models and referenced models

Mask documentation (referred as Base documentation) can be associated with a library model or a referenced model. Further uses are allowed to add an additional documentation (Referred as Custom Documentation) to the instance of library model or referenced model used in their model. In EHANDBOOK, mask documentation are indicated with tooltip as follows:

  • If a library block has a custom mask, then the documentation contents for the custom mask shall be shown in the tooltip.

  • If a library block has a base mask, but no custom mask, then the documentation contents for the base mask shall be shown in the tooltip.

MATLAB provides capabilities to create protected models. In EHANDBOOK, such protected models are made non-expandable in order to maintain the confidentiality of the content.

Thread Configuration for PDF Generation

PDF generation using command line argument -pdf is a multithreaded operation. This operation uses all the existing logical CPU cores available on the system for conversion. This might impact the overall system performance.

In order to make PDF generation more optimal, the maximum number of used threads that get spawned during PDF generation can be configured.

If the number of threads configured is greater than available logical CPU cores, then all the available logical cores are utilized.

-DthreadCountForPdfGeneration=4

This option accepts integer value.

ASCET models without ASCET project component

ASCET project component serves as an entry point for processing an ASCET model in EHANDBOOK. However a user might not define an ASCET project in an ASCET model. In such an instance, EHANDBOOK would consider components with names matching with the ASCET model name for processing. Component types which are considered for name matching and processing further are as follows:

  • ASCET_MODULE

  • AUTOSAR_SOFTWARE_COMPONENT

  • StateMachine

This behavior can be configured with the following argument.

-DaxlFileWithNoProjectComponent

ASCET models with white-listed project components

ASCET project specification serves as an reference for processing components in an ASCET model in EHANDBOOK. However we could generate kaom and svg for the white-listed components specified in a JSON which are not part of specification. In such an instance, EHANDBOOK would consider such components in the ASCET model name for processing.

This behavior can be configured with the following argument.

-DascetGenerateAllComponents

ASAM GUI Mode

Per default, the EHANDBOOK Container-Build tool starts with the GUI for Directory-based input data (i.e., if no command line parameters are given). To start the tool with the GUI for ASAM-based input data, the following entry has to be added in the eHandbookCB.ini file:

-Dasam.cb=true