.. raw:: html

    <style> .red {color:#aa0060; font-weight:bold; font-size:16px} </style>

.. role:: red

.. _KaraboChapter:

pnCCD Control Software 
======================

Karabo
------

Similar to all other detectors at European XFEL, the pnCCD detector is operated via Karabo control framework (see `Karabo <https://in.xfel.eu/readthedocs/docs/karabo/en/latest/concepts/introduction.html>`_). 

The pnCCD Karabo control system monitors the pnCCD vessel and any other device connected to it (such as vacuum, temperature control, motion systems, etc.). The status information is written to files compatible with the slow control data and file format. 

.. _KaraboGui:

Karabo GUI
~~~~~~~~~~

To open the Karabo software, one needs to first start Karabo services, e.g., the GUI server and the Karabo GUI.

1. On a control computer in the SQS hutch/control room, open a terminal and make sure the :code:`sqsop` user is logged in. From the home directory, execute the following commands:
     
     .. code-block:: bash
        :linenos:

        source karabo/activate
        karabo-start
        karabo-gui &

#. Alternatively, you can go to the desktop on the aforementioned computer and find the :code:`Karabo GUI` file. Double click on it and it will open Karabo version 10.2.4. Follow the next step once the window is opened.

#. To connect to the Karabo server, click on the button with a plug icon on the upper left of the GUI. In the pop-up window, leave all the default settings alone, make sure the username is :code:`admin` (if you are not employed by the European XFEL and are a user, please choose the :code:`user` username instead. **Users should NOT log into Karabo with the admin username**) and click on :code:`connect`. In the :code:`Projects` menu on the top left of the GUI, click on :file:`Load an Existing Project`, which looks like a blue folder. A window pops up called "Load Master Project". Choose :code:`SQS` on the top drop-down menu and double click on the :code:`AMAIN` project (or click on :code:`AMAIN` and click on :code:`Load`). Wait until the square on the top right corner of the Karabo window (see :numref:`figure11`) turns green.

.. _figure11:
.. figure:: Figures/Karabo_Main.png
    :width: 70% 
    
    The :code:`AMAIN` Karabo project.
    
Karabo scenes are found under :code:`Scenes` directory/menu of any Karabo project (if the project has any scenes). Double clicking on any of the available scenes will open that scene.

In general, any Karabo project has numerous servers and devices, all of which are listed under :file:`Device Servers`. Each Karabo device has 6 possible states:

    - **UNKNOWN**: in case of any timeout errors
    - **ERROR**: in case of any other errors such as the absence of a proper connection to the device
    - **OFF**: after initialization
    - **ACTIVE**: after auto-start and when applying basic configurations to the device has finished
    - **ON**: after main power is enabled and all other power sources are also on
    - **ACQUIRING**: during data acquisition
    - **PASSIVE**: the device is OFF (some devices have this state)
    - **CHANGING**: some automatic check is running, do not interfere

To find a device, go to :file:`System Topology` menu found on the top left corner of the Karabo window and search for the device. You can also do the search in :file:`Device Topology` menu, where the devices are listed based on the subprojects.

Generally, all the SQS Karabo devices that are related to the SQS PLCs can be found by going to Karabo :file:`System Topology` and searching for :code:`cppSever/sqs_loop_15`.

To find a server, go to :file:`System Topology` menu and click on :file:`Srevice Manager` menu found on the top left corner. A window pops up, where the servers are listed. From there, a server can be stopped, started or killed. **Be extra careful when stopping/killing a server. Make sure you know what you are doing. In case of problems, contact Controls OCD.** From this window, you can also see the status of a server and know if it is up and running.
    
.. _KaraboScenes:

pnCCD Karabo Scenes
------------------- 

From the :code:`AMAIN` project, go to :code:`Subprojects` menu (found on the left hand side of the Karabo page, scroll down till you see :code:`Subprojects`). Expand the menu and find :code:`SQS_PNCCD` subproject. Expand the latter menu. Under :code:`Scenes`, open the following Karabo scenes for the pnCCD:

    - :code:`pnCCD_Main`: With this scene (see :numref:`figure12`), you can control some vacuum gauges; check the status of vacuum pumps, valves, gauges and chillers; control the pnCCD chillers; set the temperature setpoints and heater ranges; check the history of temperatures and vacuum pressure; set the operating mode of pnCCD; power up/down the detector; check the status of FastADCs; and start ADC acquisition.
    - :code:`pnCCD_Acquisition`: With this scene (see :numref:`SceneNew`), you can see the raw and corrected data; upload new dark constants; and see the histograms of corrected data.
    - :code:`pnCCDPowerOverview_New0`: With this scene (see :numref:`figure17`), you can check the status as well as the measured (readback) bias voltages of all 88 voltage channels of pnCCD.

These three scenes are all you need to operate the pnCCD and observe the images/histograms.

.. _figure12:
.. figure:: Figures/Main_Scene.png
    :width: 70% 
    
    With the :code:`pnCCD_Main` Karabo scene, one can control and operate the pnCCD detector.
    
.. _figure17:
.. figure:: Figures/pnccdPowerOverview.png
    :width: 70% 
    
    With the :code:`pnCCDPowerOverview_New0` Karabo scene, one can check the measured (readback) bias voltages of all 88 voltage channels of pnCCD, as well as the status of each bias voltage. The available status indicators on this scene are green: ON, light blue: OFF, and magenta: interlocked.
    
.. _SceneNew:
.. figure:: Figures/pnCCD_Acquisition.png
    :width: 70% 
    
    With the :code:`pnCCD_Acquisition` Karabo scene, one can see the raw and corrected images and histograms and setup the online calibration pipeline to retrieve dark constants.
  
.. _KaraboDevices:

Karabo Devices Related to pnCCD
-------------------------------

During the pnCCD operation/commissioning, one may need to work with many Karabo devices. This section presents these devices and explain what you need to do with each device. Here, we cathegorize these devices based on their functionality.

Details of the Karabo devices mentioned in this section and some of their properties are mentioned in :numref:`RunControlChapter` and :numref:`OperationChapter`.

.. _KaraboDevicesVacuum:

Vacuum System
~~~~~~~~~~~~~

The Karabo devices related to the pnCCD vacuum gauges (see :numref:`figure3`) are:
    
    - :code:`SQS_NQS_PNCCD/DCTRL/P_CCD_HIGH`: the full range gauge (see :numref:`PccdHigh`) discussed in :numref:`HardwareChapter`. This is the gauge that controls the vacuum interlock.
    - :code:`SQS_NQS_PNCCD/DCTRL/P_CCD_LOW`: the cold cathode range gauge (see :numref:`PccdLow`) discussed in :numref:`HardwareChapter`. This is the gauge that shows the vacuum in pnCCD chamber in the :code:`pnCCD_Main` Karabo scene (see :numref:`figure12`). **This gauge should be turned OFF during the pnCCD operation to avoid producing noise on the detector, which will interfere with the experiment.**
    - :code:`SQS_NQS_PNCCD/GAUGE/P_PRE`: the Pirani gauge discussed in :numref:`HardwareChapter`. This is the gauge that shows the foreline pressure for the pnCCD foreline pump.
    - :code:`SQS_NQS_VAC/GAUGE/CHAMBER_2`: this is a gauge on the NQS chamber, which is connected to the pnCCD chamber. NQS chamber contains the sample (experimental target) and is upstream of the pnCCD chamber. If the cold cathode range gauge is OFF and needs to remain OFF, one can look at the value of this device in order to know the approximate pressure in the pnCCD chamber assuming that the valve in between the pnCCD and NQS chambers is open. This gauge usually remains ON and has no influence on the pnCCD images while the detector is fully biased.
    - :code:`SQS_NQS_CRSC/GAUGE/STAGE_3`: this is another gauge on the NQS chamber. If the cold cathode range gauge is OFF and needs to remain OFF, one can look at the value of this device in order to know the approximate pressure in the pnCCD chamber assuming that the valve in between the pnCCD and NQS chambers is open. **This gauge should be turned OFF during the pnCCD operation to avoid producing noise on the detector.**
    - :code:`SQS_NQS_CRSC/DCTRL/STAGE_3`: this is the device with which the :file:`Stage_3` gauge can be turned ON or OFF.

Clicking on these devices opens their :file:`Configuration Editor` (found on the right side of the Karabo window), where you can turn them ON/OFF. In order to remotely read the gauges on the :code:`NQS` chamber (:code:`SQS_NQS_VAC/GAUGE/CHAMBER_2` and :code:`SQS_NQS_CRSC/GAUGE/STAGE_3`), one can go to :code:`SQS_LOOP9` subproject and open :code:`NQS_VAC` scene. They are labelled in :numref:`figure13`.

.. _figure13:
.. figure:: Figures/NQS_VAC.png
    :width: 70% 
    
    The :code:`SQS_NQS_VAC/GAUGE/CHAMBER_2` and :code:`SQS_NQS_CRSC/GAUGE/STAGE_3` gauges can be read from the :code:`NQS_VAC` scene.

The Karabo devices related to the pnCCD vacuum pumps are:
    
    - :code:`SQS_NQS_PNCCD/TPUMP/TP1`: this is the main turbo pump connected to the pnCCD chamber and discussed in :numref:`HardwareChapter` (see also :numref:`TP`).
    - :code:`SQS_NQS_PNCCD/TPUMP/TP2`: this is the backup turo pump discussed in :numref:`HardwareChapter` (see also :numref:`TP`). 
    
The Karabo devices related to the pnCCD vacuum valves are:
    
    - :code:`SQS_NQS_PNCCD/VALVE/V1`: this is one of the two main valves of the pnCCD chamber discussed in :numref:`HardwareChapter` (see also :numref:`V1`). 
    - :code:`SQS_NQS_PNCCD/VALVE/V2`: this is the second main valve of the pnCCD chamber discussed in :numref:`HardwareChapter`  (see also :numref:`V2`). 
    - :code:`SQS_NQS_PNCCD/VALVE/VT1`: this is the vent valve on the pnCCD chamber discussed in :numref:`HardwareChapter`. 
    
**Please consult the SQS beamline scientists before changing anything in the Karabo devices related to the pnCCD vacuum and do NOT attempt to start pumping down or vent the pnCCD chamber on your own. The SQS instrument scientists are the ones who take care of/operate the vacuum system.** 


Cooling System
~~~~~~~~~~~~~~

Before biasing the detector, one needs to be sure that the detector is cooled down assuming that the pnCCD chamber is under good vacuum (:math:`< 10^{-7}` mbar). To cool down the detector, one needs to first set the temperature setpoints. To do this, go to the following device:

    - :code:`SQS_NQS_PNCCD1MP/CTRL/TCTRL` 
    
Click on the above device to open its :file:`Configuration Editor` (found on the right side of the Karabo window). There, you can find :file:`Output 1` and :file:`Output 2`, which correspond to the top and bottom pnCCD sensors, respectively. By expanding each of the aforementioned output menus, one can set the heater range and the desired temperature setpoint (more details are provided in the :numref:`OperationChapter`).The :file:`P Value`, :file:`I Value`, and :file:`D Value` can be set (see the Lake Shore unit's manual) to control the regulating of the temperature with the heaters. With :file:`P Value` set to 50, :file:`I Value` set to 20, and :file:`D Value` set to 0, we are able to regulate the desired pnCCD temperatures for different modes of operation (see :numref:`ModesTable`). Furthermore, this device together with the DAQ saves the temperatures (in deg K) of the top and bottom sensors (:code:`inputA/krdg` and :code:`inputB/krdg`, respectively) as the slow meta data.

The Karabo devices related to the pnCCD chillers (see :numref:`chillersPNCCD`) are:

    - :code:`SQS_NQS_PNCCD/DCTRL/COOL_TOP`: this is the device for the chiller connected to the top pnCCD sensor. 
    - :code:`SQS_NQS_PNCCD/DCTRL/COOL_BOTTOM`: this is the device for the chiller connected to the bottom pnCCD sensor. 

Clicking on these devices opens their :file:`Configuration Editor`, where you can turn them ON/OFF. You can do the latter also from the :code:`pnCCD_Main` Karabo scene once the interlock is set and the chillers are ready to be turned ON.

.. _KaraboMotion:

Motion System
~~~~~~~~~~~~~

The pnCCD top and bottom sensors can be moved independently using the following Karabo devices:

    - :code:`SQS_NQS_PNCCD/DCTRL/PNCCD_DOWN`: the stepper motor to move each pnCCD module in a downward motion.
    - :code:`SQS_NQS_PNCCD/DCTRL/PNCCD_UP`: the stepper motor to move each pnCCD module in an upward motion.
    - :code:`SQS_NQS_PNCCD/DCTRL/PNCCD_RIGHT`: the stepper motor to move each pnCCD module in a horizontal motion towards right.
    - :code:`SQS_NQS_PNCCD/DCTRL/PNCCD_LEFT`:  the stepper motor to move each pnCCD module in a horizontal motion towards left.
    - :code:`SQS_NQS_PNCCD/DCTRL/PNCCD_FEL`: the stepper motor to move each pnCCD module back and forth along the beam direction.

**Please consult the SQS beamline scientists before changing anything in the Karabo devices related to the pnCCD motion system and do NOT attempt to move the pnCCD sensors on your own. The SQS instrument scientists are the ones who take care of/operate the pnCCD motion system.** 

.. _electronicsKaraboDevices:

pnCCD Front-End Electronics \& Clock and Control
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
The Karabo devices related to the FastADC digitizers are:
 
    - :code:`SQS_NQS_PNCCD1M/ADC/PNCCD-1`: this device corresponds to the FastADC digitizer board that is connected to the top pnCCD sensor. The corresponding digitizer board only uses 6 channels out of the available 10 channels.
    - :code:`SQS_NQS_PNCCD1M/ADC/PNCCD-2`: this device corresponds to the FastADC digitizer board that is connected to the bottom pnCCD sensor. The corresponding digitizer board uses all the available 10 channels.
    
There is a piece of software called the :code:`Formatter` written by Steffen Hauf (European XFEL employee). The formatter distributes the FastADCs' output channels into a digital image and sets which ADC channel (corresponding to a particular CAMEX) corresponds to which part of the digital image. There are two Karabo devices with which the formatter works:

    - :code:`SQS_NQS_PNCCD1MP/CAL/PNCCD_FMT-0`: this device is related to the top pnCCD sensor, and is therefore related to the :code:`SQS_NQS_PNCCD1M/ADC/PNCCD-1` device.
    - :code:`SQS_NQS_PNCCD1MP/CAL/PNCCD_FMT-1`: this device is related to the bottom pnCCD sensor, and is therefore related to the :code:`SQS_NQS_PNCCD1M/ADC/PNCCD-2` device.

The abovementioned devices are found in the :file:`SQS_PNCCD_ADC` subproject of the SQS :file:`AMAIN` project.

The karabo device with which one can set the :code:`CLEAR` and :code:`START` triggers for the data acquisition and CCD readout (see :numref:`clockAndControl`) is:

    - :code:`DET_LAB_SYS/TSYS/UTC-1-S2`: for details on how to set the abovementioned clocks, see :numref:`Triggers`.
    
.. _KaraboGain:

Saving the pnCCD Gain Setting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The middle layer Karabo device related to saving the pnCCD gain setting is:

    - :code:`SQS_NQS_PNCCD1MP/MDL/DAQ_GAIN`: this is a device, which saves the gain value (:code:`pNCCDGain`) as the slow meta data. More information about this device is given in :numref:`GainSaving`.

This device is found in the :file:`SQS_PNCCD` subproject of the SQS :file:`AMAIN` project.

.. _MPODDevices:

MPOD System
~~~~~~~~~~~

The Karabo devices related to the MPOD system are:

    - :code:`SQS_NQS_PNCCD1MP/MCPS/POWER_PROC`: this device is the main device with which one can power up/down the pnCCD detector (see :numref:`PowerOn` and :numref:`PowerOff`). 
    - :code:`SQS_NQS_PNCCD1MP/MCPS/POWER`: this is a device with which one can set the voltages manually (see below).
    - :code:`SQS_NQS_PNCCD1MP/MDL/DAQ_MPOD`: this is a device, which saves the HV values of the top and bottom pnCCD sensors (:code:`u0voltage` and :code:`u500voltage`, respectively) as the slow meta data. Make sure the device is instantiated and that the :code:`Start` button is greyed our (activated). If the latter is not true, click on the :code:`Start` button and ensure :code:`U0voltage` and :code:`U500voltage` are reading a value. The former and latter values are the current voltages on the top and bottom sensors, respectively.
    
The abovementioned devices are found in the :file:`SQS_PNCCD` subproject of the SQS :file:`AMAIN` project.
    
.. danger::

    - Double clicking on the :code:`SQS_NQS_PNCCD1MP/MCPS/POWER` Karabo device will open a scene. 
    - :red:`The aforementioned scene shall only be used by Robert Hartmann (from the PNSensor GmbH company) to manually set the voltages of different channels. Please NEVER touch this scene. Never change anything in this scene as it can be VERY dangerous and could seriously damage the detector.`

.. _OnlinePreviewDevices: 

Online Preview
~~~~~~~~~~~~~~

The Karabo devices related to the online preview are:    
   
    - :code:`SQS_NQS_PNCCD1M/CAL/MANAGER`: this is the main device acting as the manager for the online correction pipeline.
    - :code:`SQS_NQS_PNCCD1M/CAL/CORR_OFFSET`: this is the offset correction device.
    - :code:`SQS_NQS_PNCCD1M/CAL/CORR_CM`: this is the common mode correction device.
    
They can be found in the :file:`SQS_PNCCD_ADC` subproject of the SQS :file:`AMAIN` project and are explained in more details in :numref:`onlinePreviewExplained`. 

.. _dataAggregatorDevices:

Data Acquisition
~~~~~~~~~~~~~~~~

The Karabo devices related to the DAQ and the pnCCD data acquisition are:

    - :code:`SQS_DAQ_DATA/PNCCD/1`: this is the pnCCD fast data aggregator, which saves the images' arrays.
    - :code:`SQS_DAQ_DATA/PNCCD/2`: this is the pnCCD slow data aggregator, which saves information such as voltages on the top pnCCD sensor, temperatures of the pnCCD sensors and the pnCCD gain setting.
    - :code:`SQS_DIGITIZER_UTC2/ADC/1`: this is the data aggregator which saves all the other SQS data as the fast data. **This device needs to be selected as a data source for proper functionality of the Karabo bridge.**

These three devices are required to correctly write the slow and fast pnCCD data onto disk.

Finally, the Karabo devices related to the data aggregators are all found in :code:`SQS_DAQ` subproject under the :code:`AMAIN` main project. Depending on what devices, other than pnCCD, along the SQS beamline are chosen to save data using the DAQ, you need to ensure that the corresponding data aggregators are all up and running. These are:

    - :code:`SQS_DAQ_DATA/DA/1`
    - :code:`SQS_DAQ_DATA/DA/2`
    - :code:`SQS_DAQ_DATA/DA/3`
    - :code:`SQS_DAQ_DATA/DA/4`
    - :code:`SQS_DAQ_DATA/DA/5`