EHB-CB Usage in General
EHB-CB 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, always check the console messages and the log file for any error or warning messages and examine the container content for completeness and accuracy upfront. Also follow the latest safety advice documents, delivered as separate documents within the EHB-CB package. |
EHB-CB Usage in Command-line Mode
Please follow the steps for generating an EHANDBOOK container from the source data:
Step 1: Open the windows command prompt and navigate to the location of EHB-CB command line application (eHandbookCB.exe).
Step 2: Please key in the appropriate command line parameters (refer the tables below) on to the command prompt. Format: eHandbookCB.exe <Option>
List of EHB-CB command line parameters:
| Parameter | Optional | Value Type | Description |
|---|---|---|---|
-i |
No |
Path enclosed within double quotes |
Location of ASAM catalog file (.ccx) for ASAM EHB-CB or top folder of input directory for DirBased 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, which is located in the sub folder ../documentation of your EHB-CB installation. 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 ClickPic |
-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 Adjustments 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. |
-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 In AUTOSAR |
-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 Container 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. |
-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. |
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 Configuration for C-Code Visualization |
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. |
-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. |
EHB-CB command line parameters only valid if optional asset is part of EHB-CB tool. This feature is sold as a separate option on request and is not included in the standard EHB-CB.
| Parameter | Optional | Value Type | Description |
|---|---|---|---|
-genxdiovr |
Yes |
None |
Option to create MSR Diagnosis XDI overview table by aggregating the XDI information |
EHB-CB command line parameter, only valid if optional asset is part of EHB-CB tool. This feature is sold as a separate option on request and is not included in the standard EHB-CB.
| Parameter | Optional | Value Type | Description |
|---|---|---|---|
-ihf |
Yes |
Text enclosed within double quotes |
Option to trigger filtering for intermediate ASCET hierarchies. For more details refer to chapter Intermediate Hierarchy Filtering |
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
EHB-CB 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! -
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 ClickPic 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… .
Adjustments 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.
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 Batch Job Server environment. Incomplete parameter supply will result in inconsistent behavior of the container build. | |
RAM Usage
The maximum RAM memory, EHB-CB 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
--add-modules=java.xml.bind
-Dorg.eclipse.update.reconcile=false
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. Value should be in integer and unit corresponds to minute.
In this 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 EHB-CB process continues without any connection retry, therefore no more masks are generated! An error entry in the log file is made. |
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. Value should be in 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 ini-file, the default is set to cache 100 library models.
|
This caching has a major impact of the overall memory consumption of the EHB-CB! If many and/or huge libraries are cached and only a small amount of RAM is specified for EHB-CB, the tool may crash with an out of memory error! In this case you have to decrease the amount of cached libs or increase the RAM, as described in chapter RAM Usage. |
Parallelization for Simulink Mask 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.
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. 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
Without any given specification in the ini-file, the default is set to all available logical CPU cores. If value is set to 0, negative or invalid also the default is used.
Types for Simulink Mask 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. |
Simulink Mask Decorations as Image
Not all the mask data is currently interpreted by EHB-CB, to overcome this, there is a new option which exports the Simulink Mask as an image and shows them in EHB-NAV. 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. |
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).
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.
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.