How to configure EHB-CB for Simulink models

EHANDBOOK Container-Build can generate SVG graphics from Simulink models as well as rendering Simulink models as interactive models in EHANDBOOK-NAVIGATOR.

While the rendering of several types of blocks is supported natively by EHANBOOK-NAVIGATOR, in order to achieve best results for complex blocks as well as blocks from libraries, it is necessary to pass all necessary information and some additional configuration for how to interpret the libraries to EHANDBOOK Container-Build.

In this how-to guide, you will learn

  1. the relevant backgrounds for how Simulink models are constructed, and

  2. what information EHANDBOOK Container-Build requires to achieve best results in EHANDBOOK.

Example

To better explain and understand the concepts, we’ll use an example Simulink model. The sources for the example can be downloaded.

The main Simulink model is contained in the file Function.slx. The model contains references to two other Simulink models, Addition and Multiplication. Furthermore, there is a subsystem that contains some example blocks from Simulink libary.

Example Simulink Model with Referenced Models and Library Blocks
Figure 1. Graphical representation of Function.slx in Simulink
Example Simulink Model Library Blocks
Figure 2. Graphical representation of subsystem Example blocks from Simulink library

The result we want to achieve in EHANDBOOK-NAVIGATOR looks as follows:

  1. The contents of the referenced models are resolved and inlined into the interactive model in EHANDBOOK-NAVIGATOR.

  2. The blocks drawn from the library are rendered with the same graphics as in Simulink.

  3. In case of library blocks that are specified as subsystems, no further inner details are shown in EHANDBOOK-NAVIGATOR (i.e., no possibility to navigate in or expand the block).

Example Desired Result EHB NAV Screenshot1
Figure 3. Interactive model for Function.slx in EHANDBOOK-NAVIGATOR in same, default layout as in Simulink
Example Desired Result EHB NAV Screenshot2
Figure 4. Interactive model for Function.slx in EHANDBOOK-NAVIGATOR with expanded subsystems

Background

A Simulink model is saved as an .slx file. A Simulink model consists of blocks with ports and connections. The model can be hierarchical. For the latter, so-called sub-systems are used.

Re-usable artifacts in Simulink models

Simulink provides two main mechanisms to build models based on re-usable artifacts.

  1. Simulink libraries

  2. Referenced models

The following figure shows the conceptual differences between blocks from libraries (e.g., the standard Simuliunk block library) and referenced models.

Simulink Model Reusable Artifacts Concept
Figure 5. Difference between referenced blocks from libraries and referenced models

Simulink libraries

"A block library is a collection of blocks that you can use in a Simulink® model. You can create instances of blocks from built-in Simulink libraries, and you can make custom libraries for instances of blocks that you create."

— Custom Libraries: Reusable libraries of blocks and subsystems
https://de.mathworks.com/help/simulink/libraries.html

Simulink libraries can be accessed through the Simulink Library browser.

Open Simulink Library Browser

The Simulink library browser provides an overview on all installed Simulink libraries as well as quick access to the specified blocks and subsystems.

Simulink Library Browser

To instantiate a block from a Simulink library, the block has to be dragged & dropped into a Simulink model.

EHANDBOOK supports rendering of blocks that originate from libraries.

For this to work properly, the following three configurations must be provided to EHANDBOOK Container-Build:

  1. The Simulink library files (typically .slx files) that contain the specification of the library blocks must be passed to EHANDBOOK Container-Build (or the Unified Graphics Generator). This is achieved by provided one or multiple paths to the location of the required libraries via the command-line option -simlib or -simlibfile. For further details, see Simulink library paths support.

  2. To render the graphics of the block appropriately, a connection to MATLAB is required (i.e., the option -nomatlab must not be used).

  3. For library blocks, it is often sufficient to show the block with its inputs, outputs and graphical rendition - but not with its inner details. In cases where library blocks are specified as subsystems, the inner details can be hidden. This is achieved specifiying a view configuration where inner details of referenced blocks are hidden.

Where to find Simulink library files

