Tutorial: Directory-based EHB-CB for ASCET 6

Introduction

In this tutorial, we are going to build a small EHANDBOOK Container for a single ECU function modeled with ASCET 6 using the Directory-based EHANDBOOK Container-Build tool-chain.

So let’s get started!

Installation

Prerequisites

To install and use the EHANDBOOK tools, you need:

A PC or laptop running Microsoft Windows 11.
Administrator rights to install the tools and license keys.
Valid ETAS license keys. If you do not have license keys, contact your local ETAS sales office.

For trial purposes, you can obtain a time-limited evaluation license.

Install EHANDBOOK Container-Build

For this tutorial, use the Directory-based EHANDBOOK Container-Build tool chain. Download the latest version from the ETAS Download Center.

Install EHANDBOOK-NAVIGATOR

To explore the generated EHANDBOOK Container, install EHANDBOOK-NAVIGATOR. Follow the instructions in the EHANDBOOK-NAVIGATOR Free Trial Version guide to download the EHANDBOOK-NAVIGATOR software.

Set Up the Input Data

To generate an EHANDBOOK Container using the Directory-based EHANDBOOK Container-Build tool chain, organize the input data in the following directory structure:

A root directory that is passed to the EHANDBOOK Container-Build tool chain as the input directory.
One or more sub-directories, where each sub-directory represents a separate function.
Each sub-directory contains the model, interface and label descriptions, and textual documentation for that function.

└── ECU_SW_XYZ
    ├── Function1
    │   ├── function_1_model.axl
    │   ├── interface_and_labels.xlsx
    │   └── textual_description.adoc
    .
    .
    .
    └── Function_n
        ├── function_n_model.axl
        ├── interface_and_labels.xlsx
        └── textual_description.adoc

Create the Input Directory Structure

Create a new directory EHB_ASCET6_Example_V1 to hold the input data for the EHANDBOOK Container.

Within this directory, create a sub-directory Function 1 to hold the source files for the ECU function to be documented.

The sub-directory represents a documentation unit, which contains all the information required to document an ECU function.

ASCET 6 model

Start with a small ASCET 6 model.

You can either create your own ASCET 6 model using the ASCET tool or download the example model here.

Place the ASCET 6 model file in the Function 1 directory. == Adding label information and interface specification

In our example, the function reads two variables, a and b, from global memory and writes the output to the global variable result. These global variables define the interface of the ECU function.

To document this information, EHANDBOOK provides structured tables for variables and parameters. In addition, it generates a graphical Function Overview.

Input data for label information and interface specification

To document the labels used by the ECU function and its interface specification in the EHANDBOOK Container, create an Excel file and store it in the same directory as the ASCET 6 model.

The Excel file template contains two sheets:

Signals
Calibrations

Signals are global variables that can be measured using measurement tools such as ETAS INCA. Signals read from and written by an ECU function are used to exchange data with other ECU functions.

Calibrations are variables whose values can be changed or fine-tuned using calibration tools such as ETAS INCA. They can be:

Single scalar values
Curves
Maps interpreted by 1D or 2D interpolation routines

For this example, create an Excel file with the following two sheets and store it in the directory where the ASCET 6 model file is located.

Alternatively, you can also download the completed Excel file.

Adding textual documentation

Textual documentation is used to explain the purpose and functionality of the ECU function.

Textual documentation as an AsciiDoc file

To add textual documentation, create an AsciiDoc (.adoc) file and place it in the directory of the ECU function.

You can create the file by:

Writing a new document using a text editor or an IDE (for example, Visual Studio Code)
Saving the document with the .adoc extension

EHANDBOOK supports basic AsciiDoc features, including:

Chapters and subsections
Paragraphs
Raster images (for example, JPEG)
Tables

Alternatively, you can download an example AsciiDoc document.

Referencing model screenshots

You can include screenshots of the ASCET 6 model in the textual documentation to help explain the structure and behavior of the ECU function.

EHANDBOOK Container-Build automatically generates the screenshots from the ASCET 6-based interactive model.

To include a model screenshot in the documentation, add an EHANDBOOK model reference directive to your AsciiDoc (.adoc) file.

Use the following syntax:

ehbmodelref::<ascet-6-model/hierarchy-path>[]

The <ascet-6-model/hierarchy-path> specifies the path of the subsystem or module in the ASCET 6 model from which the model screenshot is generated.

For example, the following directive generates a screenshot of the Main subsystem in the ASCET 6 model:

