> 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/configure-ios/communication-protocol-ios/tcp-and-udp/configure-tcp-udp.md).

# Configure TCP-UDP

When working with communication protocols, it is recommended to begin by configuring the protocol through the **I/O Interfaces** section in <code class="expression">space.vars.Software</code> before proceeding with other steps.

## Configure the TCP-UDP I/O interface

{% stepper %}
{% step %}

### Add a new 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.

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

2. Right‑click **TCP-UDP** and select **Add**. Keep the default name or enter a custom one. If multiple **TCP-UDP** are added, each one must have a unique name.

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

{% step %}

### Configure the general settings

Click the newly added **TCP-UDP** in the **I/O Interface Configuration** window and configure the general settings.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-4de3f3b9d54fca9a55e8e4f09480776996fbc883%2FDR-hyp-tcp-gen.png?alt=media" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="165">Parameter</th><th>Value (Description)</th></tr></thead><tbody><tr><td><strong>Use an RT core for asynchronous computation</strong></td><td><strong>Checked:</strong> The driver reserves a dedicated real‑time CPU core for its communication tasks.<br><strong>Unchecked:</strong> The communication system runs on core 0 alongside the operating system.</td></tr><tr><td><strong>Enable verbose mode</strong></td><td><strong>Checked:</strong> Displays the full configuration during model loading for debugging.<br><strong>Unchecked:</strong> Only standard log messages are shown.</td></tr><tr><td><strong>Data frame adjustments</strong></td><td>Controls how the data frame is automatically adjusted when a signal is added or removed, or when the vector size, byte offset, bit offset, size in bits, or signal type changes.<br><strong>None</strong>: No automatic adjustments are performed.<br><strong>Ensure no overlap</strong>: Signal overlaps are automatically corrected; gaps between signals are allowed.<br><strong>Ensure contiguous</strong>: Signal overlaps are automatically corrected and all gaps between signals are removed to maintain a contiguous frame.<br><br>When corrections are applied, all signals affected by the changes are shifted by the appropriate number of bits to maintain consistency. Signals using <strong>Float</strong> and <strong>Double</strong> data types must be byte-aligned. As a result, they are automatically moved to the nearest valid byte-aligned position whenever adjustments occur.</td></tr><tr><td><strong>Enable virtual mode</strong></td><td><strong>Checked:</strong> Allows the model to execute even if the I/O interface does not match the hardware configuration. All connections are initialized, but the interface performs no communication. Useful for troubleshooting without hardware or preparing models for future systems.<br><strong>Unchecked:</strong> The interface operates normally and requires compatible hardware.</td></tr></tbody></table>
{% endstep %}

{% step %}

### Manage streams: add, remove, rename, or reorder

Click **Streams** and use:

* **+** icon to add streams
* **–** icon to remove streams
* **Arrow** icons to reorder streams

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

{% step %}

### Configure the stream(s) settings

Click a stream under the **Streams** folder to configure its settings. Repeat this step for each additional stream.

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

{% tabs %}
{% tab title="TCP mode" %}

