> 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/connect-a-c-c++-application-with-orchestra.md).

# Connect a C/C++ Application with Orchestra

## Introduction

Use the Orchestra RT-API when an External Component is implemented as a native application rather than as a Simulink model.

The Orchestra RT-API is a C API implementing Orchestra's data-centered communication mechanism. Applications exchange data by referencing domain items by name.

## Procedure

{% stepper %}
{% step %}

### Configure the Orchestra Framework

In the RT-LAB Framework model:

1. Add the [**Orchestra Proxy C**](https://www.opal-rt.com/docs/rt-lab/simulink-blocks-reference/rt-lab-library/orchestra_proxy_c.md) block.
2. Configure the Orchestra domain.
3. Define the `PUBLISH` and `SUBSCRIBE` data items in the DDF.
4. Configure the connection used by the External Component.

The DDF defines the communication contract between the Framework and C/C++ application, including the domain, signal names, types, lengths, and directions.
{% endstep %}

{% step %}

### Configure the External Component environment

Make the Orchestra runtime and development files available to the C/C++ application.

For an OPAL-RTLinux External Component, these include:

* `RTAPI.h`, which provides the C API declarations;
* `libOpalOrchestra.so`, which provides the Orchestra shared library; and
* the required Orchestra runtime components.

These resources are found typically under `/usr/opalrt/exportedOrchestra/`.&#x20;

{% hint style="info" %}
The exact runtime requirements depend on the operating system and deployment. Current Windows Orchestra clients still depend on an RT-LAB installation on the same computer.
{% endhint %}
{% endstep %}

{% step %}

### Integrate the RT-API

Include the Orchestra RT-API in the application and implement the connection lifecycle:

1. Connect to the domain.
2. Exchange data.
3. Perform the application processing.
4. Disconnect when communication is no longer required.
   {% endstep %}

{% step %}

### Connect to the domain

Use:

`RTConnect()`

to connect the application to the Orchestra domain configured in the DDF.

The Framework and application must use the same domain and compatible data definitions.
{% endstep %}

{% step %}

### Exchange data

Use:

`RTPublish()`

to send data from the External Component to the Orchestra Framework.

Use:

`RTSubscribe()`

to retrieve data published by the Framework.

This direction may initially look confusing because the API calls are named from the **External Component's perspective**, while the DDF `PUBLISH` and `SUBSCRIBE` sets are defined from the **Framework's perspective**.

Therefore:

| C/C++ External Component | DDF set     | Direction                      |
| ------------------------ | ----------- | ------------------------------ |
| `RTPublish()`            | `SUBSCRIBE` | External Component → Framework |
| `RTSubscribe()`          | `PUBLISH`   | Framework → External Component |

For synchronous domains, use the RT-API synchronization/locking mechanism around the required Publish and Subscribe operations.
{% endstep %}

{% step %}

### Compile and link the application

Compile the C/C++ application with the Orchestra headers and link it with the Orchestra library.

For the current OPAL-RTLinux runtime layout, the relevant resources include `RTAPI.h` under the `include` directory and `libOpalOrchestra.so` under the `lib` directory of `/usr/opalrt/exportedOrchestra/`.&#x20;

A C/C++ application should not be deployed independently of its DDF and compatible Orchestra runtime. Current OPAL-RT integration guidance recommends keeping the runtime/package, application or plugin, and DDF versions aligned.
{% endstep %}

{% step %}

### Build and start the Framework

Build and load the RT-LAB Framework.

**Start the Framework before starting the External Component.**

This ordering is important because the External Component subsequently uses `RTConnect()` to join the domain provided by the Framework.
{% endstep %}

{% step %}

### Start the External Component

Start the compiled C/C++ application.

The application can now:

1. call `RTConnect()`;
2. exchange data using `RTPublish()` and `RTSubscribe()`;
3. perform its application calculations; and
4. repeat the data exchange as required.

A typical application loop is conceptually:

```
RTConnect()

while application is running:
    RTSubscribe()
    application processing
    RTPublish()

RTDisconnect()
```

{% endstep %}

{% step %}

### Disconnect

When the External Component no longer needs to communicate with the Framework, use:

`RTDisconnect()`

to disconnect it from the Orchestra domain.
{% endstep %}
{% endstepper %}


---

# 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/connect-a-c-c++-application-with-orchestra.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.
