#27: Karabo URI Scheme¶

Karabo GUI: How to start the Karabo GUI from a link¶

The Karabo GUI, since version 2.10.2 and on Windows and Linux, provides a Uniform Resource Identifier (URI) scheme handler.

A scheme handler is a standard practice that some applications use to start up an application with a specific configuration without using a specific file launcher. This standard is similar to how web addresses are formatted and is independent from the operating system. For example, The URI scheme handling is used by Zoom to open the client when clicking on a link in a browser or a mail client using the protocol zoommtg (often mediated by a web link). and the mail client is connected to the protocol mailto.

The Karabo GUI uses a similar approach to implement a unified launching scheme for different operating systems. In all production systems, the Karabo GUI will be registered as the application capable of reading the URI scheme. In user installed system the user is required to register karabo as the application, to use this feature. The registration can be triggered by clicking on the menu bar the Settings menu, and Register Application within this menu. Alternatively the registration can be done with the karabo-register-protocol command from terminal. Please note that this operation should be executed in after each update if the name of the conda environment changes from the previous installation.

How to register the current version as a scheme handler¶

To create such a link, one needs to righ-click on a scene, and follow the wizards instructions.

right-clicking on a scene, on a project will show the Create cinema link option.¶

A wizard dialog will appear and guide the user through the procedure. In the first step the user can select if the splash-screen is shown and ifthe initial login dialog is shown or the hostname, port and user of the current session will be sent automatically.

The first step of the wizard.¶

The Karabo GUI currently needs network access to the port the GUI server is running, in applications within the same network (e.g. a link meant to be opened within the control network, the show login dialog option should be deselected/unticked to save some seconds. For a link meant to be shared outside the control network, were each user might have different port redirection solutions, the show login dialog option should be selected/ticked).

The next step will allow saving the URI into the clipboard as copied content.

The user can select either the URL form or the HTML tag depending on the use case.

The second and last step of the wizard.¶

This link can be copied into wiki pages or saved as a link according to the user preference.

The examples below show how one can include these links in different applications. Please be aware that the Karabo GUI application is not responsible for these external behaviours which are operating system dependent. The Karabo GUI application might not be able to guarantee external applications’ behaviour.

Known Issues¶

This launching system is currently not supported on MacOS and on WSL installations (Ubuntu installation within a Windows System).

Use Example: Redmine Wiki¶

The link created in the previous step can be copied in a Wiki link in Redmine with the redmine markdown format:

"Link to SASE1 overview - no host":karabo://cinema?domain=SA1&scene_uuid=9b9708ab-dd85-4e02-8dd5-ad8424794e63

This will appear as an hypertext link, but will open a karabo cinema link pointing the the uuid defined by the link.

Use Example: Grafana¶

The link created in the previous step can be pasted into a Grafana panel using the HTML format.

This solution allows complex Grafana panels to be interfaced easily with the corresponding Karabo scenes in case direct intervention is necessary.

One has to select the Text visualization option, within this mode, the HTML content mode, and insert the content as HTML.

In the example below one can see how the HTML link created by the wizard can be used in practice.

An example of how a URI can be exposed in Grafana as a link.¶

Use Example: Ubuntu desktop files¶

As an ulterior exable, one can open an URI link from a file with a .desktop extension. One has to create a text file called mylink.desktop on the Desktop and include the following text:

[Desktop Entry]
Name=SA1Overview
Type=Application
Exec=xdg-open 'karabo://cinema?domain=SA1&scene_uuid=5c646610-0290-4de2-af7f-a87510ecda1b&username=operator&host=sa1-br-sys-con-gui2&port=44444'

Where the karabo://.... is the link copied by the wizard. Note that for xdg-open the whole link must be defined as a single string.

This will appear in the Desktop as a link, one needs to enable the execution for the current user and “allow launching”. Follow these general instructions for Ubuntu 20 here: https://linuxconfig.org/how-to-create-desktop-shortcut-launcher-on-ubuntu-20-04-focal-fossa-linux

Please refer to the online documentation of your operating system for details.

Multiple scenes¶

A similar dialog can be used to generate a link able to open multiple scenes when invoked from the Scenes folder of a project. Multiple scenes can be selected or excluded in the second step of the wizard.

URI Format Details¶

The URI is currently supporting 3 applications: The Karabo GUI karabo-gui, the karabo-cinena and the karabo-theatre. Currently only the karabo-cinema option has a wizard to help link generation.

Wikipedia currently has a well written page on URIs, https://en.wikipedia.org/wiki/Uniform_Resource_Identifier

According to the IETF RFC 2396 definitions, the Karabo GUI follows these specs:

protocol : karabo
path : gui, cinema, theatre
query : options varies depending on the path

karabo-cinema format¶

If a URI’s format follows this pattern:

karabo://cinema?domain=TOPIC1&scene_uuid=this-is-not-an-uuid

will open the Karabo Cinema with domain set to TOPIC1 and scene_uuid set to this-is-not-an-uuid.

For the cinema, the options are:

domain: The project domain of the scene to be opened (Mandatory).
scene_uuid: The uuid of the scene to be opened (Mandatory).
username: The username to be selected, i.e. the access level (Optional).
host: The GUI server host (Optional).
port: The GUI server port (Optional).

karabo-theatre format¶

In the theatre path, in most cases, the url will be encoded. For example, this link:

karabo://theatre?scene_id=COMPONENT%2FTYPE%2FMEMBER%7CSCENEname

Will open a karabo-theatre pointing to the device generated scene: SCENEname of the device COMPONENT/TYPE/MEMBER.

The options for theatre are:

scene_id: The identifier of the scene from a device (Mandatory).

note: / and | symbols need to be urlencoded, for example COMPONENT/TYPE/MEMBER|SCENEname encodes to COMPONENT%2FTYPE%2FMEMBER%7CSCENEname
use this online helper as a sandbox https://meyerweb.com/eric/tools/dencoder/
username: The username to be selected, i.e. the access level (Optional).
host: The GUI server host (Optional).
port: The GUI server port (Optional).

karabo-gui format¶

If a URI follows this format:

karabo://gui

The link will open the registered GUI client if the application is registered. It currently has no optional arguments.