Tutorial: Directory-based EHB-CB for C-Code

Introduction

In this tutorial, you will learn how to build a small EHANDBOOK Container for a single ECU function using C-Code and the Directory-based EHANDBOOK Container-Build tool chain.

So let’s get started!

If you are new to C-Code, see Introduction to C-Code before starting this tutorial.

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_implementation.c
    │   ├── interface_and_labels.xlsx
    │   └── textual_description.adoc
    .
    .
    .
    └── Function_n
        ├── function_n_implementation.c
        ├── interface_and_labels.xlsx
        └── textual_description.adoc

Create the Input Directory Structure

Create a new directory EHB_CCode_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.

C-Code

Start with a small C code model.

You can either create your own C code model or download the example here.

int a;
int b;

int result;

void calc() {
	result = a+b;
}

Place the C-Code file in the Function 1 directory.

Your directory structure should look like this:

└── EHB_CCode_Example_V1
    └── Function 1
       └── function_implementation.c

If the implementation is split across multiple C-Code files, place all related .c and .h files in the function directory. Common code can be provided as a library path (see C-Code configuration).
The C-Code does not have to be complete. If the source code for a called function is not available, it is shown as a black box.
If the C-Code uses preprocessor macros, make sure they can be resolved. This ensures that the code can be processed correctly.

Adding Label Information and Interface Specification

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

EHANDBOOK uses structured tables to document signals and calibrations. It can also generate a function overview from this information.

Prepare the Excel File

To document the signals and interface information, create an Excel file and store it in the same directory as the C-Code files.

The Excel template contains two sheets:

Signals – Used to describe the signals that are read or written by the ECU function.
Calibrations – Used to describe the calibration parameters of the ECU function.

For this example, create an Excel file with the following two sheets and save it in the Function 1 directory.

Alternatively, you can download the completed Excel file here.

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:

Headings and sections
Paragraphs
Images
Tables

Alternatively, you can download an example AsciiDoc document.

Referencing Model Screenshots

You can include screenshots of the C-Code block diagram in the textual documentation to help explain the structure and behavior of the ECU function.

EHANDBOOK Container-Build automatically generates these screenshots from the C-Code.

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

Use the following syntax:

ehbmodelref::<hierarchy-path-to-c-function>[]

The <hierarchy-path-to-c-function> specifies the path of the C function for which the model screenshot is generated.

For example, the following directive generates a screenshot of the calc function in Function_1:

ehbmodelref::"Function_1/Function_1/calc"[Function_1/Function_1/calc]

In this example:

Function_1/Function_1/calc is the model path of the calc function.
EHANDBOOK Container-Build uses this model path to generate the corresponding model screenshot.
Replace Function_1/Function_1/calc with the model path of the function 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_CCode_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_CCode_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 C-Code files, 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 C-Code-based interactive model
Interface and label information
Textual documentation and referenced model screenshots

You can also download the generated EHANDBOOK Container here.

Explore the EHANDBOOK Container in EHANDBOOK-NAVIGATOR

Open the generated EHANDBOOK Container in EHANDBOOK-NAVIGATOR.

The EHANDBOOK Container contains one ECU function, Function 1.

Basic Interactive Model

Expand Function 1.

A sub-entry for the interactive model is displayed.

Click the sub-entry to open the C-Code-based interactive model in a new tab.

The interactive model represents the structure of the C-Code. At the root level, the top-level function calc is displayed.

Click the + button to expand the function.

EHANDBOOK-NAVIGATOR expands the function and displays the data flow and control flow as a block diagram.

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

Interface and Label Information

The documentation also includes the interface and label information that was added using the Excel file.

The signals and calibrations are documented as structured tables.

Structured tables for signals and calibrations

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

Expand the function overview block to explore the C-Code-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.

Textual Documentation

The documentation for Function 1 also includes a textual description.

The generated model screenshots are linked to the interactive model.

Click Open interactive model to open the corresponding function in a new model viewer tab.

Interactive model opened from the linked screenshot

Using a C-Code Configuration File

The C-Code configuration file controls how EHANDBOOK Container-Build processes C-Code when generating the EHANDBOOK Container.

Specify the Configuration File

Provide the configuration file using the -ccodemeta command-line option.

Command syntax

-ccodemeta "path/to/configuration.xml"

The configuration file allows you to:

Specify shared library paths.
Simplify generated diagrams.
Inline functions.
Generate hierarchical diagrams.

Configuration File Example

<functionmetadata:FunctionMetadataRoot
    xmlns:functionmetadata="http://www.etas.com/ehandbook/functionmetadata"
    xmlns:xmi="http://www.omg.org/XMI"
    xmi:version="2.0">

    <globalConfiguration
        libraryPath="../lib"
        inlineFunctions="true"
        simplifyDiagram="true"
        generateHierarchies="true"/>

</functionmetadata:FunctionMetadataRoot>

Configuration Parameters

Parameter Description

Parameter	Description
libraryPath	Specifies the folder containing shared libraries. This allows EHANDBOOK Container-Build to resolve functions that are not available in the main source files.
inlineFunctions	When set to `true`, small or wrapper functions are expanded in the generated diagrams. This creates simpler and easier-to-read diagrams.
simplifyDiagram	Removes unnecessary nodes, ports, and intermediate blocks to create cleaner diagrams. Compatible chains of logical AND (`&&`), logical OR (`
	`), addition (`+`), and multiplication (`*`) operators are compacted into one multi-input operator block.
generateHierarchies	Generates hierarchical diagrams, making it easier to navigate and understand complex C-Code.

libraryPath

Specifies the folder containing shared libraries. This allows EHANDBOOK Container-Build to resolve functions that are not available in the main source files.

inlineFunctions

When set to true, small or wrapper functions are expanded in the generated diagrams. This creates simpler and easier-to-read diagrams.

simplifyDiagram

Removes unnecessary nodes, ports, and intermediate blocks to create cleaner diagrams. Compatible chains of logical AND (&&), logical OR (`

), addition (+), and multiplication (*`) operators are compacted into one multi-input operator block.

generateHierarchies

Generates hierarchical diagrams, making it easier to navigate and understand complex C-Code.

Summary

Congratulations! You have successfully created a complete EHANDBOOK Container for an ECU function using C-Code.

During this tutorial, you learned how to:

Generate an EHANDBOOK Container from C-Code.
Add label information and interface specification using an Excel file.
Add textual documentation using an AsciiDoc file, including references to C-Code functions.
Explore the generated EHANDBOOK Container in EHANDBOOK-NAVIGATOR, including the textual documentation, structured tables, Function Overview, and the C-Code-based interactive model.
Organize shared implementations using a library folder.
Configure EHANDBOOK Container-Build using a C-Code configuration file.
Use SWAN debug logs to understand dependency resolution and troubleshoot common issues.

Now you can continue with the following tasks:

Create EHANDBOOK Containers for additional C-Code projects. 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.
Configure shared libraries and diagram generation using the C-Code configuration file.
Generate a PDF documentation for your EHANDBOOK Container using the -pdf command-line option.
Apply custom styling and branding to your EHANDBOOK Container.