Orchestra

RT-LAB Orchestra is an add-on that extends RT-LAB’s connectivity capabilities to heterogeneous co-simulations.

Heterogeneous co-simulations consist of simulations written in different programming languages, or generated by various simulation tools. Although Simulink provides some connectivity capabilities through the use of S-functions, the main advantage of using RT-LAB Orchestra is flexibility: co-simulation components can be developed and tested by different teams, then integrated to form a cohesive co-simulation system.

When using the RT-LAB Orchestra, RT-LAB is referred to as the Framework, and simulation components that exchange data with this Framework are referred to as External Components, also known as Clients. RT-LAB Orchestra provides a real-time, user-configurable communication layer that sits on top of the RT-LAB Framework.

In this context, RT-LAB becomes a backbone that provides a transport layer between simulation components.

Currently supported External Components are:

• C code applications
• standard (non-RT-LAB and RT-LAB) Simulink models
• standalone Dymola models

As a software application, RT-LAB Orchestra consists of the following entities:

• a configuration file used to specify the simulation data exchange between the Framework and External Components; the communication layer depends on the content of this configuration file
• a library of Simulink blocks, the rtlab_orchestra Simulink library, that provides interfaces between the Framework and External Components
• a C code application programming interface, the Orchestra RT-API, which is used by External Components to exchange simulation data with the Framework. Calls to the RT-API are embedded in an External Component where the data exchange takes place

Each of these entities is further described below.

Configuring the RT-LAB Orchestra Communication Layer

The RT-LAB Orchestra Data Description File

You configure the RT-LAB Orchestra communication layer by specifying the simulation data to be exchanged in an eXtended Markup Language (XML) file called a Data Description File (DDF). A DDF is decomposed into a 4-level hierarchy. Each level is further described in subsequent sections. The figure below shows the structure of a sample DDF.

The Orchestra Root Element

The <orchestra> element is at the top of a DDF. All the XML elements comprised between the opening and closing <orchestra> tags are part of the same co-simulation. Syntactically valid XML elements that are not explicitly required to configure RT-LAB Orchestra are ignored. Also, note that all XML tags and attributes in a DDF are in lower case.

Domain Elements

The next level down from the top element contains a list of <domain> elements. An RT-LAB Orchestra domain is a container for named data items exchanged between co-simulation components, also referred to in this context as domain participants. A domain is defined by the name attribute of its element. A domain name has to be unique inside the root element.

A <domain> element contains several Quality Of Services (QoS) attributes that define the connection policies followed by domain participants:

In the DDF, this attribute is controlled by the <hasStates> element. Note that some connection policies are not compatible: a connection with states has to be synchronous, and a synchronous connection doesn’t allow multiple publishers to the same domain. Incompatible connection policies are treated as errors by RT-LAB Orchestra.

In addition, the type of connection to a domain is specified using the <connection> element. Supported types are local and remote. For a local connection, the processes associated with the RT-LAB framework and the External Component are located on the same machine and they communicate through a shared memory segment.

For a remote connection, the processes associated with the RT-LAB framework and the External Component are located on different machines and they communicate through a reflective memory segment.

When specifying a remote connection, it is also necessary to provide information about the type of communication card that is used to connect an External Component to the Framework, as well as the PCI index (a positive integer) corresponding to where the card is inserted. This is done by using <card> element and <pciindex> elements respectively.

Data Sets

Each domain is required to contain both a Publish and a Subscribe set, possibly empty.

• The Publish set contains the list of data items written by the RT-LAB Framework to the communication layer, and therefore read by external domain participants.
• The Subscribe set contains the list of data items read from the communication layer by the RT-LAB Framework, and therefore published by an external component.
• It is important to note that the XML is generated from the framework view. 
• The Client can publish data that is described in the 'Subscribe set' or subscribe to data that are described in the 'Publish set'.

Data Items

Data items are the actual signals exchanged within a co-simulation. Data items are identified by a name attribute in a DDF. Item names have to be unique within a given domain.

Data items are further defined by a type and a length. The type corresponds to native types in the C programming language (such as double or int). The C-code char type is denoted by byte. The <length> element is used to represent data items that consist of arrays of native types. For example, a data item defined with the C-code int[4] corresponds to the DDF elements <type>int</type> and <length>4</length>

For documentation purposes, you can insert an optional <description> XML element inside an <item> element.

