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. |
-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 |
-vmargs |
Yes |
None |
Option to configure special configurations from the eHandbookCB.ini file via command line. For more details refer to chapter Configurations in |
-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. |
-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. |
-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. |
-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. |
-enableVariantBlockConfiguration |
Yes |
None |
Option to process the Simulink Variant blocks during container generation, and show the active and inactive variant choices in EHANDBOOK-NAVIGATOR. |
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 |
-simulinkviewfile |
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. |
-enableVariantBlockConfiguration |
Yes |
None |
Option to process the Simulink Variant blocks during container generation, and show the active and inactive variant choices in EHANDBOOK-NAVIGATOR. |
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:
|
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:
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:
-
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
-
-
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=10Without 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=50Without 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=30If 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.
Thread Count for Simulink Mask Generation
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
|
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 |
Simulink Mask Decorations as Image
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=trueBy 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:
-DrectangularBlocksWithMaskBy 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 |
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,suffix2This 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.
Simulink Protected Model
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=4This 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.
-DaxlFileWithNoProjectComponentASCET 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