%==============================================================================
% Document header
%==============================================================================
\documentclass[a4paper,11pt]{article}

% Margin setup to use more of the page
\usepackage[top=3cm, bottom=3cm, left=2cm, right=2cm]{geometry}

% Color package
\usepackage[usenames,dvipsnames,table]{xcolor}

% Hyperrefs
\usepackage[
  colorlinks = true,
  linkcolor  = black,
  citecolor  = black,
  urlcolor   = blue,
]{hyperref}

% Longtable
\usepackage{longtable}

% Graphics, multirow
\usepackage{graphicx}
\usepackage{multirow}

% Appendix package
\usepackage[toc,page]{appendix}

\usepackage{fancyhdr}
\setlength{\headheight}{15.2pt}
\pagestyle{fancy}
\fancyhead[L]{\nouppercase{\leftmark}}
\fancyhead[R]{}
\renewcommand{\footrulewidth}{0.4pt}

% Row number command
\newcounter{rownr}
\newcommand{\rownumber}{\stepcounter{rownr}\arabic{rownr}}

%==============================================================================
% Start of document
%==============================================================================
\begin{document}

%------------------------------------------------------------------------------
% Title
%------------------------------------------------------------------------------
\include{cern-title}

%------------------------------------------------------------------------------
% Licensing info
%------------------------------------------------------------------------------
\pagebreak

\thispagestyle{empty}

\addcontentsline{toc}{section}{Licensing information}
\section*{Licensing information}

