The Command Line Interface (CLI)¶

The karabo scan device comes with a dedicated command line interface. Similar to ikarabo an IPython shell is launched. In this python shell a scan client is created and registered on the broker to communicate with the desired scan device.

In order to connect to a scandevice, a SCANDEVICE variable has to be defined in the environment of the operating system:

export SCANDEVICE=DEVICEID_SCANDEVICE

Once the scan device is exported, type karabacon and follow the initialization. The scan client is automatically updated during a scan and retrieves the messages from the scanDevice. Hence, the configuration and scan messages in the graphical user interface and the command line are identical.

Note

For any CLI command the brackets don’t have to be typed. The karabacon CLI is configured to use the IPython autocall option, e.g. to view the data source environment:

sources() -> sources

In general, the command line interface follows spec syntax!

Configure the scan environment¶

Before a scan can be launched the scan environment has to be configured. This is required for the scan device to know which triggers and data sources have to be considered (and plotted) in a scan. In addition, this information is provided to the XFEL DAQ system for recording data. The actual configuration can be viewed by:

def status():
   """Retrieve the full status of the scan device

   - Current configuration for motors, triggers and data sources
   - State of the scan device

In general, the scan device knows the last active configuration and won’t perform a new configuration if the settings do not change between scans.

Since the motor environment is most likely the device which change between scans, the motors are configured with the scan function directly. The overview of the motor environment can be viewed by:

def motors():
    """Retrieve the full motor environment"""

Data sources¶

Data sources are most likely passive providers of data. The selected sources will be plotted by the scantool. Data sources can be viewed and configured via:

def sources():
    """Show the available data sources environment of the scan device
    """

def add_sources(alias):
    """Add desired sources to the scan environment

    :alias: Alias of the sources (string)
    """

def remove_sources(alias):
    """Remove desired sources from the scan environment

    :alias: Alias of the sources (string)
    """

Note

The alias for data sources MUST NOT be unique. Hence multiple data can be configured at once.

Triggers¶

Triggers are active devices which are responsible for producing data. Triggers can be viewed and selected via:

def triggers():
    """Show the available trigger environment
    """

def add_trigger(alias: (str,)):
    """Add a single trigger to the active scan environment

    :alias: Alias of the trigger
    """

def remove_trigger(alias: (str,)):
    """Remove a single trigger from the active scan environment

    :alias: Alias of the trigger
    """

Note

The alias for triggers MUST be unique. The first trigger with found with given alias is taken.

Launching scans¶

In general, the motors for a scan are always selected in the scan function. Simply provide a matching alias (string type) of the motor environment. Absolute scans and relative scans are provided and follow the described stopping policy.

The following scan functions are provided in the command line interface

def ascan(axis, start, stop, steps, acqtime, wait)
     """Perform an absolute step scan with the scan device

     :axis: alias(es) of the motor axis (str, list or tuple)
     :start: start point(s) of the axis (int, float, list or tuple)
     :stop: stop point(s) of the axis (int, float, list or tuple)
     :steps: number of steps (int)
     :acqtime: acquisition time per step (int, float)
     :wait: Set to True to wait till scan ends

     If the acquisition parameter is 0, the trigger devices
     are not configured.

     NOTE: After the scan, the motors stay a final position.
     """

 def dscan(self, axis, start, stop, steps, acqtime, wait):
     """Perform a relative step scan with the scan device

     :axis: alias(es) of the motor axis (str, list or tuple)
     :start: start point(s) of the axis (int, float, list or tuple)
     :stop: stop point(s) of the axis (int, float, list or tuple)
     :steps: number of steps (int)
     :acqtime: acquisition time per step (int, float)
     :wait: Set to True to wait till scan ends

     If the acquisition parameter is 0, the trigger devices
     are not configured.

     NOTE: After the scan, the motors will move back to start position.
     """

 def cscan(self, axis, start, stop, steps, acqtime, wait):
     """Perform a continuous scan with the scan device

     :axis: alias(es) of the motor axis (str, list or tuple)
     :start: start point(s) of the axis (int, float, list or tuple)
     :stop: stop point(s) of the axis (int, float, list or tuple)
     :acqtime: acquisition time per step (int, float)
     :wait: Set to True to wait till scan ends

     If the acquisition parameter is 0, the trigger devices
     are not configured.

     NOTE: After the scan, the motors will move back to start position.
     """

 def tscan(self, acqtime, wait):
     """Perform a time scan with the scan device

     :acqtime: acquisition time
     :wait: Set to True to wait till scan ends
     """


 def mesh(self, axis, start, stop, steps, acqtime, bidirectional=False, wait):
     """Perform an absolute mesh step scan with the scan device

     :axis: aliases of the motor axis (list or tuple)
     :start: start points of the axis (list or tuple)
     :stop: stop points of the axis (list or tuple)
     :steps: number of steps (list or tuple)
     :acqtime: acquisition time per step
     :bidirectional: Set to True for a snake scan
     :wait: Set to True to wait till scan ends

     This scan performs a mesh scan - Depending on the setting for
     a *True* bidirectional input, the scan is performed as a snake scan.

     If the acquisition parameter is 0, the trigger devices
     are not configured.

     NOTE: After the scan, the motors stay a final position.
     """


 def dmesh(self, axis, start, stop, steps, acqtime, bidirectional=False, wait):
     """Perform a relative dmesh step scan with the scan device

     :axis: aliases of the motor axis (list or tuple)
     :start: start points of the axis (list or tuple)
     :stop: stop points of the axis (list or tuple)
     :steps: number of steps (list or tuple)
     :acqtime: acquisition time per step
     :bidirectional: Set to True for a snake scan
     :wait: Set to True to wait till scan ends

     This scan performs a dmesh scan - Depending on the setting for
     a *True* bidirectional input, the scan is performed as a snake scan.

     If the acquisition parameter is 0, the trigger devices
     are not configured.

     NOTE: After the scan, the motors will move back to start position.
     """

Stopping Scans¶

Scans can be stopped or aborted. Aborting a scan means, that no motor will move back to start position (valid for relative scans.):

def stop():
    """Stop a running scan from the scan device
    """

def abort():
    """Abort a running scan from the scan device
    """