Skip to content

Commit 90b16aa

Browse files
stv0gstv0g
committed
Rework documentation of OPAL-RT node-types
Signed-off-by: Steffen Vogel <[email protected]>
1 parent ab87cf3 commit 90b16aa

File tree

4 files changed

+209
-32
lines changed

4 files changed

+209
-32
lines changed

‎docs/node/guides/lab21.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
sidebar_position: 21
3+
---
4+
5+
# Lab 21: Run on OPAL-RT real-time targets
6+
7+
## Introduction
8+
9+
This guide aims to provide step-by-step instructions for using VILLASnode with OPAL-RT's real-time simulation targets.
10+
For didactic reasons, the example employed in this guide is build from scratch.
11+
12+
However, a completed RT-LAB example model is provided as well in the VILLASnode Git-repository: **TODO**.
13+
14+
### Orchestra
15+
16+
OPAL-RT's Orchestra is a co-simulation environment allowing the integration and interoperability between heterogeneous models, written in different programming languages or generated by various tools. It is acting as a communication layer between OPAL-RT's HYPERSIM and RT-LAB software platforms and the external components.
17+
18+
OPAL-RT's Orchestra consists of two main components:
19+
20+
- **Framework:** An Orchestra _Framework_ provides publish-subscribe like broker functionality and is started as part of the real-time simulation model by HYPERSIM or RT-LAB. Each framework hosts a single Orchestra _Domain_. A _Domain_ describes the set of signals which are exchanged between the models and one-or-more connected _Clients_.
21+
- **Client:** An external / third-party component connecting to a Orchestra framework domain. Clients connect to the framework locally via a shared-memory segment or remotely via Ethernet (UDP or TCP), or Dolphin / Reflective memory fabrics.
22+
23+
In this guide, VILLASnode takes the role of a _Client_.
24+
By doing so, we can utilize the large set of available [VILLASnode node-types](../nodes) to exchange signals with a real-time model.
25+
26+
To limit the complexity of the setup, we run the VILLASnode gateway on the real-time simulation target itself.
27+
This is made possible by the OPAL-RT Linux Operation System which allows us to run standard Linux applications directly on the real-time target.
28+
29+
It should be noted that thanks to the flexibility of Orchestra communication layer, VILLASnode could also be executed on a different Linux system and communicate with the _Framework_ over Ethernet (UDP / TCP).
30+
However, we do not recommend this approach as it increases communication overhead and adds additional latency and computation overhead.
31+
32+
## Requirements
33+
34+
This guide has been tested with the following software versions:
35+
36+
- **VILLASnode:** v1.0.1
37+
- **RT-LAB:** v2025.1.3.77
38+
- **OPAL-RT Linux:** v3.5.4
39+
- **Python:** v3.9
40+
- **Real-time Target:** OP5033XG, OP5707XG or similar
41+
42+
## Step-by-Step Guide
43+
44+
### 1. Create a new RT-LAB Project
45+
46+
1. **Enable Advanced User features:** RT-LAB Menubar -> Window -> Preferences -> RT-LAB -> Capabilities -> Check "Advanced User"
47+
2. **Create RT-LAB project:** RT-LAB Menubar -> File -> New -> RT-LAB Project
48+
- **Project name:** `Orchestra_VILLASnode_Loopback_simple`
49+
- **Use default location:** checked
50+
- **Template:** empty
51+
3. **Enable PyDev features in project:** RT-LAB Project Explorer -> Right-click on new Project -> PyDev -> Set as PyDev Project
52+
4. **Add project-wide Python scripts:**
53+
1. **Create a new PyDev source directory:** RT-LAB Menubar -> New -> Other -> PyDev -> Source Folder
54+
- **Project:** `Orchestra_VILLASnode_Loopback_simple` (your new RT-LAB project)
55+
- **Name:** `scripts`
56+
2. **Add package:** RT-LAB Menubar -> New -> Other -> PyDev -> PyDev Package
57+
- **Source Folder:** `Orchestra_VILLASnode_Loopback_simple/scripts`
58+
- **Name:** `orchestra`
59+
3. **Copy contents new module (opened text editor):**
60+
- **Source:** TODO
61+
4. **Create new PyDev "Launch Configuration":** RT-LAB Menubar -> Tools -> Python -> Run Configurations...
62+
1. Select "Python Run" -> Click on "New" icon in upper-left corner of the dialog
63+
- **Name:** `Generate Orchestra DDF`
64+
- **Main Tab**
65+
- **Project:** `Orchestra_VILLASnode_Loopback_simple` (your new RT-LAB project)
66+
- **Main Module:** `${workspace_loc:VILLASnode_Orchestra_Loopback/scripts/orchestra/__init__.py}`
67+
- **Arguments Tab**
68+
- **Arguments**: `${workspace_loc:VILLASnode_Orchestra_Loopback/models/model/orchestra.conf}` (and possible more VILLASnode configuration files, if used)
69+
70+
### 2. Create a new RT-LAB Model
71+
72+
1. **Create RT-LAB model:** RT-LAB Menubar -> File -> New -> RT-LAB Model -> Finish
73+
- **Model name:** model
74+
- **Model type:** MATLAB/Simulink (.slx)
75+
2. **Add RT-LAB user script:** RT-LAB Menubar -> New -> Other -> General -> File
76+
- **Parent folder:** `VILLASnode_Orchestra_Loopback/models/model`
77+
- **File name:** `target_preload.py`
78+
- **Contents:** Copy from TODO
79+
80+
### 3. Installation of VILLASnode
81+
82+
The installation of VILLASnode on the real-time target is fully automated by the `target_preload.py` [user script](https://opal-rt.atlassian.net/wiki/spaces/PRD/pages/143985689/Executing+Models#User-script-files) created in the previous step.
83+
VILLASnode will be automatically installed during model load.
84+
85+
To verify that the installation succeeded, you can login to the target via SSH and run the `villas node -V` command:
86+
87+
```shell
88+
$ ssh root@<target-ip-address>
89+
90+
root@rtserver:~# villas node -V
91+
13:12:35 info node This is VILLASnode 1.0.1 (built on Jan 1 1980, 00:00:00)
92+
13:12:35 info signals Initialize subsystem
93+
1.0.1
94+
```
95+
96+
Alternative installation methods as documented on the [Installation page](../installation.md) are supported as well.
97+
98+
### 4. Create a VILLASnode Configuration File: `orchestra.conf`
99+
100+
Next, we create a [VILLASnode configuration file](../config/) named an place it into the RT-LAB model directory:
101+
102+
```text url="external/node/clients/rtlab-orchestra/models/model/orchestra.conf" title="<RTLAB-PROJECT-ROOT>/models/model/orchestra.conf"
103+
104+
```
105+
106+
This configuration file defines how signals exchanged between VILLASnode and the simulation model over Orchestra are further processed in the VILLASnode gateway.
107+
In the example above, we simply perform a loopback over the VILLASnode [`socket`](../nodes/socket.md) node-type to localhost.
108+
This configuration file also include a defintition of all signals including their name and data-type which are exchanged with the simulation model.
109+
110+
### 4. Generate an Orchestra Data Definition File: `orchestra.xml`
111+
112+
Based in the VILLASnode config file prepared in the previous step, we now generate an Orchestra data-definition file (DDF): `orchestra.xml`.
113+
This file is used by the Orchestra Framework to specify which _Domains_ exist and which signals they contain.
114+
This step is automated using a Python script which we first add to our RT-LAB project:
115+
116+
117+
:::caution
118+
The VILLASnode config file (`orchestra.conf`) and the Orchestra data-definition file (`orchestra.xml`) must kept synchronized.
119+
Please repeat this step, whenever you change the VILLASnode config file.
120+
:::
121+
122+
### 6. Build the RT-LAB Model on the Target
123+
124+
### 7. Add an Orchestra Framework I/O Interface
125+
126+
### 8. Create Connections between I/O Interface and Model
127+
128+
### 9. Run Model

‎docs/node/nodes/opal/index.md‎

Lines changed: 22 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,30 @@ hide_table_of_contents: true
66

77
There are three options to exchange simulation signals with an OPAL-RT real-time simulator:
88

9-
1. **[UDP Sockets](../socket.md):** Use OPAL-RT's UDP/TCP I/O interfaces or an adapted version of the AsyncIP example for asynchronous processes.
9+
1. **[Orchestra](opal_orchestra.md):** VILLASnode can act as an [Orchestra client](https://opal-rt.atlassian.net/wiki/spaces/PRD/pages/505348099/Orchestra+I+O).
10+
Orchestra is OPAL-RT's co-simulation framework for integrating custom code and external models.
11+
12+
The functionality is implemented by the [`opal.orchestra`](opal_orchestra.md) node-type.
13+
14+
:::tip
15+
This node-type is recommended for new setups.
16+
:::
17+
18+
2. **[UDP Sockets](../socket.md):** Use OPAL-RT's [UDP/TCP I/O interfaces](https://opal-rt.atlassian.net/wiki/spaces/PCPM/pages/143720599/TCP+UDP).
1019
In this mode, OPAL-RT targets will send signals via a UDP socket to VILLASnode.
11-
VILLASnode use the [`socket` node-type](../socket.md) node-type to send and receive these UDP packets.
1220
More information about our adapted AsyncIP example can be found here: [AsyncIP client](../../clients/opal_async_ip.md).
1321

14-
2. **[Orchestra](opal_orchestra.md):** VILLASnode can act as an Orchestra client.
15-
Orchstra is OPAL-RT's co-simulation framework for integrating custom code and external models.
16-
The functionality is implemented in the closed-source [`opal.orchestra`](opal_orchestra.md) node-type.
22+
This functionality is implemented by the [`socket`](../socket.md) node-type.
23+
24+
:::caution
25+
This node-type is not recommended due to limited synchronizations, and limitations in I/O signal management.
26+
:::
1727

18-
3. **[Asynchronous Process](opal_async.md):** VILLASnode can act as an RT-LAB Asynchronous Process.
28+
3. **[Asynchronous Process](opal_async.md):** VILLASnode can act as an [RT-LAB Asynchronous Process](https://opal-rt.atlassian.net/wiki/spaces/PRD/pages/144020065/Asynchronous+Processes).
1929
Data exchange is then handled using OPAL-RT's `libOpalAsyncApi`.
20-
The functionality is implemented in the closed-source [`opal.async`](opal_async.md) node-type.
30+
31+
The functionality is implemented by the [`opal.async`](opal_async.md) node-type.
32+
33+
:::danger Deprecation
34+
This node-type is deprecated and not recommended for new setups.
35+
:::

‎docs/node/nodes/opal/opal_async.md‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,40 @@
11
---
22
hide_table_of_contents: true
3+
sidebar_position: 99
34
---
45

5-
# OPAL-RT Asynchronous Process
6+
# Asynchronous Process
67

78
> In keeping with the design principle of openness, RT-LAB features can be extended through the use of Asynchronous User Applications also called Asynchronous Processes. This gives RT-LAB users access to the full power of the operating system and allow them to implement their own interfaces to various external devices. Although usually targeted for use with communication devices such as GPS receivers and power monitors, Asynchronous User Applications can be developed to interface acquisition boards, or implement system-specific software such as file management, etc.
89
910
(From [RT-LAB user documentation](https://opal-rt.atlassian.net/wiki/spaces/PRD/pages/144020065/Asynchronous+Processes))
1011

1112
They are used to exchange data between RT-LAB Simulink models and custom user-defined programs via [shared memory](https://en.wikipedia.org/wiki/Shared_memory) on a real-time target.
1213

13-
## Prerequisites
14+
:::danger[Deprecation]
15+
The `opal.async` node-type is deprecated for the following reasons.
1416

15-
This node-types requires a running version of VILLASnode on an OPAL-RT target:
17+
**Please consider the more actively supported [`opal.orchestra`](./orchestra) node-type instead!**
1618

17-
- An OPAL-RT target running OPAL-RT Linux v3.4.1 or newer
18-
- RT-LAB v2023.1 or newer
19+
- The OPAL-RT **HYPERSIM** simulation environment is not supported.
20+
- Older targets running RHEL / CentOS operating systems are not supported.
21+
- Due to the shared-memory communication remote execution of VILLASnode is not supported.
22+
- Communication between VILLASnode and the RT-LAB model is asynchronous. Its not possible to block the execution of the RT-LAB model until new data is available.
23+
- Asynchronous processes are integrated via legacy S-function IO blocks into the RT-LAB model. Modern RT-LAB & HYPERSIM use a new system for I/O configuration and connections management.
24+
:::
1925

20-
:::caution
21-
The node-types requires the use of the RT-LAB simulation environment.
22-
When using HYPERSIM, please consider the running VILLASnode as an [OPAL-RT Orchestra Client](opal_orchestra.md).
26+
## Prerequisites
2327

24-
Older targets running RHEL / CentOS operating systems are not supported.
25-
:::
28+
This node-types requires a running version of VILLASnode on an OPAL-RT target:
2629

27-
## Implementation
30+
- An OPAL-RT real-time simulator.
31+
- 64-bit OPAL-RT Linux v3.4.1 or newer.
32+
- RT-LAB v2023.1 or newer.
2833

29-
:::note
30-
The implementation of the `opal.async` node-type is currently not open source.
34+
## Implementation
3135

32-
Please contact [Steffen Vogel](mailto:[email protected]) if you are interested in run
33-
:::
36+
The source code of the node-type is available here:
37+
https://github.com/VILLASframework/node/blob/master/lib/nodes/opal_async.cpp
3438

3539
## Installation
3640

@@ -76,7 +80,7 @@ During model load the configuration file will be loaded to the target and used b
7680

7781
import ApiSchema from '@theme/ApiSchema';
7882

79-
{/* <ApiSchema id="node" example pointer="#/components/schemas/opal" /> */}
83+
{/* <ApiSchema id="node" example pointer="#/components/schemas/opal_async" /> */}
8084

8185
## Example
8286

‎docs/node/nodes/opal/opal_orchestra.md‎

Lines changed: 39 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,42 @@
11
---
22
hide_table_of_contents: true
3+
sidebar_position: 1
34
---
45

5-
# OPAL-RT Orchestra
6+
# Orchestra
67

7-
Orchstra is OPAL-RT's co-simulation framework for integrating custom code and external models.
8-
More information about Orchestra can be found in the [OPAL-RT Wiki](https://opal-rt.atlassian.net/wiki/spaces/PRD/pages/143626248/Orchestra).
8+
Orchestra is OPAL-RT's co-simulation framework for integrating custom code and external models.
9+
More information about Orchestra can be found in the [OPAL-RT Wiki](https://opal-rt.atlassian.net/wiki/spaces/PRD/pages/505348099/Orchestra+I+O).
910

10-
## Prerequisites
11+
:::tip
12+
Please familiarize yourself first with Orchestra using the [OPAL-RT Wiki](https://opal-rt.atlassian.net/wiki/spaces/PRD/pages/505348099/Orchestra+I+O) before attempting to use it with VILLASnode.
13+
:::
1114

12-
- `libOpalOrchestra.so` & `RTAPI.h`
15+
## Prerequisites
1316

14-
## Implementation
17+
- A OPAL-RT real-time simulator.
18+
- 64-bit OPAL-RT Linux v3.4.1 or newer.
19+
- `libOpalOrchestra.so` & `RTAPI.h`
20+
- One of:
21+
- RT-LAB v2025.1 or newer
22+
- HYPERSIM v2025.3 or newer
1523

16-
:::note
17-
The implementation of the `opal.orchestra` node-type is currently not open source.
24+
:::info
25+
The RT-LAB and HYPERSIM versions above were validated. Other versions might work as well. Use at your own discretion.
26+
:::
1827

19-
Please contact [Steffen Vogel](mailto:[email protected]) if you are interested in run
28+
:::caution
29+
Older 32-bit OPAL-RT targets running RHEL / CentOS operating systems are not supported.
2030
:::
2131

32+
## Implementation
33+
34+
The source code of the node-type is available here:
35+
https://github.com/VILLASframework/node/blob/master/lib/nodes/opal_orchestra.cpp
36+
2237
## Installation
2338

39+
Please refer to the [Lab 21](../../guides/lab21) for a detailed guide on how to install VILLASnode on an OPAL-RT Real-time target.
2440

2541
## Configuration {#config}
2642

@@ -137,3 +153,17 @@ paths = (
137153
}
138154
)
139155
```
156+
157+
## Running VILLASnode on a remote system
158+
159+
Orchestra offers the possibility to run VILLASnode (as an Orchestra client) on a separate machine from the real-time target.
160+
This allows for integration and Co-simulation external systems.
161+
In this case signals between the client and the framework are exchanged over a TCP or UDP/IP connection.
162+
163+
:::caution
164+
This is an advanced use-case as it requires linking of VILLASnode against `libOpalOrchestra.so` on a non-OPAL-RTLinux system.
165+
166+
When [building VILLASnode with Nix](../../installation.md#nix), or using any of the by-Nix pre-compiled installations options like the [standalone](../../installation.md#standalone) or `.rpm` packages or [Docker images](../../installation.md#docker),
167+
VILLASnode, should be already compiled with the necessary `libOpalOrchestra.so` library and `OrchestraExtCommIP` helper tool.
168+
:::
169+

0 commit comments

Comments
 (0)