diff --git a/docs/index.md b/docs/index.md index b85d0ba1..c575bcc2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -101,7 +101,7 @@ Most contributions are made by the following authors: [OPAL-RT Germany GmbH](https://www.opal-rt.com/) -OPAL-RT Germany Logo +OPAL-RT logo ## Contact & Community diff --git a/docs/node/clients/opal_async_ip.md b/docs/node/clients/opal_async_ip.md index f0db6785..61645f18 100644 --- a/docs/node/clients/opal_async_ip.md +++ b/docs/node/clients/opal_async_ip.md @@ -3,7 +3,7 @@ sidebar_label: OPAL-RT RT-LAB title: OPAL-RT RT-LAB Asynchronous Process (AsyncIP) --- -# OPAL-RT RT-LAB Asynchronous Process (AsyncIP) OPAL-RT logo +# OPAL-RT RT-LAB Asynchronous Process (AsyncIP) OPAL-RT logo ## OPAL-RT RT-LAB Example Project diff --git a/docs/node/guides/lab21.md b/docs/node/guides/lab21.md new file mode 100644 index 00000000..ba577279 --- /dev/null +++ b/docs/node/guides/lab21.md @@ -0,0 +1,128 @@ +--- +sidebar_position: 21 +--- + +# Lab 21: Run on OPAL-RT real-time targets + +## Introduction + +This guide aims to provide step-by-step instructions for using VILLASnode with OPAL-RT's real-time simulation targets. +For didactic reasons, the example employed in this guide is build from scratch. + +However, a completed RT-LAB example model is provided as well in the VILLASnode Git-repository: **TODO**. + +### Orchestra + +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. + +OPAL-RT's Orchestra consists of two main components: + +- **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_. +- **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. + +In this guide, VILLASnode takes the role of a _Client_. +By doing so, we can utilize the large set of available [VILLASnode node-types](../nodes) to exchange signals with a real-time model. + +To limit the complexity of the setup, we run the VILLASnode gateway on the real-time simulation target itself. +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. + +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). +However, we do not recommend this approach as it increases communication overhead and adds additional latency and computation overhead. + +## Requirements + +This guide has been tested with the following software versions: + +- **VILLASnode:** v1.0.1 +- **RT-LAB:** v2025.1.3.77 +- **OPAL-RT Linux:** v3.5.4 +- **Python:** v3.9 +- **Real-time Target:** OP5033XG, OP5707XG or similar + +## Step-by-Step Guide + +### 1. Create a new RT-LAB Project + +1. **Enable Advanced User features:** RT-LAB Menubar -> Window -> Preferences -> RT-LAB -> Capabilities -> Check "Advanced User" +2. **Create RT-LAB project:** RT-LAB Menubar -> File -> New -> RT-LAB Project + - **Project name:** `Orchestra_VILLASnode_Loopback_simple` + - **Use default location:** checked + - **Template:** empty +3. **Enable PyDev features in project:** RT-LAB Project Explorer -> Right-click on new Project -> PyDev -> Set as PyDev Project +4. **Add project-wide Python scripts:** + 1. **Create a new PyDev source directory:** RT-LAB Menubar -> New -> Other -> PyDev -> Source Folder + - **Project:** `Orchestra_VILLASnode_Loopback_simple` (your new RT-LAB project) + - **Name:** `scripts` + 2. **Add package:** RT-LAB Menubar -> New -> Other -> PyDev -> PyDev Package + - **Source Folder:** `Orchestra_VILLASnode_Loopback_simple/scripts` + - **Name:** `orchestra` + 3. **Copy contents new module (opened text editor):** + - **Source:** TODO + 4. **Create new PyDev "Launch Configuration":** RT-LAB Menubar -> Tools -> Python -> Run Configurations... + 1. Select "Python Run" -> Click on "New" icon in upper-left corner of the dialog + - **Name:** `Generate Orchestra DDF` + - **Main Tab** + - **Project:** `Orchestra_VILLASnode_Loopback_simple` (your new RT-LAB project) + - **Main Module:** `${workspace_loc:VILLASnode_Orchestra_Loopback/scripts/orchestra/__init__.py}` + - **Arguments Tab** + - **Arguments**: `${workspace_loc:VILLASnode_Orchestra_Loopback/models/model/orchestra.conf}` (and possible more VILLASnode configuration files, if used) + +### 2. Create a new RT-LAB Model + +1. **Create RT-LAB model:** RT-LAB Menubar -> File -> New -> RT-LAB Model -> Finish + - **Model name:** model + - **Model type:** MATLAB/Simulink (.slx) +2. **Add RT-LAB user script:** RT-LAB Menubar -> New -> Other -> General -> File + - **Parent folder:** `VILLASnode_Orchestra_Loopback/models/model` + - **File name:** `target_preload.py` + - **Contents:** Copy from TODO + +### 3. Installation of VILLASnode + +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. +VILLASnode will be automatically installed during model load. + +To verify that the installation succeeded, you can login to the target via SSH and run the `villas node -V` command: + +```shell +$ ssh root@ + +root@rtserver:~# villas node -V +13:12:35 info node This is VILLASnode 1.0.1 (built on Jan 1 1980, 00:00:00) +13:12:35 info signals Initialize subsystem +1.0.1 +``` + +Alternative installation methods as documented on the [Installation page](../installation.md) are supported as well. + +### 4. Create a VILLASnode Configuration File: `orchestra.conf` + +Next, we create a [VILLASnode configuration file](../config/) named an place it into the RT-LAB model directory: + +```text url="external/node/clients/rtlab-orchestra/models/model/orchestra.conf" title="/models/model/orchestra.conf" + +``` + +This configuration file defines how signals exchanged between VILLASnode and the simulation model over Orchestra are further processed in the VILLASnode gateway. +In the example above, we simply perform a loopback over the VILLASnode [`socket`](../nodes/socket.md) node-type to localhost. +This configuration file also include a defintition of all signals including their name and data-type which are exchanged with the simulation model. + +### 4. Generate an Orchestra Data Definition File: `orchestra.xml` + +Based in the VILLASnode config file prepared in the previous step, we now generate an Orchestra data-definition file (DDF): `orchestra.xml`. +This file is used by the Orchestra Framework to specify which _Domains_ exist and which signals they contain. +This step is automated using a Python script which we first add to our RT-LAB project: + + +:::caution +The VILLASnode config file (`orchestra.conf`) and the Orchestra data-definition file (`orchestra.xml`) must kept synchronized. +Please repeat this step, whenever you change the VILLASnode config file. +::: + +### 6. Build the RT-LAB Model on the Target + +### 7. Add an Orchestra Framework I/O Interface + +### 8. Create Connections between I/O Interface and Model + +### 9. Run Model \ No newline at end of file diff --git a/docs/node/installation.md b/docs/node/installation.md index 6dad8a7f..8b890178 100644 --- a/docs/node/installation.md +++ b/docs/node/installation.md @@ -6,7 +6,8 @@ sidebar_position: 3 VILLASnode can be installed in multiple ways: -- [Precompiled standalone binaries](#standalone) +- [Pre-compiled standalone binaries](#standalone) +- [Pre-compiled RPM package](#rpm) - [Docker image](https://git.rwth-aachen.de/acs/public/villas/node/container_registry) - [Kubernetes (Helm chart)](../installation.md) - [Nix Flake](#nix) @@ -18,45 +19,68 @@ Please make sure that your system fulfills the [requirements](requirements.md) b ## From sources {#source} -VILLASnode can be compiled from source using [CMake](http://cmake.org). +VILLASnode can be compiled from source using [CMake](http://cmake.org): + +#### TL;DR Version + +```shell +mkdir -p ~/build/villas +cd ~/build/villas + +git clone https://github.com/VILLASframework/node.git + +mkdir -p node/{prefix,build} +cd node + +export PREFIX=/opt/villas +export CMAKE_PREFIX_PATH=${PREFIX} +export CMAKE_INSTALL_PREFIX=${PREFIX} +mkdir -p ${PREFIX} + +DEPS_NONINTERACTIVE=1 \ +bash packaging/deps.sh + +cmake -B build -S . +cmake --build build --parallel 4 --target install +``` ### Prerequisites VILLASnode currently has the following list of dependencies: -| Package | Version | Purpose | Optional | License | -| --- | --- | --- | --- | --- | -| [CMake](http://cmake.org/) | >= 3.9 | for generating the build-system | required | BSD 3 | -| [fmtlib](https://github.com/fmtlib/fmt) | >= 6.1.2 | for string formatting | required | MIT | -| [libcurl](https://curl.haxx.se/libcurl/) | >= 7.29.0 | for HTTP REST requests by the [NGSI node-type](nodes/ngsi.md) node-type | required | similar to MIT | -| [libjansson](http://www.digip.org/jansson/) | >= 2.7 | JSON parser for [Websocket node-type](nodes/websocket.md) and [NGSI node-type](nodes/ngsi.md) node-types | required | MIT | -| [libuuid](https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git) | >= 2.29 | - | required | BSD | -| [libwebsockets](http://libwebsockets.org) | >= 3.1.0 | for the [Websocket node-type](nodes/websocket.md) | required | MIT | -| [openssl](https://www.openssl.org) | >= 1.0.0 | for cryptographic hashing functions | required | Apache 2 for >=3.0 | -| [spdlog](https://github.com/gabime/spdlog) | >= 1.8.2 | for logging | required | MIT | -| [comedilib](http://comedi.org) | >= 0.11.0 | for the [Comedi node-type](nodes/comedi.md) | optional | LGPL-2.1 | -| [Criterion](https://github.com/Snaipe/Criterion) | >= 2.3.1 | for running the unit tests | optional | MIT | -| [Etherlab](http://etherlab.org) | >= 1.5.2 | for the [Ethercat node-type](nodes/ethercat.md) | optional | __GPL 3__ | -| [Graphviz](https://graphviz.org/) | >= 2.30 | for the visualisation of configuration files | optional | EPL | -| [libconfig](http://www.hyperrealm.com/libconfig/) | >= 1.4.9 | for parsing the configuration file | optional | LGPL-2.1 | -| [libdatachannel](https://libdatachannel.org/) | >= 0.18.4 | for the WebRTC node-type | optional | MPL-2.0 | -| [libibverbs](https://github.com/linux-rdma/rdma-core) | >= 16.2 | for the [Infiniband node-type](nodes/infiniband.md) | optional | BSD | -| [libiec61850](http://libiec61850.com/libiec61850/) | >= 1.3.1 | for the [IEC61850-8-1](nodes/iec61850-8-1.md) and [IEC61850-9-2](nodes/iec61850-9-2.md) node-types | optional | __GPL 3__ | -| [libmodbus](https://libmodbus.org/) | >= 3.1.0 | for the [Modbus](nodes/modbus.md) node-type | optional | LGPL-2.1 | -| [libnanomsg](http://nanomsg.org/) | >= 1.0.0 | for the [Nanomsg node-type](nodes/nanomsg.md) | optional | MIT | -| [libnice](https://libnice.freedesktop.org/) | >= 0.1.16 | for libdatachannel / WebRTC | optional | MPL-1.1 & LGPL-2.1 | -| [libnl3](http://www.infradead.org/~tgr/libnl/) | >= 3.2.27 | for the network communication & emulation support of the [Socket node-type](nodes/socket.md) node-type | optional | LGPL-2.1 | -| [librdmacm](https://github.com/linux-rdma/rdma-core) | >= 16.2 | for the [Infiniband node-type](nodes/infiniband.md) | optional | BSD | -| [libre](http://www.creytiv.com/re.html) | >= 2.9.0 | for the [RTP node-type](nodes/rtp.md) | optional | BSD 3 | -| [libuldaq](https://github.com/mccdaq/uldaq) | >= 1.0.0 | for the [ULDAQ node-type](nodes/uldaq.md) | optional | MIT | -| [libxil](https://github.com/VILLASframework/libxil) | >= 1.0.0 | for the [VILLASfpga node-type](nodes/fpga.md) | optional | MIT | -| [libzmq](http://zeromq.org) | >= 2.2.0 | for the [ZeroMQ node-type](nodes/zeromq.md) | optional | MPL-2.0 | -| [Lua](http://www.lua.org/) | >= 5.1 | for the [Lua hook](hooks/lua.md) | optional | MIT | -| [mosquitto](https://mosquitto.org) | >= 1.4.15 | for the [MQTT node-type](nodes/mqtt.md) | optional | EPL 2 | -| [protobuf-c](https://github.com/protobuf-c/protobuf-c/) | >= 1.1.0 | for the [Protobuf format-type](formats/protobuf.md) | optional | similar to BSD | -| [protobuf](https://github.com/google/protobuf) | >= 2.6.0 | for the [Protobuf format-type](formats/protobuf.md) | optional | similar to BSD | -| [rabbitmq-c](https://github.com/alanxz/rabbitmq-c) | >= 0.8.0 | for the [AMQP node-type](nodes/amqp.md) | optional | MIT | -| [rdkafka](https://github.com/edenhill/librdkafka) | >= 1.5.0 | for the [Kafka node-type](nodes/kafka.md) | optional | BSD | +| Package | Version | Purpose | Optional | License | +| --------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------- | -------- | ------------------ | +| [CMake](http://cmake.org/) | >= 3.9 | for generating the build-system | required | BSD 3 | +| [fmtlib](https://github.com/fmtlib/fmt) | >= 6.1.2 | for string formatting | required | MIT | +| [libcurl](https://curl.haxx.se/libcurl/) | >= 7.29.0 | for HTTP REST requests by the [NGSI node-type](nodes/ngsi.md) node-type | required | similar to MIT | +| [libjansson](http://www.digip.org/jansson/) | >= 2.7 | JSON parser for [Websocket node-type](nodes/websocket.md) and [NGSI node-type](nodes/ngsi.md) node-types | required | MIT | +| [libuuid](https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git) | >= 2.29 | - | required | BSD | +| [libwebsockets](http://libwebsockets.org) | >= 3.1.0 | for the [Websocket node-type](nodes/websocket.md) | required | MIT | +| [openssl](https://www.openssl.org) | >= 1.0.0 | for cryptographic hashing functions | required | Apache 2 for >=3.0 | +| [spdlog](https://github.com/gabime/spdlog) | >= 1.8.2 | for logging | required | MIT | +| [comedilib](http://comedi.org) | >= 0.11.0 | for the [Comedi node-type](nodes/comedi.md) | optional | LGPL-2.1 | +| [Criterion](https://github.com/Snaipe/Criterion) | >= 2.3.1 | for running the unit tests | optional | MIT | +| [Etherlab](http://etherlab.org) | >= 1.5.2 | for the [Ethercat node-type](nodes/ethercat.md) | optional | __GPL 3__ | +| [Graphviz](https://graphviz.org/) | >= 2.30 | for the visualisation of configuration files | optional | EPL | +| [libconfig](http://www.hyperrealm.com/libconfig/) | >= 1.4.9 | for parsing the configuration file | optional | LGPL-2.1 | +| [libdatachannel](https://libdatachannel.org/) | >= 0.18.4 | for the WebRTC node-type | optional | MPL-2.0 | +| [libibverbs](https://github.com/linux-rdma/rdma-core) | >= 16.2 | for the [Infiniband node-type](nodes/infiniband.md) | optional | BSD | +| [libiec61850](http://libiec61850.com/libiec61850/) | >= 1.3.1 | for the [IEC61850-8-1](nodes/iec61850-8-1.md) and [IEC61850-9-2](nodes/iec61850-9-2.md) node-types | optional | __GPL 3__ | +| [libmodbus](https://libmodbus.org/) | >= 3.1.0 | for the [Modbus](nodes/modbus.md) node-type | optional | LGPL-2.1 | +| [libnanomsg](http://nanomsg.org/) | >= 1.0.0 | for the [Nanomsg node-type](nodes/nanomsg.md) | optional | MIT | +| [libnice](https://libnice.freedesktop.org/) | >= 0.1.16 | for libdatachannel / WebRTC | optional | MPL-1.1 & LGPL-2.1 | +| [libnl3](http://www.infradead.org/~tgr/libnl/) | >= 3.2.27 | for the network communication & emulation support of the [Socket node-type](nodes/socket.md) node-type | optional | LGPL-2.1 | +| [librdmacm](https://github.com/linux-rdma/rdma-core) | >= 16.2 | for the [Infiniband node-type](nodes/infiniband.md) | optional | BSD | +| [libre](http://www.creytiv.com/re.html) | >= 2.9.0 | for the [RTP node-type](nodes/rtp.md) | optional | BSD 3 | +| [libuldaq](https://github.com/mccdaq/uldaq) | >= 1.0.0 | for the [ULDAQ node-type](nodes/uldaq.md) | optional | MIT | +| [libxil](https://github.com/VILLASframework/libxil) | >= 1.0.0 | for the [VILLASfpga node-type](nodes/fpga.md) | optional | MIT | +| [libzmq](http://zeromq.org) | >= 2.2.0 | for the [ZeroMQ node-type](nodes/zeromq.md) | optional | MPL-2.0 | +| [Lua](http://www.lua.org/) | >= 5.1 | for the [Lua hook](hooks/lua.md) | optional | MIT | +| [mosquitto](https://mosquitto.org) | >= 1.4.15 | for the [MQTT node-type](nodes/mqtt.md) | optional | EPL 2 | +| [protobuf-c](https://github.com/protobuf-c/protobuf-c/) | >= 1.1.0 | for the [Protobuf format-type](formats/protobuf.md) | optional | similar to BSD | +| [protobuf](https://github.com/google/protobuf) | >= 2.6.0 | for the [Protobuf format-type](formats/protobuf.md) | optional | similar to BSD | +| [rabbitmq-c](https://github.com/alanxz/rabbitmq-c) | >= 0.8.0 | for the [AMQP node-type](nodes/amqp.md) | optional | MIT | +| [rdkafka](https://github.com/edenhill/librdkafka) | >= 1.5.0 | for the [Kafka node-type](nodes/kafka.md) | optional | BSD | There are three ways to install these dependencies: @@ -192,12 +216,10 @@ DEPS_INCLUDE='uldaq jansson' bash packaging/deps.sh DEPS_SKIP='libre rdkafka' bash packaging/deps.sh ``` -## Compile and install +### Compile VILLASnode `VILLASnode` uses CMake for the build and install process. -### Simple build - Simply build VILLASnode with all features available for the dependencies installed on your system. ```shell @@ -211,7 +233,7 @@ cmake --build ./build ./build/src/villas-node -h ``` -### Installation +### Install VILLASnode You can also install the binaries and tools into to your search path after building them. @@ -288,7 +310,7 @@ This can be achieved by using the `WITHOUT_GPL` CMake option: cmake -S . -B build -DWITHOUT_GPL=ON ``` -## Single-binary / Standalone Executable {#standalone} +## Pre-compiled standalone binary {#standalone} We provide single-binary / standalone executable builds of VILLASnode bundle all depdendencies in a [self-extracting ARX archive](https://en.wikipedia.org/wiki/Self-extracting_archive). These standalone binaries allow running VILLASnode irrespectively of the underlying Linux distribution or availability of library dependencies. @@ -311,7 +333,23 @@ The standalone VILLASnode binary is currently only compatible Linux systems runn - ARM v8 Aarch64 :::: -## Docker images {#docker} +## Pre-compiled RPM package {#rpm} + +VILLASnode can be installed from an pre-compiled package on systems with which use the RPM package manager, such as: + +- Fedora and derivatives +- Redhat Enterprise Linux +- CentOS stream +- Rocky Linux + +```shell +rpm \ + --install \ + --excludepath=/usr/lib/.build-id/ \ + 'https://git.rwth-aachen.de/api/v4/projects/79039/jobs/artifacts/master/raw/artifacts/villas-x86_64-linux.rpm?job=pkg:nix:rpm:%20[x86_64-linux]' +``` + +## Docker Images {#docker} There exists a set of Docker images for running and developing VILLASnode. Docker images are available for x86_64/amd64, armhf and arm64 architectures it you can run it also on a Raspberry Pi or other embedded platforms. diff --git a/docs/node/nodes/opal/index.md b/docs/node/nodes/opal/index.md index 15832052..ca69a536 100644 --- a/docs/node/nodes/opal/index.md +++ b/docs/node/nodes/opal/index.md @@ -2,19 +2,34 @@ hide_table_of_contents: true --- -# OPAL-RT Integration +# OPAL-RT Integration OPAL-RT logo There are three options to exchange simulation signals with an OPAL-RT real-time simulator: -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. +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). + Orchestra is OPAL-RT's co-simulation framework for integrating custom code and external models. + + The functionality is implemented by the [`opal.orchestra`](opal_orchestra.md) node-type. + + :::tip + This node-type is recommended for new setups. + ::: + +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). In this mode, OPAL-RT targets will send signals via a UDP socket to VILLASnode. - VILLASnode use the [`socket` node-type](../socket.md) node-type to send and receive these UDP packets. More information about our adapted AsyncIP example can be found here: [AsyncIP client](../../clients/opal_async_ip.md). -2. **[Orchestra](opal_orchestra.md):** VILLASnode can act as an Orchestra client. - Orchstra is OPAL-RT's co-simulation framework for integrating custom code and external models. - The functionality is implemented in the closed-source [`opal.orchestra`](opal_orchestra.md) node-type. + This functionality is implemented by the [`socket`](../socket.md) node-type. + + :::caution + This node-type is not recommended due to limited synchronizations, and limitations in I/O signal management. + ::: -3. **[Asynchronous Process](opal_async.md):** VILLASnode can act as an RT-LAB Asynchronous Process. +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). Data exchange is then handled using OPAL-RT's `libOpalAsyncApi`. - The functionality is implemented in the closed-source [`opal.async`](opal_async.md) node-type. + + The functionality is implemented by the [`opal.async`](opal_async.md) node-type. + + :::danger Deprecation + This node-type is deprecated and not recommended for new setups. + ::: \ No newline at end of file diff --git a/docs/node/nodes/opal/opal_async.md b/docs/node/nodes/opal/opal_async.md index 04710a99..47ef3ffa 100644 --- a/docs/node/nodes/opal/opal_async.md +++ b/docs/node/nodes/opal/opal_async.md @@ -1,8 +1,9 @@ --- hide_table_of_contents: true +sidebar_position: 99 --- -# OPAL-RT Asynchronous Process +# Asynchronous Process > 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. @@ -10,27 +11,30 @@ hide_table_of_contents: true 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. -## Prerequisites +:::danger[Deprecation] +The `opal.async` node-type is deprecated for the following reasons. -This node-types requires a running version of VILLASnode on an OPAL-RT target: +**Please consider the more actively supported [`opal.orchestra`](./opal_orchestra) node-type instead!** -- An OPAL-RT target running OPAL-RT Linux v3.4.1 or newer -- RT-LAB v2023.1 or newer +- The OPAL-RT **HYPERSIM** simulation environment is not supported. +- Older targets running RHEL / CentOS operating systems are not supported. +- Due to the shared-memory communication remote execution of VILLASnode is not supported. +- 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. +- 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. +::: -:::caution -The node-types requires the use of the RT-LAB simulation environment. -When using HYPERSIM, please consider the running VILLASnode as an [OPAL-RT Orchestra Client](opal_orchestra.md). +## Prerequisites -Older targets running RHEL / CentOS operating systems are not supported. -::: +This node-types requires a running version of VILLASnode on an OPAL-RT target: -## Implementation +- An OPAL-RT real-time simulator. +- 64-bit OPAL-RT Linux v3.4.1 or newer. +- RT-LAB v2023.1 or newer. -:::note -The implementation of the `opal.async` node-type is currently not open source. +## Implementation -Please contact [Steffen Vogel](mailto:steffen.vogel@opal-rt.com) if you are interested in run -::: +The source code of the node-type is available here: +https://github.com/VILLASframework/node/blob/master/lib/nodes/opal_async.cpp ## Installation @@ -76,7 +80,7 @@ During model load the configuration file will be loaded to the target and used b import ApiSchema from '@theme/ApiSchema'; -{/* */} +{/* */} ## Example diff --git a/docs/node/nodes/opal/opal_orchestra.md b/docs/node/nodes/opal/opal_orchestra.md index d4c4895f..d2ae07bb 100644 --- a/docs/node/nodes/opal/opal_orchestra.md +++ b/docs/node/nodes/opal/opal_orchestra.md @@ -1,26 +1,42 @@ --- hide_table_of_contents: true +sidebar_position: 1 --- -# OPAL-RT Orchestra +# Orchestra -Orchstra is OPAL-RT's co-simulation framework for integrating custom code and external models. -More information about Orchestra can be found in the [OPAL-RT Wiki](https://opal-rt.atlassian.net/wiki/spaces/PRD/pages/143626248/Orchestra). +Orchestra is OPAL-RT's co-simulation framework for integrating custom code and external models. +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). -## Prerequisites +:::tip +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. +::: -- `libOpalOrchestra.so` & `RTAPI.h` +## Prerequisites -## Implementation +- A OPAL-RT real-time simulator. +- 64-bit OPAL-RT Linux v3.4.1 or newer. + - `libOpalOrchestra.so` & `RTAPI.h` +- One of: + - RT-LAB v2025.1 or newer + - HYPERSIM v2025.3 or newer -:::note -The implementation of the `opal.orchestra` node-type is currently not open source. +:::info +The RT-LAB and HYPERSIM versions above were validated. Other versions might work as well. Use at your own discretion. +::: -Please contact [Steffen Vogel](mailto:steffen.vogel@opal-rt.com) if you are interested in run +:::caution +Older 32-bit OPAL-RT targets running RHEL / CentOS operating systems are not supported. ::: +## Implementation + +The source code of the node-type is available here: +https://github.com/VILLASframework/node/blob/master/lib/nodes/opal_orchestra.cpp + ## Installation +Please refer to the [Lab 21](../../guides/lab21) for a detailed guide on how to install VILLASnode on an OPAL-RT Real-time target. ## Configuration {#config} @@ -137,3 +153,17 @@ paths = ( } ) ``` + +## Running VILLASnode on a remote system + +Orchestra offers the possibility to run VILLASnode (as an Orchestra client) on a separate machine from the real-time target. +This allows for integration and Co-simulation external systems. +In this case signals between the client and the framework are exchanged over a TCP or UDP/IP connection. + +:::caution +This is an advanced use-case as it requires linking of VILLASnode against `libOpalOrchestra.so` on a non-OPAL-RTLinux system. + +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), +VILLASnode, should be already compiled with the necessary `libOpalOrchestra.so` library and `OrchestraExtCommIP` helper tool. +::: + diff --git a/external/controller b/external/controller index 039870a7..53324a18 160000 --- a/external/controller +++ b/external/controller @@ -1 +1 @@ -Subproject commit 039870a7b3e43121ba5bcfe8fa0f49898aea30ce +Subproject commit 53324a1872afd58ee173e693e5485b231a3e884d diff --git a/static/img/logos/opal-rt.svg b/static/img/logos/opal-rt.svg new file mode 100644 index 00000000..9b6795cb --- /dev/null +++ b/static/img/logos/opal-rt.svg @@ -0,0 +1,152 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/static/img/logos/opal.jpg b/static/img/logos/opal.jpg deleted file mode 100644 index ec5687ad..00000000 Binary files a/static/img/logos/opal.jpg and /dev/null differ