dls.tex

\chapter{DLS}


\label{chap:dls}
The Data Logging Service (DLS) is a data logging system for EtherLab. It
connects to PdServ and stores time series on disk.
The official documentation is available in \cite{dls_user_manual}.


\section{Install prerequisites}

The following prerequisites must be installed to compile DLS.

\subsubsection{Binary packages}
\begin{shellcmd}
sudo apt install autoconf libtool libexpat1-dev    \
                 libxml2-dev libfltk1.3-dev        \
                 libfftw3-dev liburiparser-dev     \
                 protobuf-compiler libprotobuf-dev \
                 libpcre3-dev
\end{shellcmd}

\subsubsection{PdCom library}
PdCom is the library used to communicate with PdServ. It must be downloaded
and compiled from source.

\noindent Download and compile the PdCom library
\begin{shellcmd}
cd /tmp
git clone https://gitlab.com/etherlab.org/pdcom.git
cd pdcom
git checkout 3.0.9
./bootstrap.sh
./configure --prefix=/opt/etherlab
make
\end{shellcmd}

\noindent Install the PdCom library
\begin{shellcmd}
sudo make install
\end{shellcmd}



\section{Get the DLS source code}
Download the source code with git, then switch to the revision
that has been tested in this tutorial (commit 370553789444).
\begin{shellcmd}
cd /tmp
git clone https://gitlab.com/etherlab.org/dls.git
cd dls
git checkout 370553789444fc6c19ae22091db00067791370ef
\end{shellcmd}

\section{Compile the DLS source code}

DLS uses a classic autoconf script to generate the Makefile.
\begin{shellcmd}
cd /tmp/dls
./bootstrap.sh
./configure --prefix=/opt/etherlab
make
\end{shellcmd}


\section{Install the DLS programs}
The programs are installed in \texttt{/opt/etherlab}. \\

\begin{shellcmd}
sudo make -C /tmp/dls install
sudo ldconfig
\end{shellcmd}

\subsubsection{Create a system account}
Create a system account \texttt{dls}.

\begin{shellcmd}
sudo useradd -s /usr/sbin/nologin -r dls
\end{shellcmd}


\subsubsection{Create data directories}

Create a directory (\texttt{/home/dls/data}) to store recorded data.
\begin{shellcmd}
sudo install -d -o dls -g dls /home/dls/data
\end{shellcmd} 


\section{Manage acquisitions with dls\_ctl}

Acquisitions are managed with \texttt{dls\_ctl}.

\begin{shellcmd}
sudo -i
export PATH=/opt/etherlab/bin:$PATH
dls_ctl -d /home/dls/data
\end{shellcmd}

\subsubsection{Initialize the data directory}
The main window appears. The program asks whether the data directory
  should be initialized. Answer YES.

\begin{center}
\includegraphics[width=\textwidth]{genpicts/dls_ctl-00.eps}
\end{center}

\subsubsection{Start the acquisition daemon}
The program asks whether the acquisition daemon
  should be started. Answer YES.

\begin{center}
\includegraphics[width=\textwidth]{genpicts/dls_ctl-01.eps}
\end{center}

\noindent In the console, a message indicates that the DLS daemon is now running.

\begin{shellout}
dls_ctl 1.4.0-rc2 revision 51dc3443178a
DLS data directory "/home/dls/data"
dlsd 1.4.0-rc2 revision 51dc3443178a
Using dls directory "/home/dls/data"
DLS running with PID 26307 [daemon]
\end{shellout}


\subsubsection{Configure acquisition}

\noindent Click \textit{New job} to create a new acquisition job
\begin{center}
\includegraphics[width=\textwidth]{genpicts/dls_ctl-02.eps}
\end{center}


\begin{warning}
Fill in the form with the job properties. The \textit{Source} field cannot be
modified later; therefore it must be entered correctly the first time.
\end{warning}

\begin{center}
\includegraphics[width=0.35\textwidth]{genpicts/dls_ctl-03.eps}
\end{center}

\noindent The new job appears in the list. Double-click it
to edit the channels.

\begin{center}
\includegraphics[width=\textwidth]{genpicts/dls_ctl-04.eps}
\end{center}

\noindent Click on \textit{Add channels...}
\begin{center}
\includegraphics[width=0.75\textwidth]{genpicts/dls_ctl-05.eps}
\end{center}

\noindent Select the channel \textit{/s1/c}
\begin{center}
\includegraphics[width=0.75\textwidth]{genpicts/dls_ctl-06.eps}
\end{center}

\noindent Close the job window.
\begin{center}
\includegraphics[width=0.75\textwidth]{genpicts/dls_ctl-07.eps}
\end{center}

\noindent Click the \textit{Start} button
\begin{center}
\includegraphics[width=\textwidth]{genpicts/dls_ctl-08.eps}
\end{center}

\noindent The acquisition is running.
\begin{center}
\includegraphics[width=\textwidth]{genpicts/dls_ctl-09.eps}
\end{center}




\section{Plot channels with dls\_view }

\texttt{dls\_view} is the legacy viewer for DLS.
The newer viewer (\texttt{dlsgui}) is explained in section \ref{chap:dlsgui}.


\subsubsection{Run dls\_view}

Unlike \texttt{dlsgui}, \texttt{dls\_view} needs file system access to the
recorded data.

\begin{shellcmd}
sudo -i
export PATH=/opt/etherlab/bin:$PATH
dls_view -d /home/dls/data
\end{shellcmd}


\noindent Select the acquisition job to display.

\begin{center}
\includegraphics[width=0.9\textwidth]{genpicts/dls_view-00.eps}
\end{center}


\noindent Select the channel to display
\begin{center}
\includegraphics[width=0.9\textwidth]{genpicts/dls_view-01.eps}
\end{center}


\noindent The plot appears as a green rectangle because the lines
are too densely compressed.

\begin{center}
\includegraphics[width=0.9\textwidth]{genpicts/dls_view-02.eps}
\end{center}


\noindent Draw a rectangle in the viewing area to zoom in; click on
the viewing area to zoom out. See \cite{dls_user_manual} for the
complete description of the user interface.

\begin{center}
\includegraphics[width=0.9\textwidth]{genpicts/dls_view-03.eps}
\end{center}