Preparation Steps for Directory Based EHB-CB
Minimum input for container generation is one single model file (Simulink/ASCET/C-Code). The container can be enriched by RTF-, AsciiDoc- and Excel-files to show more functionality in EHB-NAV.
Input Directory Structure
Define a directory structure with different names and sub hierarchies if required.
|
Each sub directory name must be unique even it is in a separate branch or level! |
This structure is 1:1 used to generate the table of contents in NAV. Two TOCs will be created: SW architecture (like above) and flat alphabetical.
Generation of Input Directory Structure from AUTOSAR files
EHB-CB is capable of generating Input directory structure from AUTOSAR files. A command line argument -ar2ehbcbinput is used for this purpose. In order to create such a directory structure, a path to the folder containing a root composition and corresponding ARXML file serves as input. For file details see also In AUTOSAR. Optionally, the root composition can be specified with the command line argument -autosarcomposition "RootCompositionName". EHB-CB will generate a directory structure in the given output path. For each composition in the corresponding sub folder, an AsciiDoc file is also auto generated. It contains a component interface diagram. The folder structure is directly suitable as input for the standard Directory Based EHB-CB. Beforehand, it could also be enriched manually or scripted with additional files, e.g. models, attachments or further description files.
Example:
C:\eHandbook\CB_Windows\eHandbookCB.exe -i "c:\user\input" -o "c:\user\output" -ar2ehbcbinput
Models
Place exact one model in the lowest sub-hierarchy of the directory structure.
Model could be:
-
Preprocessed ANSI c-code as *.c and *.h in ASCII text, saved in UTF-8 encoding format (multiple files allowed)
-
C-Code models packed as *.zip also possible
-
Simulink model as *.mdl or *.slx with MATLAB version R2016b - R2022b
-
Simulink models packed all together as one .zip wherein zip name is exactly same as main model name (.slx or *.mdl) also possible (see also Name Matching for zipped Simulink Main Files)
-
ASCET model as *.axl out of ASCET V5.2.1 – V6.4.3
|
C code source files must be saved in UTF-8 encoding format. ANSI, other Unicode formats and Big-Endian formats are not supported. |
Model Interface & Data Description
To allow the search proposal dialog, function overview, and label pop-up feature in EHB-NAV, labels have to be identified by the tool. To get to know, what are variables and parameters, and how a model component is interfacing to other components an internal data dictionary is used.
In XLS
As input format for EHB-CB *.xls is used here. The xls-files are placed in their respective function named folder, together with the model file. Per function, only one xls-file is allowed. Processing of this file provides the metadata dictionary.
|
For further details and restrictions of XLS converter, please refer to the XLS Format Specification for EHB-CB document, which is located in the sub folder ../documentation of your EHB-CB installation folder. |
In AUTOSAR
AUTOSAR Classic xml ( *.arxml) files are processed to fetch information about the AUTOSAR packages like compositions, components, ports and interfaces. These files can be placed in component named folders, together with the model file. Multiple arxml files can be placed inside a folder. Among the compositions in the arxml the user can provide the root composition by using the command line argument -autosarcomposition. Otherwise the root composition is calculated by CB.
| Supported Types | Supported Elements out of this Type |
|---|---|
Interfaces |
SenderReceiverInterface, ParameterInterface |
Components |
CompositionSwComponentType, AtomicSwComponentType, ParameterSwComponentType, AdaptiveApplicationSwComponentType |
Connections |
AssemblySwConnector, DelegationSwConnector |
Datatypes |
ApplicationRecordDataType, ImplementationDataType, ApplicationArrayDataType |
|
A separate electronic license (EHB_CB_CON_AUTOSAR_CLASSIC) is required for this feature |
|
EHANDBOOK 9.2.1 does not support AUTOSAR application software which makes use of multiple instantiation concept. In case when a software component is instantiated multiple times, duplicate information can be shown in the label pop-up for ports. |
|
EHBANDBOOK-NAVIGATOR 9.2.1 does not show AUTOSAR compositions as nested components. Furthermore, connections between ports of compositions are not shown. |
In A2L
The file extension of ASAM MCD-2 MC compliant description files is "A2L", which is an abbreviation of "ASAM MCD-2 MC Language". The internal format of A2L-files is based upon a non-XML notation. Refer https://www.asam.net/standards/detail/mcd-2-mc/wiki/#TechnicalContent for specification details.
These files can be included globally in the input folder or in a sub-directory, along with the model file in directory-based EHB-CB. Multiple A2L files can be placed inside a folder. Processing of these A2L files provide the metadata dictionary. The A2L-converter for the directory-based EHB-CB toolchain generates model interface data out of A2L files and aggregates them into the metadata database inside the container. This will allow enhanced EHB-NAV features like Label Tagging, Label-Popup, Search Proposals, Function Overview, Importing/Exporting Functions.
File Location and Usage
Single or multiple A2L files(s) per functional component or globally in the input folder can be placed.
.
└── input/
├── Actuators/
│ ├── Actuators.mdl
│ └── documentation.adoc
├── Tqs/
│ ├── Tqs.mdl
│ └── documentation.adoc
└── EHANDBOOK_FlexECU_Demo.a2l
.
└── input/
├── Actuators/
│ ├── Actuators.mdl
│ ├── documentation.adoc
│ └── EHANDBOOK_FlexECU_Demo.a2l
└── Tqs/
├── Tqs.mdl
├── documentation.adoc
└── EHANDBOOK_FlexECU_Demo.a2l
Support for meta-data from multiple sources
Information for model interfaces and labels (meta-data) can be read from multiple source formats in parallel. The files are to be placed in their respective function named folder (Directory based EHB-CB) or referenced in CCX (ASAM based EHB-CB, see in the document ASAM Format Specification for EHB, which is located in the sub folder ../documentation of your EHB-CB installation folder). AUTOSAR information will be treated as base source with other sources complimenting the AUTOSAR meta-data.
| Product | Supported Meta-data sources |
|---|---|
ASAM |
MDX,ARXML |
Directory |
ARXML,XLS |
Textual Content
Per sub directory, (normally this corresponds to a function component) you can add textual documents in RTF- or AsciiDoc format, together with the model file. This content is then transformed into the EHB container. Later it is shown in the function documentation window of the function component in EHB-NAV and describes verbally the functionality of the corresponding model. These documents can contain also images and screenshots of model hierarchies. You can add multiple documents per folder, even in both formats in parallel.
In RTF
EHB-CB supports a limited set of the styling and format possibilities of RTF only.
|
For further details, e.g. chapter identification, linking of images and restrictions of RTF converter please refer to the RTF Format Specification for EHB-CB document, which is located in the sub folder ../documentation of your EHB-CB installation folder. |
Predefined Key Words in RTF
EHB-CB provides some key words, which can be used to in-line additional graphical and textual information additionally to the RTF content into the text pane in EHB-NAV later.
Link a given image to an interactive model hierarchy:
[model]
<image>
ASCET/Simulink models: Model hierarchy path in text style of type “Caption”
Place a model screenshot, generated out of the interactive model and link to it:
[ehbmodelref]
ASCET/Simulink models: Model hierarchy path in text style of type “Caption”
Simulink library models: Model hierarchy path from the referenced model in text style of type “Caption”
C-code: filename.c/SubFunctionName in text style of type “Caption”
Integrates the text out of an additional file:
[ehbinline] filename
-
Only the very most top sub functions of the c-file can be defined and selected for the graphic
-
All elements of the model are shown in unexpanded view
-
The c-file is in the same location as the RTF file
-
Depending on the code size, the image of the interactive model may be too big to be shown fully in the text pane or be in reduced downsized view to fit in.
Integrates a Function Overview Diagram (refer 6.9):
[ehbfunctionoverview-begin]
List of function names separated by comma (“,”). Function name is the name of the corresponding sub directory name.
[ehbfunctionoverview-end]
Integrates a Function Overview Diagram for all functions:
[ehbfunctionoverview-all]
In AsciiDoc
Textual content can also be provided via AsciiDoc (https://asciidoc.org).
Currently the following basic set of AsciiDoc attributes is supported:
-
Paragraphs
-
Text formatting
-
Lists (ordered list, unordered list without nesting)
-
Simple Tables
-
Embed Graphics
-
Source Code (Literal, Inline, Code block, Include are supported)
-
Links to URL or files
EHB-CB provides predefined key words, which can be used as macros to in-line additional model screenshots in the text pane and link them to an interactive model of function overview.
A detailed description of all supported AsciiDoc attributes can be found in the AsciiDoc specification for EHB document, which is located in the sub folder ../documentation of your EHB-CB installation folder.
Attachments
An attachment is an additional file that is associated with content of an EHANDBOOK Container. Attachments are stored in EHANDBOOK Container files and shipped with them. Users of EHANDBOOK-NAVIGATOR can open attachments to obtain additional information or data.
Addressed problems
When adopting EHANDBOOK, it is sometimes too hard to convert existing textual documentation contents (e.g. PDF or Word documents) to an EHANDBOOK input format (e.g. FSX or AsciiDoc). Instead of spending efforts on converting such contents, these can be added as attachments to a function documentation.
Furthermore, there are various use cases where users of ECU software documentation can benefit from additional data or information, e.g. initial calibration data or automation scripts. However, this information is available in file formats that cannot be read with EHANDBOOK-NAVIGATOR or where it even does not make sense to view or read them in EHANDBOOK-NAVIGATOR directly. On the other hand, it would be good for users to have all the information and data for an ECU function at a single place.
Benefits
Adding additional textual documentation as attachment to an EHANDBOOK Container saves time and effort to convert existing textual contents to an input format supported by EHANDBOOK. Rather than spending efforts, the contents can be directly added to the EHANDBOOK Container "as-is".
Secondly, it is possible to enrich the EHANDBOOK Container with additional file-based information.
Examples for attachments
Attachments can be distinguished into Documentation Contents and Complementary Information & Data.
-
Documentation contents are contents which can be captured as documentation text in EHANDBOOK if the contents were provided by one of the supported input data formats (e.g., FSX or AsciiDoc). Documentation contents which are converted to EHANDBOOK internal format are shown in the built-in browser in a content tab.
-
Complementary Information & Data are additional files which are typically not used directly in EHANDBOOK-NAVIGATOR. The EHANDBOOK Container file acts as a structured and organized way to ship the information and data to users.
The following table provides a list of examples.
Documentation Contents |
Complementary information & data |
|
|
How to provide attachments to EHB-CB
Attachments are files associated to a documentation unit in particular a chapter in EHANDBOOK. This can be a general text chapter, a function description or a software component description.
Depending on the EHANDBOOK Container-Build approach, this can be achieved in the following ways.
Dir-based EHB-CB
In the directory-based EHB-CB approach, all files which shall be added as attachments must be stored in a sub-directory named _attachments. During EHANDBOOK Container-Build, the files are picked up and added as attachments.
Tqs (1)
|_ Tqs.adoc (2)
|_ Tqs.slx (3)
|_ Tqs.xslx (4)
|_ _attachments (5)
|_ Tqs_Calibration_Guide.pdf (6)
|_ Tqs_Initial_Calibration_Values.dcm (6)
|_ Tqs_Variables_List.lab (6)| 1 | Directory for documentation unit Tqs |
| 2 | Textual documentation in AsciiDoc format |
| 3 | Simulink model (source for interactive model) |
| 4 | Excel file with function interface and label description |
| 5 | Sub-directory _attachments for attachments for the documentation unit |
| 6 | File to be attached |
|
Folders with name |
ASAM-based EHB-CB
In the ASAM-based EHB-CB approach, an <ABLOCK> with category ATTACHMENTS has to be created and linked to the documentation chapter to which the attachments shall be associated.
The 'ABLOCK' then has to list each file that represents an attachment.
<ABLOCK> (1)
...
<AREFS>
<AREF ID-REF="ID_Tqs_Attachments" /> (2)
</AREFS>
...
</ABLOCK>
<ABLOCK ID="ID_Tqs_Attachments"> (3)
<SHORT-NAME>Tqs_Attachments</SHORT-NAME>
<CATEGORY>ATTACHMENTS</CATEGORY>
<FILES>
<FILE>_attachments\Tqs_Calibration_Guide.pdf</FILE> (4)
<FILE>_attachments\Tqs_Initial_Calibration_Values.dcm</FILE> (4)
<FILE>_attachments\Tqs_Variables_List.lab</FILE> (4)
</FILE>
</ABLOCK>| 1 | ABLOCK of the documentation unit to which attachments shall be associated |
| 2 | Reference to the ABLOCK specifying the attachments |
| 3 | ABLOCK with category ATTACHMENTS |
| 4 | File to be attached |
Attachments in EHANDBOOK-NAVIGATOR
In EHANDBOOK-NAVIGATOR, attachments are shown as part of the chapters in the selected table of contents. For each documentation chapter which has additional attachments, an entry Attachments is added. This entry contains the attached files as a list.
-
The name of the entry corresponds to the file name of the attachment as provided to EHANDBOOK Container-Build.
-
The icon of the attachment entry is provided by your operating system.
Important Notices
NOTICE
Incomplete container content due to wrong or corrupt file formats
Content of the generated EHANDBOOK Container may be incomplete, if the input data used for generating the container are not compliant to the following file formats:
-
ASAM formats
-
CCX
-
FSX
-
MDX
-
-
Image formats
-
JPG
-
PNG
-
EPS
-
-
Formulas
-
TeX
-
-
Text formats
-
AsciiDoc (supported subset)
-
These container contents can not be displayed in the EHANDBOOK-NAVIGATOR. Therefore, always check the log file of the EHANDBOOK Container-Build, after generating a new container. Missing, incorrect or false content will be tracked in the log file.
After generating a new container:
-
Check the entries in the log file of the EHANDBOOK Container
Build indicating missing or incorrect container content.
-
Ensure that the data used during the import match the above specified formats.
-
Generate a new container.
-
Only provide containers for further usage in the EHANDBOOK- NAVIGATOR, if the log file contains no entries indicating any missing or incorrect content.
If it is not possible to completely clean up the log file, inform the intended user of the container about this missing, incorrect or false container content.
NOTICE
Incomplete container content due to defective or inconsistent input data
Content of the generated EHANDBOOK Container may be missing, if the input data used for generating the container is defective or inconsistent. Affected container contents cannot be displayed or will be displayed incorrectly in the EHANDBOOK-NAVIGATOR. Therefore, always check the log file of the EHANDBOOK Container-Build. Defective or inconsistent input data that have led to errors when converting will be tracked in the log file.
The content consistency is in the responsibility of the data supplier (documentation publisher). We recommend that the data supplier develop a standard procedure for pre-processing the input data outside the EHANDBOOK Container-Build tool chain to ensure the data consistency and to reduce the workload for reviewing the input data. In addition, the pre-processing should be properly documented to ensure transparency.
After generating a new container:
-
Check the entries in the log file of the EHANDBOOK Container-Build indicating defective or inconsistent input data.
-
If necessary, fix the incorrect or inconsistent input data.
-
Re-build the EHANDBOOK Container.
-
Only provide containers for further usage in the EHANDBOOK-NAVIGATOR, if the log file contains no entries, indicating any defective or inconsistent input data.