> 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/automation-api-and-scripting/rt-lab-api/rt-lab-controller-architecture.md).

# RT-LAB Controller Architecture

## Introduction

The **RT-LAB API** communicates with RT-LAB objects through the **Controller** process. Multiple API clients can connect to the same Controller simultaneously. The Controller is responsible for managing all commands sent to the model, as well as handling and returning the values received from it.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-7cd0ecb48e5a0a6b75f5ab7c2369c38fb45a162c%2FRTLAB-API-controller.png?alt=media" alt="" width="302"><figcaption></figcaption></figure>

**Here is the list of the available controls:**

* system control
* monitoring control
* snapshot control
* acquisition control
* signal control
* parameter control
* blob control

Refer to the **Required Control** section for each API function to determine which control must be granted before calling the function.

Each control supports up to **256 priority levels**, allowing developers flexibility when designing their applications and managing access to API functions.

For more details on acquiring and releasing controls, see the **TakeFunctionControl** and **ReleaseFunctionControl** documentation.

## **Controller objects**

The Controller is composed of various object types (OP\_OBJECT\_TYPE). Each object contains a set of attributes (OP\_ATTRIBUTE) and may also own other objects. For example, RT-LAB owns a Project, and the Project, in turn, owns Models.

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

These objects are organized in a hierarchical tree structure (see Figure). Each object is identified by a unique Reference ID and its attributes can be accessed using Generic API calls (OP\_COMMAND).

There are specific rules governing how objects are arranged within this tree. In particular, each Controller always contains exactly one (1) project. While multiple Controllers can exist simultaneously, each Controller manages a single project.

### RT-LAB Global Object <a href="#rt-lab-global-object" id="rt-lab-global-object"></a>

This object is the root of the Controller’s object tree. All other objects are direct or indirect children of RT‑LAB. The attributes defined at the RT‑LAB level serve as default settings that are applied when new child objects are created.

For example, if the ATT\_TARGET\_PLATFORM attribute of RT‑LAB is set to REDHAWK\_TARGET, any newly created Model will inherit this value by default, unless it is explicitly modified afterward.

### Project Object <a href="#project-object" id="project-object"></a>

The Project object primarily serves as a container for models. A project can contain anywhere from 0 to 253 models. It also includes attributes that define its configuration and behavior.

### Model Objects <a href="#model-objects" id="model-objects"></a>

Models consist of a set of subsystems that are managed and executed together to run simulations. They are defined using block diagrams created with the third-party application MATLAB Simulink.

### Subsystem Objects <a href="#subsystem-objects" id="subsystem-objects"></a>

Subsystems contain various model elements, such as signals, block parameters, variables, and other components. The block diagrams that make up a Model are partitioned into Subsystems to better structure the model and optimize interactions between blocks by localizing certain operations to specific hardware.

### Controller Lists <a href="#controller-lists" id="controller-lists"></a>

Any Controller object that has children manages them through lists. The representation shown earlier is a simplified view of object relationships within the Controller. In practice, each object maintains a dedicated list for every type of child it owns.

For example, a Project does not directly own Models; instead, it owns a *Model List*, which in turn contains all the Models. This pattern is consistent across all Controller objects: objects can only own lists, and lists can only own objects.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-805a7ce1507cc190f26ac5031a51c6c1e02cffbc%2Fcontroller-list.png?alt=media" alt=""><figcaption><p>Controller list example.</p></figcaption></figure>

This structure provides a clear classification of an object’s children by type and offers flexibility, allowing users to add or remove child objects either through the parent object or via the corresponding intermediate list.

As illustrated in this Figure, each object owns exactly one (1) instance of each list type. Lists, however, can contain multiple objects (OP\_OBJECT\_TYPE for exact limits), provided all objects belong to the corresponding type.

For example, a Model List can contain only Model objects, and a Model owns several lists, such as an Environment List, a Subsystem List, and a Transfer File List.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-90c0ce46e0268220baa9114b5ca1d6d7662a69b3%2Fimage.png?alt=media" alt="" width="405"><figcaption><p>Detailed view of the Controller.<br>This diagram is provided for illustrative purposes only.</p></figcaption></figure>

### Reference IDs <a href="#reference-ids" id="reference-ids"></a>

All object and list instances are accessible through their unique reference ID. These IDs are 64-bit integers and are globally unique, allowing users to perform generic commands on objects as well as read and write operations on their attributes.

Some reference IDs are static. For example, the RT‑LAB object always has the same reference ID, OP\_RTLAB\_OBJ.

Additionally, all direct children of RT‑LAB also have fixed reference IDs (e.g., ProjectList). Since each Controller contains exactly one project, it can always be accessed using the OP\_SINGLE\_PROJECT reference ID.

## RT LAB States

An RT-LAB model may be in different states depending on the actions performed by the user.

RT-LAB states can be grouped in two categories:

* Disconnected and connected states. Before performing an API call, the project is set to the disconnected state. This is the initial state and the final state.
* Intermediate states when configuring, compiling or loading.

The next illustration depicts the different states available when using the RT-LAB API. The main functions which enable you to change a state are displayed on the transitions.

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


---

# 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/automation-api-and-scripting/rt-lab-api/rt-lab-controller-architecture.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.
