[Py] Usage

The Dashboards application is part of the Opal One software suite developed by OPAL-RT. This software suite comes with a REST API (HTTP protocol) to ensure communication between the UI (User Interface) and the backend server.

The Extended Python API for Dashboards is a wrapper on top of that REST API. It allows interaction with the backend server using a Python script. This Python script takes the role of “yet another client”, just like the Dashboards UI.

The main goal of having a Python client is to automate interactions with the backend server. This allows the user to rapidly and programmatically create panels, widgets, connections and so on.

The two layers of the Python API

There are two layers composing the Python API. The one presented in this documentation is a high-level wrapper designed on top of a low-level API.

Whenever the terms “Python API” is mentioned in this documentation, the reader must see this as the high-level wrapper API, unless specified otherwise.

After installation of the high-level Python API, the user can observe two Python packages related to OPAL-RT when running the command pip list:

opalone: The high-level, user API (users shall use this one)
opal-unified-api-client: The low-level API (users shall avoid using this one directly).

Installing

The installation of Dashboards includes a set of Python wheels that can be installed in the Python environment of your choice. You can find the wheel files in your Opal One installation folder. To install the wheels:

python C:\OPAL-RT\OpalOne\<version>\api\client\python\install_opalone_api.py

In the above command, replace <version> with your actual installed version.

The above command assumes you have a functional Python interpreter, version 3.7+ installed on your machine and that you also have the path to the pip tool in your PATH environment variable. To troubleshoot your Python environment with pip, see this documentation.

For HYPERSIM users

In the HYPERSIM context, the folder C:\OPAL-RT\OpalOne\<version>\api\client\python does not exist. Instead, the wheels can be found in C:\OPAL-RT\HYPERSIM\<hs_version>\Windows\OpalOne\api\client\python.

Please note that the script install_opalone_api.py is not available in this installation context.

Example scripts

Description

File

1

Print information about datapoints of a given project.

Usage:

python print_datapoints_example.py <name>

<name>: The name of an open project in RT-LAB

print_datapoints_example.py

2

A step by step example to generate a panel for a project.

Usage:

python panel_creation_example.py

Before using, make sure you setup the following:

Create a project in RT-LAB, with any name you want, and use basic/rtdemo1 as a template project.
Compile the rtdemo1 model for simulation on localhost (Windows) with your preferred version of Matlab.
When compilation is done, open the Dashboards UI from RT-LAB.
In the navigation pane on the left, click on your model’s name and check that the model’s datapoints are showing.
Check that the model state is “Loadable” since the model was compiled in RT-LAB.

panel_creation_example.py

3

Run model simulations of a given project.

Usage:

python simulations_example.py <name>

<name>: The name of an open project in RT-LAB

simulations_example.py

Uninstalling

To uninstall the wheel packages from your Python installation, run the following command:

pip uninstall opalone opal-unified-api-client

Answer yes if/when prompted.