Added description of the camera data format

5 files changed, 218 insertions, 7 deletions

diff --git a/ChangeLog b/ChangeLog
new file mode 100644
index 0000000..0dc9b5f
--- /dev/null
+++ b/ChangeLog
@@ -0,0 +1,11 @@
+ChangeLog
+
+
+
+- Added description of the data format in the development part
+  1.8.12 (ak)
+- Initial version a quite complete description of the operation
+  and less information in admin and devel parts
+  31.7.12 (ak) 
+ 
+
diff --git a/admin.tex b/admin.tex
index 51ce433..5bd8671 100644
--- a/admin.tex
+++ b/admin.tex
@@ -81,6 +81,77 @@ To autoload driver, copy \verb|misc/50-pcidriver.rules| into the \verb|/etc/udev
 
 \subsection{Universal camera layer -- libuca}
 
+Libuca is an abbreviation for Unified Camera access. It is a library to access two-dimensional pixel detectors most commonly called cameras. It gives the user a general interface to a variety of different cameras and camera types. It is used to configure them via a property based
+interface and acquire images.
 
+Installation instruction from libuca/INSTALL.
+
+\begin{verbatim}
+Simple install procedure
+========================
+
+  $ tar xfz libuca-0.x.tar.gz
+  $ cd libuca-0.x
+  $ mkdir build
+  $ cd build/
+  $ cmake ..
+  $ make
+
+  [ Become root if necessary ]
+  $ make install
+
+
+Requirements
+============
+
+libuca requires CMake and pkg-config for building libraries and accompanying
+tools. Information about CMake can be found at:
+
+    http://www.cmake.org
+
+and pkg-config at:
+
+    http://www.freedesktop.org/software/pkgconfig
+
+libuca depends on the GObject library for object oriented programming.
+Information about this library can be found at:
+
+    http://developers.gnome.org/gobject/stable
+
+Each specific camera needs a camera SDK and/or a driver:
+
+    - UFO camera: pcilib
+    - pco.edge, pco.4000, pco.dimax cameras: SiliconSoftware menable IV driver
+      and SDK as well as the libpco wrapper.
+
+The control tools require Gtk+ GUI toolkit. Information is available at:
+
+    http://developer.gnome.org/platform-overview/
+
+
+Building the Library
+====================
+
+On Linux, libuca uses the CMake build system and pkg-config for dependency
+detection. The normal procedure to build this library is to create an empty
+build directory:
+
+    $ mkdir build/ && cd build
+
+configure the project using CMake:
+
+    $ cmake ../
+
+and compiling the library with make:
+
+    $ make
+    $ make install
+
+Options to the build process can be passed to the system when configuring:
+
+    $ cmake ../ -DCMAKE_INSTALL_PREFIX=/usr
+
+or via configuration tools like `ccmake`.
+\end{verbatim}
 
 
diff --git a/camera-manual.tex b/camera-manual.tex
index 6b5a018..ffeded8 100644
--- a/camera-manual.tex
+++ b/camera-manual.tex
@@ -11,7 +11,8 @@
 \usepackage{a4wide}
 \usepackage[utf8]{inputenc}
 \usepackage{graphicx}
-\usepackage{longtable}
+\usepackage{hyperref}
+%\usepackage{longtable}
 \usepackage{listings}
 \usepackage[usenames]{color}
 \definecolor{comment}{rgb}{1,0,0}
diff --git a/devel.tex b/devel.tex
index a48cce3..2088d70 100644
--- a/devel.tex
+++ b/devel.tex
@@ -51,6 +51,134 @@ Sensor features and characteristics:
 
 Please look at the CMV2000 datasheet for more information regarding the sensor, and additional CMOSIS white papers regarding recommended register settings \cite{CMOSIS:CMV2000}. Also, in section \ref{camera_char} is given the overview of the sensor characterization for several different parameters.
 
