General Information

Supported devices

The scantool distinguishes three different device types: Triggers, Data Sources and Motors. These devices either have a standardized interface, or the support of the device is explicitly integrated in an alias mapping within the scantool.

The motor and data source devices can have different axes and sources. An example for a multiple axis system is a slitsystem inheriting five (5) axis - default, x, y, gapx, gapy. A default axis is always provided, in case of the slitsytem the default is the x axis.

The following devices are currently integrated.

Motors

Following device classes as motor interfaces are supported:

Motors	axis name
BeckhoffMC2Base	default
BeckhoffMC2Beckhoff	default
BeckhoffMC2Technosoft	default
BeckhoffMC2Elmo	default
BeckhoffMC2Hexapod	default
BeckhoffSimpleMotor	default
DoocsPhaseshifter	default
CrystalManipulator	default
CrystalManipulatorGroup	default
DoocsOpticalDelay	default
DoocsPhaseshifter	default
DoocsUndulatorEnergy	default
JJAttenuator	default
MonoChromator	default
MonoChromatorGroup	default
MonoChromatorEnergyChanger	default
OpticalDelay	default
PicoMotor	default
PpLaserDelayCopy	default
RobotManipulatorStaubli	default
SlitSystem	default, x, y, gapx, gapy
SoftMono	default
TangoMotor	default
X2TimerML	default

If the device to be scanned is not in the list of supported devic classes then it might be integrated via abstract motor interface.

Abstract Motor Interface

A device might have interfaces property that defines interfaces it is compatbile with. If the interface property contains Motors then first the Standard motor with limits interface with following mandatory properties:

• actualPosition (DOUBLE/FLOAT)

• targetPosition (DOUBLE/FLOAT)

• isCWLimit (BOOL)

• isCCWLimit (BOOL)

• isSWLimitHigh (BOOL)

• isSWLimitLow (BOOL)

and commands

• move

• stop

is validated. If one or several properties or commands are missing then the device is validated against the Standard motor without limits interface. Such a device should contain the actualPosition, and targetPosition properties and move, stop commands.

In general, it is expected that a motor device has the state State.ON when it is ready to move and goes to State.MOVING when it is moving towards the target position. If a motor is following the target position, it is expected to use State.ACTIVE instead of State.ON.

Custom Motor Interface

If the requested scan device is not supported with the abstract motor interface, then there is a possibility to use custom a motor interface. The device has to be added as a motor with custom axis definition starting with “custom#”:

• Mandatory attributes are actualPosition and targetPosition: custom#actualPosition=someReadProperty&targetPosition=someWriteProperty

• Other attributes isCWLimit, isCCWLimit, isSWLimitHigh, isSWLimitLow, move, stop and state are not mandatory.

• Example of custom motor having move and stop slots and soft-limit switches: custom#actualPosition=actual&targetPosition=target&move=moveSlot&stop=stopSlot&isSWLimitLow=limitLow&isSWLimitHigh=limitLow

Fig. 1 Custom motor definition in the device tree.

Data sources

Data sources are considered to represent a single point of data on device level. Any scalar attribute of any karabo device can be added as a data source. Therefore there is no default value anymore. An internal mechanism considers if the data source is a pipeline value or not. If the data source depends on the pipeline processing, the data source is awaiting for a small amount of time (~second) a new value. It is possible to use vector data source. Currently ascan and dscan in Single acquisition mode with one vector data source is supported. Scan is plotted as a mesh scan.

Warning

The “Data Sources” table does not replace the DAQ. It should be used only for online preview and alignment. Data should be recorded by the properly configured DAQ.

Triggers

Triggers are a key element of the scantool. They trigger the data generation for the data sources. In the scantool the acquisition of all trigger devices is done in a synchronous way by software.

The scantool can only perform basic trigger configuration. Specialized setup must be done manually. The operator must also be familiar with the particular trigger device: some devices can take minutes to configure, others carry significant overhead or synchroniztion issues. The online preview data is collected after the ACQUISITION of all data triggers has completed. Supported devices are:

• LPDMainControl

• GotthardDetector

• JungfrauDetector

• AdqDigitizer

• GreatEyes

• SimulatedTrigger

• AgipdComposite

• PulsePickerTrigger

