Skip to main content

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.

tip

Please familiarize yourself first with Orchestra using the OPAL-RT Wiki before attempting to use it with VILLASnode.

Prerequisites​

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

The RT-LAB and HYPERSIM versions above were validated. Other versions might work as well. Use at your own discretion.

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 for a detailed guide on how to install VILLASnode on an OPAL-RT Real-time target.

Configuration​

Reference​

domain
required
string

The name of the domain to which the connection is requested. This domain must exist in the DDF read by an RT-LAB subsystem.

synchronous
boolean

Determines whether domain participants exchange simulation data synchronously or asynchronously.

states
boolean
object (opal_orchestra_connection)

Configuration of the connection to the OPAL-RT Orchestra framework.

ddf
string

The path to the DDF file that describes the data exchanged in the specified domain.

string or integer (duration)
string or integer (duration)
string or integer (duration)
skip_wait_to_go
boolean
Default: false

Sets the WaitToGo setting of the model. When true, VILLASnode ignores the WaitToGo during the connection step. When false, VILLASnode performs the WaitToGo during the connection step.

ddf_overwrite
boolean
Default: false

If true, the DDF file provided in the 'dff' setting will be overwriting with settings and signals from the VILLASnode configuration.

ddf_overwrite_only
boolean
Default: false

If true, VILLASnode will overwrite the file provided in the 'ddf' setting, and terminate immediately afterwards.

rate
number
Default: 1

In asynchronous mode (see 'synchronous' setting), this rate defines how often per second the data exchange with the Orchestra domain takes place.

object (Input configuration (received by VILLASnode))
vectorize
integer
Default: 1

This setting allows to send multiple samples in a single message to the destination nodes.

The value of this setting determines how many samples will be combined into one packet.

Array of Hook Object (object) or Hook Name (string) (hook_list)
builtin
boolean (Builtin hook functions)
Default: true

By default, each node and paths has a couple of default hooks attached to them. With this setting the attachment of built-in hooks can be disabled.

object (Output configuration (sent out by VILLASnode))
{
  • "domain": "string",
  • "synchronous": true,
  • "states": true,
  • "connection": {
    },
  • "ddf": "string",
  • "connect_timeout": "6d23h30m50s40ms",
  • "flag_delay": "6d23h30m50s40ms",
  • "flag_delay_tool": "6d23h30m50s40ms",
  • "skip_wait_to_go": false,
  • "ddf_overwrite": false,
  • "ddf_overwrite_only": false,
  • "rate": 1,
  • "in": {
    },
  • "vectorize": 1,
  • "hooks": [
    ],
  • "builtin": true,
  • "out": {
    }
}

Example​

node/etc/examples/nodes/opal_orchestra.conf
stats = 1

nodes = {
    domain1 = {
        type = "opal.orchestra"

        # Path  to the OPAL-RT Orchestra Data Definition XML file (DDF).
        ddf = "orchestra.xml"

        # Enable to overwrite the DDF file.
        # This is useful when you want to generate the DDF file from the configuration file
        # for importing it into RT-LAB or HYPERSIM.
        ddf_overwrite = true

        # Orchestra domain name.
        domain = "domain1"

        # Connection timeout. In seconds.
        connect_timeout = "2s"

        # Define the delay to wait when using flag synchronisation (XHP).
        # This will call the system function usleep and free the CPU.
        # In micro-seconds.
        flag_delay = "5us"

        # Force the local Orchestra communication to be made with flag instead of semaphore when using an external communication process.
        # Define the delay to wait, this will call the system function usleep and free the CPU.
        # In micro-seconds.
        flag_delay_tool = "5us"
        skip_wait_to_go = false

        rate = 500.0;

        # The following parameters are used to generate the Orchestra DDF XML file.
        synchronous = false
        states = false
        multiple_publish_allowed = false

        connection = {
            # One of: local, remote or dolphin
            type = "local"

            # For 'local'
            extcomm = "udp";
            addr_framework = "127.0.0.1";
            port_framework = 10000
            core_framework = 0
            core_client = 0
            nic_framework = "eth0"
            nic_client = "eth0"

            # For 'remote'
            card = "test"
            pci_index = 0

            # For 'dolphin'
            node_id_framework = 0
            segment_id = 0
        }

        in = {
            hooks = (
                { type = "stats" },
                { type = "print" }
            )

            signals = (
                {
                    name = "pub_signal1"
                    type = "float"

                    orchestra_name = "pub_signal_float"
                    orchestra_type = "float64"
                    orchestra_index = 0
                },
                {
                    name = "pub_signal2"
                    type = "float"

                    orchestra_name = "pub_signal_float"
                    orchestra_type = "float64"
                },
                { name = "signal_float", orchestra_name = "some_bus/signal_float", orchestra_type = "float64", orchestra_index = 2 },
                { name = "signal_bool", orchestra_name = "some_bus/signal_bool", orchestra_type = "boolean" },
                { name = "signal_uint8", orchestra_name = "some_bus/some_nested_bus/signal_uint8", orchestra_type = "unsigned int8" },
                { name = "signal_uint8_2", orchestra_type = "unsigned int8" }
            )
        }

        out = {
            signals = (
                { name="sub_signal_float", init = 1.2, orchestra_name = "sub_signal_float", type = "float" }
            )
        }
    }
}

paths = (
    {
        in = "domain1"
        out = "domain1"
    }
)

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, or using any of the by-Nix pre-compiled installations options like the standalone or .rpm packages or Docker images, VILLASnode, should be already compiled with the necessary libOpalOrchestra.so library and OrchestraExtCommIP helper tool.