Tutorial: Generate EHB Containers from AUTOSAR (Classic) .arxml files only
Introduction
Welcome to EHANDBOOK! If you don’t know about EHANDBOOK yet, check out the overview at www.etas.com/ehandbook to get a background on what EHANDBOOK is, the problems it addresses and the benefits it provides.
In this tutorial, we are going to build a small EHANDBOOK Container for an AUTOSAR (Classic) system using the Directory-based EHANDBOOK Container-Build tool-chain. For this, we will only utilize the AUTOSAR .arxml files relevant for the application software and the EHANDBOOK Container-Build tool-chain - nothing more.
|
This tutorial requires EHANDBOOK 10.1 or higher. |
If you are interested in ASCET or Simulink models or C-Code, there are similar tutorials available as this one. Also, if you are more interested in ASAM-based XML formats for ECU software documentation, there is another EHANDBOOK Container-Build tool-chain available with a separate set of tutorials.
So let’s get started!
Installation
Prerequisites
In order to install and execute EHANDBOOK tools, you need a PC (or laptop) with Microsoft Windows 10 or 11.
You also need administrator rights to install the tools and license keys. For license keys, please contact your local ETAS sales office.
Installation of EHANDBOOK Container-Build tools
For this tutorial, we’ll use the Directory-based EHANDBOOK Container-Build tools. You can download the latest version from the ETAS Download Center.
Installation of EHANDBOOK-NAVIGATOR
To explore the generated EHB Container, you also need EHANDBOOK-NAVIGATOR installed. You can download the latest version from the ETAS Download Center.
License keys
ETAS EHANDBOOK products are protected by electonic license keys. Please ensure that you have valid license keys to operate the tools.
|
Please ensure that you have valid licenses for the AUTOSAR (Classic) add-ons for both EHANDBOOK Container-Build as well as EHANDBOOK-NAVIGATOR. |
For trial purposes, you can obtain evaluation licenses for a limited time.
Setting up the input data
To generate EHB Containers using the Directory-based EHANDBOOK Container-Build tools, the input data such as models, interface and label descriptions as well as textual documentation must be arranged in a directory structure. The directory structure must follow a specific convention:
-
A root directory: This directory is passed to EHB-CB tool-chain as input directory
-
One or more sub-directories: Each sub-directory represents a separate software component
-
Within each sub-directory, files with model data as well as textual description is placed
└── 📒 ECU_SW_XYZ
├── 📒 SWC_1
│ ├── 📄 swc_1_model.slx
│ └── 📄 textual_description.adoc
.
.
.
└── 📒 SWC_2
├── 📄 swc_n_model.slx
└── 📄 textual_description.adoc
For AUTOSAR (Classic)-based projects, the directory structure can be automatically generated with the help of EHANDBOOK Container-Build tools from the AUTOSAR .arxml files of the project.
Generate directory structure for EHB-CB from AUTOSAR .arxml files
You can either use your own AUTOSAR .arxml files or download the example here.
First, create a directory named FlexECU_AUTOSAR_files and copy the .arxml files into it.
└── 📒 FlexECU_AUTOSAR_files
├── 📄 Actuators_Comp.arxml
├── 📄 Compositions.arxml
├── 📄 FlexECUDemoActuatorSoftwareComponents.arxml
├── 📄 FlexECUDemoApplicationSoftware.arxml
├── 📄 FlexECUDemoSensorSoftwareComponents.arxml
├── 📄 Interfaces.arxml
├── 📄 ParameterInterfaces.arxml
├── 📄 PlatformTypes.arxml
└── 📄 Sensors_Comp.arxmlThen, create a further directory named FlexECU_Dir_AUTOSAR. This will be the directory where EHANDBOOK Container-Build will create the directory structure for all the software components in the .arxml files.
To generate the directory structure, run the following command:
C:\ETAS\EHANDBOOK-Container-Build_10.1.0-Windows\eHandbookCB.exe ^
-i "FlexECU_AUTOSAR_files" ^
-n "FlexECU_Dir_AUTOSAR" ^
-o "FlexECU_Dir_AUTOSAR" ^
-ar2ehbcbinput (1)| 1 | The command-line option -ar2ehbcbinput is used to initialize and generate EHANDBOOK folder structure from AUTOSAR files. |
The result should look like this:
└── 📒 FlexECU_Dir_AUTOSAR (1)
├── 📒 CPT_Afr (2)
│ └── 📄 CPT_Afr.adoc (3)
├── 📒 CPT_Ais (2)
│ └── 📄 CPT_Ais.adoc (3)
.
.
.
├── 📒 CPT_Wgc (2)
│ └── 📄 CPT_Wgc.adoc (3)
.
├── 📄 Actuators_Comp.arxml (4)
├── 📄 Compositions.arxml
├── 📄 FlexECUDemoActuatorSoftwareComponents.arxml
├── 📄 FlexECUDemoApplicationSoftware.arxml
├── 📄 FlexECUDemoSensorSoftwareComponents.arxml
├── 📄 Interfaces.arxml
├── 📄 ParameterInterfaces.arxml
├── 📄 PlatformTypes.arxml
├── 📄 Sensors_Comp.arxml
.
├── ar2ehcbinput.log (5)
└── 📄 tocs.yaml (6)| 1 | Output directory as specificied with -o command line option |
| 2 | Directory created for a software component prototype from the .arxml files |
| 3 | Textual documentation template in AsciiDoc format generated for the software component |
| 4 | AUTOSAR .arxml files (copied from input folder) |
| 5 | Log file created by EHANDBOOK Container-Build |
| 6 | The .yaml file which can be used to explicitly specify the table of contents |
For each software component, a separate sub-directory was generated. Within the sub-directory, an auto-generated AsciiDoc file got created.
= CPT_Afr (1)
== Component Overview (2)
ehbfunctionoverview::CPT_Afr[Component Overview for CPT_Afr] (3)| 1 | Heading for documentation chapter for the software component |
| 2 | Heading for sub-section |
| 3 | EHANDBOOK AsciiDoc macro for generating a component overview diagram picture |
The EHANDBOOK container generated out of this directory structure will have two table of contents:
-
Alphabetic order view: This is a flat list of all Atomic software components in alphabetic order.
-
Composition view: This is a hierarchical structure which contains the Compositions along with the respective Atomic software components.
The tocs.yaml file that is generated can be edited to explicitly specify the table of contents. For more information, refer to: Syntax of tocs.yaml.
|
The contents of the generated directory structure can be further customized:
|
Generate EHANDBOOK Container
To generate the EHANDBOOK, run the following command:
C:\ETAS\EHANDBOOK-Container-Build_10.1.0-Windows\eHandbookCB.exe ^
-i "FlexECU_Dir_AUTOSAR" ^ (1)
-o "." ^ (2)
-n "FlexECU_Dir_AUTOSAR" ^ (3)| 1 | Input directory for generating the EHANDBOOK Container |
| 2 | Output directory |
| 3 | Name of generated EHANDBOOK Container file |
Exploring the EHB Container in EHANDBOOK-NAVIGATOR
When you open the EHB Container in EHANDBOOK-NAVIGATOR, the table of contents shown in the Document Explorer contains an entry for each software component. You can use the filter to quickly find a software component of interest.
Each software component comes with a textual documentation as derived from the minimal AsciiDoc file. It comprises an auto-generated component overview diagram with requiring and providing ports as well as an auto-generated table with ports and their interface elements.
You can create overview diagrams for multiple software components, showing the dependencies amongst the application software. To display more details, invoke "Show Interface Elements" from the global toolbar or the context menu.
When you connect the overview diagram to an INCA experiment, this can be used for adding variables and parameters from ports with Sender/Receiver or Parameter interfaces directly to the experiment. The visualization of live values can provide you with more insights on the behavior of your AUTOSAR (Classic) based application software.
Summary
Congratulations! You have successfully completed the tutorial!
Here are few things you can do now:
-
Add ASCET or Simulink models as specifications for the internal behavior for the software components.
-
Alter the textual documentation by adding some auto-generated model screenshots using EHANDBOOK’s AsciiDoc extensions.
-
Generate a PDF documentation for the contents of your EHANDBOOK Container. Check the command-line option
-pdf. -
Apply custom styling and branding to your EHANDBOOK Container.