> 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/cybersecurity-with-exata-cps/run-a-cyber-physical-co-simulation.md).

# Run a Cyber-Physical Co-Simulation

## Introduction

In a cyber-physical co-simulation, the physical system simulated by <code class="expression">space.vars.Software</code> and the communication network emulated by EXata CPS run together on the same OPAL-RT simulator. The two environments are isolated using Linux network namespaces: <code class="expression">space.vars.Software</code> runs in the default namespace, while EXata CPS runs in the dedicated `ns_exata` namespace.

<code class="expression">space.vars.Software</code> automatically creates virtual Ethernet interfaces (`veth`) that connect communication endpoints in the <code class="expression">space.vars.Software</code> model to the corresponding nodes in EXata CPS. Network traffic exchanged by the model is therefore routed through the EXata CPS network rather than directly between endpoints, allowing the network behavior configured in EXata CPS to affect communications in the real-time simulation.

As illustrated below, the simulator also uses separate physical network interfaces for different purposes. In this example, `eno1` is the simulator network interface connected to the Windows workstation, while `eno2` is the network interface associated with the EXata CPS simulator license and is moved to the `ns_exata` namespace.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-3481e5a7ffaec39ad69ab640d603c29d9ba0bc5b%2Fexata-namespaces.png?alt=media" alt=""><figcaption></figcaption></figure>

In the example, a TCP server and TCP client run in <code class="expression">space.vars.Software</code> and communicate through virtual interfaces and the EXata CPS network. The same architecture can be used with other supported communication protocols and more complex network topologies.

## Procedure

{% stepper %}
{% step %}

### Create and validate the <code class="expression">space.vars.Software</code> model

Create the <code class="expression">space.vars.Software</code> model that will exchange data through the communication network. The communication endpoints can use any protocol supported by the <code class="expression">space.vars.Software</code> model and the selected communication driver.

Before introducing EXata CPS, verify that the RT-LAB model behaves as expected.

**Example**: A model containing a TCP server and a TCP client that exchange signals bidirectionally.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-8815318063437f1448b838fc0ba8225719e78161%2Fexata-rtlab-model-example.png?alt=media" alt=""><figcaption></figcaption></figure>

The transmitted sine-wave signals are associated with the TCP interface transmit channels, while received TCP data is routed back into the model.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-8cb9bf596f2bfdcd95861fed6e9671979ef809ee%2Fexta-rtlab-transmit-example.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-7149727a6bc45c8e9d49aa3df83a7f5a2771296f%2Fexata-rtlab-streams-example.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Add an EXata CPS configurator I/O interface

1. In RT-LAB Project Explorer, right-click **I/O Interfaces**, select **New I/O Interface**, and choose **EXata CPS Configurator**. Double-click the newly created interface to begin configuration.
2. Click the **+** icon to add an EXata CPS interface. In the **EXata Network Interface** field, enter the name of the network adapter associated with the EXata CPS license (for example, `eno2`). Refer to the **System Description Document** provided with the simulator to identify the correct network adapter.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-7ea97d36689a42ea9246b79e15d750db583f44f7%2Fexata-rtlab-configuration.png?alt=media" alt=""><figcaption></figcaption></figure>

3. No other settings need to be modified. Save the configuration.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-8925c376b1572421281e4ea6a016ebb6dbad87c4%2Fexata-rtlab-save-configuration.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Route communications through EXata CPS

To use EXata CPS, configure the communication protocol I/O interface to exchange data through the EXata CPS emulated network instead of a direct connection.

For each communication endpoint:

1. **Assign a virtual Ethernet interface.** Replace the direct network interface with a unique interface name beginning with `veth`, followed by a number (for example, `veth11`).
2. **Assign a unique local IP address** to the virtual interface. The address must be on the same subnet as the network interface associated with the EXata CPS simulator license, but must be unique. Do not use an address in the `10.10.10.xxx` range.
3. **Specify the destination IP address**, when required by the protocol. For endpoints that initiate a connection, set the remote IP address to the local IP address of the destination endpoint.

**Example**: The TCP server and client previously using `lo` are assigned separate virtual Ethernet interfaces and IP addresses.

Server:

* NIC name: `veth12`
* Local IP address: `10.10.1.33`

Client:

* NIC name: `veth11`
* Local IP address: `10.10.1.45`
* Remote IP address: `10.10.1.33`

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-24966c8a08d282f929ebdbf25bdec48c7aea0bc9%2Fexata-rtlab-modifications-example.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Start the <code class="expression">space.vars.Software</code> simulation

