> 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/orchestra-ddf-reference.md).

# Orchestra DDF Reference

## Introduction

The **Data Description File (DDF)** is an XML file that defines the communication contract between the RT-LAB Orchestra Framework and its External Components.

A DDF defines:

* domains;
* domain communication policies;
* connection settings;
* Publish and Subscribe sets; and
* the data items exchanged through each domain.

Data-item names, types, and lengths must match the interfaces implemented by the Framework and External Components.

## `<orchestra>`

The `<orchestra>` element is the root element of the DDF.

```
<orchestra>
    ...
</orchestra>
```

All domains participating in the same Orchestra configuration are defined within this element.

## `<domain>`

A `<domain>` defines a communication space between Orchestra participants. Each domain name must be unique within the `<orchestra>` root element.

Separate domains can be used for independent components or data exchanges requiring different communication or synchronization behavior. Orchestra training material also uses different domains for independent clients.&#x20;

```
<orchestra>

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

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

</orchestra>
```

## `<synchronous>`

Controls whether the domain operates synchronously or asynchronously.

### Synchronous

```
<synchronous>yes</synchronous>
```

Participating simulations coordinate their execution through the domain.

### Asynchronous

```
<synchronous>no</synchronous>
```

Participants exchange data without requiring synchronized progression for every exchange.

## `<states>`

Controls Orchestra's **Writer Access Priority** behavior. The setting uses `yes` or `no`. For example:

```
<states>no</states>
```

## `<multiplePublishAllowed>`

Controls whether more than one participant can publish to the same domain. The setting uses `yes` or `no`. For example:

```
<multiplePublishAllowed>yes</multiplePublishAllowed>
```

Multiple publishers are relevant to asynchronous domains using shared-memory communication where several clients participate in a domain.

For the common case of one External Component per domain, use:

```
<multiplePublishAllowed>no</multiplePublishAllowed>
```

{% hint style="danger" %}
**Important:** Synchronous operation does not support multiple publishers to the same domain.
{% endhint %}

## `<connection>`

Defines the communication mechanism used by a domain.

The element is placed inside `<domain>` before its Publish and Subscribe sets in current Orchestra examples.

### Local connection

Use a local connection when the Orchestra communication occurs locally:

```
<connection type="local" />
```

### Ethernet connection

When Orchestra external communication uses TCP or UDP, additional attributes can be added to the local connection.

For example:

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

<table data-search="false"><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody><tr><td><code>extcomm</code></td><td>Selects the external Ethernet communication protocol. Use <code>tcp</code> or <code>udp</code>.</td></tr><tr><td><code>addrframework</code></td><td>IP address of the RT-LAB target running the Framework.</td></tr><tr><td><code>portframework</code></td><td>Orchestra communication port on the Framework target. Must match the port configured on the target.</td></tr><tr><td><code>nicframework</code></td><td>Network interface used by the Framework-side communication process.</td></tr><tr><td><code>nicclient</code></td><td>Network interface used by the External Component-side communication process.</td></tr><tr><td><code>coreframework</code></td><td>CPU core assigned to the Framework-side external communication process.</td></tr><tr><td><code>coreclient</code></td><td>CPU core assigned to the External Component-side communication process.</td></tr></tbody></table>

## `<set>`

Each domain contains sets defining the direction of its data exchange.

The standard sets are "PUBLISH" and "SUBSCRIBE".

Direction is always defined from the **Framework's perspective**.

### `PUBLISH`

Contains data sent: **Framework → External Component**

For example:

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

### `SUBSCRIBE`

Contains data sent: **External Component → Framework**

For example:

```
<set name="SUBSCRIBE">
    <item name="Measurement">
        <type>float64</type>
        <length>1</length>
    </item>
</set>
```

## `<item>`

An `<item>` defines one named data item within a Publish or Subscribe set.

Keep data-item names consistent between:

* the DDF;
* the RT-LAB Framework; and
* the External Component.

Even small differences in data-item definitions can prevent correct data exchange.

### `<type>`

Defines the data type of an item. For example:

```
 <type>float64</type>
```

### `<length>`

Defines the number of values contained in a data item.

For a scalar:

```
<length>1</length>
```

For an array containing four elements:

```
<length>4</length>
```

The length defined in the DDF must match the corresponding signal dimensions in the participating models.&#x20;

### `<default>`

Defines the initial or fallback value for an eligible subscribed data item.

For example:

```
<item name="Setpoint">
    <type>double</type>
    <default>12.3e4</default>
</item>
```

`<default>` applies to data received by the Framework and therefore belongs to data items in the `SUBSCRIBE` set.

Do not use `<default>` for a `PUBLISH` item because the Framework provides the published value.

### `<description>`

Adds descriptive text to a data item.

For example:

```
<item name="Heading">
    <type>double</type>
    <description>Direction of travel</description>
</item>
```

The description is metadata. It does not change the exchanged value.

The DDF Configurator can store an item description in the DDF and display it again when the file is reopened.

Use descriptions when a signal name alone does not sufficiently explain its purpose.

## Complete example

The following example defines one synchronous local domain.

The Framework publishes a scalar control command and subscribes to an array of two measurements:

```
<?xml version="1.0" encoding="ISO-8859-1"?>

<orchestra>
    <domain name="CONTROL">

        <synchronous>yes</synchronous>
        <states>no</states>
        <multiplePublishAllowed>no</multiplePublishAllowed>

        <connection type="local" />

        <set name="PUBLISH">
            <item name="ControlCommand">
                <type>float64</type>
                <length>1</length>
                <description>Command sent to the external component</description>
            </item>
        </set>

        <set name="SUBSCRIBE">
            <item name="Measurements">
                <type>float64</type>
                <length>2</length>
                <description>Measurements received from the external component</description>
            </item>
        </set>

    </domain>
</orchestra>
```


---

# 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/orchestra-ddf-reference.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.
