> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/rt-lab/model-and-simulation/co-simulation/co-simulation-with-orchestra/configure-orchestra-data-exchange.md).

# Configure Orchestra Data Exchange

## Introduction

Create a Data Description File (DDF) in `.xml` format to define the interface between the RT-LAB Framework and its External Components.

For a description of the DDF structure, elements, and settings, refer to [Orchestra DDF Reference](https://www.opal-rt.com/docs/rt-lab/model-and-simulation/co-simulation/co-simulation-with-orchestra/configure-orchestra-data-exchange/orchestra-ddf-reference.md).

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2FwwYnFM3B7YEVP3FsUQAb%2Fimage.png?alt=media&amp;token=b67af8b6-12f7-4057-be44-6d11f920bfc2" alt=""><figcaption></figcaption></figure>

## Procedure

{% stepper %}
{% step %}

### Identify the data to exchange

For each data item, define its **name, direction, type, length, domain, exchange rate, and synchronization requirements**. Use the same definitions consistently in the DDF, Framework, and External Component.
{% endstep %}

{% step %}

### Add the Orchestra root element

Create an `.xml` file and add the `<orchestra>` opening and closing tags. All elements between these tags belong to the same co-simulation.

For example:

<pre><code><strong>&#x3C;orchestra>
</strong>        ...
&#x3C;/orchestra>
</code></pre>

{% endstep %}

{% step %}

### Create the domains

Group related data exchanges into domains using `<domain name="DOMAIN_NAME">` and `</domain>`. Each domain must have a unique name within the DDF.

Use separate domains when components **operate independently, require different synchronization settings or exchange rates, or need separate namespaces**.

For example:

```
<orchestra>
    <domain name="CONTROL">
        ...
    </domain>

    <domain name="MONITORING">
        ...
    </domain>
</orchestra>
```

{% endstep %}

{% step %}

### Select the synchronization mode

Configure each domain as:

* **Synchronous**, to coordinate execution between the participating simulations. Use `<synchronous>yes</synchronous>`.
* **Asynchronous**, to exchange data without requiring participants to progress together for every exchange. Use `<synchronous>no</synchronous>`.

For example:

```
<orchestra>
    <domain name="DOMAIN_1">
        <synchronous>yes</synchronous>
        ...
    </domain>

    <domain name="DOMAIN_2">
        <synchronous>no</synchronous>
        ...
    </domain>
</orchestra>
```

{% hint style="danger" %}
Some domain policies cannot be combined. A connection using states must be synchronous, while synchronous operation does not support multiple publishers to the same domain. Orchestra reports incompatible policies as configuration errors.
{% endhint %}
{% endstep %}

{% step %}

### Define the Publish set

Add all data sent from the **RT-LAB Framework → External Component** to the `PUBLISH` set.

In this example, `ControlCommand` is sent by the Framework:

```
<set name="PUBLISH">
    <item name="ControlCommand">
        <type>float64</type>
        <length>1</length>
    </item>
</set>
```

{% endstep %}

{% step %}

### Define the Subscribe set

Add all data sent from the **External Component → RT-LAB Framework** to the `SUBSCRIBE` set.

In this example, `Measurements` contains two values returned to the Framework:

```
<set name="SUBSCRIBE">
    <item name="Measurements">
        <type>float64</type>
        <length>2</length>
    </item>
</set>
```

{% hint style="info" %}
**Remember:** Publish and Subscribe are named from the **Framework's perspective**.
{% endhint %}
{% endstep %}

{% step %}

### Define each data item

For each data item, specify:

* `name`
* `type`
* `length`

Orchestra uses native C-style types. The legacy reference explicitly identifies types such as `double`, `int`, and `byte`, with `length` used for arrays. For example, a four-element integer array is represented as type `int` with length `4`.&#x20;
{% endstep %}

{% step %}

### Select the connection

Configure the connection according to where the Framework and External Component execute:

* **Shared memory** for local communication.
* **Ethernet** for TCP or UDP communication between systems.
* **Dolphin** for compatible systems connected through Dolphin.
* **Reflective memory** for supported legacy remote configurations.

For example, an Ethernet connection using TCP can be defined as:

```
<connection
    type="local"
    extcomm="tcp"
    addrframework="192.168.1.10"
    portframework="23425"
    nicframework="auto"
    nicclient="auto"
/>
```

{% endstep %}

{% step %}

### Save the DDF

Save the configuration as an XML DDF.
{% endstep %}
{% endstepper %}

## Use a CSV file to define DDF data

As an alternative to editing all DDF data directly in XML, you can define Orchestra domains and data items in a CSV file. The CSV format is compatible with spreadsheet applications such as Excel and can be imported into the **DDF Configurator** to create or update the DDF.

You can also export DDF data from the DDF Configurator to a CSV file for easier bulk editing.

For details, refer to [Orchestra CSV File](https://www.opal-rt.com/docs/rt-lab/model-and-simulation/co-simulation/co-simulation-with-orchestra/configure-orchestra-data-exchange/orchestra-csv-file.md).

### Use the DDF configurator

As an alternative to editing the DDF directly in XML, use the **DDF Configurator** to graphically create and configure Orchestra domains, Publish and Subscribe sets, and data items.

You can also use the DDF Configurator to **open and modify existing DDFs, import configuration data from DDF or CSV files, and save the resulting configuration as a DDF or CSV file**.

For details, refer to [DDF Configurator](https://www.opal-rt.com/docs/rt-lab/model-and-simulation/co-simulation/co-simulation-with-orchestra/configure-orchestra-data-exchange/ddf-configurator.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/rt-lab/model-and-simulation/co-simulation/co-simulation-with-orchestra/configure-orchestra-data-exchange.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
