% UFO camera user manual % \chapter{User manual} \section{Concept} A high performance camera interface combined with application specific camera controllers opens a wide range of opportunities for scientific applications. Figure \ref{camera-setup} shows the first prototype of the fully programmable high-throughput UFO camera currently developed at KIT. The main features of the UFO camera are: \begin{itemize} \item Modular concept with fast FMC interface between camera controller and image sensor. With minimal effort a large variety of image sensors can be included in the setup. \item Powerful high bandwidth firmware to handle data rate currently up to 2GByte/sec. \item Fast interface to the readout PC using a PCI Express extender. High performance Linux drivers for the architecture are available. \item Interfaces for attaching application specific logic in FPGA and driver. \end{itemize} \begin{figure} \includegraphics[width=\textwidth]{images/Figure_2.png} \caption{\label{camera-setup} Prototype of the modular UFO camera.} \end{figure} \section{Supported image sensors} The prototype of the UFO camera has been developed using the images sensor CMOSIS CMV2000 with 2.2 mega pixel and frames rates of up to 340 fps in full resolution. The sensor supports to modes of operation with 10bit and 12bit resolution \cite{CMOSIS:CMV2000}. A full list of supported and future sensors is given in table \ref{image-sensors}. \begin{table} \begin{center} \begin{tabular}{|c|c|p{8cm}|} \hline Image sensor & Mode & Comment \\ \hline CMOSIS CMV2000 & 10bit, 340fps & Implemented, tested, characterized \\ \hline CMOSIS CMV2000 & 12bit, 70fps & Implemented, tested, characterized \\ \hline CMOSIS CVM4000 & & Ordered. Note: the sensor is pin compatible with the smaller CMV2000 and provides the same operation mode \cite{CMOSIS:CMV4000}. \\ \hline Fairchild CIS1021 & 2x11bit, 100fps & Planned \cite{FAIRCHILD:CIS1021}\\ \hline \end{tabular} \end{center} \caption{List of supported image sensors.} \label{image-sensors} \end{table} \section{Starting the camera} Camera and readout PC are considered as a unit. In order to establish word with the camera prototype a certain procedure has to be followed. \begin{itemize} \item First, the camera has to be turned ON while the readout PC is ON. \item Reboot the readout PC. Currently only then the connection is properly established. \item Check that the camera is operational. The LEDs on the controller board should show the following values:\\ DS19 blinking, DS18 ON, DS20 ON, DS17 OFF. All three LEDs on FMC board should be ON to indicate proper voltage levels. CBL and EDGE LEDs should be ON to indicate proper PCIe connection. \item Select the desired frame rate using the script \verb/Reset__bits.sh/ \item Check again the status. Now also the LEDS DS21, DS14, DS15 need to be ON. \end{itemize} \subsection{LED status indicators} For visual confirmation of the camera's proper working state, number of LED indicators are provided on the camera controller board, shown in \figurename~\ref{pic_LED}. The description of this LEDs is given in \tablename~\ref{LEDs}. For other existing LEDs on the FPGA main board, they are related to ML605 board functionality \cite{XILINX:ML605}. Beside the visual information of the LEDs more details are given by the status register of the camera. \begin{figure}[p] \centering \includegraphics[width=0.7\textwidth]{images/pic_LEDs.png} \caption{\label{pic_LED} Camera indicator LEDs} \end{figure} \begin{table}[p] \caption{\label{LEDs} List of status LEDs on the camera controller board.} \begin{center} \begin{tabular}{|c|c|c|} \hline LED & Status & Comment \\ \hline DS18 & On & DDR3 initialization has completed \\ \hline DS16 & On & Readout in progress \\ \hline DS14 & On & data register is locked\\ \hline & Off, Flashing & data register doesn’t work correctly \\ \hline DS15 & On & status register is locked\\ \hline & Off, Flashing & status register doesn’t work correctly \\ \hline DS19 & Flashing & 200 MHz clock is alive \\ \hline DS21 & On & Busy active \\ \hline DS17 & Off & PCIe connection is properly established \\ \hline DS12 & On & DMA ready to accept data \\ \hline \end{tabular} \end{center} \end{table} \newpage \subsection{Reset scripts} The script \verb/Reset__bits.sh/ will report if initialization completed successfully. If initialization is executed successfully the status OK is printed and the camera is ready for operation. Example: configuring camera for 12 bit mode \begin{lstlisting} ufo@ufocamera:~> Reset_Init_all_reg_12bit.sh Reset Readout and CMOSIS Release Reset for Readout Start CMOSIS Configuration .. 12 - bit mode, set Bit_mode 12 bit mode, set ADC resolution 12 bits End CMOSIS Configuration .. Write exp time...... cmosis_number_lines = 1088 Camera READY ........ OK \end{lstlisting} \newpage \section{Camera interfaces} The camera can be used by a graphical user interface. It displays life images and provides access to all camera parameters. For automation of purpose the powerful command-line tool pcitool is available. The distribution contains several scripts that implement some often used functions. \subsection{Graphical camera user interface} The camera comes with a graphical application that displays live images from the camera. The bottom tab provides some short cuts for often used camera functions. The full set of camera properties are accessible in the right part of the application. The graphical user interface is shown in \figurename~\ref{camera-gui}. The main screen display the image data from the camera. The control buttons above the main window allow an video recorder like recording and replay of the selected scenes. The bottom part provides some shortcuts for often used camera parameters. The full set of camera properties are accessible in the right part of the application. With the double click on the parameter name the value can be changed. All sensor registers are accessible as well. \begin{figure}[h] \includegraphics[width=\textwidth]{images/ufo_gui2.png} \caption{\label{camera-gui} Camera frontend} \end{figure} \subsubsection{Set camera parameters} Select the parameter "Exposure" in the bottom window, increment the value, or directly writing the desired value in the appropriate space. The value should be given in units of seconds. Alternatively the parameter "exposure-time" from the parameter list in the right window could be chosen. \subsubsection{Piecewise-linear response function} The camera can be used with a piecewise linear response function. This gives the possibility to achieve a virtual higher optical dynamic range. The feature will clip illuminated pixels which reach a programmable voltage, while leaving the darker pixels untouched. The clipping level can be adjusted 2 times within one exposure time to achieve a maximum of 3 slopes in the response curve. In the dislay it is shown using bar for piecewise linear response. It is shown in \figurename~\ref{ufo_gui_piecewise_bar}. More information for using the piecewise can be found in CMOSIS2000 reference sheet \cite{CMOSIS:CMV2000}. \begin{figure}[h] \centering \includegraphics[width=1\textwidth]{images/ufo_gui_piecewise_bar.png} \caption{\label{ufo_gui_piecewise_bar} Dialog to customize the piecewise linear response function} \end{figure} \subsubsection{Monitoring of the camera temperatures} Finally the temperature of sensor and FPGA is monitored. It is shown in \figurename~\ref{ufo_gui_temp_bar}. Alarm would indicate if the temperature of the FPGA exceeds the alarm limits. \begin{figure}[h] \centering \includegraphics[width=\textwidth]{images/ufo_gui_temp.png} \caption{\label{ufo_gui_temp_bar} Sensor temperature monitoring} \end{figure} %TODO: How to save a picture with the GUI? % Host: ipecamera \subsection{Command line tools in pci-tools} The pcitools provide complete control of all camera properties. It allows to read and write the camera registers, trigger frame acquisition, initiate DMA transfers, and check the status of active operations. Basically, the command is executed as follows: \begin{verbatim} pci [options] [hex data] \end{verbatim} The first argument mode defines the global mode of operation. Examples are retrieving current camera configuration, reading and writing registers and device memory, performing DMA transfers, or performing continuous frame grabbing. There mode of operation is followed by one or more options that specify various parameters like the register name or address to read/write, required frame rate, number of frames to grab, etc. Finally, the hex data is hex decimal values written to the registers. More information about of the pcitool usage can be found with \verb/pci -h/. \begin{lstlisting} ufo@ufocamera:~> pci -h Usage: pci [options] [hex data] Modes: -i - Device Info -l[l] - List (detailed) Data Banks & Registers -r - Read Data/Register -w - Write Data/Register --benchmark - Performance Evaluation --reset - Reset board --help - Help message Event Modes: --trigger [event] - Trigger Events -g [event] - Grab Events DMA Modes: --start-dma [r|w] - Start specified DMA engine --stop-dma [num[r|w]] - Stop specified engine or DMA subsystem --list-dma-engines - List active DMA engines --list-dma-buffers - List buffers for specified DMA engine --read-dma-buffer - Read the specified buffer --wait-irq - Wait for IRQ Kernel Modes: --list-kernel-memory - List kernel buffers --read-kernel-memory - Read the specified block of the kernel memory block is specified as: use:block_number --free-kernel-memory - Cleans lost kernel space buffers (DANGEROUS) dma - Remove all buffers allocated by DMA subsystem #number - Remove all buffers with the specified use id Addressing: -d - FPGA device (/dev/fpga0) -m - Memory model (autodetected) pci - Plain ipecamera - IPE Camera -b - PCI bar, Register bank, or DMA channel Options: -s - Number of words (default: 1) -a [fifo|dma] - Access type and bits per word (default: 32) -e - Endianess Little/Big (default: host) -o - Append output to file (default: stdout) -t - Timeout in microseconds Event Options: --event - Specifies event for trigger and grab modes --data - Data type to request for the events --run-time - Limit time to grab/trigger events -t - Timeout to stop if no events triggered --trigger-rate - Generate tps triggers per second --trigger-time - Specifies delay between triggers (us) -s - Number of events to grab and trigger --format [type] - Specifies how event data should be stored raw - Just write all events sequentially add_header - Prefix events with 512 bit header: event(64), data(64), nope(64), size(64) seqnum(64), offset(64), timestamp(128) --buffer [size] - Request data buffering, size in MB --threads [num] - Allow multithreaded processing DMA Options: --multipacket - Read multiple packets --wait - Wait until data arrives Information: --verbose [level] - Announce details of ongoing operations -q - Quiete mode (suppress warnings) Data: Data can be specified as sequence of hexdecimal number or a single value prefixed with '*'. In this case it will be replicated the specified amount of times \end{lstlisting} Example: read the exposure time \begin{verbatim} pci -r cmosis_exp_time \end{verbatim} \begin{description} \item[] The argument \verb/-r cmosis_exp_time/ reads the register from the image sensor. \end{description} \section{Working with the camera} This section describes common operations with the pcitools. \subsection{Take a single picture} \begin{verbatim} pci --grab -s 1 --trigger -o \end{verbatim} \begin{description} \item[ ] Mode \verb/--grab/ instructs pcitool to start grabbing \item[ ] \verb/-s 1/ option specifies that only a single frame is required \item[ ] \verb/--trigger/ instructs camera to self trigger, if this option not provided the pcitool will wait until camera will decide to send the frame (possibly triggered by external hardware trigger) \item[ ] \verb/-o / specifies the file to store images. The images are stored in raw format, each 16 bit word describing a single pixel. The horizontal dimension is changing before vertical. \end{description} The raw image data does not contain information on image size and colors. This information has to be specified when the image should be displayed. Standard image analysis applications like \emph{Imagej} \cite{SW:IMAGEJ} have raw data import filter that allow to decode the data correctly. The following examples shows the import dialog of an ImageJ distribution called \emph{Fiji} \cite{SW:FIJI}. \includegraphics[width=\textwidth]{images/Fiji_set_param.png} For opening the frame(s) we should execute: \textbf{File} $\rightarrow $ \textbf{Import} $ \rightarrow $ \textbf{Raw...}. After the selection of the frame we should set the frame info: width, height, it's size, endianess, and number of frames. When hovering over the picture with the mouse, in the status bar of the \emph{Fiji} is shown the pixel position and pixel value. In the upper left corner of the picture are additional informations: which frame is displayed, how many frames are open, size of the frame, etc. \subsection{Taking a series of pictures} Similarly, multiple images may be grabbed \begin{verbatim} pci --grab --run-time --trigger --trigger-rate -o \end{verbatim} In this case: \begin{description} \item[ ] \verb/--run-time / option specifies how long to grab frames in microseconds \item[ ] \verb/--trigger-rate / option instructs pcitool how often to issue software triggers. This value is desired frame rate in frames per second \item[ ] \verb/-o / option agains specifies the output file. The frames are stored sequentially one after another in a single file \end{description} There is additional options which may define the duration and speed of grabbing process \begin{description} \item[ ] \verb/--trigger-time