+
+
+\subsection{Data format}
+
+The UFO camera uses a special data format to be able to send images and trigger 
+information in a compact form. The format needs also to ensure data integrity. 
+In case of transmission errors the information can partly be recovered. 
+
+The data is send frame by frame.
+Each frame consist of the HEADER, DATA PAYLOAD and TAIL.
+
+
+\subsubsection{Header}
+
+HEADER contains 8 word of information:
+
+\begin{verbatim}
+DHEADER_1 DHEADER_2 DHEADER_3 DHEADER_4
+DHEADER_5 DHEADER_6 DHEADER_7 DHEADER_8
+
+\end{verbatim}
+Each DHEADER word has 32 bits.
+\begin{verbatim}
+DHEADER_1 = {4'h5, 28'h1111111};
+DHEADER_2 = {4'h5, 28'h2222222};
+DHEADER_3 = {4'h5, 28'h3333333};
+DHEADER_4 = {4'h5, 28'h4444444};
+DHEADER_5 = {4'h5, 28'h5555555};
+DHEADER_6 = {4'h5, CMOSIS_start_addr[9:0], skip_lines[6:0], number_of_lines};
+DHEADER_7 = {4'h5, 4'h5, frame_number};
+DHEADER_8 = {4'h5, ADC_Resolution, Output_mode, FR_timestap};
+\end{verbatim}
+
+The values for \verb/ADC_resolution/ are given in the following table.
+
+\begin{tabular}{|c|c|}
+\hline
+ADC resolution				& Value 	\\	
+\hline
+10-bit				& 0 \\
+\hline
+11-bit				& 1 \\
+\hline
+12-bit				& 2 \\
+\hline
+\end{tabular}
+
+The parameter \verb/Output_resolution/ is given in the following table
+
+\begin{tabular}{|c|c|}
+\hline
+ADC resolution			& Value 	\\	
+\hline
+16 outputs				& 0 \\
+\hline
+8 outputs-not used		& 1 \\
+\hline
+4 outputs				& 2 \\
+\hline
+2 outputs-not used		& 3 \\
+
+\hline
+\end{tabular}
+
+
+\subsubsection{Tail}
+
+The TAIL contains again 8 words.
+
+\begin{verbatim}
+TAIL_1 TAIL_2 TAIL_3 TAIL_4
+TAIL_5 TAIL_6 TAIL_7 TAIL_8
+\end{verbatim}
+
+All TAIL fields are 32 bits wide. In total the tail has a length of 256 bits.
+\begin{verbatim}
+TAIL_1 = {4'h0, 28'hAAAAAAA};
+TAIL_2 = {Status1};
+TAIL_3 = {Status2};
+TAIL_4 = {Status3};
+TAIL_5 = {4'h0, 2'h0, app_addr_rd};
+TAIL_6 = {4'h0, 2'h0, app_addr_wr};
+TAIL_7 = {4'h0, 28'h0000000};
+TAIL_8 = {4'h0, 28'h1111111};
+\end{verbatim}
+
+
+\subsubsection{Data}
+
+Data payload is organized in blocks of 256 bits. One block contains the information of 16 pixel. Each block starts with a 32bit wide data block header. Depending on the mode of operation 16 x 10, 16 x 11 or 16 x 12bit of data are contained in the block. The rest of the data block is filled with zeros. At maximum ADC data with up to 14bit per pixel can be coded by this scheme.  
+
+For 10bit data per pixel:
+\[
+\underbrace{Header}_{32bit} \; \; \underbrace{00000000}_{32bit} \;  \;\underbrace{00000000 }_{32bit} \; \; \underbrace{Pix\;ch0 \;  \; \ldots  \;  \;Pix\;ch15}_{160 \; bits}
+\]
+
+For the 12bit data per pixel:
+\[
+\underbrace{Header}_{32bit} \; \; \underbrace{00000000}_{32bit} \;  \; \underbrace{Pix\;ch0 \;  \; \ldots  \;  \;Pix\;ch15}_{192 \; bits}
+\]
+
+
+The data block header gives information on the position of the pixel in the images. 
+The whole image is organized in 16 columns, each served by one channel.
+One data block contains always the data of one pixel from each channel.
+All the pixel in the block have the same relative position in the 16 columns. 
+The position is given by row and column (called pixel number). 
+The resulting pixel map is is shown below.
+
+\includegraphics[width=0.8\textwidth]{images/pixel_map.png}
+
+The format of the data block header is:
+\begin{verbatim}
+Header = {8'b10000000, pixel_size (4 bits), 
+          1'b0, row_number (11 bits), 1'b0, pixel_number(7 bits)};
+\end{verbatim}
+
+In order to cover all pixel of the CMOSIS sensor CMV2000 the parameter \verb/pixel_number/ has values from 0 to 127 and \verb/row_number/ has value from 0 to 1088.
+
+Example of a single data payload block with 10bit ADC values:
+\begin{verbatim}
+0x80a00000 0x00000000 0x00000000 0x595794d9  
+0xd96c5257 0x6d5655e5 0x97059571 0xf5a96b59
+\end{verbatim}
+
+
+
+
 \section{Software}
 
 The camera software splits in three parts. Interface to the camera hardware, a general camera interface library and specific decoding modules for the supported image sensors.
diff --git a/user.tex b/user.tex
index 368435a..5bb2793 100644
--- a/user.tex
+++ b/user.tex
@@ -157,10 +157,10 @@ The camera comes with a graphical application that displays live images from the
 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 inferface 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 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]
+\begin{figure}[h] 
 \includegraphics[width=\textwidth]{images/ufo_gui2.png}
 \caption{\label{camera-gui} Camera frontend}
 \end{figure}
@@ -509,7 +509,7 @@ pci -w cmosis_exp_time 0x25
 For often used operations pcitool contains scripts.
 The scripts are self-explanatory. More information, if needed, can be found inside the scripts itself.
 
-\begin{tabular}{|c|p{10cm}|}
+\begin{tabular}{|l|p{10cm}|}
 \hline
 Script						& Description \\
 \hline
@@ -518,11 +518,12 @@ Script						& Description \\
 \verb/Reset_10_bits.sh/ 	& Reset sequence for setup with the 10bit/pixel. \\
 \hline
 
-\verb/Reset\_11\_bits.sh/ 	& Reset sequence for setup with the 11bit/pixel. \\
+\verb/Reset_11_bits.sh/ 	& Reset sequence for setup with the 11bit/pixel. \\
 \hline
-\verb/Reset\_12\_bits.sh/ 	& Reset sequence for setup with the 12bit/pixel. \\
+\verb/Reset_12_bits.sh/ 	& Reset sequence for setup with the 12bit/pixel. \\
 \hline
 \verb/frame.sh/ 			& For requesting frames. Number of frames and exposure time is settable by user. \\
+\hline
 \verb/stimuli.sh/			& \\
 \hline
 \end{tabular}
@@ -531,7 +532,6 @@ Script						& Description \\
 
 
 %\subsection{Performing calibration of the image sensor}
-
 % TODO: Add description of scripts used to calibrate the sensor