Skip to content

lab21.md

Latest commit

 

History

History
128 lines (90 loc) · 6.85 KB

lab21.md

File metadata and controls

128 lines (90 loc) · 6.85 KB
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 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 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:

$ ssh root@<target-ip-address>

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 are supported as well.

4. Create a VILLASnode Configuration File: orchestra.conf

Next, we create a VILLASnode configuration file named an place it into the RT-LAB model directory:

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 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