Simulink library files can typically found in the MATLAB installation path where the specific toolbox that provides the library is installed.

For example, for the standard Simulink library, this can typically be found under

C:\Program Files\MATLAB\R2021a\toolbox\simulink\blocks\library\simulink.slx
The path is different for the specific MATLAB release.

Referenced models

A model reference is a reference to another model using a Model block. These references create model hierarchy. Each referenced model has a defined interface that specifies the properties of its inputs and outputs. The defined interface makes the behavior of the referenced model independent of its context in the model hierarchy. (…​) Model references are ideal for code reuse, unit testing, parallel builds, and large components. They can also reduce file contention and merge issues.

— Model References: Reuse models as blocks in other models
https://de.mathworks.com/help/simulink/model-reference.html

EHANDBOOK supports resolving and including referenced models.

For this to work properly, the referenced models have to be provided along with the main model file to EHANDBOOK Container-Build.

To form an unambiguous unit, referenced model files must be zipped together with the main model file into a ZIP archive file. The ZIP archive file must have the same name as the main model file.

Example Simulink Model and Referenced Models as ZIP file
Figure 6. Example Simulink model with referenced models in a ZIP file (as expected by EHANDBOOK Container-Build)

Hiding contents of blocks from Simulink libraries

Simulink provides the possibility to create new, custom blocks and add them to the Simulink library browser (see Block Authoring and Simulation Integration).

There are various types of blocks based on which a custom block can be specified (e.g., based on an S-Function). One possibility is to specify the behavior of a custom block by means of a Simulink block diagram. In this case, the custom block to be used is a subsystem.

Per default, you can navigate subsystems or expand them in EHANDBOOK-NAVIGATOR.

Example EHB NAV no view
Figure 7. Example interactive model with library blocks

For blocks that originate from a library, it is possible to hide the inner contents.

This has various benefits:

  1. The Simulink-based interactive model is less complex (i.e., fewer model hierarchies)

  2. The know-how for how library blocks are specified is not exposed (know-how protection)

In order to hide the contents of library blocks, a view configuration has to be specified and passed to EHANDBOOK Container-Build via command-line options.

{
  "GlobalView": { (1)
    "HideContents": [ (2)
      {
        "BlockType": "Reference" (3)
      }
    ]
  }
}
1 Name of the view
2 Specification of what view type to apply
3 Criterion that view shall be applied to blocks of type reference

To pass the view configuration to EHANDBOOK Container-Build, the following CLI options have to be passed.

-simulinkview ".\configuration\SimulinkViewConfig.json" ^ (1)
-viewtype "GlobalView" ^ (2)
1 Provide path to Simulink view configuration file
2 Provide name for the Simulink view that shall be applied
Example Desired Result EHB NAV Screenshot1
Figure 8. Interactive model for Function.slx in EHANDBOOK-NAVIGATOR in same, default layout as in Simulink

Complete EHB-CB example

You can download a complete example using the following link:

set EHB_CB_PATH=C:\ETAS\EHANDBOOK-CB10.3 (1)
set MATLAB_PATH=C:\Program Files\MATLAB\R2021a (2)

%EHB_CB_PATH%\eHandbookCB.exe ^ (3)
-i ".\Input" ^ (4)
-o ".\Output" ^ (5)
-n "EHB_Demo_DirBased_SL_Libraries_with_matlab_with_view" ^ (6)
-simlib ".\simlibs,%MATLAB_PATH%\toolbox\simulink" ^ (7)
-simulinkview ".\configuration\SimulinkViewConfig.json" ^ (8)
-viewtype "GlobalView" ^ (9)
-gensvg (10)
1 Set path to EHANDBOOK Container-Build installation
2 Set path to MATLAB installation
3 Call EHANDBOOK Container-Build executable
4 Pass path for input data
5 Pass path for output (i.e., generated EHB Container)
6 Specify name for generated EHB Container file
7 Provide paths to directories with libraries for the Simulink models
8 Provide path to Simulink view configuration file
9 Provide name for the Simulink view that shall be applied
10 Option to generate embedded SVG graphics for the documentation text