Welcome to Karabo DOOCS Integration’s documentation!¶
Contents:
DOOCS to Karabo Enhancement Design¶
Motivation¶
- The main motivation of this enhancement design is to provide user friendly interface to our instrument scientists to import DOOCS data/devices to the Karabo ecosystem without involving much effort from the Controls group side.
- To have one-to-one connection between DOOCS and Karabo which enables load / throughput tuning between the two control systems at the single tuning point.
- To have unified interface which shows the list of all the devices “cloned” in Karabo.
Implementation overview¶
Overview of the implemented design is shown in the figure below:
- Dedicated “DOOCS” topic: Dedicated “DOOCS” topic has been created to have a one-to-one connection between DOOCS and Karabo, which enables load/throughput tuning between the two control systems at the single tuning point.
- Devices involved: The concept is surrounded around the following devices:
- DOOCS Mirror device: It is a generic DOOCS bridge, which imports DOOCS data(slow or fast data, and images) to Karabo ecosystem.
- Doocs Manager device: It is responsible for managing and instanating the DoocsMirror device upon the request of DoocsRequestor.
- Doocs Requestor device: It acts as the request gateway for a DOOCS location and properties, whether or not they have been requested already (whether through the same Karabo topic or another). There is one DoocsRequestor device per Karabo topic.
- Device Clone: It is used to clone to DoocsMirrors device from one topic to another.
Workflow¶
The workflow diagram is shown in the figure below:
- User requests needed “bridge” of the DOOCS location using the interface of the DoocsRequestor located in the specific Karabo topic.
- The DoocsRequestor passes the request to the DOOCSManager device located in the dedicated “DOOCS” topic.
- DoocsManager checks if for the requested location/properties corresponding DoocsMirror device is already instantiated and instantiate new one if needed.
- DoocsMirror devices take care of the communication between DOOCS and Karabo. They are instantiated in the “DOOCS” topic and cloned to the specific Karabo topic.
The DOOCS Manager Device¶
The DOOCS manager device maintains a list of available DOOCS locations, which can be exposed in the Karabo topology as DOOCS mirror devices.
The DOOCS manager takes care of instantiating the needed mirror devices if they are missing, upon request of the DoocsRequestor.
Note that this device is not meant to be exposed to the beamline operators. Users who would like to access DOOCS devices from Karabo should instead use DoocsRequestor.
Note that the DOOCS manager device runs in a dedicated Karabo topic (called DOOCS) and it must be cloned in the instrument topic.
To get started, double click on the device in the topology panel to display the device scene.
A series of drop-down selections following the DOOCS nomenclature (Facility, Device, Location, Property) allows the user to browse across for DOOCS locations and select the DOOCS properties that need to be accessed via Karabo.
Once the selection is complete, the DOOCS manager goes into the ‘FILLING’ state. To confirm the selection, one must press the Add button. To abort the operation, press the Cancel Adding button.
After hitting Add, the property is added to the relevant DOOCS mirror device. If no DOOCS mirror corresponding to the selected DOOCS location is running, one is automatically instantiated. Such events are logged in the upper part of the scene.
The Refresh button re-instantiates all the missing DOOCS mirrors that are needed to access the selected properties from the ones listed in Configured DOOCS Mirror Devices.
The Reset button clears the current selection.
The bottom left table (Configured DOOCS Mirror Devices) displays all the DOOCS locations and their associated properties requested since the manager device was instantiated. The bottom right one (Online DOOCS Mirror Devices) lists the online DOOCS mirror devices and their status in the current topic.
Note that from the latter table the DOOCS mirror scenes can be easily accessed.
Troubleshooting¶
If the device tables do not display in the device scene, you might need to update your GUI extentions:
- Access the XFEL VPN if you are not inside the European XFEL internal network.
- On your GUI menu select Help->Check for updates.
- Click on the ‘refresh’ button
- Click on ‘Update’
The DOOCS Requestor Device¶
The DoocsRequestor device acts as the request gateway for a DOOCS location and properties, whether or not they have been requested already (whether through the same Karabo topic or another). There is one DoocsRequestor device per Karabo topic.
The device provides an overview of the available DOOCS locations. The user can browse through the lists of locations according to the DOOCS nomenclature - first through Facility then Device, Location, and finally Property.
The DoocsRequestor keeps the list of currently “active” requested locations/properties and also the list of locations/properties requested in the past.
After the user has made a request for specific DOOCS location/property an instance of DoocsMirror will be created behind the scenes (or the existing one will be used if the corresponding DOOCS location is already “bridged” in any Karabo topic). DoocsMirror devices act like “bridges” between DOOCS locations and Karabo. They can be added then to the DAQ for storing “bridged” locations/parameters.
Note
There is always a one-to-one correspondence between the requested DOOCS locations and the DoocsMirror devices. Each DoocsMirror represents (“bridges”) only one DOOCS location with a subset of the properties available in the DOOCS location.
This device works with a DoocsManager device behind the scenes.
Instantiation¶
Normally the DoocsRequestor device is instantiated automatically without the need for the user to instantiate it. There is always only one DoocsRequestor device in the Karabo topic; if you don’t know the exact Karabo project try searching DoocsRequestor in the GUI’s System Topology to find the instantiated device. After instantiation the device should go to the ACTIVE state.
Requesting DOOCS locations and parameters¶
In order to add locations using the device generated scene:
- Double click on the device in the System Topology or the Projects in the Karabo GUI. The auto-generated scene will appear.
- Choose DOOCS location and property according to the DOOCS nomenclature by specifying through a series of drop-down selections Facility, Device, Location and Property:
Note that after the selection is made in all of the drop down lists, the device goes to the FILLING state
- Click the ADD button (or click Cancel Adding to cancel):
The property specified by the user will be then added to the corresponding DoocsMirror (to the existing one, or a new one will be automatically instantiated). The Location and Property will appear in the Saved DOOCS Mirror Devices widget table on the scene (it corresponds to the table DOOCS Locations in device’s configuration editor):
Adding Location/Property will automatically create a DOOCS Mirror device (or the existing one will be used) which then appears in the Online Doocs Mirror Devices table. Mirror devices are listed with their Karabo name (Name), mirror connection (Mirror Connection, which can be on, error or unknown), link to the mirror’s own scene (Scene Link) and actual status of the mirror device (Status)
Refresh¶
If in the Online DOOCS Mirror Devices table, some DoocsMirror device is missing for the property/location listed in the Configured Doocs Mirror Devices table, it is possible to instantiate it by clicking the Refresh button.
Resetting the selection¶
To reset the current selection, click Reset.
Opening the auto-generated scene of the DoocsMirror¶
In order to open directly the autogenerated scene of the DoocsMirror, click the corresponding button Scene Link on the table Online DOOCS Mirror devices as shown in figure below:
The Saved DOOCS Mirror Devices table popup menu¶
- Right-click on a row in the Saved DOOCS Mirror Devices table. The popup menu will appear as shown in figure below:
- Selecting Remove Device in the popup menu will remove a location row from the Saved DOOCS Mirror Devices table.
Troubleshooting¶
- If a device seems stuck in the FILLING state for too long (and no one seems to be operating it at the moment), try to cancel with the Cancel Adding button. The device should return to the ACTIVE state.
- If the device tables do not display in the device scene, you might need to
update your GUI extensions:
- Access the XFEL VPN if you are not inside the European XFEL internal network.
- On your GUI menu select Help->Check for updates.
- Click on the ‘refresh’ button .
- Click on ‘Update’.