The DoocsMirror device

The DoocsMirror is a generic DOOCS bridge, which renders properties from one or more DOOCS locations to Karabo properties (slow or fast data, and images).

It is a C++ device which uses the DOOCS API to poll and set DOOCS properties for accessible DOOCS locations. More on DOOCS API can be found in this documentation.

The user specifies the list of DOOCS locations and properties before instantiation. After the instantiation, the mapped properties appear in device’s configuration with one to one mapping: each added property in this Karabo device corresponds to the DOOCS property of the location as specified before instantiation.

Instantiation and connection to the DOOCS locations

Before the device can be instantiated, all mandatory parameters should be specified, namely in the table of the parameter (DOOCS locations).

alternate text

The table should contain at least one row with values specified in all three columns:

  • Location Prefix: Location prefix that identifies the DOOCS server, like XFEL.FEL/UNDULATOR.ML/COLOR2.SA1.* expressions can be used.
  • Properties: Names of the properties to be exposed from the locations Matching the prefix expression. If multiple properties are provided, they have to be separated by commas.
  • Property Description: Description of the group of properties.

After the device is instantiated, it will connect to the requested DOOCS locations and will change its own state to State.ON. New properties will appear in the device’s configuration panel, each one mapping the Properties specified in the table DOOCS locations.

In case a DoocsMirror device goes to State.ERROR due to connection error, the device will try to reconnect automatically with reconnecting intervals as set by user in Reconnect Interval (in minutes).

Composite and non-composite mode

To enable the composite mode, the parameter Composite Behaviour must be set to True before instantiating the device.

In composite mode, the DoocsMirror device supports polling of multiple DOOCS servers in a single device instance. In this case, there will be a top-level node for each DOOCS location:

alternate text

If the Composite Behaviour is set to False, then the device ID must match the connected DOOCS location (with ‘.’ replaced by ‘_’), and there will be no node for the DOOCS properties:

alternate text

A Special Case: Images

In case one of the DOOCS property to be polled is an image, for example

alternate text

several properties will be created in the Karabo device:

alternate text
  • the Camera State, which can be either ON or ACQUIRING;
  • the Acquire button, to start polling images from the DOOCS location;
  • the Stop button, to stop polling images;
  • the DOOCS Exposure time (read-only).

The image correctly formatted for tha visualisation in the GUI are available in the GUI Output node. These images are not suitable for being sent to the DAQ.

The images in the correct format for the DAQ, can be found in the Output node, which also contains all the other fast properties.

Auto-generated Scene

By double clicking on the device in the project (as well as in the topology), the auto generate scene will pop-up.

In the composite mode, this overview scene

alternate text

will contain a link to the node scenes, e.g.

alternate text

In the case of non-composite mode, all the properties will be directly visible in the overview:

alternate text

How the key names of mapped parameters are generated

The karabo key of the exposed parameter is automatically generated by this rule: camel.case to camelCase, with DOOCS name applied as an alias to Karabo property. The alias will be in the location@property form, for example:

Displayed name of the property: ALLOW.MAX.E_PHOTON

Key: allowMaxEPhoton

Alias: XFEL.FEL/UNDULATOR.ML/COLOR2.SA1@ALLOW.MAX.E_PHOTON

In case of composite mode the keys generated will look differently, for example:

Displayed name of the node: XFEL.FEL/UNDULATOR.ML/COLOR2.SA1

Displayd name of the property: ALLOW.MAX.E_PHOTON

Alias: XFEL.FEL/UNDULATOR.ML/COLOR2.SA1@ALLOW.MAX.E_PHOTON

Key: XFEL_FEL_UNDULATOR_ML_COLOR2_SA1.allowMaxEPhoton

Polling frequency, when and how exactly are properties updated

Simple DOOCS properties are polled with the time interval set in the parameter Polling Interval (1000 ms by default), whereas for vector properties the Pulse Resolved Polling Interval (100 ms by default) is used, but another frequency might be agreed with the DOOCS side, depending on how the DOOCSserver is implemented in detail and on which kind of hardware it is running. Also a polling interval can be adjusted by DoocsMirror itself depending on the number of locations to be polled. See DOOCS manual documentation for more information on polling intervals.

Note:: in general there is no strict guarantee that DOOCS parameters will be polled with the exact polling interval set by the user.

Polling Interval: The interval for polling DOOCS for read-out values (ms). May be restricted depending on the total number of properties from locations to be polled.

Pulse Resolved Polling Interval: The interval for polling pulse resolved data from DOOCS for read-out values (ms).

Timestamps and trainID distribution

If a DOOCS property contains already a non-zero train ID, this will be kept as well for the corresponding Karabo property.

If there is no train ID provided by DOOCS for the property, then the Karabo device uses the time information (Epochstamp) provided by DOOCS to compute the corresponding train ID. This is extrapolated from the last value received from the Time Server.

For pulse-resolved properties, a maximum span of 10 train IDs per location and per update is allowed. If the span is larger, the exceeding train IDs will be dropped, and the DoocsMirror will go to ERROR.

Output channel and recording to DAQ

For each DOOCS location, a different output channel is created for the pulse-resolved data. These output channels provide DAQ compatible data.

Writing to DOOCS

The DoocsMirros currently provides read-only access to DOOCS properties.

Additional Information

  • The DoocsMirror allows at most 1000 properties to be polled, from at most 100 locations.
  • The Polling Interval might be automatically limited, so that no more than 100 properties are polled per second.
  • In the case of non-composite mode, the device ID must match the name of the DOOCS location (with dots replaced by underscores).

Examples

Given a Karabo device XFEL/RadMonIP_DarkCurrent/DC-014, to poll the DOOCS property MCA.DoseRateGamma at the DOOCS location XFEL/RadMonIP.DarkCurrent/DC-014, the table DOOCS locations should have the next values:

Location Prefix”: XFEL/RadMonIP.DarkCurrent/DC-014

Properties: MCA.DoseRateGamma

Property Description: <any kind of meaningful user-defined description>

After instantiation the property appears with such attributes:

Displayed Name: MCA.DoseRateGamma

Key: mcaDoserategamma

Alias: XFEL/RadMonIP.DarkCurrent/DC-014@MCA.DoseRateGamma

Known issues

  • Resources consumption (CPU/Memory) (important for CTRL group)