You can also assign a default value to data items in the Subscribe set. Valid formats for default values correspond to acceptable definitions for a C code double (e.g.: 1.2, +1e2, .E-2 etc.).

Note that it is an error to assign a default value to a data item that is part of the Publish set of a domain; this is because an Orchestra framework publishes all the data items of a Publish set at every time step, therefore default values would be overwritten before they can be read by a subscriber External Component.

Constraints on Element Names

The following constraints apply to domain and data item names:

• the names are case-sensitive,
• leading and trailing spaces are stripped, and the resulting stripped names are limited to 64 characters,
• the names have to consist of at least one non-space character.
• the names cannot contain a comma (,) or a pound sign (#).

The RT-LAB Orchestra CSV File

CSV stands for Comma Separated Values, a file format that is compatible with MS Excel. An Orchestra CSV file consists of a header followed by a body made up of rows of data.

The CSV Header

The header consists of 2 distinct and required elements, namely a Domain Descriptor and a Column List.

The Domain Descriptor provides a description of a DDF domain in the format of a pair of attribute/value pairs separated by :, namely following the format: domain attribute1=value1:attribute2=value2 etc.

The table below shows the list of defined attributes and the corresponding valid values.

The Column List is a list of named columns that RT-LAB Orchestra uses to map the data in the CSV file to the various DDF elements.

The Column List should contain the following columns:

domain, frameworkToClient, clientToFramework, type, length, default, description.

The columns can be provided in any order, but if the CSV file contains columns in addition to the Column List, then the entire Column List has to come first in the file. The domain names under the domain column must be defined in the domain descriptor.

The CSV Body

The CSV body contains a series of rows, one per data item. The content of each column of the data row is read and parsed based on the corresponding column of the Column List.

Each domain referred to in the CSV body has to appear in the Domain Descriptor. Data items for a given domain do not have to be contiguous; if a data row does not contain a domain name, the corresponding data item is assumed to belong to the domain that was last defined in the body.

Creating a CSV File

You can create a CSV file by editing a text file and saving it with the .csv extension, or by editing an Excel spreadsheet and saving it with the file type set to CSV.

DDF Configurator

RT-LAB Orchestra includes a graphical tool called the DDF Configurator that you can use instead of editing the XML file directly.

Launching the Orchestra DDF Configurator

The DDF Configurator can be launched as a standalone application or from a block of the RT-LAB Orchestra Simulink library.

Double click the file DDFConfig.jar located in <RT-LAB installation dir>\Common\bin to run the DDF Configurator. DDF Configurator is a Java application that requires a Java Runtime Environment to be installed. Refer to the section Environment Requirements for further detail.

Once you have created a DDF, you can use it to configure a block from the RT-LAB Orchestra Simulink library. To launch DDF Configurator from a Simulink block, open the RT-LAB Orchestra library - Click the block and select Configure.

Key Features

DDF Configurator allows you to:

• Create a DDF from scratch
• Import and update an existing DDF
• Import a Dymola configuration file and create a DDF from it
• Import data from a CSV file into DDF Configurator
• Save DDF data to a CSV file

Graphical Views

The DDF Configurator consists of two views separated by a movable divider, and of a toolbar located along the upper edge of the panel. The lefthand side view is called the Explorer View, while the righthand side view is called the Properties View. The Explorer View is a tree structure that displays the simulation data currently defined under the Orchestra root node. At the top of the Explorer View is the root node. The root node is a container for all the other data elements of a DDF, namely: domains, data sets, and item names. You can expand a tree node to view its content. The Properties

View displays the properties of the element currently selected in the Explorer View. There are 4 variants of the Properties View that correspond to the 4 level hierarchy of a DDF. The figure below shows a snapshot of the DDF Configurator with the data item Heading selected in the Explorer View and the corresponding Properties View.

Creating a Domain

A domain in the Explorer View consists of a Publish set and a Subscribe set. The Publish set, denoted FRAMEWORK-->CLIENT, contains the data items published (written) by the RT-LAB Framework to the Orchestra communication layer, whereas the Subscribe set, denoted CLIENT-->FRAMEWORK, contains\ the data subscribed from (read) from the Orchestra communication layer.

There are 2 ways to create a new domain:

• right-click the Orchestra root element in the Explorer View, this causes a pop-up menu to appear. Left-click the Add Domain of the pop-up menu, this causes a new domain element to be added to the Explorer View,
• select the Domain->Add New Domain item on the toolbar menu.

When created, a domain is automatically assigned the name new Domain#, where # represents a positive integer that increments sequentially, You can then choose to rename the domain. A newly created domain contains empty Publish and Subscribe sets.

Renaming a Domain

To rename a domain, select the domain in the Explorer View then double-click or press the F2 key. The Domain name becomes editable, enter the new Domain name and press the Enter key. If the domain name is not unique, an error message is displayed and the domain name is reverted to its previous value. Note that all leading and trailing spaces are stripped from the domain name.

Opening an Existing DDF

Select the File->Open item on the toolbar menu, this causes a dialog window to appear. Select the DDF you want to open and click the Open button on the dialog panel. The DDF is parsed (checked for correct syntax), and its content is displayed in the Explorer View. The title bar of the DDF Configurator displays the name of the file that you just opened. If the DDF could not be processed successfully, an error message is displayed and the opening process is aborted.

Creating a Data Item

Data items are created inside the Publish or the Subscribe set of a domain.

There are 2 ways to create a new data item:

• right-click either the Publish or the Subscribe set of a domain, this causes a pop-up menu to appear. Select the Add Item item on the pop-up menu,
• select either the Publish or the Subscribe set of a domain, then select the Item >Add New Item item on the toolbar menu.

The default data type for a new data item is double. Once an item has been created, you can add a description for it in the Properties View. This description will be saved inside a DDF so that it can be displayed again the next time the DDF is open. A newly created item is automatically assigned the name new Item#, where # represents a positive integer that increases sequentially.

Renaming a Data Item

Select the data item to rename, then double-click or press the F2 key. The data item name is editable, enter the new data item name and press the Enter key. If the new name doesn't match a name existing in the domain, the data item is renamed, otherwise, an error message is displayed and the data item name is changed back to its previous value. Note that all leading and trailing spaces are removed from the item name.

Adding a Text Description for a Data Item

To add a text description to a data item, select the item in the Explorer View, this will show the Properties View for the item. Enter a text description under the field entitled Description For Item [item name], then press Enter.

Adding a Default Value for a Data Item

To add a default value to a data item, select the item in the Explorer View, this will show the Properties View for the item. Enter a default value under the Default Value For Item [item name], then press Enter. The value is acceptable if the format is acceptable as a C code definition of a double-precision float.

Saving the Content of the Explorer View

If the Explorer View contains data read from an existing DDF, the current content of the Explorer View is saved to that same DDF by selecting the Save->File item on the toolbar menu. If no DDF has been opened, the current content of the Explorer View can be saved to either a new DDF or a new CSV file.

To do so, select the Save As menu item from the File menu, then choose the desired file format.

Importing an Existing DDF

Select File > Import on the toolbar menu, then choose the DDF item. A dialog allows you to pick the DDF. The DDF is opened and parsed, then it is added to the current Orchestra container. If the imported DDF contains a domain whose name matches another domain already present in the Explorer View, the imported domain is rejected and processing proceeds with the remaining domains of the DDF.

Importing a Dymola input file

Select the File->Import item on the toolbar menu, then choose the dsin.txt item. A dialog allows you to pick the Dymola input file. The file dsin.txt is opened and parsed, then its content is added to a default menu named dsinImportDomain#, where # represents a positive integer that increments sequentially until there is no name conflict with any already defined domain. The inputs to the Dymola model are inserted into the Publish set (namely the FRAMEWORK->CLIENT set), and the outputs generated by the Dymola model are inserted into the Subscribe set (namely the CLIENT→FRAMEWORK set).

Importing from a CSV File

To import a CSV file, Select the File > Import item on the toolbar menu, then choose the CSV File items.

Clearing the Explorer View

Select the File > Clear item on the toolbar menu to delete all the data contained inside the Orchestra root node.

Selecting a Domain and Data Items

When you launch the DDF Configurator from a Simulink block of the RT-LAB Orchestra library, not all the domains and data items present in the Explorer View will be mapped back to the block’s mask. Only one domain can be associated with a given block, and therefore you need to select that domain if there is more than one domain in the Explorer View. To select a specific domain, left-click it, and set the toggle button to yes. At any time, you can view which domain is currently selected by clicking the Orchestra root node, and checking the Selected Domain field of the corresponding Properties View.

Once a domain is selected, you can also choose to map only a subset of the data items to a block’s inports and outputs. By default, all data items created inside a data set are selected. To un-select a data item, click the item name in the Explorer View, this will display the Properties View for that item.

Then choose no under the Item [item name] Is Selected field on the Properties View. When DDF Configurator is launched as a standalone application, selecting a domain or selecting data items has no incidence on the generated DDF.

DDF Configurator Command Line Arguments

To launch the DDF Configurator from the command line, enter ddfConfig.jar or java -jar ddfConfig.jar. Either of these commands will show an empty DDF Configurator. The difference between these 2 commands is that the former version does not associate a console with the executable, therefore any error reporting will not appear on the screen. For this reason, it is always preferable to use the latter version of the command when launching DDF Configurator from the command line.

In addition, you can pass options to the DDF Configurator as command-line arguments.

The following command formats are supported:

• DDFConfig.jar -open sourceFile.[xml,csv,txt]: This command imports a DDF, CSV or Dymola input file and starts a DDF Configurator that shows the corresponding data.
• DDFConfig.jar -convert sourceFile.[xml,csv,txt] targetFile.[xml,csv]: This command imports a DDF, CSV or Dymola input file and converts it to either a DDF or a CSV file. Note that this command will not show the graphical interface.
  Again, to execute the DDF Configurator with a console you need to prepend java -jar to the above commands.

RT-LAB Orchestra Simulink Blocks

RT-LAB Orchestra blocks are connection endpoints of the Orchestra communication layer, they are used to bridge the Framework and External Components.

There are 2 types of blocks in the RT-LAB Orchestra Simulink library, namely Proxy blocks and External Components blocks. You insert Proxy blocks into a subsystem of an RT-LAB Framework, whereas External blocks are used from within an external Simulink model that you want to connect to an RT-LAB Framework. Refer to the Blocks reference on page 1 chapter of the RT-LAB library’s documentation for a detailed description of these blocks.

Setting up an RT-LAB Orchestra Co-Simulation

Using the Orchestra RT-API

Once you have defined the data items to be exchanged between an external component and the RT-LAB framework in a DDF, you need to embed calls to the Orchestra RT-API into the external component.

The Orchestra RT-API is a C code Application Programming Interface (API) that implements a data-centered communication mechanism between co-simulation components. This mechanism allows domain participants to exchange data by referring to it by name only.

Prior to exchanging data with the RT-LAB Framework, a connection to a domain must be established by calling the RTConnect() function of the Orchestra RT-API. Data items are published (sent to the RT-LAB Framework) and subscribed to (received from an RT-LAB Framework) by calling RTPublish() and RTSubscribe() respectively, referring to data items by name. The data exchange with a domain can be synchronous or asynchronous, as specified by the Synchronicity QoS defined in the DDF. For a synchronous connection, calls to RTPublish() and RTSubscribe() must be enclosed between calls to functions that provide a locking mechanism. Disconnection from a domain is achieved by calling RTDisconnect(). Disconnection can happen at any time after an external component has connected, without affecting the RT-LAB Framework.

Refer to chapter Functions reference on page 3 of the RTAPI Reference Guide for a description of the functions that are part of the Orchestra RT-API.

Integration of External C Code to an RT-LAB Model

This section details the steps required to connect some C code to an RT-LAB Framework

Add a C Proxy block to a subsystem of the Framework. Configure the block by double-clicking on it, which opens the DDF Configurator graphical tool. Specify a domain name and define a list of signals to be exchanged with the legacy C code. Select items in the Publish set (Framework-->Client) to send the corresponding signals to external domain participants. Reciprocally, select items in the Subscribe Set to receive data from external domain participants.

• Build and load the RT-LAB Framework like any other RT-LAB model.
• In the legacy C code, add calls to connect to the domain and publish/subscribe calls to send signals to the RT-LAB Framework and receive signals from it respectively.
• Compile and link the C code into a standalone process.

A C code sample is provided in the RT-LAB distribution under the directory <RT-LAB installation dir>\Examples\Features\Orchestra\C_Code\src.

Integration of an External Simulink Model to an RT-LAB Framework

• Add a Controller block anywhere inside the external Simulink model.
• Add Publish and Subscribe blocks where you want signals to be sent to and received from the RTLAB Framework.
• Build the model by using Simulink RTW.

A sample Simulink model that connects to an Orchestra co-simulation is provided in the RT-LAB distribution under the directory <RT-LAB installation dir>\Examples\Features\Orchestra\Simulink\src.

Integration of a Dymola Model to an RT-LAB Framework

This section details the steps required to connect a standalone Dymola application to an RT-LAB Framework.

• Translate the Dymola model you want to connect to an RT-LAB Framework. This will generate a dsmodel.c file, and a dsin.txt that contains the lists of inputs and outputs signals to the Dymola model.
• In a subsystem of the RT-LAB Framework, add a Dymola Proxy block. Configure the block by double-clicking on it, which will open the DDF Configurator graphical tool. Import the Dymola dsin.txt file and select the input and output signals.
• Add calls to the Orchestra RT-API in file StandAloneDymosim.c. Build an executable for the standalone Dymola model. 

Running an RT-LAB Orchestra Co-Simulation

This section describes how to set up the External Components you want to connect to an RT-LAB Framework. It is assumed that you have already built and loaded the Framework itself.

Transferring External Components Executables

Build an executable for each external component you want to connect to an RT-LAB Framework by following the steps listed above. Note that when setting up an RT-LAB Orchestra co-simulation, domain participants need to be co-located on the same processor. Specifically, the executable for an external component that connects to a given domain must reside on the same target node as the RT-LAB subsystem that contains the Proxy block for that domain. Open an FTP connection to a target node and copy the External Component’s executable. Run the executable by typing its name inside of a command window.

Orchestra Ethernet 

It is possible to use UDP or TCP to synchronize two simulations running on two different systems within the same network. In this section, we will first talk briefly about the architecture and then take a look at the XML configuration of the DDF file.

Orchestra Ethernet basic architecture knowledge

When using Orchestra Ethernet, an external communication process, also called tool, is launched. This tool is responsible to do the Ethernet communication and is synchronized with the Framework or the External Component with an Orchestra shared-memory.

To gain performance the tool can be migrated to a dedicated core. The next section describes how.

Orchestra Ethernet configuration  

Within the <connection> element the following attributes can be added to configure the UDP/TCP communication. The type attribute must be set to local i.e. <connection type="local"/>.

Example of configuration

An example of configuration is given below. The order of the attributes does not matter. 

<connection type="local" addrframework="192.168.3.16" extcomm="udp" nicframework="eth1" portframework="23423" coreframework="3" coreclient="3" />

In other words, the above means:

• The orchestra communication will be made by UDP.
• The framework will communicate through its network interface eth1 having the IP address 192.168.3.16 and using port 23423.
• The client will reach the framework at IP address 192.168.3.16 and port 23423 and its network interface will be chosen automatically (nicclient=auto by default).
• The tool of the client and the tool of the framework responsible for the Ethernet communication will run on core 3.

External communication process logs

For debugging purposes, it is possible to retrieve the external communication process logs. To get those logs into the RT-LAB Display, the Target display information must be set in Exhaustive and XHP mode must be disabled.

Orchestra Dolphin 

It is possible to use a Dolphin PX or IX PCIe adapter to synchronize two simulations running on two different systems within the same network. In this section, we will first talk briefly about the architecture and then take a look at the XML configuration of the DDF file.

Orchestra Dolphin configuration  

Within the <connection> element the following attributes can be added to configure the Dolphin communication. The type attribute must be set to local i.e. <connection type="dolphin"/>.

Additional elements inside the <connection> element must be added:

Example of configuration

An example of configuration is given below. The order of the inner elements does not matter. 

<connection type="dolphin">
  <nodeIdFramework>4</nodeIdFramework>
  <segmentId>13</segmentId>
</connection>

In the above example, Orchestra communication will occur through the Dolphin network. The framework node identified in the Dolphin network as <nodeIdFramework> and the orchestra domain is attached to <segmentId> on the framework side.

Environment Requirements

RT-LAB Orchestra is supported on the same platforms as RT-LAB.

To run the DDF Configurator as a standalone application, you need a Java J2SE Runtime Environment  5.0 or later (JRE) installed on your machine. The JRE can be downloaded free of charge from Sun’s website (http://java.sun.com). To run the DDF Configurator from a Simulink block and load the model in RT-LAB, you need to use a version of MATLAB that is compatible with the version of RT-LAB you are using.