KaptureControlGui/Docu/chapters/part01-use.tex

%!TEX root = ../Kapture2 Docu.tex
%% ==============================
\chapter{Using Kapture 2}
\label{ch:use}
%% ==============================
\section{Measurement in a nutshell}
\begin{itemize}
	\item start-up procedure: Boot PC, switch HighFlex off and on, reboot PC
	\item Prepare Board can always be used to reset the board
	\item check that PLL lock LEDs are on
	\item use internal pilot bunch
	\item activate HEADER
	\item T/H FMC2 25ps to 4 is no offset
	
	\item Using 500\,MHz reference
	\begin{enumerate}	
		\item connect the 125\,MHz 
		\item do normal init with 125\,MHz reference
		\item connect the 500\,MHz
		\item run \textit{PLL swap 125 to 500}, \textit{PLL Synch}, \textit{ADC Synch}
		\item now it should be working. If log is missing redo step 4. 
		\item do not run \textit{Board Reset} or other \textit{PLL Init}! Then you would need to redo from beginning.
		\item If a DMA error etc happens try \textit{soft reset}
	\end{enumerate}	
	\item shutdown: Just turn off the PC and the two switches for the T/H.
\end{itemize}

\section{start}
\Grafik[H]{1}{Kapture.png}
The left Ethernet connector is configured for the KARA office network. The right one can be used for other networks.

Currently the Start-up of the system needs some manual workaround. Before turning on the PC put switches 1 and 2 in off state. The unlabeled switch is always on!
Then Boot the PC when the Lock-in screen is visible turn the HighFlex of and on with the big switch on the Highflex. Then reboot the PC. 

\Grafik[H]{0.5}{switch.jpg}
The two switches are to power down the input stage of the KAPTURE Modules. To power them up first turn on the switch 1 and than the switch 2! (if there is a longer period without measurement one can turn them back of to reduce thermal stress.)

Now you are good to go ;)

After starting the PC, start the GUI and hit 'Prepare Board' and you are ready to Measure at 500\,MHz with 125\,MHz as reference. To reset the Board one can just use Prepare Board. (Soft Reset and Board Off are not necessary for KAPTURE-2). After that DataFlow, Master Control and Data Check should be green. Also take a look on the LEDs of the HighFlex. The 3 inside the red circle indicate that the PCI is working (if one of them is not on - turn the HighFlex off and on and reboot). The 2 inside the blue circle indicate that both PLL are locked. If one is of, redo the prepare Board.

It can be also done manually. For example if the 500\,MHz is used as input clock. Than first \textit{Board Reset}, now the correct \textit{PLL init} then \textit{PLL Sync}, then \textit{ADC Calib} and \textit{ADC Autosync}.

On the MultiView Page one can find all the controls. 

\subsection{Basic Settings}
\subsubsection{Configfile}
In 'home/user/.kcg2' are two config files. One for the general and one specific for epics.
The Configfile is more or less self explaining. The newest option is the "Working Channels" config. It can be used to define which channels are used. It does not affect the RAW-file but it ins used for displaying in some cases.
If the file does not exist a window opens where the config can also be edited.  

The epics config is best to edit only via the epicsWidget.

After a change, the GUI needs to be restarted.

\subsubsection{file/settings}
This is a small Settings window to set at runtime the Save Location and the Sub-directory.




\newpage
\section{Timing Widget}
\includegraphics[width=1.5em]{Plots/Icons/clock.png} (Ctrl+T) contains the delay settings. KAPTURE-2 has 3 different delays. \\
\Grafik[H]{0.8}{Widgets/TimingWidget.PNG}
330ps global Delay with 20 possible steps\\
25ps global Delay with 24 possible steps\\
3ps channel independent Delay with 32 steps\\

In addition the second KAPTURE Module can be delayed with the 25ps in the \textit{T/H FMC2} column. The Default is 4! So for example value of 3 means that the second board will sample 25\,ps earlier.

The advanced settings for ADC Delay and FPGA Delay are usually not to use. They are mainly for development. In normal user-operation the GUI handles them automatically.
\TextGrafik[h]{Timing distribution of a KAPTURE-2 Module. The Cascade Clock output of the first Module is used as input for the second modul. One Important information: The PLL is running with internal loopback to achieve a global Delay. This means that one output of the PLL is looped back to the input and by changeing the delay of this output, the complete System is shifted. But it is shifted in the oposite direction: increasing the delay means sampling earlyer. BUT the GUI takes care of this so that for the user it feels like it is shown in the graphic.}{pl:T:bahn}{0.7}{timeplan4.png}



\newpage
\section{Time Scan Widget}
\includegraphics[width=1.5em]{Plots/Icons/timescan.png} (Ctrl+Shift+T)
\Grafik[H]{1}{Widgets/TimeScan.PNG}
The Time Scan was moved to a new Widget (mostly for code simplification). A TimeScan can be used to find the delays. 

Via a drop down menu one can select how the measured data is processed.
\begin{itemize}
	\item Mean over Everything:
	It just calculates the mean of the complete data. This is usually not to helpful.
	\item Threshold:
	Calculates the mean only for data points with not in $2048 +$ threshold. If you have a negative peak, enter a negative sign. 
	\item Bucket:
	Calculates the mean of only on bucket - usually the best way.
	\item All Buckets:
	New Feature: It calculates the mean for all buckets individually. Therefore the resulting file is bigger but it allows to compare the buckets.
\end{itemize}