<table><thead><tr><th width="145">Parameter</th><th>Value (Description)</th></tr></thead><tbody><tr><td><strong>Protocol</strong></td><td><strong>TCP:</strong> Data is exchanged over TCP.</td></tr><tr><td><strong>TCP mode</strong></td><td><strong>Server:</strong> The stream endpoint acts as a TCP server.<br><strong>Client:</strong> The stream endpoint acts as a TCP client.</td></tr><tr><td><strong>TCP port</strong></td><td>TCP port used for stream communication. Default: <strong>23000</strong>.</td></tr><tr><td><strong>NIC name</strong></td><td>Network interface name. Select the correct interface based on your <strong>System Description Document</strong> or Linux <code>ifconfig</code> command. For local testing on the same simulator, use the loopback interface <strong>lo</strong>.</td></tr><tr><td><strong>Local IP address</strong></td><td>IP address of the local TCP endpoint. The keyword <strong>auto</strong> may be used to automatically select the IP address of the first available network interface. For local testing on the same simulator, use <strong>127.0.0.1</strong>.</td></tr><tr><td><strong>NIC speed</strong></td><td>Desired network interface speed. Ignored when running on Windows.<br>Available options:<br>• <strong>Default</strong>: Do not change interface speed<br>• <strong>ForceAuto</strong>: Enable auto-negotiation<br>• <strong>Force10</strong>: 10 Mbps<br>• <strong>Force100</strong> : 100 Mbps<br>• <strong>Force1000</strong>: 1 Gbps<br>• <strong>Force10000</strong>: 10 Gbps</td></tr><tr><td><strong>Decimation factor</strong></td><td>Number of simulation time steps between transmission triggers. A value of <code>1</code> triggers transmission at every time step.</td></tr><tr><td><strong>Enable transmission control</strong></td><td><strong>Checked:</strong> Exposes the <strong>Transmission enable</strong> connectable point. This connectable point allows to enable or disable transmission directly <strong>from the model</strong> during execution.<br><strong>Unchecked:</strong> Transmission is always enabled.</td></tr><tr><td><strong>Enable reception control</strong></td><td><strong>Checked:</strong> Exposes the <strong>Reception Enable</strong> connectable point. This connectable point allows to enable or disable reception directly <strong>from the model</strong> during execution.<br><strong>Unchecked:</strong> Reception is always enabled.</td></tr><tr><td><strong>Swap byte order</strong></td><td><strong>Checked:</strong> Swaps the native byte order when transmitting data.<br><strong>Unchecked:</strong> Keeps the native byte order.</td></tr><tr><td><strong>Use sequential bit ordering for custom data</strong></td><td><strong>Checked:</strong> Reorders bits within each custom data frame from Most Significant Bit (MSB) to Least Significant Bit (LSB), regardless of machine endianness. Bytes within messages are serialized MSB-first, and messages with smaller bit offsets are serialized first.<br><strong>Example:</strong><br>Message 0 (bit offset 0, value <code>0x1</code>) and Message 1 (bit offset 4, value <code>0xABCDEF0</code>) are serialized as <code>0x1A BC DE F0</code>, instead of the traditional little-endian layout <code>0xF0 DE BC 1A</code>.<br><strong>Unchecked:</strong> Keeps the native bit and byte ordering. Bits and bytes are serialized according to the machine endianness.</td></tr><tr><td><strong>Use VLAN</strong></td><td><p><strong>Checked:</strong> Creates a VLAN interface based on the selected NIC. The following additional VLAN parameters must be configured:</p><ul><li><strong>VLAN index:</strong> Unique VLAN identifier. Each stream must use a distinct index.</li><li><strong>VLAN address:</strong> IP address assigned to the VLAN interface.</li></ul><p><strong>Unchecked:</strong> No VLAN interface is created. The stream uses the selected NIC directly.</p></td></tr></tbody></table>
{% endtab %}

{% tab title="UDP mode" %}

