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
-
the relevant backgrounds for how Simulink models are constructed, and
-
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.
Function.slx
in SimulinkExample blocks from Simulink library
The result we want to achieve in EHANDBOOK-NAVIGATOR looks as follows:
-
The contents of the referenced models are resolved and inlined into the interactive model in EHANDBOOK-NAVIGATOR.
-
The blocks drawn from the library are rendered with the same graphics as in Simulink.
-
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).
Function.slx
in EHANDBOOK-NAVIGATOR in same, default layout as in SimulinkFunction.slx
in EHANDBOOK-NAVIGATOR with expanded subsystemsBackground
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.
-
Simulink libraries
-
Referenced models
The following figure shows the conceptual differences between blocks from libraries (e.g., the standard Simuliunk block library) 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."
https://de.mathworks.com/help/simulink/libraries.html
Simulink libraries can be accessed through the 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.
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:
-
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. -
To render the graphics of the block appropriately, a connection to MATLAB is required (i.e., the option
-nomatlab
must not be used). -
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.
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.
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.
For blocks that originate from a library, it is possible to hide the inner contents.
This has various benefits:
-
The Simulink-based interactive model is less complex (i.e., fewer model hierarchies)
-
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 |
Function.slx
in EHANDBOOK-NAVIGATOR in same, default layout as in SimulinkComplete 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 |