The preferred method to run the \gls{tlu} is by using the \href{https://github.com/eudaq/eudaq}{EUDAQ}\footnote{https://github.com/eudaq/eudaq} data acquisition framework.\\
A \gls{tlu} producer, based on C++, has been written to integrate the hardware in EUDAQ and is regularly pushed to the master repository. Checking out the latest EUDAQ software ensures to also have a stable version of the producer.\\
In addition to the EUDAQ producer, a set of Python scripts has been developed to enable users to configure and run the \gls{tlu} using a minimal environment without having to setup the whole data acquisition framework. The scripts are meant to reflect all the functionalities in the EUDAQ producers, i.e. using the scripts it should be possible to perform any operation available on the EUDAQ producer. However, they should only be used for local debugging and testing.\\
\begin{alertinfo}{Warning}
When fixing bus or developing new software for the \gls{tlu}, priority will be given to ensure that the EUDAQ producer is patched first. As a consequence, there is a higher chance to find bugs in the Python scripts.
\item[Flag] Independent from producer. See the \href{https://github.com/eudaq/eudaq/blob/master/main/lib/core/include/eudaq/Event.hh#L87}{EUDAQ documentation} for details.
\item[RunN]
\item[StreamN]
\item[EventN]
\item[TriggerN] Both in the event and subevent this is written byt the producer with \verb|ev->SetTriggerN(trigger_n);|
\item[Timestamp] The event timestamp is currently always 0. The subevent timestamps is written by the producer \verb|ev->SetTimestamp(ts_ns, ts_ns+25, false);|. The top line (0x0000000105b44f91, in the example) is coarse time stamp multiplied by 25, so it represents the time in nanoseconds. The bottom one (4390670225) is the same number but written in decimal format instead of hexadecimal.
\item[PARTICLES] Number of pre-veto triggers recorded by the \gls{tlu}: the trigger logic can detect a valid trigger condition even when the unit is vetoed. In this case no trigger is issued to the \gls{dut}s but the number of such triggers is stored as number of particles. \verb|ev->SetTag("PARTICLES", std::to_string(pt));|
\item[SCALER\#] Number of triggers edges seen by the specific discriminator. \verb|ev->SetTag("SCALER", std::to_string(sl));|
\item[???] Event type from \gls{tlu} is missing?
\item[???] Input trig, i.e. the actual firing inputs should be in TRIGGER but there seems to be nothing there
\end{description}
\section{Python scripts}
The scripts used to debug work locally with the \gls{tlu} are located in a dedicated folder in the \href{https://github.com/PaoloGB/firmware_AIDA/tree/master/TLU_v1e/scripts}{firmware repository}\footnote{https://github.com/PaoloGB/firmware\_AIDA/tree/master/TLU\_v1e/scripts} and rely on additional packages and software.
First of all, the user should download the \href{https://github.com/PaoloGB/firmware_AIDA/tree/master/packages}{packages} used to control the various components of the hardware\footnote{https://github.com/PaoloGB/firmware\_AIDA/tree/master/packages}. It is also necessary to have a local installation of \href{https://ipbus.web.cern.ch/ipbus/doc/user/html/index.html}{IPBUS and uHAL}\footnote{https://ipbus.web.cern.ch/ipbus/doc/user/html/index.html}.\\
Once all the necessary packages have been installed and the environment is set to point to the right folders, it is possible to run the \verb|startTLU_v1e.py| script to start an interface that allows to operate the \gls{tlu}.
@@ -86,16 +86,17 @@ Each unit is shipped with the latest version of the firmware written onto its bo
If the \gls{fpga} detects a programming cable connected it will not load the firmware from its memory after a power cycle.\\
It is recommended to leave the \gls{usb} cable disconnected from the back panel unless there is the intention to re-program the firmware.
\end{alertinfo}
The latest version of the firmware can be found on the project github repository (named \href{https://github.com/PaoloGB/firmware_AIDA}{firmware\_AIDA}).\\
The user can decide to configure the unit with a new version of the firmware that will remain active until the \gls{tlu} is powered off (standard programming). It is also possible to write the \gls{eeprom} to replace boot program with a new one (configuration memory programming). Both procedures are described below.
The latest version of the firmware can be found on the project \gls{ohwr} github repository (\href{https://ohwr.org/project/fmc-mtlu-gw}{AIDA-2020 TLU - Gateware}).\\
The user can decide to configure the unit with a new version of the firmware that will remain active until the \gls{tlu} is powered off (standard programming). It is also possible to write the \gls{eeprom} to replace boot program with a new one (configuration memory programming). Both procedures are described below.\\
Programming the \gls{fpga} requires the Vivado Lab Tools, available free on the \href{https://www.xilinx.com/support/download.html}{on the Xilinx website}\footnote{https://www.xilinx.com/support/download.html}. Depending on the hardware installed internally, some additional drivers might be required to correctly use the \gls{jtag} cable.\\
At the time of writing, the preferred cable is the Digilent HS2 and the corresponding driver package is ADEPT 2, available on the \href{https://reference.digilentinc.com/reference/software/adept/start}{Digilent website}\footnote{https://reference.digilentinc.com/reference/software/adept/start}.
At the time of writing, the preferred cable for the table-top \gls{tlu} is the \href{https://store.digilentinc.com/jtag-hs2-programming-cable/}{Digilent HS2}\footnote{https://store.digilentinc.com/jtag-hs2-programming-cable/}; the corresponding driver package is ADEPT 2, available on the \href{https://reference.digilentinc.com/reference/software/adept/start}{Digilent website}\footnote{https://reference.digilentinc.com/reference/software/adept/start}.\\
For the 19-inch rack mount unit, the cable used is the Trenz \href{https://shop.trenz-electronic.de/en/TE0790-02-XMOD-FTDI-JTAG-Adapter-Xilinx-compatible?c=318}{TE0790-02}\footnote{https://shop.trenz-electronic.de/en/TE0790-02-XMOD-FTDI-JTAG-Adapter-Xilinx-compatible?c=318}. This cable is compatible with Xilinx products and does not require additional software.
Updating the firmware on the \gls{tlu} requires writing a bit stream file to its \gls{fpga}.
This operation is performed using the left \gls{usb} port located on the back panel, labelled \verb"FPGA PROGRAMMING" in figure~\ref{ch:backpanelintro}.\\
Once the Vivado tools have been installed the user should also install the drivers for the programming cable in the enclosure (see previous section for software sources).\\
The bit stream is provided as a \verb".bit" file. They can be found on the firmware \href{https://github.com/PaoloGB/firmware_AIDA/tree/master/bitFiles}{git repository} for the \gls{tlu}\footnote{https://github.com/PaoloGB/firmware\_AIDA/tree/master/bitFiles}.\\
The bit stream is provided as a \verb".bit" file and can be found on the firmware \href{https://ohwr.org/project/fmc-mtlu-gw}{\gls{ohwr} repository} for the \gls{tlu}\footnote{https://ohwr.org/project/fmc-mtlu-gw/tree/master/AIDA\_tlu/bitFiles}.\\
Once these prerequisites are met, the procedure is as follows:
\begin{enumerate}
\item Open the Vivado tools and select "Hardware manager", figure\ref{fig:hw_open}
...
...
@@ -125,7 +126,8 @@ This will open a new window, shown in figure~\ref{fig:hw_eeprom}, from which it
\caption{\gls{eeprom} interface. The options shown in the picture are suitable to configure the device correctly.}
\label{fig:hw_eeprom}
\end{figure}
Make sure that the options are set as shown in figure~\ref{fig:hw_eeprom}.
Make sure that the options are set as shown in figure~\ref{fig:hw_eeprom}.\\
The firmware loaded this way will overwrite any pre-existing firmware and will be loaded automatically whenever the unit is powered up.
\section{Inspection (table top unit)}\label{ch:inspection}
At some point someone, somewhere, will want to disassemble the unit to poke at its internal electronics; the top cover of the unit can only slide away when either the front or back frame are removed.
...
...
@@ -148,12 +150,15 @@ The same procedure can be repeated with the front frame, if necessary. In this c
\caption{Steps to remove the cover from the unit.}
\caption{Steps to remove the cover from the unit. The screws to take the unit apart are hidden behind the corner plates. The plates can be removed by pulling.}
\label{fig:dismantle}
\end{figure}
\section{Inspection (19"-rack unit)}
Accessing the hardware on the 19"-unit is more straightforward: simply remove the four M2.5 Pozi screws located on the top panel and slide the panel away. Please note that this unit has an internal AC-DC converter that can potentially store an harmful amount of energy even when powered-off and disconnected from the mains: always use care when accessing the unit.
Accessing the hardware on the 19"-unit is more straightforward: simply remove the four M2.5 Pozi screws located on the top panel and slide the panel away. Please note that this unit has an internal AC-DC converter that can potentially store an harmful amount of energy even when powered-off and disconnected from the mains: always use care when accessing the unit.
\begin{alertinfo}{Danger}
Before disassembling the 19-inch rack mounted \gls{tlu} disconnect the mains cable from the back and leave sufficient time for the internal capacitors to discharge.
\end{alertinfo}
%\section{Preparation}
%Before powering the \gls{tlu} it is necessary to follow a few steps to ensure the board and the \gls{fpga} work correctly.\\