ehbmodelref::"Project/Main/Module/Main"[Project/Main/Module/Main]

In this example:

Project/Main/Module/Main is the model path of the Main subsystem.
EHANDBOOK Container-Build uses this model path to generate the corresponding model screenshot.
Replace Project/Main/Module/Main with the model path of the subsystem or module that you want to document.

When you generate the EHANDBOOK Container, Container-Build automatically generates the referenced model screenshot and embeds it in the textual documentation.

Generate the EHANDBOOK Container

Use the Directory-based EHANDBOOK Container-Build tool in GUI (Graphical User Interface) mode to generate the EHANDBOOK Container.

In the installation directory, double-click eHandbookCB.exe to launch the tool in GUI mode.

Alternatively, run eHandbookCB.exe from the command line without any arguments.

In the Build information section, specify the following:

Input folder: <path>\EHB_ASCET6_Example_V1\Input
Output folder: Select the directory where you want to save the generated EHANDBOOK Container. We recommend creating an Output or EHANDBOOK Containers directory next to the input directory.
EHB file name: EHB_ASCET6_Example_V3

The following example shows the recommended project directory before generating the EHANDBOOK Container.

The project directory now contains the Input and Output folders. Place the required input files in the Input folder.

The Input folder contains the ASCET 6 model, interface and label information, and the textual documentation used to generate the EHANDBOOK Container.

Click Generate to create the EHANDBOOK Container.

After the generation is complete, you can open the output directory or directly open the generated EHANDBOOK Container.

Open the EHANDBOOK Container in EHANDBOOK-NAVIGATOR to explore the interactive model.

The generated EHANDBOOK Container includes:

The ASCET 6-based interactive model
Interface and label information
Textual documentation and referenced model paths

You can also download the generated EHANDBOOK Container here.

Explore the EHANDBOOK Container in EHANDBOOK-NAVIGATOR

Open the generated EHANDBOOK Container in EHANDBOOK-NAVIGATOR.

When you expand Function 1, a sub-entry named Project is displayed.

The Project sub-entry links to the ASCET 6-based interactive model.

Click the Project sub-entry to open the ASCET 6-based interactive model in a new tab.

The ASCET 6-based interactive model resembles the original ASCET 6 model. Therefore, the root level is displayed.

Click on the + button to expand the contents.

EHANDBOOK-NAVIGATOR expands the subsystem and displays its contents in the current context. Note that there are gaps between the input and output ports and the corresponding input and output blocks of the subsystem.

Click on the + button of the class instance block AddSrvClassInstannce to expand its contents.

Click on the Auto-Layout button in the toolbar or select Auto Layout from the context menu.

The diagram is now laid out using an automatic layout algorithm. Additional connections are drawn to provide a seamless signal flow across subsystems. The diagram is also more compact.

When you switch to the Model Explorer, you can inspect the complete ECU function hierarchy as a tree view.

Double-click Function Overview to open the external interface of the ECU function.

Expand the function overview block to explore the ASCET 6-based interactive model.

The input and output signals are connected through the label ports, allowing the ECU function to exchange data with other ECU functions.

The signals and calibrations are documented as structured tables.

Structured tables for signals and calibrations

The documentation for Function 1 now includes a textual description.

EHANDBOOK including textual documentation

The generated model screenshots are linked to the interactive model. Click Open interactive model to open the corresponding subsystem in a new model viewer tab.

Interactive model opened from the linked screenshot

Summary

Congratulations! You have successfully created a complete EHANDBOOK Container for an ECU function modeled with ASCET 6.

During this tutorial, you learned how to:

Generate an EHANDBOOK Container from an ASCET model.
Add label information and interface specification using an Excel file.
Add textual documentation using an AsciiDoc file.
Reference ASCET 6 model elements in the documentation using model paths.
Explore the generated EHANDBOOK Container in EHANDBOOK-NAVIGATOR, including the textual documentation, structured tables, Function Overview, and the ASCET 6-based interactive model.

Now you can continue with the following tasks:

Create EHANDBOOK Containers for additional ASCET 6 models. You can load and combine multiple containers in EHANDBOOK-NAVIGATOR.
Create a single EHANDBOOK Container containing multiple ECU functions by adding additional function directories and running EHB-CB again.
Generate a PDF documentation for your EHANDBOOK Container using the -pdf command-line option.
Apply custom styling and branding to your EHANDBOOK Container.