KaptureControlGui/Docu/chapters/part02-develope.tex

%!TEX root = ../Kapture2 Docu.tex
\chapter{GUI Developement}
\label{ch:dev}
\section{Pagackelist}
\begin{itemize}
	\item PyQT4
	\item sip
	\item pyqtgraph
	\item numpy
	\item psutil
	\item pyepics
	\item setuptools
\end{itemize}


\section{misc}
\label{ch:dev:misc}
The Code is written to be working on both Python2 and Python3. At the moment this guide mostly only provides infos for the modules I developed or changed.

Before the Idea of KAPTURE2 came to live there was the idea to put multiple Kapture1 boards in on PC. So to the GUI a multi Kapture support was added. Unfortunately not in a perfect OOP fashion and therefore the code is now a little bit inconsistent. The new changes for KAPTURE2 mostly ignore things from the multi kapture implementation and therefore the current GUI version does not really support multi KAPTURE anymore - sry. 

Also it should work also on the old KAPTURE-1 System but it has not been tested.

The configfiles and the icons etc are located in \textit{.kcg2} to avoid conflicts with the old KAPTURE-1 GUI.

\section{Modules}
This is a not a complete list of all the modules with more or less small informations. 

\subsubsection*{base/backend/board/communication}
This contains the \code{class PCI}, witch wraps the system-calls for the pci communication to the FPGA.
It also creates one instance of the class with the name \code{pci}. By using 
\begin{lstlisting}
	from .communication import pci
\end{lstlisting}
one can then read and write to the FPGA.

There is also a dummy class which is selected when the gui is started with --testing parameter. It does not read or write to the hardware and can be therefore used while developing on a system without a KAPTURE board - even on a windows system.


\subsubsection*{base/backend/board/board\_config}
This contains the \code{class BoardConfiguration}. It is the central control Class for all the KAPTURE settings. (Like Delay, Turns to observe ...) It uses a dictionary to stores all the settings. 

It is mainly base on observers. The function \code{update(key, value)} is used to change a setting. It then calls the observers. There are 3 Types of observers
\begin{enumerate}
	\item observers\_write:\\ those are controlled by the class it self. They write the settings to the board.
	\item observers\_for\_all:\\ they are called every time one setting is changed - independent of the key
	\item observers:\\ they are called when the corresponding key changes. Those are mainly used to update the GUI.
\end{enumerate}

The \code{update} function has an additional parameter \code{write=True} it controls weather the observers\_write will be called or not. By default it is set to true. This is only needed for the function \code{read\_from\_board}, wich reads the settings from the FPGA, to prevent it from unnecessary rewrite it.


In widgets one can register a observer via the function \code{observe(who, callback, key)}\\
who is used as an identifier when one wants to remove the observer. It can be nearly everything - Object, variable - usually in the GUI it is the Object that will be changed (Like the label that is updated). \\
callback is the function that will be called and needs to have one parameter by which the new value will be passed.\\
key is the setting that will be observed.

When the widget will be deleted all corresponding observers need to be removed by \code{unobserve(who, key)}!

One example from acquiresettings widget
\begin{lstlisting}
	def __init__(...):
		self.board_config = board.get_board_config(board_id)
		self.fileSizeOutLabel = self.createLabel("??")
		self.board_config.observe(self.fileSizeOutLabel, self.set_filesize, 'turns_observe')
		.
		.

	def set_filesize(self, state):
		.
		.

	def closeEvent(self, event):
		self.board_config.unobserve(self.fileSizeOutLabel, 'turns_observe')
		.
		.

\end{lstlisting}


\subsubsection*{base/backend/board/sequences} 
The sequences are used to initialize the board. They are series of commands send to the FPGA. It is controlled by the \code{board_config} and from the backendinterface.
The module contains two function:\\
\code{def read_sequence(board_version)}\\
\code{def run_sequnce(board_id, sequence, progressbar=None)}

The sequences are stored in json files in \textit{base/backend/board/sequences/sequence\_x.json} with x to be the \code{board_version}. The \code{board_version} is read by \code{board_config} from the FPGA. 

All sequences in the \code{"sequence\_names"} list will have a Button.\\
The \code{"initialization\_sequence\_order"} specifies which sequences will be run for \textit{Prepare Board} 

One Sequence is represented like this
\begin{lstlisting}
	"demo_sequence": {
        "Comment": "Text shown on Button",
        "status_val": "", #some Sequences set these to enable functions inside the gui
        "sequence": [
            [
                "value", "reg", 
                "dialog text",  #If not an empty string a popup is shown before sending
                "comment",      #Printed in Logfile
                "key", "value", #Optional: used to update the board_config 
                "key", "value"  #          It calls config.update(key, value, write=False)
            ],
            [
                "value", "reg", 
                "",             #No popup  
                "another command without update the board_config"
            ],
            [
                "value", "reg", 
                "",               
                "",
                "key", "value", #only one update of board_config

            ]           
        ]
    },
\end{lstlisting}


\subsubsection*{base/backend/DataSet} 
Contains measured data. It has all the needed functions to open files, decode them and prepare them for plotting etc. 

This Class is also used outside the KCG.

\subsubsection*{base/backend/TimeScan} 
Class to read and generate timescans files.

This Class is also used outside the KCG.

\subsubsection*{base/backend/CalibrationHandle} 
This Class Handles the Calibration Files and is used by the \code{DataSet} and \code{TimeScan}. 
It contains also an instance of itself which should be used. So don't create a new one.
\begin{lstlisting}
		theCalibration = CalibrationHandle()
\end{lstlisting}

When ever one cals \code{theCalibration.openFile(...)} it returns a identifier. 


\subsubsection*{base/backendinterface}
The most messy module. It contains a vast amount of functions.
Including:\\
wrapper functions for the \code{board_control} \\
functions to run the sequences\\
everything for data acquisition



\subsubsection*{widgets/} The most of the controlling is in the widgets. They can be understood as some kind of modules. To add new functionality to the GUI - like advanced analytic - one can just add a new Widget.

there are by now:
\begin{itemize}
	\item AcquireSettingsWidget
	\item PlotWidget
	\item SingleReadWidget
	\item TimeingWidget
	\item TimescanWidget
	\item EpicsWidget\\
		Has one speciality: it is initialized in \textit{base/kcg} via
		\begin{lstlisting}
		if config.use_epics:
			from ..widgets import EpicsWidget
			EpicsWidget.epicsConfig = EpicsWidget.EpicsConfig()
	   \end{lstlisting}
	%\item AdcWidget
	\item UpdateCalibrationWidget
	\item CorrelationWidget
\end{itemize}
To activate a widget put the module name in widgets/\_\_init\_\_.py

If a widget should be updated everytime a new Data is acquired. register a observer onto \code{"lastDataSet"}. Like it is done in the \code{PlotWidget} 
\begin{lstlisting}
	def initUI(self):
		self.board_config.observe(self, self.observeDataSet, 'lastDataSet')

	def observeDataSet(self, data):
		self.plot_live(data=data)

	def closeEvent(self, event):
		self.board_config.unobserve(self, 'lastDataSet')
\end{lstlisting}
Do not forget to unobserve!

\subsubsection*{config.py}
Module to handle the config file. It also provides some helperfunctions for accessing the current working path as well as the installation path. Also is it the place where the colors for the Plotwidget are defined.



\newpage
\section{FPGA stuff}

\TextGrafik[H]{Bank Register}{pl:bank}{1}{BankRegister.PNG}