\noindent
This document is licensed under a Creative Commons Attribution-ShareAlike 4.0
International License. If you have not received a copy of the license along with this
work, see \\
\url{http://creativecommons.org/licenses/by-sa/4.0/}

%------------------------------------------------------------------------------
% Revision history
%------------------------------------------------------------------------------
\section*{Revision history}
\addcontentsline{toc}{section}{Revision history}

\centerline
{
  \rowcolors{2}{white}{gray!25}
  \begin{tabular}{l c p{.6\textwidth}}
  \hline
  \multicolumn{1}{c}{\textbf{Date}} & \multicolumn{1}{c}{\textbf{Version}} & \multicolumn{1}{c}{\textbf{Change}} \\
  \hline
  12-01-2015 & 0.1 & First draft \\
  \hline
  \end{tabular}
}

%------------------------------------------------------------------------------
% Table of contents, list of figs, tables
%------------------------------------------------------------------------------
\pagebreak
\pdfbookmark[1]{\contentsname}{toc}
\tableofcontents

%------------------------------------------------------------------------------
% List of abbreviations
%------------------------------------------------------------------------------
\pagebreak
\section*{List of abbreviations}
\begin{tabular}{l l}
FM & Front Module \\
PTS & Production Test Suite \\
RTM & Rear-Transition Module \\
\end{tabular}
\addcontentsline{toc}{section}{List of abbreviations}

%==============================================================================
% SEC: Intro
%==============================================================================
\pagebreak
\section{Introduction}
\label{sec:intro}

This document shows how to install a PTS test system for the CONV-TTL-RS485 FM cards.
It takes the reader through installing wires that are needed for these cards through the 19'' rack,
and then focuses on installing the test system (scripts, preparing shortcuts, etc.) on the PTS laptop.

%==============================================================================
% SEC: Rack setup
%==============================================================================
\section{Rack setup}
\label{sec:rack}

To setup the rack for the PTS system, we will need to pass some Lemo 00 cables from the
front to the back of the 19'' rack. Then, we'll need to connect two RS-485 tester cards
to these cables so that the FM can drive the tester card to perform the tests.
The following steps should be performed:

\begin{enumerate}
  \item Open the top and back of the 19'' rack
  \item Take four \textcolor{red}{\textbf{LENGTH}} Lemo 00 cables and pass them from the front
  to the back of the rack
  \item Fix them to the rack so that they can be inserted in slot 5 of the ELMA crate
  \item Take four Lemo 00 T splitters and connect one short (1~ns delay) Lemo 00 cable
  on each female plug of the T splitters
  \item Using Lemo 00 female-to-female adapters, connect the long cables coming
  from the front of the rack to the T splitters' male side
  \item Label each of the long cables with colored labels on both sides, in this order from
  left to right:
  \begin{itemize}
    \item blue
    \item green
    \item red
    \item yellow
  \end{itemize}
  \item Take the two RS-485 tester cards and insert the short (1~ns) cables to the plugs
  according to the color coding:
  \begin{itemize}
    \item blue cables to BLU plugs
    \item green cables to GRN plugs
    \item red cables to RED plugs
    \item yellow cables to YEL plugs
  \end{itemize}
  \item Insert a CONV-TTL-RTM-RS485 card into the back of the ELMA crate, in slot 4
  \item Insert the two RS485 tester cards all the way into the RTM in slot 5:
  \begin{itemize}
    \item one tester card for channels 1--3
    \item the other for channels 4--6
  \end{itemize}
  \item Close the top of the 19'' rack
  \item Close the back of the 19'' rack
\end{enumerate}

%==============================================================================
% SEC: Install Ubuntu on the laptop
%==============================================================================
\pagebreak
\section{Install Ubuntu on the laptop}
\label{sec:install-ubuntu}

If you end up with a bare laptop without an OS installed, you have to follow the
laptop installation guide written by Julian for the SVEC PTS system:

  \begin{itemize}
    \item \url{http://cern.ch/go/H9tv}
  \end{itemize}

Note that this guide can be followed selectively, for example you need not set up your
system to gain remote access to the laptop, the installation of the system can also be done
on the laptop directly. However, the steps related to network drivers and configuration
should be followed in order to have a properly working PTS system.

The guide should be followed until \textbf{step 17} of section \textbf{Set up the PTS user account}.
After this step, the guide is SVEC-related and need not be followed. We will continue with
the details in the next section to test our system and network was properly installed.

%==============================================================================
% SEC: ELMA setup
%==============================================================================
\section{Setting up the ELMA crate}
\label{sec:elma-setup}

\begin{enumerate}
  \item The ELMA crate should be configured to have the password \verb=ADMIN= for the \verb=admin= account
  \item Login to the ELMA crate to test the setup in Section~\ref{sec:install-ubuntu}:
  \begin{verbatim}
  $ telnet elma
  Trying 192.168.20.22...
  Connected to elma.
  Escape character is '^]'.
  login:admin
  password: ADMIN
  %>
  \end{verbatim}
  \item If the prompt appears as above, the setup is fine. Now we need to disable the telnet ping
  that the SysMon does, so it doesn't get in the way of our Python scripts, which use Telnet
  to talk to the CONV-TTL-RS485 FPGA:
  \begin{verbatim}
  %> telnetping 0
  %> saveenv
  %> reboot
  \end{verbatim}
  \item This last command will reboot the SysMon to store the telnetping settings, so the connection to the
  ELMA will be lost. This is an expected behaviour and should not get in our way. Simply reconnect
  as in step 2 to make sure the connection still works after reboot.
\end{enumerate}

%==============================================================================
% SEC: Test environment
%==============================================================================
\pagebreak
\section{Preparing the laptop test environment}
\label{sec:environment}

After Ubuntu has been set up and the ELMA connection tested, we need to set up the
actual test scripts and a way of running them. This entails copying the PTS folder
structure for the CONV-TTL-RS485 PTS to the laptop, copying the shortcuts to the
Desktop so that a user can run them and creating a dedicated Ubuntu user for the
CONV-TTL-RS485 PTS.

Note that there are two ways of obtaining the PTS folder structure:

\begin{itemize}
  \item Download the ready-made archive from OHWR
  \item Build the test system from the repository
\end{itemize}

We will detail here the simplest of the two, downloading the ready-made archive.
See Appendix~\ref{app:build} for details on the second.

\begin{enumerate}
  \item Log in to the \verb=pts= user on the laptop
  \item Open up a terminal window, download the PTS folder structure tarball from OHWR
  to the home folder of the \verb=pts= user and extract the archive:
  \begin{verbatim}
  cd ~
  wget http://www.ohwr.org/attachments/download/3745/ubuntu.tar.gz
  tar xzvf ubuntu.tar.gz
  \end{verbatim}
  \item Check that all extracted files and folders have write permissions:
  \begin{small}
  \begin{verbatim}
  $ cd ubuntu/t485/
  $ ls -l
  total 56
  drwxrwxr-x 7 tstana tstana  4096 Jan  8 11:45 ./
  drwxrwxr-x 3 tstana tstana  4096 Jan  8 11:45 ../
  drwxrwxr-x 2 tstana tstana  4096 Jan  8 11:45 boot/
  drwxrwxr-x 3 tstana tstana  4096 Jan  8 11:45 config/
  lrwxrwxrwx 1 tstana tstana    17 Jan  8 11:45 flashtest.py -> pyts/flashtest.py
  -rwxrwxr-x 1 tstana tstana 10933 Jan  8 11:45 jpts*
  drwxrwxr-x 2 tstana tstana  4096 Jan  8 11:45 log/
  -rwxrwxr-x 1 tstana tstana  2949 Jan  8 11:45 one*
  -rwxrwxr-x 1 tstana tstana  9906 Jan  8 11:45 pts*
  drwxrwxr-x 2 tstana tstana  4096 Jan  8 11:45 pyts/
  drwxrwxr-x 2 tstana tstana  4096 Jan  8 11:45 shell/
  lrwxrwxrwx 1 tstana tstana    20 Jan  8 11:45 test01.py -> pyts/dac_vcxo_pll.py
  lrwxrwxrwx 1 tstana tstana    12 Jan  8 11:45 test02.py -> pyts/leds.py
  lrwxrwxrwx 1 tstana tstana    24 Jan  8 11:45 test03.py -> pyts/ttl_pulse_switch.py
  lrwxrwxrwx 1 tstana tstana    23 Jan  8 11:45 test04.py -> pyts/rs485_pulse_rtm.py
  lrwxrwxrwx 1 tstana tstana    16 Jan  8 11:45 test05.py -> pyts/therm_id.py
  lrwxrwxrwx 1 tstana tstana    18 Jan  8 11:45 test06.py -> pyts/sfp_eeprom.py
  lrwxrwxrwx 1 tstana tstana    16 Jan  8 11:45 test07.py -> pyts/sfp_test.py
  \end{verbatim}
  \end{small}
  \item If they do not have write permissions, as in the case above, make sure they do:
  \begin{verbatim}
  chmod a+w *
  \end{verbatim}
  \item Now we that have the test scripts on the system we can create a dedicated
  user that will be used to run the PTS for the CONV-TTL-RS485. Open up Ubuntu's
  \textbf{User Accounts} window (click the \verb=pts= user account name at the top
  left of the screen), unlock this window by providing the \verb=pts= user account's
  password (\verb=pts-user=) and create a new user with the following settings:
  \begin{itemize}
    \item \textbf{Account Type:} Standard
    \item \textbf{Full name:} conv-ttl-rs485
    \item \textbf{Username:} conv-ttl-rs485
  \end{itemize}
  \item While still in the \textbf{User Accounts} window, click the new 
  \verb=conv-ttl-rs485= user account
  \item Under \textbf{Login options}, click the \textbf{Password} dialog which should 
  at this moment be set to \textit{Account disabled}
  \item In the dialog that opens up, set the following parameters:
  \begin{itemize}
    \item \textbf{Action: } Set a password now
    \item \textbf{New password: } pts-user
  \end{itemize}
  \item Log in to the new \verb=conv-ttl-rs485= user account
  \item Open up a terminal window here, and copy 
  the desktop shortcuts from the extracted PTS tarball to this user's desktop:
  \begin{verbatim}
  cd ~/Desktop/
  cp /home/pts/ubuntu/t485/config/*.desktop .
  \end{verbatim}
  \item You should now have a working PTS test system. Navigate to the desktop and
  try to run the new \textbf{Run CONV-TTL-RS485 PTS} executable here. Plug in a card
  to see if the PTS system communicates to it (no need to set up daisy-chains or anything
  for this test, you can do that later).
\end{enumerate}

%==============================================================================
\pagebreak
\begin{appendices}
%==============================================================================

\section{Building the test system from the repository}
\label{app:build}

The CONV-TTL-RS485 test system is devised to be built using a simple \verb=make=
command. The system contains a Makefile which, based on a few PTS-specific options,
builds up a folder structure for the PTS as the designer wants it. The \verb=make=
options for the PTS are:

\begin{itemize}
  \item \textbf{BOARD} -- in the case of converter boards, it is the board ID~\cite{board-id}; this
  option also specifies what is the starting string of the PTS log files (in the
  case of CONV-TTL-RS485: \verb=t485-*.log=, \verb=t485-*.inf= )
  \item \textbf{ELMAIP} -- the IP or hostname of the ELMA crate the PTS is built for
  \item \textbf{ELMAPWD} -- the password for the admin account of the ELMA crate
  the PTS is built for
  \item \textbf{ELMASLOT} -- the slot number where the CONT-TTL-RS485 card is placed during testing
\end{itemize}

As an example, the PTS folder structure for the CONV-TTL-RS485 was built using the following
command:

\begin{verbatim}
  make ELMAIP=elma ELMAPWD=ADMIN ELMASLOT=5
\end{verbatim}

This built a system that communicates with the ELMA crate with the hostname \verb=elma= that
has the RS485 pulse repeaters placed in slot 5 when the PTS is run.

In order to build a test system from scratch, follow these steps:

\begin{enumerate}
  \item Clone the repository for the CONV-TTL-RS485 (\verb=git= is needed for this):
  \begin{small}
  \begin{verbatim}
  git clone git://ohwr.org/level-conversion/conv-ttl-rs485/conv-ttl-rs485-tst.git
  \end{verbatim}
  \end{small}
  \item Run \verb=make= in the \verb=pts-fm/= folder, setting the options as appropriate
  in your case:
  \begin{verbatim}
  cd conv-ttl-rs485-tst/pts-fm/
  make # ... set options here ...
  \end{verbatim}
\end{enumerate}

This will generate an archive similar to that downloaded in Section~\ref{sec:environment},
that should be copied to the test system as described in Section~\ref{sec:environment}.

%==============================================================================
\end{appendices}
%==============================================================================
\pagebreak
\bibliographystyle{ieeetr}
\bibliography{setup}
\addcontentsline{toc}{section}{References}

\end{document}