It offers different Scan Modes. In the standard way (as it is in the Screenshot) it scans step by step through all delays. In this mode usually one uses the 25\,ps Step4 Option. If it is set to Step 1 one does over sample the Signal and increases the needed Time. 
The \textbf{Fast Mode} is primary designed to find the region of the Signal inside the 2\,ns Bucket. In this case it sets spreads the 8 ADCs over the 100\,ps area of the 3\,ps. and then  goes over the complete 2\,ns domain with 25\,ps Step 1. It is usually best to use with a threshold of 20.
The \textbf{Calibration Scan} is only needed to generate the Calibration data with the analog 500\,MHz signal and will take a long time. (Details in the Calibration Section)

The Scan Results are stored in the sub folder \texttt{TimeScan}. In the logfile \texttt{scan.info} will the Scan Parameters be stored. The user has the possibility to use the identifier entry to add any text to the Logfile. 

The Plotwindow offers multiple view. In \textbf{default} the data is plotted for each Channel separately over the delay setting. The other option is the \textbf{timecorrected} where the selected ADCs are plotted in one plot over Time. In this view also the Calibration can be activated and the Error can be plotted. In Addition a Fit can be performed.

For simpler positioning of the ADC Timings one can plot them inside the Timescan via \textbf{show ADC} in the timecorrected view.


\newpage
\section{Calibration}
\includegraphics[width=1.5em]{Plots/Icons/calib.png} (Ctrl+U)
\Grafik[H]{0.3}{Widgets/CalibrationWidget0.PNG}
This offers a Calibration Routine. First a small widget opens where the TimeScan that will be used is to be selected. It is also Possible to open the Calibration directly from the Scan Results Widget. In this case this File selection is skipped.

\Grafik[H]{0.8}{Widgets/CalibrationWidget.PNG}
The main Widget. The Left plot shows the original data with no calibration applied. The Right Plot than with all calibration used. The lower input lines can be  used to manually adjust the calibration. 

The Calibration is split into two Parts
\begin{itemize}
	\item 500\,MHz:\\
		This needs only to be done once. Maybe it is useful to repeat it after one year or so. To do this one uses the 500\,MHz RF clock as Input for the Channels and does a Calibration Scan. And then in this Widget select the type to be \textit{500\,MHz}. (the other Options have no effect in this case). It will take a view minutes! It calibrates the width of the Delays.
	\item Peak:\\
		This is the more often needed One. It should be done at least every time the Measurement setup is changed. This calibrates the Baseline, Gain and Time offset for the 8 Channels. To do that take a Timescan (usualy with step 4) of the Measurement Signal (as seen in the Screenshot). Now select if it is a Negative Peak or a Positive Peak. If there is a region with the Baseline in front of the Puls (like in the screen-shot) one can force the system to use that for Baseline determination via \textit{use first data as Baseline}. If not or not wanted, set it to 0 (which is also the default).
\end{itemize}
To run the Calibration hit \texttt{Run}. This does not override the old one. If the result is good use \texttt{Save} to write it into the file. The old calibration file will than be renamed.


\section{Correlation Test}
\includegraphics[width=1.5em]{Plots/Icons/correlation.png} (Ctrl+Shift+C)
\Grafik[H]{1}{Widgets/Correlation.PNG}
This is only needed if a PeakReconstruction is later to be done. It can also be opened from the Scan Results Widget. With this, one can test if the used distribution of the Channels will give good results. Every time a SingeRead or a ContinuousRead is done the widget updates the distribution. To Perform the test hit \texttt{Run} and wait. On the current KAPTURE-2 System without a CUDA-GPU this is done remotely on ibpt-kapture1. If the result is pleasing one can save the Correlation Correction Parameters via \texttt{Save} so that they can be used later for the ReconstructionAlgorithm.



\newpage
\section{Acquisition}
\includegraphics[width=1.5em]{Plots/Icons/wrench.png} (Ctrl+A)
\Grafik[H]{0.4}{Widgets/AcquireSetting.PNG}

The first to parameters define each acquisition, with the number of turns to observe and the number to skip. Be aware, that the turns to observe the skipped turns include. (e.g. If observe is 1000 and skip is 1, the file contains 500 data points). 

The option \textit{shift FMC2} can be used if there is a shift between ADC1-4 and ADC5-8 witch is with the current firmware usually the case. It does not change anything in the raw file!
The shift can change when the 330\,ps is changed.

Currently also KAPTURE-2 is most stable without external revolution clock. Therefore \textit{Simulate Pilot Bunch} needs to be checked.



\section{Ploting}



\section{EPICS}
\includegraphics[width=1.5em]{Plots/Icons/EPICS_Logo.png} (Ctrl+E)
The epics widget allows to read out parameters of KARA to store them in the Logfile for every acquisition. To change the known PVs open the PV List. Here you can edit the display name and the PV name as well as make them available for the Log and show them in the Monitor. To remove one entry use the garbage can icon. A new PV can be added in the last line of the table. 
Changes will only be done in the config file by \textit{apply + save}. With \textit{apply} the changes will be only temporally.
\Grafik[H]{0.3}{Widgets/Epics1.PNG}
\Grafik[H]{0.8}{Widgets/Epics2.PNG}





%\section{CUDA}

%\section{ADC}
%(Ctrl+G)
%This Widget contains two features. Primary it is to set the Gain and the offset correction for every adc.

%The value range is:\\
%Gain 0 -- 0x7FFF\\
%Offset 0 -- 0x1FFF (the leading 1 is used as sign. So 0x0FFF is the maximum positive offset and 0x1FFF the maximum negative offset)

%The widget has addidionaly a Calibration Helper. This can be used to determine the right Gain and Offset value so that all ADCs are equal.
%\begin{itemize}
%	\item Baseline: it just calculates the mean and std for the complete data for every ADC
%	\item Peak: It splits the Signal in two region (upper and lower) and calculates the mean and std for both. 
%\end{itemize}