Load and execute the model to create the EXata namespace and virtual interfaces defined in the communication configuration. During load, RT-LAB also generates the configuration files required by EXata CPS, including `vethscript.sh` and a `.json` mapping file.

In the RT-LAB console, locate the **successfully updated EXata configuration** message and note the configuration folder path. The generated `.json` file will be used later to configure the EXata CPS scenario.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-1ee253631ea31ad7050b0c9646aafc93aaae5bd4%2Fexata-rtlab-files.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Create an EXata CPS Scenario

1. Open or create a network scenario in the **EXata CPS GUI**. The scenario should represent the communication network connecting the simulated devices.
2. Add the required nodes and connect them according to the desired network topology.
3. Configure the network subnet:
   1. Right-click the wired link and select **Properties**.
   2. Select **Network Protocol**.
   3. Set the subnet to match the network used by the <code class="expression">space.vars.Software</code> virtual interfaces.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-f1feb573fd25222eccb954321ca1aa80e89a30b5%2Fexata-wired-link-properties.png?alt=media" alt=""><figcaption></figcaption></figure>

4. Configure the node IP addresses:
   1. Right-click a node and select **Properties**.
   2. Under the **Interfaces** tab, select **Network Layer**.
   3. Set the IP address to match the local IP address assigned to the corresponding virtual interface in <code class="expression">space.vars.Software</code>.
   4. Repeat for each node.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-4a0df8e4a593a0337bb05b6fb2bd4015dc16cd0c%2Fexata-node-properties.png?alt=media" alt=""><figcaption></figcaption></figure>

**Example**: Create two EXata CPS nodes on the `10.10.1.0` subnet and connect them directly:

* **TCP server node:** IP address `10.10.1.33`
* **TCP client node:** IP address `10.10.1.45`
  {% endstep %}

{% step %}

### Add the JSON to the EXata CPS scenario

Configure the EXata CPS scenario to use the JSON configuration file generated by <code class="expression">space.vars.Software</code>.

1. Copy the generated `.json` file to the same directory as the EXata CPS network model.
2. In the EXata CPS **Scenario Properties**, navigate to **CPS Settings** and specify the generated JSON file.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-1057e29bd17617f3f6508430b2981bd6040f2cef%2Fexata-cps-settings.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Map the EXata CPS nodes to the <code class="expression">space.vars.Software</code> devices

Open the EXata CPS mapping configuration and click the **+** icon to create the required mappings.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-9484d009e8f1f71134b5a9f26e33387ae247fe4a%2Fexata-mapping-button.png?alt=media" alt=""><figcaption></figcaption></figure>

For each endpoint, associate the EXata CPS network node with the corresponding OPAL-RT device defined in the JSON configuration.

**Example:** Map **EXata Node** `10.10.1.33` to **OPAL-RT device** `TCPUDP veth12:10.10.1.33`, and **EXata Node** `10.10.1.45` to **OPAL-RT device** `TCPUDP veth11:10.10.1.45`.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-e97045dcd9b483fe9b67a2fd2128165b8e468800%2Fexata-mapping-example.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Start the EXata CPS Emulation

{% hint style="danger" %}
Always start the <code class="expression">space.vars.Software</code> simulation before starting the EXata CPS emulation. Before starting EXata CPS, open **Run Settings** and, under **Execution Mode**, make sure **Standalone Execution** is unchecked.
{% endhint %}

In the EXata CPS GUI, click **Run Emulation**.

Once the scenario has loaded, verify that the EXata CPS nodes are connected to their corresponding virtual interfaces. Then start the scenario execution.
{% endstep %}

{% step %}

### Validate communication

Validate that communication is flowing correctly through EXata CPS using <code class="expression">space.vars.Software</code> probes, EXata CPS animations, communication statistics, signal values, and other available diagnostics.
{% endstep %}

{% step %}

### Perform network experiments

Once communication is operational, use the EXata CPS GUI to introduce network events such as device and link failures, packet loss, latency, congestion, and cyber-attacks, and evaluate their impact on system behavior.
{% endstep %}

{% step %}

### Stop the co-simulation

Shut down the simulation in the reverse order:

1. Stop EXata CPS.
2. Wait until the emulation is fully stopped.
3. Reset the <code class="expression">space.vars.Software</code> model.

This completes the cyber-physical co-simulation workflow.
{% 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/cybersecurity-with-exata-cps/run-a-cyber-physical-co-simulation.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.