• DoocsPulseKicker

The trigger devices (device developers) are responsible to provide

• A start acquisition slot

• An acquisition time property (FLOAT) which configures the trigger

A common state behavior for a trigger device is:

• State.PASSIVE (Derived): Trigger is NOT ready for data acquisition

• State.ACTIVE (Derived): Trigger IS ready for data acquisition

• State.ACQUIRING (Derived): Trigger is acquiring data

Warning

CAMERAS are not supported as trigger sources as they don’t tell us when the acquisition is done. Just make sure the camera is ACQUIRING data.

Note

Unfortunately AGIPD cannot be supported at the moment as this device does not provide any information if it is ACQUIRING data or not.

Note

Depending on the type, scan does not always require motors, data sources and triggers.

Scan devices are stored in deviceEnv.motors, deviceEnv.sources and deviceEnv.triggers tables and can be edited via device tree available in the device scene.

Scans

The scantool provides following scans:

Name	Description
ascan	Linear step scan with up to 4 motors. Uses absolute coordinates and stays at last position.
dscan	Linear step scan with up to 4 motors. Uses relative coordinates and returns to start.
cscan	N dimensional fly scan based on absolute coordinates. These are start and go fly scans with optional velocity setting. If the velocity control is set, motor velocities will be set based on the exposure time. Most motors do not support velocity setting and others have severe restrictions (also in hardware).
tscan	Scan without the motor movement. For defined time acquires data from sources.
mesh	2D scan based on absolute coordinates.
dmesh	2D scan based on relative coordinates.
custom	Step scan uses absolute coordinates defined in the scanEnv.customScanPattern.
external	Linear step scan with up to 4 motors. Uses externaly retrieved scan pattern

• At the moment, scans with up to 4 motors and 6 data sources are available.

• Based on the scan type start and stop positions of motors and the number of scan steps has to be provided.

• After moving motors to the start positions, they are locked by the scantool and unlocked at the end of the scan or when the scan is paused.

• For details on how to use custom scans see: Custom Scan Patterns.

Acquisition Modes

For step scans acquistionMode property can be used to adjust the data acquisition mode:

• Single: Acquire data once after the acquisition time.

• Continuous: Continuous data acquisition during the acquisition time, excluding motor movement.

• Continuous Averaged: Average acquired data over the acquisition time.

• Continuous Extended: Continuous data acquisition during the acquisition time and motor movements.

Property is available as a combo box in the main scene.

Device Related Settings

Name	Attribute	Default	Description
Use DAQ	deviceEnv.useDaq	False	Use DAQ
Acquisition Time	deviceEnv.acquisitionTime	0.1 sec	Vector of acquisition times per step
Mottor settling time	deviceEnv.motorSettlingTime	0.0 sec	After motor movement wait this time before further action
Configure Triggers	deviceEnv.configureTriggers	False	True: Triggers will configure the acquisition time
Configure Velocity	deviceEnv.configureVelocity	False	Control motor velocity in cscan based on the acquisition time
Pipeline Wait	deviceEnv.pipelineWait	1.5	Time for the pipeline data sources to wait for a new value
Vector Data range	deviceEnv.vectorDataRange	0	List of one or two integers define slice of vector data

Note

• Acquisition time is taken into account if the configureTriggers is set to True.

• It is a vector of floats and should contain at least one value.

• If a single value is defined then this acquisition time will be used for all steps.

• Number of acquisition time values in the vector should be equal to the number of scan steps +1.

• If the number of values in the vector is less then number of steps + 1,

then missing values are equal to the last value of the vector.

Scan Environment Settings

Name	Attribute	Default	Description
Comment	scanEnv.comment	“”	Free form text to describe the executed scan.
Bidirectional	scanEnv.bidirectional	False	Enable bidirectional (snake) mesh scan

Stopping Policy

The XFEL scantool comes with a defined stopping policy

• Absolute scans: The motors stay a final position.

• Relative scans: The motors will move back to start positions.

• Stopping scan: see absolute and relative scan behavior.

• Aborting scan: If a motor experiences an unexpected behavior during scan (e.g .error state), the scan will abort and the motors won’t be moved any further.

Note

A scan can be manually aborted and subsequently any post scan action (move back to start position) is not executed.