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

# Run a HIL Cyber-Physical Co-Simulation

## Introduction

A cyber-physical hardware-in-the-loop (HIL) co-simulation extends the <code class="expression">space.vars.Software</code> and EXata CPS setup to include **real external devices**. Instead of exchanging data only between simulated communication endpoints, network traffic can travel through the EXata CPS emulated network between the real-time model running on the OPAL-RT simulator and physical devices connected to the simulator.

EXata CPS continues to run in its dedicated network namespace on the simulator. Because this namespace has its own network stack, communication with an external device requires additional network configuration. In particular, EXata CPS must know the **IP address and MAC address** of **each external device** it needs to reach. The physical simulator interface connected to the external network must also be available within the EXata CPS namespace.

From the external device's perspective, EXata CPS remains transparent: the device communicates with the IP address assigned to the corresponding <code class="expression">space.vars.Software</code> communication endpoint, while EXata CPS emulates the network between them. This makes it possible to introduce network conditions and cyber events while exchanging real network traffic with physical hardware.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-35cd538bc6cf81a6b9a708b4cf1600ee7a517fc0%2Fexata-namespaces-ext-device.png?alt=media" alt=""><figcaption></figcaption></figure>

**Example:** A Raspberry Pi running a TCP client is connected to a physical Ethernet interface on the OPAL-RT simulator, while a TCP server runs in <code class="expression">space.vars.Software</code>. The client and server exchange data through the EXata CPS emulated network, allowing communication behavior and cyber events configured in EXata CPS to affect the data exchanged with the physical device.

## 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.
{% endstep %}

{% step %}

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

1. In the **HYPERSIM** tab, click **I/O Interface** in the **Sensors & I/Os** section to open the **I/O Interface Configuration** window.
2. Right‑click **EXata CPS Configurator** and select **Add**. Keep the default name or enter a custom one.
3. 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.
4. Enable **Add ARP Entry**, then enter the **IP address** and **MAC address** of the external device.
5. Repeat for each additional external device: click the **+** icon, select the appropriate **EXata Network Interface**, enable **Add ARP Entry**, and enter the device's **IP address** and **MAC address**.
6. Click **Ok** or **Apply** to save the configuration.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-0f360925d006f3d92750e70a789ecebea51b9548%2Fexata-hyp-arp-entry.png?alt=media" alt=""><figcaption></figcaption></figure>

**Example:** A Raspberry Pi running a TCP client is connected to the OPAL-RT simulator through the `eno2` Ethernet interface. The Raspberry Pi has IP address `10.10.1.102` and MAC address `3c:18:a0:d4:e4:d1`.
{% 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, `veth12`).
2. **Assign a unique local IP address** to the virtual interface. 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 is assigned a virtual Ethernet interface and IP addresses.

Server:

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

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-df3f33b8a21744565197e74caefdf36a1e6bfa97%2Fexata-hyp-server2.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

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

Execute the model to create the EXata namespace and virtual interfaces defined in the communication configuration. During execution, HYPERSIM also generates the configuration files required by EXata CPS, including `vethscript.sh` and a `.json` mapping file.

In the HYPERSIM 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://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-89b9830fb92f78f3cf642c4f0adc7e6ec24bc5b9%2Fexata-hyp-json.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://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-f1feb573fd25222eccb954321ca1aa80e89a30b5%2Fexata-wired-link-properties.png?alt=media" alt=""><figcaption></figcaption></figure>

4. Configure the node IP addresses:
   1. Right-click the node representing the **OPAL-RT device** and select **Properties**.
   2. Under **Interfaces > Network Layer**, set the IP address to match the local IP address of the corresponding virtual interface (`veth`) configured in <code class="expression">space.vars.Software</code>.
   3. For the node representing the **external device**, set the IP address under **Properties > Interfaces > Network Layer** to match the actual IP address of the external device.
   4. Repeat for each node in the scenario.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%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`, matching the local IP address assigned to the corresponding virtual interface in <code class="expression">space.vars.Software</code>.
* **TCP client node:** IP address `10.10.1.102`, matching the IP address of the Raspberry Pi.
  {% 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://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%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

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

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

2. For a node representing an **OPAL-RT device**, associate the EXata CPS node with the corresponding device defined in the JSON configuration.
3. For a node representing an **external device**:
   1. Set **IP Address Input Type** to **Custom** instead of **File**.
   2. In **OPAL-RT Device**, enter the IP address of the external device.
   3. In **Interface Name**, enter the simulator network interface to which the external device is connected, for example `eno2`.
4. Repeat until all required nodes are mapped.

**Example:** Map the OPAL-RT node using the device information from the JSON file. For a Raspberry Pi with IP address `10.10.1.102` connected through `eno2`, select **Custom**, enter `10.10.1.102` as the OPAL-RT device, and enter `eno2` as the interface name.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-e89185b49a5ca165cfc134a655f237b99dabad12%2Fexata-mapping-hil.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.
{% 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 %}

### Start the application on the external device

Once <code class="expression">space.vars.Software</code> and EXata CPS are running, verify that the external device can reach the corresponding <code class="expression">space.vars.Software</code> communication endpoint. Then start the application on the external device.
{% 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 the application on the external device.
2. Stop EXata CPS.
3. Wait until the emulation is fully stopped.
4. Reset the <code class="expression">space.vars.Software</code> model.

This completes the HIL 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/hypersim/model-and-simulation/cybersecurity-with-exata-cps/run-a-hil-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.
