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.

image7

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 with MATLAB version R2016b - R2020b 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.

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

  • Textual documentation of ECU functions (e.g., function description)

  • ECU software program files (.a2l and .hex/.s19)

  • Calibration data files with initial or neutral calibration data (.dcm, .cdfx)

  • Automation scripts (e.g., INCA Flow scripts, Matlab scripts, etc.)

  • Additional training documents (e.g., calibration guides) (PDF, Word, PowerPoint, Excel)

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 _attachments are not interpreted as documentation units and ignored from further processing.

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.

ehb nav attachments example1

  • 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.

Opening an attachment

You can open an attachment by

  1. left-clicking on the corresponding entry with the mouse,

  2. right-clicking on the entry and selecting Open attachment from the context menu or

  3. hitting the <Enter> key when the entry is selected

Saving an attachment

You can save an attachment by right-clicking on the entry and selecting Save attachment from the context menu.

Limitations

EHANDBOOK Container-Build

  • Duplicate files are not supported by attachments. For example, if you specify two ABLOCKS with category ATTACHMENTS and associate both ABLOCKS with the same function component, then any duplicate attachments will be ignored (see log file).

EHANDBOOK-NAVIGATOR

  • Attachments cannot be deleted from an EHANDBOOK Container.

  • To make use of attachments, EHANDBOOK-NAVIGATOR 10.0 or newer is required.

  • It is not (yet) possible for users of EHANDBOOK-NAVIGATOR to add attachments.

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:

  1. Check the entries in the log file of the EHANDBOOK Container-Build indicating defective or inconsistent input data.

  2. If necessary, fix the incorrect or inconsistent input data.

  3. Re-build the EHANDBOOK Container.

  4. Only provide containers for further usage in the EHANDBOOK-NAVIGATOR, if the log file contains no entries, indicating any defective or inconsistent input data.