> 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/simulink-blocks-reference/rt-lab-i-o-library/opctrl.md).

# OpCtrl

## Description

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

The **OpCtrl** block, located in the **RT-LAB I/O/Opal-RT/Common** library, provides the interface between an RT‑LAB model and the FPGA installed in the simulator or expansion unit via the **PCIe bus**. It is **required** when using the [S‑Function workflow](https://www.opal-rt.com/docs/rt-lab/configure-ios/analog-digital-and-sfp-ios/s-function-workflow.md) to interface an RT‑LAB model with the simulator or expansion unit FPGA, for example when exchanging signals with external hardware or a device under test (DUT) through OPAL‑RT I/O modules. It is **not required** when using the [OPAL‑RT Board workflow](https://www.opal-rt.com/docs/rt-lab/configure-ios/analog-digital-and-sfp-ios/opal-rt-board-workflow.md), which manages FPGA interaction differently.

The **OpCtrl** block is responsible for:

* **Configuring FPGA synchronization**, including master/slave operation in multi‑FPGA systems.
* **Propagating the simulation state** to the FPGA. During execution, RT‑LAB models transition through four states: **LOAD**, **PAUSE**, **EXECUTE**, and **RESET**. The OpCtrl block communicates the current state to the FPGA over PCIe.
* **Associating the FPGA with functional I/O blocks**. Each **FPGA** must be controlled by **exactly one OpCtrl block**, which must be placed in a **real‑time subsystem** (SM\_ or SS\_) that exchanges signals through OPAL‑RT I/O modules. All **functional I/O blocks** in that subsystem must reference the corresponding **OpCtrl** instance.

  In systems with **multiple expansion units**, create **one OpCtrl block per unit**, each configured with a **unique Controller Name** and the appropriate **Board ID**. Functional I/O blocks must reference the OpCtrl block associated with the physical unit hosting the I/O module. For example, the simulator I/O modules must reference the simulator OpCtrl block, and the expansion‑unit I/O modules must reference the corresponding expansion‑unit OpCtrl block.\
  In models where **multiple subsystems access the same FPGA**, only one subsystem contains the OpCtrl block. Additional subsystems must use [OpLnk](https://www.opal-rt.com/docs/rt-lab/simulink-blocks-reference/rt-lab-i-o-library/oplnk.md) blocks to connect to that OpCtrl instance.

## Mask parameters

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

{% tabs %}
{% tab title="All Board Types except OP48xx" %}
These are the standard parameters for all board types **except** the OP48xx boards.

<table><thead><tr><th width="225">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Controller Name</strong></td><td>Unique identifier for this <strong>OpCtrl</strong> block. Functional I/O blocks must reference this <strong>Controller Name</strong> to bind themselves to this <strong>OpCtrl</strong> instance.</td></tr><tr><td><strong>Board ID</strong></td><td>Identifies the simulator or expansion unit controlled by this <strong>OpCtrl</strong> block. Each unit is assigned a unique <strong>chassis index</strong>. Set the <strong>Board ID</strong> to match the chassis index specified in the <strong>System Description Document</strong>. For a simulator, the <strong>Board ID</strong> is typically <code>0</code>.</td></tr><tr><td><strong>Primary Bitstream FileName</strong></td><td>Specifies the name of the bitstream <code>.bin</code> to program before the model is loaded. Both <strong>bitstream files</strong> (<code>.bin</code> and <code>.conf</code>) provided with your system must be copied in the model folder. <strong>Do not rename bitstream files</strong>, as their naming convention is critical for correct operation.</td></tr><tr><td><strong>Synchronization mode</strong></td><td><strong>Master</strong>: The FPGA is the <strong>synchronization source for the model</strong>. The FPGA generates the system clock, which is distributed internally and made available on the hardware unit to synchronize other units (e.g., expansion chassis).<br><strong>Slave</strong>: The FPGA is <strong>synchronized to an external clock source</strong>.<br><strong>Master with external clock</strong>: The FPGA uses an <strong>external clock source</strong> as its input but acts as the <strong>synchronization master for the model</strong>.</td></tr><tr><td><strong>Generate External Clock</strong></td><td>Not yet supported.</td></tr><tr><td><strong>Sample Time (s)</strong></td><td><p>Specifies the block sample time, in seconds. A value of <code>0</code> sets a continuous sample time, inherited from the parent subsystem. A value of <code>−1</code> specifies an inherited sample time from the model.</p><p>The <strong>OpCtrl</strong> block and its associated functionality blocks and must execute at the same <strong>sample time</strong>.</p></td></tr><tr><td><strong>Board Type</strong></td><td>Specifies the FPGA board to control. Simplifies switching between boards. Must match the FPGA board in the bitstream filename.</td></tr><tr><td><strong>Synchronization type</strong></td><td>Specifies the synchronization link: LVDS (audio) or optical fiber.</td></tr><tr><td><strong>Enable FPGA Scope</strong></td><td><strong>Checked:</strong> Enables <a href="https://www.opal-rt.com/docs/rt-lab/simulation-control-monitoring-and-logging/monitor-fpga-signals-with-fpga-scope.md">FPGA Scope</a> availability during model execution, provided the selected bitstream configuration supports it.<br><strong>Unchecked:</strong> FPGA Scope is not available.</td></tr><tr><td><strong>Disable strict hardware mismatch validation</strong></td><td><strong>Checked:</strong> Allows the use of multiple I/O module types based on general compatibility rules instead of exact hardware ID matching.<br><strong>Unchecked:</strong> Exact hardware ID validation is enforced.</td></tr></tbody></table>
{% endtab %}

{% tab title="Board Type = OP48xx" %}
These are parameters specific to the **OP48xx** boards only.

<table><thead><tr><th width="225">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Controller Name</strong></td><td>Unique identifier for this <strong>OpCtrl</strong> block. Functional I/O blocks must reference this <strong>Controller Name</strong> to bind themselves to this <strong>OpCtrl</strong> instance.</td></tr><tr><td><strong>Board ID</strong></td><td>Identifies the simulator or expansion unit controlled by this <strong>OpCtrl</strong> block. Each unit is assigned a unique <strong>chassis index</strong>. Set the <strong>Board ID</strong> to match the chassis index specified in the <strong>System Description Document</strong>. For a simulator, the <strong>Board ID</strong> is typically <code>0</code>.</td></tr><tr><td><strong>Primary Bitstream FileName</strong></td><td>Specifies the name of the bitstream <code>.bin</code> to program before the model is loaded. Both <strong>bitstream files</strong> (<code>.bin</code> and <code>.conf</code>) provided with your system must be copied in the model folder. <strong>Do not rename bitstream files</strong>, as their naming convention is critical for correct operation.</td></tr><tr><td><strong>Synchronization mode</strong></td><td><strong>Master</strong>: The FPGA is the <strong>synchronization source for the model</strong>. The FPGA generates the system clock, which is distributed internally and made available on the hardware unit to synchronize other units (e.g., expansion chassis).<br><strong>Slave</strong>: The FPGA is <strong>synchronized to an external clock source</strong>.<br><strong>Master with external clock</strong>: The FPGA uses an <strong>external clock source</strong> as its input but acts as the <strong>synchronization master for the model</strong>.</td></tr><tr><td><strong>Generate External Clock</strong></td><td>Not yet supported.</td></tr><tr><td><strong>Sample Time (s)</strong></td><td><p>Specifies the block sample time, in seconds. A value of <code>0</code> sets a continuous sample time, inherited from the parent subsystem. A value of <code>−1</code> specifies an inherited sample time from the model.</p><p>The <strong>OpCtrl</strong> block and its associated functionality blocks and must execute at the same <strong>sample time</strong>.</p></td></tr><tr><td><strong>Board Type</strong></td><td>Specifies the FPGA board to control. Simplifies switching between boards. Must match the FPGA board in the bitstream filename.</td></tr><tr><td><strong>IP address</strong></td><td>Specifies the IP address of the chassis as shown on its LCD. Press the <strong>menu</strong> button on the unit to navigate to the <strong>ID page</strong>.</td></tr><tr><td><strong>Chassis name</strong></td><td>Specifies the name of the chassis, shown on its LCD. Press the <strong>menu</strong> button on the unit to navigate to the <strong>ID page</strong>.</td></tr><tr><td><strong>Synchronization type</strong></td><td>Specifies the synchronization link: LVDS (audio) or optical fiber.</td></tr><tr><td><strong>Enable FPGA Scope</strong></td><td><strong>Checked:</strong> Enables <a href="https://www.opal-rt.com/docs/rt-lab/simulation-control-monitoring-and-logging/monitor-fpga-signals-with-fpga-scope.md">FPGA Scope</a> availability during model execution, provided the selected bitstream configuration supports it.<br><strong>Unchecked:</strong> FPGA Scope is not available.</td></tr><tr><td><strong>Disable strict hardware mismatch validation</strong></td><td><strong>Checked:</strong> Allows the use of multiple I/O module types based on general compatibility rules instead of exact hardware ID matching.<br><strong>Unchecked:</strong> Exact hardware ID validation is enforced.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Inputs

This block has no inputs.

## Outputs

<table><thead><tr><th width="136">Output</th><th>Description</th></tr></thead><tbody><tr><td><strong>Error</strong></td><td><p>Outputs error codes:</p><ul><li><code>0</code>: No error.</li><li><code>-1</code>: FPGA board not detected.</li><li><code>-2</code>: Timeout waiting for a synchronization signal. If in <strong>Slave</strong> mode, verify the RTSI synchronization signal connection.</li><li><code>-3</code>: Overrun detected.</li><li><code>-10</code>: Indicates a hardware mismatch error.</li></ul></td></tr><tr><td><strong>IDs</strong></td><td>Returns hardware identification codes for all I/O modules installed in the associated simulator or expansion unit. Empty slots return <strong>255</strong> (<code>0xFF</code>).</td></tr></tbody></table>

## Characteristics and limitations

| Characteristic                 | Value                            |
| ------------------------------ | -------------------------------- |
| **Hardware synchronized mode** | Required                         |
| **XHP support**                | Yes (only XHP mode is supported) |
| **Direct feedthrough**         | No                               |
| **Discrete sample time**       | No                               |
| **Work offline**               | No                               |


---

# 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/simulink-blocks-reference/rt-lab-i-o-library/opctrl.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.