<table><thead><tr><th width="145">Parameter</th><th>Value (Description)</th></tr></thead><tbody><tr><td><strong>Protocol</strong></td><td><strong>UDP:</strong> Data is exchanged over UDP.</td></tr><tr><td><strong>UDP local port</strong></td><td>Local UDP port on which the endpoint receives data. Default: <strong>23001</strong>.</td></tr><tr><td><strong>UDP remote port</strong></td><td>Remote UDP port to which the endpoint sends data. Default: <strong>23002</strong>.</td></tr><tr><td><strong>NIC name</strong></td><td>Network interface name. Select the correct interface based on your <strong>System Description Document</strong> or Linux <code>ifconfig</code> command. For local testing on the same simulator, use the loopback interface <strong>lo</strong>.</td></tr><tr><td><strong>Local IP address</strong></td><td>IP address of the local UDP endpoint. The keyword <strong>auto</strong> may be used to automatically select the IP address of the first available network interface. For local testing on the same simulator, use <strong>127.0.0.1</strong>.</td></tr><tr><td><strong>NIC speed</strong></td><td>Desired network interface speed. Ignored when running on Windows.<br>Available options:<br>• <strong>Default</strong>: Do not change interface speed<br>• <strong>ForceAuto</strong>: Enable auto-negotiation<br>• <strong>Force10</strong>: 10 Mbps<br>• <strong>Force100</strong> : 100 Mbps<br>• <strong>Force1000</strong>: 1 Gbps<br>• <strong>Force10000</strong>: 10 Gbps</td></tr><tr><td><strong>Remote IP address</strong></td><td>IP address of the remote TCP/UDP endpoint.<br><br><em>Visible only when <strong>TCP Server</strong> or <strong>Protocol = UDP</strong></em></td></tr><tr><td><strong>Decimation factor</strong></td><td>Number of simulation time steps between transmission triggers. A value of <code>1</code> triggers transmission at every time step.</td></tr><tr><td><strong>Enable transmission control</strong></td><td><strong>Checked:</strong> Exposes the <strong>Transmission enable</strong> connectable point. This connectable point allows to enable or disable transmission directly <strong>from the model</strong> during execution:<br><strong>Unchecked:</strong> Transmission is always enabled.</td></tr><tr><td><strong>Enable reception control</strong></td><td><strong>Checked:</strong> Exposes the <strong>Reception Enable</strong> connectable point. This connectable point allows to enable or disable reception directly <strong>from the model</strong> during execution.<br><strong>Unchecked:</strong> Reception is always enabled.</td></tr><tr><td><strong>Swap byte order</strong></td><td><strong>Checked:</strong> Swaps the native byte order when transmitting data.<br><strong>Unchecked:</strong> Keeps the native byte order.</td></tr><tr><td><strong>Use sequential bit ordering for custom data</strong></td><td><strong>Checked:</strong> Reorders bits within each custom data frame from Most Significant Bit (MSB) to Least Significant Bit (LSB), regardless of machine endianness. Bytes within messages are serialized MSB-first, and messages with smaller bit offsets are serialized first.<br><strong>Example:</strong><br>Message 0 (bit offset 0, value <code>0x1</code>) and Message 1 (bit offset 4, value <code>0xABCDEF0</code>) are serialized as <code>0x1A BC DE F0</code>, instead of the traditional little-endian layout <code>0xF0 DE BC 1A</code>.<br><strong>Unchecked:</strong> Keeps the native bit and byte ordering. Bits and bytes are serialized according to the machine endianness.</td></tr><tr><td><strong>Use VLAN</strong></td><td><p><strong>Checked:</strong> Creates a VLAN interface based on the selected NIC. The following additional VLAN parameters must be configured:</p><ul><li><strong>VLAN index:</strong> Unique VLAN identifier. Each stream must use a distinct index.</li><li><strong>VLAN address:</strong> IP address assigned to the VLAN interface.</li></ul><p><strong>Unchecked:</strong> No VLAN interface is created. The stream uses the selected NIC directly.</p></td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Configure the stream(s) data points

1. Expand a stream to reveal its data points.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7e79e5283e5ffeb697ccccac74493e337f4a3ac4%2FDR-hyp-tcp-data.png?alt=media" alt=""><figcaption></figcaption></figure>

2. Click **Transmit** or **Receive** and use:

* **+** icon to add data points
* **–** icon to remove data points
* **Arrow** icons to reorder data points

3. Change parameters as desired:

<table data-header-hidden><thead><tr><th width="135"></th><th></th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>Unique identifier for the data point. The name must be unique within the data frame.</td></tr><tr><td><strong>Type</strong></td><td>Data type used to transmit and receive the value. Custom data types allow the definition of bit‑level fields.</td></tr><tr><td><strong>Vector size</strong></td><td>Number of values transmitted or received for this data point.</td></tr><tr><td><strong>Byte offset</strong></td><td>Starting position of the data within the frame, expressed in bytes.</td></tr><tr><td><strong>Bit offset</strong></td><td>Starting position of the data within the byte, expressed in bits.<br><em>Available only for custom data types.</em></td></tr><tr><td><strong>Size (bits)</strong></td><td>Number of bits used to transmit or receive each value.<br><em>Available only for custom data types.</em></td></tr><tr><td><strong>Initial value</strong></td><td>Initial value assigned to each element of the data point.</td></tr><tr><td><strong>Min</strong></td><td>Minimum valid value for the selected data type.</td></tr><tr><td><strong>Max</strong></td><td>Maximum valid value for the selected data type.</td></tr></tbody></table>
{% endstep %}

{% step %}

### Save the configuration

Click **Ok** or **Apply** to save the configuration.
{% 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/configure-ios/communication-protocol-ios/tcp-and-udp/configure-tcp-udp.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.
