Introduction

This user-guide describes the components require to integrate an FMU in RT-LAB:

• FMUConfGenerator : Generates configuration files from a given FMU archive (*.fmu file)

• URTMain : Runs the FMU.

• Orchestra Framework I/O interface : Makes connections between the FMU and the Simulink model.

This feature is available since RT-LAB 2021.3.

The tool can be found in the following folder/path:
<RT-LAB install-dir>/<RT-LAB version>/common/bin/FMUConfGenerator.exe

The next chapters present the following:

• Lists the functionalities of the configuration generator tool.

• Provides an overview of the configuration files generated.

• Explains how to use those files with RT-LAB and Simulink model.

• The last part presents step-by-step explanation of how to use the fmuloopback example with RT-LAB.

FMUConfGenerator Tool description

Tool command line Functionality

The FMUConfGenerator tool should be executed in the format shown below:
FMUConfGenerator.exe -f <Path_to_FMU_folder>\fmu_file_name.fmu
The tool is invoked from a command line using the following arguments:

Generated files overview

The FMUConfGenerator tool produces a set of configuration-files which are required by RT-LAB Orchestra Framework and URTMain tools that operate on the FMU archive file and helps in its integration.
All files are generated within a directory with the same name as the model. The model name is extracted directly from the modelDescription.xml contained within the FMU file. This directory is contained inside the folder under which the provided *.FMU file resides. If directory does not exist it is automatically created by the tool. So, the path of the directory created by the tool will be as follow:
<path_to_fmu_file>\<modelName>

The following 4 files are generated :

Using generated files in RT-LAB

The RT-LAB UI provides a File tab under the model properties window to include the files that are transferred to the target. Here we can add the generated files of the FMUConfGenerator tool. This Files tab is available under the Model Properties window in RT-LAB ui as shown below.

Open

Use the Delete button to remove the default files added in the list and then click on Add to see a dialog-box which allows to browse to the folder containing the generating file and then inserting them here in the list.

Open

Though the default file type used for the transfer is ascii, one can also specify binary type. Binary type should be specified for the FMULoopBack.fmu file which should also be included in the files to be transferred.

URTMain

URTMain is a process running on the target to execute the FMU file. It is connected to the Orchestra Framework of the model, based on its configuration file given in parameter.
Usually, the configuration files and the FMU are transferred with the model.
In order to launched the URTMain process on the target, it is necessary to configure "External executable" property of the OrchestraFramework - this topic is covered in the next section.

Orchestra Framework I/O interface

Prior to reading this section, it is advisable to get acquainted with Orchestra documentation.

Definition

I/O interface is used to integrate the FMU by establishing a connection between the Simulink model and the FMU's input/output signals.
It uses 2 main elements:

• The XML interface file generated with FMUConfGenerator (<fmu_file_name>.xml) for generating correct data points in the UI and connecting them to the Simulink model via OpDilInterface blocks.

• The domain name where data points of the FMU are present.

How to add to RT-LAB project

Add new I/O Interface named Orchestra Framework.

The Orchestra Framework properties window open up when we double-click on it in the Project-Explorer window. There we can add the <fmu_file_name>.XML interface file using the DDF Import button.

Once the XML interface is selected in the Import pop-up window then make sure to select the Domain name shown there (fetched from the selected XML file).

After a successful compilation of the model, be sure to assign the I/O interface to the Model's computation (or sm) subsystem from the Associated Subsystem drop-down menu. Once the model is loaded, then the correct XML file name and the domain defined within it should appear in the Orchestra Framework properties window.

Ultimately, in order to launch the URTMain process on the target, a proper command-line must be specified in the "External executable" property; this command-line should include the path to the urtmain executable on the given platform followed by '-j' parameter and then the urtmain configuration file, e.g. "/usr/opalrt/common/bin/urtmain -j urtmain_fmuloopback.json":

How to be connected to the Simulink model

In the modern versions of RT-LAB (2023.1) a Simulink model interacts with FMU by an OpDilInterface block:

Additional documentation on its usage can be found here.

OpDilInterface block requires minimal configuration using a json-file which is automatically generated when the configuration of Orchestra Framework is saved. This file is produced in the directory "<project_folder>\configurations\SyncExchangerRegistry\DriverConfigs" and has the following naming convention: "dib_configuration_for_<interface_name>.json".

This file must be specified in the configuration dialog of the OpDilInterface:

Please note, that an absolute path specified in the dialog following pressing "Select" button is automatically transformed in to a relative (to the model) path.

After configuring OpDilInterface it is important to ensure proper bus arrangement considering bus hierarchy (modern RT-LAB supports multiple bus layers in a model). Following facts might help in arranging the buses:

• bus_OrchestraFramework_in and bus_OrchestraFramework_out are the most adjacent to the OpDilInterface input and output buses respectively.

• ‘PUBLISH’ bus is in input tree.

• ‘SUBSCRIBE’ bus is in output tree.

• Output bus_OrchestraFramework_out bus contains a signal "Status" which carries out information about status of connection with FMU - a value '0' indicated a failure.

Additional note: the subsystem association step done after a successful compilation of the model hosting the OpDilInterface is optional when using this method.

FMULoopBack Example

Here we will use RT-LAB to create a sample project using an example model from the library of models provided within the RT-LAB package. That is a quick way to start integrating a FMU-file in a Simulink model instead of starting from scratch.

Creating RT-LAB Project

Launch the RT-LAB ui from its local installation folder on the host PC and create a new project. Go to the RT-LAB Project dialog box and use the Available Templates search box with keyword fmuloopback. The figure below shows the FMULoopBack co-simulation example with a brief explanation on the side.

Use this example to create a project and then assign the model to a target. Here we are using a target with Opal-RTLinux (x64) operating system. Compile/build the model. Make sure no Simulink windows for model editing is open. Once the model is built without errors, run the model. The output from the Scope object in the console subsystem is shown in the right-side figure above. This proves that we have a working model. Now Reset and unloaded the model.

Editing RT-LAB project

Here we will modify the project parameters in RT-LAB ui and include the files generated by the FMUConfGenerator tool. Execute the FMUConfGenerator tool with the FMU-file named FmuLoopBack.fmu (included with RT-LAB example model). For our example the syntax to use FMUConfGenerator will look as shown below:
<RT-LAB dir>/common/bin/FMUconfGenerator.exe -f <RT_LAB_Workspace_path>/<project_name>/Simulink/FmuLoopBack.fmu
This will give us the four files mentioned before, stored in a folder in the same location as the FMU-file. The folder path will be:
<RT_LAB_Workspace_path>/<project_name>/Simulink/fmuloopback
Include all these files for transfer using the Files tab of the Models properties window as shown in previous section. Make sure to change the FMU file type to binary from ascii.

Ultimately, adjust settings in OrchestraFramework I/O interface, including setting proper "External executable" property.

Editing the Model

FMULoopback example model comprises of two subsystems:

• sc_user_interface - interface subsystem where input signals are set and output signals are displayed.

• sm_master - computational subsystem which contains OpDilInterface that interacts with FMU on the target.

Now, in sm_master it is necessary to initialize OpDilInteface with a configuration file generated by the OrchestraFramework :

Then verify and/or edit bus arrangement ("Refresh data types" can be initially selected in order to update bus context):

After necessary preparations, Simulink model is supposed to be run locally, within Simulink:

After building, loading and executing the model in RT-LAB sc_user_interface should demonstrate correct values, including "Status" signal: