slsDetectorPackage/manual/manual-main/slsDetectorInstall.tex

\documentclass{article}
\usepackage{amssymb}
\usepackage[dvips]{graphicx}
\usepackage{verbatim}
\usepackage{hyperref}
\usepackage{color}



\begin{document}

\title{SLS Detectors software installation}
\author{Anna Bergamaschi, Dhanya Thattil}
\date{\today}
\maketitle
\tableofcontents
\clearpage

%setcounter{tocdepth}{4} and \setcounter{secnumdepth}{4}






\section{The Software Package}

The SLS detectors software is intended to control the detectors developed by
the SLS Detectors group. The detectors currently supported are:

MYTHEN, GOTTHARD, EIGER and JUNGFRAU.\bigskip

\noindent The package provides software for the distributed system that comprises of
detectors, data receivers (to process detector data), and the client (to control
or monitor the system). The client and data receivers can be embedded in
the user's acquisitions system. Furthermore, the package also provides some
tools for detector calibration.\bigskip

\subsection{Binaries}
\noindent The complete software package is composed of several programs which
can be installed (or locally compiled) depending on one's requirements:

\begin{itemize}

\item \textcolor{blue}{libSlsDetector.so, libSlsReceiver.so}:\\
The \textit{slsDetector shared and static libraries}, which are
necessary for all user interfaces. The \textit{C++ API} via the class
\textit{slsDetectorUsers} (installed with the default package) or the
\textit{Python API} via the class \textit{sls\_detector} (installed with the
package including Python API), which can be used from the user's acquisition
software to control the detectors and the data receivers.

\item \textcolor{blue}{sls\_detector\_put, sls\_detector\_get,
sls\_detector\_acquire, sls\_detector\_help}: \\
The \textit{command line interfaces}, which are provided to communicate with the
detectors and data receivers using the command line.

\item \textcolor{blue}{slsReceiver}: \\
The \textit{data receiver}, which can be run on a different machine than the
client, receives the data from the detector and processes it. The receiver can
be configured, controlled and monitored by the client.

\item \textcolor{blue}{slsDetectorGUI}: \\
The \textit{graphical user interface}, which provides a user friendly way
of operating the detectors and data receivers with online data preview.

\item \textcolor{blue}{energyCalibrationWizard,angularCalibrationWizard}: \\
The \textit{calibration wizards} to analyze the data and produce the energy or
angular calibration files.

\item The \textit{virtual Detector servers} to simulate the detectors behavior.
However, only control commands work, not the data acquisition itself.
\end{itemize}




\section{Install Binaries via Conda}
This section is useful only if one wants to download only the binaries for
specific distribution and use the package via command line. Please refer later
sections to download source code and compile them.\bigskip

\noindent The conda package uses Travis CI for continuous integration with
automatic deployment to Anaconda Cloud. One can download only the package or the
package including the python interface.


\begin{itemize}
 \item Only the package
\begin{verbatim}
#Add conda channels
conda config --add channels conda-forge
conda config --add channels slsdetectorgroup

#Install latest version
conda install sls_detector_software

#Install specific release (GLIBC2.14)
conda install sls_detector_software=3.0.1

#Scientific Linux 6 version (GLIBC2.12)
conda install sls_detector_software=SL6_3.0.1
\end{verbatim}
 \item The package including Python interface
\begin{verbatim}
#Add conda channels
conda config --add channels conda-forge
conda config --add channels sls_detector

#Install latest version
conda install sls_detector

#Install specific release (GLIBC2.14)
conda install sls_detector=3.0.1

#Scientific Linux 6 version (GLIBC2.12)
conda install sls_detector=SL6_3.0.1
\end{verbatim}
\end{itemize}

\clearpage
\section{Install via Source Code}
This section is useful if one wants to use the API and embed it in their
acquisition system, or if one wants to download the source code and compile.

\subsection{Download Source Code}

\begin{itemize}
 \item Only the package
\begin{verbatim}
#Clone source code with specific release
git clone https://github.com/slsdetectorgroup/slsDetectorPackage.git --branch
3.0.1
\end{verbatim}
 \item The package including Python interface
\begin{verbatim}
#Clone source code with specific release
git clone https://github.com/slsdetectorgroup/sls_detector.git --branch
3.0.1
\end{verbatim}
\end{itemize}



\subsection{Requirements}
These are the basic requirements to install and use the software. Fine Tuning
the system will be discussed in other documentation provided.
\begin{itemize}

 \item \emph{C/C++}:\\
The software is written in C/C++. If Python API is used, it is a wrap around
to the C++ software.  Any Linux installation with working libgcc should be
sufficient.

 \item \emph{Shared Memory}:\\
Access to the shared memory of the control PC is required for the client.

 \item \emph{Network}:\\
The control PC communicates to the detectors and data receivers over TCP/IP.
Therefore, the detector should receive a proper IP address (either DHCP or
static) and no firewall should be present between the control PC and the
detector.

\item \emph{Compilation}:\\
cmake is required to compile. make is also possible, but is harder to find
dependencies.

\item \emph{GUI}:\\
To use the GUI, one requires atleast Qt4.8.2 and Qwt6.0. Installation of these
are discussed in the next sections.

\item \emph{Calibration Wizards}:\\
They are based on the CERN Root data analysis framework. Installation of it is
discussed in the next sections.

\end{itemize}


\subsubsection{Qt4 Installation for GUI}
It must be installed before Qwt. A Qt version equal or higher than 4.6 is
required. One can install it:
\begin{itemize}
 \item via YUM:
\begin{verbatim}
 yum install qt-devel
\end{verbatim}
 \item via download from:\\
\url{
https://download.qt.io/archive/qt/4.8/4.8.2/qt-everywhere-opensource-src-4.8.2.t
ar.gz} \bigskip

\noindent To install:
\begin{verbatim}
> gunzip qt-everywhere-opensource-src-4.8.2.tar.gz
> tar xvf qt-everywhere-opensource-src-4.8.2.tar
> ./configure
> make
> make install
\end{verbatim}
By default Qt4 will be installed in /usr/local/Trolltech/Qt-4.8.2/. 
\end{itemize}

\noindent \textbf{Setup Environment} 

\noindent One has to ensure that \verb=PATH= and \verb=LD_LIBRARY_PATH= have
been updated to include Qt4 install path, binaries and libraries.
Confirm by executing \verb=qmake -v= and ensuring the result points to Qt4 (not
Qt3 or Qt5). \bigskip

\noindent If the environment is not set up, one can add the libraries and
executables to the .bashrc by adding
\verb=LD_LIBRARY_PATH= and \verb=PATH=:
\begin{verbatim}
export QTDIR=/usr/local/Trolltech/Qt-4.8.2
export PATH=$QTDIR/bin:$PATH
export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
\end{verbatim}


\subsubsection{Qwt Installation for GUI}
Before installing Qwt, one must install Qt
and ensure that \verb=QTDIR=, \verb=LD_LIBRARY_PATH= and \verb=PATH= point to
the correct Qt4
version. \bigskip

\noindent A Qwt version equal or higher than 6 is required. One can
install it:
\begin{itemize}
 \item via YUM:
\begin{verbatim}
 yum install qwt-devel
\end{verbatim}
 \item via download from:\\
\url{
https://sourceforge.net/projects/qwt/files/qwt/6.0.0/qwt-6.0.0.zip/download}
\bigskip

\noindent To install:
\begin{verbatim}
> cd qwt-6.0.0
> qmake
> make
> make install
\end{verbatim}
By default Qwt will be installed int /usr/local/qwt-6.0.0 
\end{itemize}

\noindent \textbf{Setup Environment} 

\noindent One has to ensure that \verb=QWTDIR= and \verb=LD_LIBRARY_PATH= have
been updated to include Qwt install path and libraries. \bigskip

\noindent If the environment is not set up, one can add the libraries to the
.bashrc by adding \verb=LD_LIBRARY_PATH=:
\begin{verbatim}
export QWTDIR=/usr/local/qwt-6.0.0/
export LD_LIBRARY_PATH=$QWTDIR/lib:$LD_LIBRARY_PATH
\end{verbatim}







\subsubsection{Root Installation for Calibration Wizards}
The software has been developed and tested with root 5.20, but any version
should work. One can download it from:
\begin{verbatim}
> svn co https://root.cern.ch/svn/root/trunk root
\end{verbatim}

\noindent To install:
\begin{verbatim}
> cd root
> ./configure --enable-qt
> make
> make install
\end{verbatim}

Edit your .bashrc to define the ROOTSYS enviroment variable and annd
the libraries and executables to the \verb=LD_LIBRARY_PATH= and \verb=PATH=:
\begin{verbatim}
export ROOTSYS=/usr/local/root-5.34
export PATH=$ROOTSYS/bin:$PATH
export LD_LIBRARY_PATH=$ROOTSYS/lib:$LD_LIBRARY_PATH
\end{verbatim}

You can also download the binaries, assuming that your linux and gcc versions
match as in:
\begin{verbatim}
http://root.cern.ch/drupal/content/production-version-534
\end{verbatim}





\subsection{Compilation}
One requires \verb=cmake= to compile and can be done in two ways:

\subsubsection{Using script cmk.sh}
The script uses \verb=cmake=. After compiling, the libraries and executables
will be found in `slsDetectorPackage/build/bin` directory.
Usage: [-c] [-b] [-h] [-d HDF5 directory] [-j]
\begin{itemize}
 \item -[no option]: only make
 \item -c: Clean
 \item -b: Builds/Rebuilds CMake files normal mode
 \item -h: Builds/Rebuilds Cmake files with HDF5 package
 \item -d: HDF5 Custom Directory
 \item -t: Build/Rebuilds only text client
 \item -r: Build/Rebuilds only receiver
 \item -g: Build/Rebuilds only gui
 \item -j: Number of threads to compile through
\end{itemize}

Some example options for compilation:

For only make: \verb=./cmk.sh=

For make clean;make: \verb=./cmk.sh -c=

For using hdf5 without custom dir /blabla: \verb=./cmk.sh -h -d /blabla=

For rebuilding cmake without hdf5: \verb=./cmk.sh -b=

For using multiple cores to compile faster: \verb=./cmk.sh -j9=

For rebuilding only certain parts: \verb=./cmk.sh -tg= (only text client and
gui)


\subsubsection{Directly using cmake}

Use cmake to create out-of-source builds, by creating a build folder parallel to
source directory. 
\begin{verbatim}
 $ cd ..
 $ mkdir slsDetectorPackage-build
 $ cd slsDetectorPackage-build
 $ cmake ../slsDetectorPackage  -DCMAKE_BUILD_TYPE=Debug -DUSE_HDF5=OFF 
 $ make
\end{verbatim}

Use the following as an example to compile statically and using specific hdf5
folder 
\begin{verbatim}
 $ HDF5_ROOT=/opt/hdf5v1.10.0 cmake ../slsDetectorPackage
-DCMAKE_BUILD_TYPE=Debug -DUSE_HDF5=ON
\end{verbatim}

After compiling, the libraries and executables will be found at `bin` directory 
\begin{verbatim}
 $ ls bin/
    gui_client  libSlsDetector.a  libSlsDetector.so  libSlsReceiver.a 
libSlsReceiver.so    sls_detector_acquire  sls_detector_get  slsDetectorGui 
sls_detector_help sls_detector_put  slsReceiver
\end{verbatim}



\section{Software Upgrade}

The upgrade of the package could require an upgrade of the on-board detector
server and/or firmware running on the detector as well. 


\subsection{MYTHEN}
In such cases, the users are not expected to compile the software
themselves (which would require dedicated softwares) but only to download on the
detector board the programming files and/or software package provided by
the SLS Detectors group.

\subsubsection{Firmware}

To upgrade the firmware you need either a working version of the Altera
Quartus software or of the Quartus programmer, which can easily be downloaded
from: \\
\url{https://www.altera.com/download/programming/quartus2/pq2-index.jsp}
\medskip

\noindent Normally, installation of the software and of the driver for the
USB-Blaster (provided together with the MYTHEN detector) are simpler under
Windows. \bigskip

\noindent Under Windows, the first time that you connect the USB-Blaster to one
of your USB ports, you will be asked to install new hardware. Set the path to
search for the driver to:
\verb=C:\altera\80sp1\qprogrammer\drivers\usb-blasterp= (where 
\verb=C:\altera\80sp1\qprogrammer\= is assumed to be ther path where your
Quartus version is installed).
\begin{enumerate}
\item After starting the Quartus programmer, click on Hardware Setup and in the
"Currently selected hardware" window select USB-Blaster.
\item In the Mode combo box select "Active Serial Programming".
\item Plug the end of your USB-Blaster WITH THE ADAPTER PROVIDED in the
connector ASMI on the MCS board taking care that pin1 corresponds to the one
indexed and with the rectangualr pad.
\item Click on add file and from select the programming file provided when
the upgrade has been reccomended.
\item Check "Program/Configure" and "Verify".
\item Push the start button and wait until the programming process is
finished (progress bar top left).
\item In case the programmer gives you error messages, check the polarity of
your cable (pin1 corresponds) and that you have selected the correct programming
connector.
\end{enumerate}

\subsubsection{On-board Software}
\begin{enumerate}
 \item Connect to the board using telnet:
\begin{verbatim}
telnet  mymcs.mydomain.com
username: root
password: pass
\end{verbatim}
 \item Kill currently running servers and ensure \verb=/mnt/flash/root= exists.
\begin{verbatim}
killall mythenDetectorServer
ls /mnt/flash/root
#if the directory does not exist mkdir /mnt/flash/root
\end{verbatim}
 \item Transfer the provided software by ftp to the MCS.
\begin{verbatim}
ftp  mymcs.mydomain.com
username: root
password: pass
cd /mnt/flash/root
put mythenDetectorServer
quit
\end{verbatim}

\item After pressing reset on the board, the board should reboot.

\item If the program does not correctly start
 \begin{enumerate}
  \item Check by using the http interface that it is started by the inittab
(check that the file \verb=/mnt/etc/inittab= ends with the line \\
\verb=myid2:3:once:/mnt/flash/root/mythenDetectorServer=).  
  \item If program has not started, make the program executable by telnetting to
the MCS and executing: \\
\verb=chmod a+xrw  /mnt/flash/root/mythenDetectorServer=
  \item After pressing reset on the board, the board should reboot and the
acqusition program correctly start.
 \end{enumerate}
\end{enumerate}


\begin{comment}
\section{Detector system architecture}

For most users the detector will be composed by a single module. Therefore all configurations of the detector will refere to that single entity.

However, for some experiments it is necessary to concatenate the data from several detector controllers, and sometimes (e.g. MYTHEN) each controller can control many modules. This should be transparent to the user since most parameters will be identical for all controllers (e.g. exposure time, energy threshold etc.), except for the configurations specific to the controller (e.g. hardware configuration).\\
In principle it is possible to combine controllers of different type (e.g. MYTHEN, GOTTHARD, EIGER) but the user should then evaluate if it really makes sense to control such different systems in parallel.

In other cases, several SLS detectors will independently acquire data during the same experiment. In this case it will be necessary to be able to seperately control them.

The detectors can be controlled in parallel from several PCs (clients). However it is important the the configurations match on all of the them such that no conflict arise. Eventually a detector can be locked to a specific control PC, still different users interfaces (command line, GUI) can be used in parallel.

A sketch of a possible complex detector configuration is shown in figure~\ref{fig:multi_detector}
\subsection{Detector indexes}
For this reason and index is assigned to each detector. If a single detector is used, as in most cases, the index will be omitted and defaults to 0.\\
To control the other detectors the index cannot be omitted!\\


An index will also be assigned to each controller within a detector. However the user normally will not need to address single controllers, except for the most advanced settings which can be left to configuration files.\\


Finally each module within a controller has an internal index. However in general it is not required that the user is aware of the system architecture and, if needed (rarely), the modules can simply be addressed sequentially starting from controller 0.



\begin{figure}
\caption{Scketch of a possible complex system architecture composed of several detector, each consisting in many controllers eventually controlling several modules.}\label{fig:multidet}
\includegraphics[width=\textwidth]{multi_detector}
\end{figure} 

\subsection{Data receiver}

For slower acquisitions, the detector will return the data to the control PC over TCP/IP (e.g. MYTHEN).

However, for faster frame rates (e.g. GOTTHARD, EIGER) the controllers will return the data to a data receiver i.e. a process specifically designed to receive the data from the controller over a GBit network and save them to disk. \\
The data receiver can run on any machine (e.g. a file server) accessible by both the control PC and the detector controller, as sketched in figure~\ref{fig:datareceiver}.

After starting the data receiver process and correctly configuring the client and the detector, this architecture should be completely transparent for the user, except that the output file path must be properly configured from the client for the data receiver machine (easiest is that the disk is mounted for both machines in the same location).\\
The cleint will take care of communicating with the data receiver and the detector. A feedback about the progress of the acquisition and a preview of the data being acquired can also be obtained by the client from the data receiver.


\begin{figure}
\caption{Scketch of the comminication between the control PC, the detector and the data receiver.}\label{fig:datareceiver}
\includegraphics[width=\textwidth]{data_receiver}
\end{figure} 

\subsection{Examples}

For MYTHEN, if one needs to control 6 modules, the system can either be composed by and MCS6 with 6 modules (1 detector, 1 controller, 6 modules), or by 6 MCS1 (1 detector, 6 controller, 1 module each). After apppropriate configuration of the system, the interface to the user will be the same for both systems.

For GOTTHARD, one module corresponds to one controller. A detector will have the smae number of controllers and modules.

For EIGER, one module consists in two controllers. Fo a multi-module system, the number of controllers will increase accordingly, but should be left to a configuration file.

You will need to configure more than one detector, only in case you want to operate several detectors independently.


\section{The trimbits and calibration files} \label{sec:trimdir}


\subsection{MYTHEN}
In order to be able to properly operate your detector you need a directory where the trimbit files (needed to set the detector settings and eventually equalize the individual channel thresholds) which in the following will be named \textit{settingsdir} and a directory where the calibration files (needed to convert the threshold energy in DAC units) are stored which in the following will be named \textit{caldir}. \\
\textit{settingsdir} and \textit{caldir} can even be the same directory, and an example of it is given in the software package by the example directory \verb=trimdir=. 
Since these directories are customized by producing trimbit files and calibration for each detector, make sure not to overwrite yours every time you upgrade the software.

\textit{settingsdir} should contain three subdirectories \verb=standard=,  \verb=fast= and  \verb=highgain= containing respectively the trimfiles \verb=standard.trim=,  \verb=fast.trim= and  \verb=highgain.trim= which contain the correct voltage settings for the detector although all the individual channel thresholds set to 0. The original files contained in the package should be used, infact in case of error the detector would not recognize the correct settings.\\
The default trimbit files for each file will be stored in the directory according to the settings with the name \verb=noise.snxxx= where \verb=xxx= is the module serial number.\\

\textit{caldir} should contain three subdirectories \verb=standard=,  \verb=fast= and  \verb=highgain= containing respectively the trimfiles \verb=standard.cal=,  \verb=fast.cal= and  \verb=highgain.cal= which contain an average calibration of the modules for the diffrent settings. However this can different from the correct one for each individual module even of several kev and therefore it is very important to perform an energy calibration on a module basis.\\
The default calibration files for each file will be stored in the directory according to the settings with the name \verb=calibration.snxxx= where \verb=xxx= is the module serial number.

The \textit{settingsdir} and \textit{caldir} should be properly configured for your detector either in a configuration file (for use with text clients, GUI or API) or dynamically (works only for the text clients).

\subsection{GOTTHARD}
A \textit{settingsdir} should be configured, as the directory  \verb=settings= in this software package.\\
It must contain the subdirectories \verb=dynamicgain=, \verb=gain1=, 
\verb=gain2=,  \verb=gain3=,  \verb=highgain=,  \verb=lowgain=, 
\verb=mediumgain=, and   \verb=veryhighgain= in order to properly configure the
GOTTHARD detector using the various gain settings.

\end{comment}

\end{document}