Versions Compared

Old Version 3

changes.mady.by.user Louis-Philippe Bell

Saved on

compared with

New Version Current

changes.mady.by.user Louis-Philippe Bell

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
← Previous

Next →

...

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

...

term “Python API” is mentioned in this documentation, the reader

...

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

Code Block
languagenone
linenumbersfalse
python C:\OPAL-RT\OpalOne\<version>\api\client\python\install_opalone_api.py
Tip

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

Note

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,

...

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.

...

refer to the pip documentation.

Example scripts

...

Description

...

File

...

1

...

2

(1) Print information about datapoints of a given project

Download print_datapoints_example.py

Usage:

python print_datapoints_example.py <name>

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

...

print_datapoints_example.py

...

3

(2) A step by step example to generate a panel for a project

Download panel_creation_example.py

Usage:

python panel_creation_example.py

Tip

Before using, make sure you setup the following:

  1. Create a project in RT-LAB, with any name you want, and use basic/rtdemo1 as a template project.

  2. Compile the rtdemo1 model for simulation on localhost (Windows) with your preferred version of Matlab.

  3. When compilation is done, open the Dashboards UI from RT-LAB.

  4. In the navigation pane on the left, click on your model’s name and check that the model’s datapoints are showing.

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

Download simulations_example.py

Usage:

python simulations_example.py <name>

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

...

(4) Export a panel to a JSON file

Download export_panel_example.py

Usage:

python export_panel_example.py

Tip

Before using, please consider the following:

  1. Export Location:

    • By default, the panel exports in a folder under the project path.

    • You may specify CUSTOM_EXPORT_PATH if needed.

  2. Script Environment:

    • In a Dashboards environment, the current project is retrieved automatically.

    • In an external environment, specify PROJECT_PATH to retrieve the project containing the panel to export.

(5) Import a panel from a JSON file

Download import_panel_example.py

Usage:

python import_panel_example.py

Tip

Before using, please consider the following:

  1. Import Location:

    • By default, the panel folder to import must be in project path.

    • You may specify CUSTOM_IMPORT_PATH if needed.

  2. Script Environment:

    • In a Dashboards environment, the current project is retrieved automatically.

    • In an external environment, specify PROJECT_PATH to retrieve the project containing the panel to import.

Uninstalling

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

Code Block
languagenone
linenumbersfalse
pip uninstall opalone opal-unified-api-client

Answer yes if/when prompted.