\chapter{Introduction}

This manual describes how to install, configure, and use the MX beamline
control toolkit 
\myurl{http://mx.iit.edu/}
for use with area detectors.  Currently, the only
supported area detector hardware is the PCCD-170170 from AVIEX LLC, but it
is anticipated that the list of supported detectors will grow with time.

MX is capable of controlling a wide variety of other devices such as motors,
counter/timers, MCAs, MCSs, and so forth.  However, since this is of limited
relevance to sites that only use MX for its area detector support, support
for these other devices will not be described further in this manual.

\section{Driver and Platform Support}

\subsection{MX Clients}
\label{subsec:mxclients}

The {\it network\_area\_detector} driver used by MX area detector clients
runs on all of the platforms currently supported by MX.  As of October 2007,
the supported plaftorms include:
{\it BSD, Cygwin, DJGPP, eCos, HP-UX, Irix, Linux, \mbox{MacOS X}, QNX, RTEMS,
Solaris, Tru64, VMS, VxWorks, and Windows (Win32).}

\subsection{MX Server}

The platforms supported by the MX server depend on the drivers used by
your area detector.

\begin{itemize}
  \item {\bf AVIEX PCCD-170170 CCD detector}

  For this detector, the top level area detector driver, {\it pccd\_170170},
  is layered on top of the video input driver, {\it epix\_xclib\_video\_input},
  for the imaging board used to read out frames from the AVIEX camera head.
  The video board itself is a PIXCI E4 frame grabber from EPIX, Inc.\ 
  You can find the hardware manual for the E4 here
  \myurl{http://www.epixinc.com/products/pixci\_e4.htm}.
  The PIXCI E4 is a PCI Express board that plugs into an x4 PCI Express slot.

  Please note that the company, EPIX, Inc., has absolutely no relation
  to the control system called EPICS
  \myurl{http://www.aps.anl.gov/epics/}.
  The similarity of the names is completely a coincidence.

  The MX {\it epix\_xclib\_video\_input} driver depends on the 
  XCLIB library \myurl{http://www.epixinc.com/products/xclib.htm} 
  provided by EPIX, Inc.\ for use with their PIXCI line of imaging boards.
  EPIX, Inc.\ currently provides versions of XCLIB for Windows XP, Windows 2000,
  Linux, and 32-bit DOS.  MX has been tested with version 2.2 of the 
  XCLIB library.

  At present, MX support for the PIXCI E4 has been tested on the
  following 32-bit operating systems:
  \begin{itemize}
    \item Fedora Core 5 Linux (x86)
    \item Red Hat Enterprise Linux 5 (x86)
    \item Debian 4.0 Linux (etch) (x86)
    \item Windows XP SP2 with Visual C++ 2005 Express.
  \end{itemize}
  The versions that run under Linux use recompiled versions of 
  Epix's kernel module for Fedora Core 4.

  Currently, our recommendation is to use Linux on the detector control
  computer.  The main reason for this is that it is easier to do remote 
  configuration and debugging of a Linux based system.  If your firewall
  allows SSH connections to the detector control system, that is all
  that is needed to enable remote support.

  It might be possible to get the Linux support working on another distribution,
  but this depends on the portability of the binary Linux module provided
  by EPIX, Inc.\ with their imaging boards.  However, portability of the
  EPIX binary module for Linux has not yet been significantly tested by us.
  The simplest path would be to stick with the distributions listed above.
  MX support for the PCCD-170170 detector has not yet been tested with 64-bit
  operating systems.

  Although the EPIX XCLIB programming library can be downloaded from the
  EPIX web site, you need a license key to unpack and install it.
  In order to get a license key, you must purchase a single developer
  XCLIB license from EPIX, Inc.  As of late 2007, this license costs \$495.

  \item {\bf Software emulated area detector}

  The {\it soft\_area\_detector} driver attempts to emulate enough of the
  behavior of a real area detector that higher level code will mostly not 
  notice
  the difference.  The {\it soft\_area\_detector} driver is layered on top
  of a video input driver in a similar manner to the design of the 
  {\it pccd\_170170} driver mentioned above.  The video input driver can 
  either be an emulated video input or a real video input.  The following
  three choices are the most useful ones:

  \begin{itemize}
    \item {\bf Software emulated video input}

    The {\it soft\_video\_input} driver generates test images and returns
    them to the caller.  Three types of test images are currently available.
    %
    \begin{itemize}
      \item[\textbf{(1)}] {\it Diagonal Gradient} - 
      This type of test image returns a repeating sequence of four test
      images, each of which has a maximum in a different corner of the image.
      An example database record for a 640 by 480 16-bit greyscale
      image would look like this:
      {\small
\begin{verbatim}
video0 device video_input soft_vinput "" "" 640 480 GREY16 -1 1 ""
\end{verbatim}
}
      %
      \item[\textbf{(2)}] {\it Bands} -
      This type of test image also returns a repeating sequence of four
      test images.  The sequence is ``vertical bands'', ``diagonal
      bands from lower left to upper right'', ''horizontal bands'',
      and ``diagonal bands from upper left to lower right''.
      An example database record for a 4096 by 4096 16-bit greyscale
      image would look like this:
      {\small
\begin{verbatim}
video0 device video_input soft_vinput "" "" 4096 4096 GREY16 -1 2 512
\end{verbatim}
}
      %
      The value at the end of the line (512 in the above example) 
      controls how closely spaced the peaks of the bands are.
      %
      \item[\textbf{(3)}] {\it Logarithmic Spiral} -
      This type of test image displays a logarithmic spiral which
      is defined by the equation
      $$
      	R = Ae^{B\theta}
      $$
      The logarithmic spiral is useful for testing ROI support, since
      the spiral is asymmetric.
      An example database record for a 4096 by 4096 16-bit greyscale
      image would look like this:
      {\small
\begin{verbatim}
video0 device video_input soft_vinput "" "" 4096 4096 GREY16 -1 3 "5 0.24 10"
\end{verbatim}
}
      %
      The three values inside the string field (\texttt{"5 0.24 10"}) at the
      end of the record are used to tune the dimensions of the logarithmic
      spiral.  The first parameter A (5 in the above example) determines the
      radial scale of the spiral.
      The second parameter B (0.24 in the above example), sets the rate
      at which the value of the exponential above increases.
      The third parameter C (10 in the above example), sets the maximum
      value of $\theta$ for which the spiral is computed.  For $C = 10$,
      the spiral is computed from $\theta = 0$ to $\theta = 10 \pi$ radians.
    \end{itemize}
    %
    This driver is available on all MX platforms.

    \item {\bf File-based video input emulator}

    The {\it file\_vinput} driver reads detector images from 
    files contained in a directory specified in the MX database file.
    The driver goes through the files in the image directory
    in alphanumeric order and loops back to the first file after
    returning the last file.  The files in the image directory must
    all be image files in a format understood by MX.  The currently
    supported formats are SMV and PNM.

    \item {\bf Video4Linux 2}

    The {\it v4l2\_input} driver uses any commercial frame grabber or
    TV capture card
    that has a Video4Linux version 2 driver.  Video4Linux version 1 drivers
    are not supported.  With this driver, it is possible to easily change
    the test image merely by pointing your video camera at a different target.
    Unfortunately, Video4Linux 2 only supports 8-bit greyscale images, but
    the MX area detector support will automatically adjust to compensate
    for this.
    
    Obviously, this driver is only available on Linux platforms.
    Not all Linux distributions include the header file
    \myfilename{/usr/include/linux/videodev2.h}
    in their core {\it glibc} development package, so
    you must explicitly enable this driver by making the
    following definition in the file \myfilename{mx/libMx/mxconfig.h}:

\begin{verbatim}
    #define HAVE_VIDEO_4_LINUX_2            1
\end{verbatim}

  \end{itemize}

\end{itemize}

\section{Installation from Prebuilt Binaries}

Although the server and the client may use different sets of binaries,
the process of installation is essentially the same for both computers.
Thus, the following description applies to both the server and its clients
unless otherwise indicated.

Prebuilt Binaries for MX are generally delivered in the form of .tar.gz
archives or .zip archives.  The first thing to do is to decide
which directory you want to install MX in.  Although you are free to install
the binaries anywhere you want, the conventional place to install MX is
either in the directory \myfilename{/opt/mx}\ on Linux/Unix or the
directory \myfilename{c:$\backslash$opt$\backslash$mx} on Windows.
On Linux/Unix systems with support for symbolic links, we commonly install
to a directory with a name that contains the MX version number such as
\myfilename{/opt/mx-1.5.0} and then use a symbolic link to link this
name to \myfilename{/opt/mx}.  In this case, the process looks like this
%
\begin{verbatim}
    cd /opt
    mkdir mx-1.5.0
    ln -s mx-1.5.0 mx
\end{verbatim}
%
The last step of this process cannot be done on Windows systems, since
they do not support symbolic links.

At this point, you may jump forward to Section~\ref{sec:configuring}.

\section{Installation from Source}

We describe here the process of building and installing MX from source code
on the detector server computer and follow that with comments
about the client computer.

\subsection{Before Building MX}

For real area detector hardware, MX controls the image capture card
using software libraries provided by the maker of the image capture card.

\subsubsection{EPIX PIXCI cards}
If you need support for the PCCD-170170 detector, you must
first download and install the XCAP and XCLIB
packages from the EPIX web site and FTP site, which you can find on
the web page \myurl{http://www.epixinc.com/support/files.htm}.
This web page redirects you to various directories on their FTP site
underneath the directory \myurl{ftp://ftp.epixinc.com/software/}.
Occasionally, newer versions may be found in the directory
\myurl{ftp://ftp.epixinc.com/downloads/} and you may need to use a version
from here if directed to by AVIEX or EPIX personnel.  However, normally
the versions found in \myurl{ftp://ftp.epixinc.com/software/} are
the preferred versions.

MX has been tested with versions 2.2 of XCAP and XCLIB.  We have not
yet tested with versions of XCAP or XCLIB newer than that.

\paragraph{{\hskip 5mm}\textit{XCAP}}
\ \newline

The XCAP package contains both the kernel mode driver needed by the EPIX
software and a user GUI called {\it xcap} which can be used to control
the imaging board.  Currently you may download the kernel driver from the
directory \myurl{ftp://ftp.epixinc.com/software/xcap\_v22/}.  For Linux,
you will want to download the file {\it xcaplnx\_i386.bin}, while for Windows
you will want to download the file {\it xcapwi.exe}.

For the EPIX PIXCI E4 card used by the AVIEX PCCD-170170, you install
XCAP using the procedure described in the User's Manual for the card, 
which may be found at
\myurl{http://www.epixinc.com/manuals/pixci\_e14el/index.htm}.
The actual installation is described in chapter 3 of that manual.
The PIXCI E4 is bundled with a license for the XCAP-Lite version
of the program.  XCAP-Lite is what we have used for the development
of the MX drivers.  On Linux, by default, the software will end up
in the directory \myfilename{/usr/local/xcap}, while on Windows, it
will end up in the directory \myfilename{C:$\backslash$XCAP}.

We do not recommend that users use the XCAP-Lite version of the program
for normal operation, since it has limited functionality.  In addition,
XCAP-Lite will not start if you have configured the kernel mode image
buffer for more than approximately 64 megabytes of memory.
At present, we only use XCAP-Lite to generate configuration files
that are to be read by XCLIB.

\paragraph{{\hskip 5mm}\textit{XCLIB}}
\ \newline

The XCLIB library is used by third-party application packages like MX
to control EPIX PIXCI imaging boards.  You may download the 
library from the EPIX FTP site's directory
\myurl{ftp://ftp.epixinc.com/software/xclib\_v22/}.  However,
the license for the development package is {\it not} included with the
purchase price of the EPIX PIXCI E4.  Instead, it is an additional charge
of \$495 as of late 2007.  The installer for XCLIB will fail unless you
have a license key.

For Linux, you should download the {\it xcliblnx} version for Fedora Core 4,
which is the version intended for the Linux 2.6 kernel series.
For Windows XP, you should download
the file {\it xclibwnt.exe}.  Please be careful to download files
whose names begin with {\it xclib} with a {\bf b} and not files whose names
begin with {\it xclip} with a {\bf p}.  The {\it xclip} versions include
image processing functionality not used by MX and the license cost for those
versions is higher.  
By default, XCLIB will be installed to \myfilename{/usr/local/xclib}
on Linux and to \myfilename{C:$\backslash$XCLIB} on Windows.
The procedure for installing XCLIB is not described in
any document on the EPIX web site.  It is only described in the manual
distributed with licensed versions of the XCLIB development kit.

Please note that in the XCLIB download directory, there are versions of
the library for Mandrake 9.1 using the older Linux 2.4 kernel,
for Windows 95/98/ME and for the 32-bit DOS Watcom compiler.
We have no plans to support these older operating system platforms.

\paragraph{{\hskip 5mm}\textit{Installing the PIXCI Kernel Driver}}
\ \newline

Application programs communicate with EPIX PIXCI imaging boards
through a kernel mode driver.  On Windows, this driver is installed
automatically by the EPIX installation program for XCAP.  Normally,
you should not need to do anything else on Windows.

The Linux
version of the EPIX installation program attempts to install a Linux
kernel module called \textit{pixci}.  The installer comes bundled with
kernel modules for Fedora Core 4 and Mandrake 9.1.  Since these versions
of Linux are obsolete, in general you will have to compile the kernel
modules yourself to match the version of the Linux kernel that you
are running.  In addition, if you upgrade to a newer version of the
kernel, you will need to recompile the kernel module again.

When run, the XCLIB installation program for Linux will attempt to build
and install a kernel module on its own.  If that procedure fails, here is
a manual procedure that we have successfully used:
%
\begin{enumerate}
\item\ 
If you have installed XCAP in the default location of
\myfilename{/usr/local/xcap}, then the kernel module source
will be found in the directory
\myfilename{/usr/local/xcap/drivers/i386/src\_2.6}.
However, the source as distributed by EPIX for XCAP 2.2 does not compile with
recent version of the Linux 2.6 kernel.  Fortunately, the fix is simple.
%
\item\ 
Copy the contents of \myfilename{src\_2.6} to a new directory.  We typically
pick a name based on the version name of the kernel, such as
\myfilename{src\_2.6.20-1.2307.fc5smp}.
%
\item\
Change to the new directory and edit the file \myfilename{pixcipub.c}.
%
\item\
After the line that contains
\begin{center}
\texttt{\#include <linux/interrupt.h>}
\end{center}
\ 
insert an additional line that contains
\begin{center}
\texttt{\#include <linux/utsrelease.h>}
\end{center}
%
\item\
Compile the kernel module using the \mycommand{make} command.
%
\item\
Copy the new kernel module to the modules directory in the subdirectory
\myfilename{extra}.  You may have to manually create the subdirectory.
If the kernel you are running is Linux \textit{2.6.20-1.2307.fc5smp}, then the
full name of the subdirectory will be 
\myfilename{/lib/modules/2.6.20-1.2307.fc5smp/extra}.
You can get the version of the kernel you are running from the
Linux command \mycommand{uname -r}.
%
\item\
Finish by running the command \mycommand{depmod} to rebuild the
\myfilename{modules.dep} in the top level modules directory for the
currently running kernel.  In the example given above, that directory
will be 
\myfilename{/lib/modules/2.6.20-1.2307.fc5smp}.
\end{enumerate}

Detector control computers installed by Aviex will already have the 
necessary kernel module installed in the right place.

\paragraph{{\hskip 5mm}\textit{Configuring the PIXCI Kernel Driver}}
\ \newline

After installing the PIXCI kernel driver, you must now configure 
the amount of memory reserved for PIXCI image frame buffers.  The default
amount of memory reserved tends to be quite small.  In fact, on Windows XP
the default appears to be 50000 kbytes which only provides enough memory
for one PCCD-170170 frame buffer.
Increasing the amount of memory requires experimenting with the parameters
described in section 3.9 \textit{(PIXCI Driver Esoterica)} of the PIXCI E4
hardware manual.

For Windows XP, configuring image frame buffers is done through the registry.
Instructions on how to do this can be found in section 3.4
\textit{(Windows XP, XP(x64) or Server 2003 Esoterica)} of the PIXCI E4
hardware manual.  The relevant registry key is
\begin{verbatim}
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EPIXXCW2\PIXCI
\end{verbatim}

For Linux, configuration of the image frame buffers
is done via the command line of the \mycommand{insmod} command that
loads the \textit{pixci} module.  Details of the command line arguments
can be found in section 3.7 \textit{(For Linux)}
of the PIXCI E4 hardware manual.  The MX source code distribution 
contains a sample \myfilename{/etc/init.d} style script called
\myfilename{driver\_info/epix\_xclib/pixci} which automates the loading
of the \textit{pixci} module at boot time.  The number of image frames
is controlled by the PIXCIPARM variable.

If you request a certain amount of memory for image frame buffers, you are
not guaranteed to actually get the amount of memory you asked for.
For example, if you set PIXCIPARM to -IM\_2097152, instead of getting
2 gigabytes of frame buffers, you may instead get around 800 megabytes
or enough memory for around 23 frame buffers that are 32 megabytes each
in size.
Things are even worse on Windows where you may only get 65 megabytes or so
and just 1 frame buffer.
In order to get more frame buffer memory, it is necessary to artificially
limit the amount of memory available to the operating system.  This
procedure is described in great detail the PIXCI E4 manual.

For Windows XP,
an example of the procedure would be to add an additional entry to
\myfilename{C:\\BOOT.INI} with \texttt{/MAXMEM=512} appended to the end
of the kernel command line.  This gives only 512 megabytes to the
operating system and theoretically all of the rest to image frame buffers.
The equivalent procedure on Linux is to add a new entry to 
\myfilename{/etc/grub.conf} or \myfilename{/etc/lilo.conf} with
\texttt{mem=512M} appended to the end of the kernel command line.

Having done this, you can now change the starting address for frame buffers
using the -IA parameter as described in the PIXCI E4 hardware manual.
\textit{However}, we have had to use a slight modification of the
procedure described in the PIXCI E4 manual.  That manual implies that
you can set the base address for the frame buffers with the -IA command
to a value equal to the top of operating system memory.  Using our example
above of 512 megabytes for the operating system, the manual implies that
you could use something like \texttt{-IA 524288} which would make the
frame buffers start just beyond the top of operating system memory.
However, our experience is that this \textit{does not work!}
Instead, you must leave a small amount of unused memory between the top
of operating system memory and the start of the image frame buffers.
For example,
\begin{verbatim}
PIXCIPARM=-IM_2097152_-IA_600000_-MB_250000_-MU_3
\end{verbatim}
has been successfully used on a Linux 2.6 system with 4 gigabytes of RAM
and provides enough space for 56 image frames.

\subsection{Cygwin {\it (for Windows platforms)}}

Although MX can be compiled on Windows with Microsoft Visual C++,
Borland C++, MinGW, Cygwin, or DJGPP, the build process is {\it always}
managed using the Cygwin version of {\it Make}.
Microsoft's {\it Nmake} cannot be used since the MX makefiles make use
of features not available in {\it Nmake}.

Cygwin can be found at the web site \myurl{http://www.cygwin.com/}.
In brief, the procedure consists of downloading and running Cygwin's
\myfilename{setup.exe} installation program to download and install the
Cygwin packages you need.  The bare minimum needed are the base packages
and the {\it make} package plus their dependencies.  When building MX
himself, the author of MX
generally installs a variety of other packages including the Cygwin SSH
server to create a more congenial development environment, but this is
not absolutely necessary.

\subsection{Downloading MX}

The MX home page can be found at \myurl{http://mx.iit.edu/}.  Official 
releases can be found on the download page 
\newline
\myurl{http://mx.iit.edu/source.html}.
In the future, when area detector support has been made part of an official
MX 1.5.0 release, this will be the best place to get the source code.  However,
until this happens, you will need to download a development snapshot or
else checkout the code from the MX Subversion repository.

Development snapshots can be downloaded from the directory
\myurl{http://mx.iit.edu/src/devel/}.  In general, you should use the
development snapshots rather than code checked out from Subversion, since
the development snapshots can generally be counted on to compile and run
correctly on the most commonly used MX platforms such as Linux, Windows,
MacOS X, and Solaris.

If you really do need the newest possible code, then you must checkout 
the code 
from the MX Subversion repository.  The various repositories can be
browsed with a web browser at \myurl{http://mx.iit.edu/svn.html}.  
The core MX package can be checked out with a command like this:
%
\begin{center}
    \texttt{svn checkout http://svn.csrri.iit.edu/mx/trunk \ mx}
\end{center}
%
This will create a new MX source tree in the subdirectory \myfilename{mx}
which is ready to be configured and built.

Please bear in mind that the Subversion repository is in constant change
with commits sometimes taking place several times a day.  The most recent
commit is not guaranteed to work correctly or even compile correctly
at any given moment, so, in general, you are better off using a development
snapshot as described above.

\subsection{Building MX for the Detector Computer}

Building MX is a multistep process.

\begin{enumerate}
  \item The first step is to edit the top level makefile.
  Relative to the directory you unpacked MX into, the name of this file is
  \myfilename{mx/Makefile}.

  In the makefile, the first thing that you will want to do is to change
  the value of the variable MX\_ARCH to match the platform that you are
  compiling the code.  For AVIEX area detectors, the only suitable
  choices are \texttt{linux} and \texttt{win32}.

  Then, you will need to change the value of the MX\_INSTALL\_DIR variable.
  In general, this can be anywhere you want.  Typically,
  the author generally chooses a name containing the version number of MX
  such as \myfilename{/opt/mx-1.5.0} on Linux or \myfilename{c:/opt/mx-1.5.0}
  on Windows.  On Linux, this directory will generally be symlinked to
  \myfilename{/opt/mx}.

  Warning: For Windows, you must use {\it forward slashes} $(/)$ in the
  file name, rather than {\it backslashes} $(\backslash)$.  Using
  backslashes here will cause the build process to fail.

  A more general warning is that you must not use filenames that include
  spaces anywhere in the MX makefiles, since that will also cause the build
  to fail.  On Windows, this means that you must use 
  \myfilename{c:/progra$\sim$1} rather than \myfilename{c:/Program Files}
  and \myfilename{c:/docume$\sim$1} rather than
  \myfilename{c:/Documents and Settings}.
  This is all a consequence of the way that Gnu make processes filenames.

  \item The next step is to edit the file \myfilename{mx/libMx/mxconfig.h}.
  This file is used to enable or disable the compilation drivers that make 
  use of software libraries external to MX that are not guaranteed to be
  available.  For the AVIEX PCCD-170170 detector, you will need to define
  the HAVE\_EPIX\_XCLIB flag as follows:
\begin{verbatim}
        #define HAVE_EPIX_XCLIB                 1
\end{verbatim}

  If you wish to include the Video4Linux 2 driver for test purposes as well,
  then you will also need to make the definition
\begin{verbatim}
        #define HAVE_VIDEO_4_LINUX_2            1
\end{verbatim}

  All of the other defines should be set to 0.

  \item The last file to edit is \myfilename{mx/libMx/Makehead.linux} or
  \myfilename{mx/libMx/Makehead.win32}, depending on your platform.  What
  you must do here is make sure that the correct version of the macros
  INCLUDES,
  LIB\_DIRS, and LIBRARIES is uncommented.  On Linux, the correct version
  to uncomment is
\begin{verbatim}
        INCLUDES  = $(MX_INCLUDES)
        LIB_DIRS  = -L$(MX_LIB_DIR) $(EPIX_XCLIB_LIB_DIRS)
        LIBRARIES = $(EPIX_XCLIB_LIBRARIES) -lpthread -lrt -lm
\end{verbatim}
  while on Windows, the correct version is
\begin{verbatim}
        INCLUDES  = $(MX_INCLUDES) $(EPIX_XCLIB_INCLUDES)
        LIBRARIES = $(WIN32_LIBS) $(EPIX_XCLIB_LIBS)
\end{verbatim}

  If the EPIX, Inc.\ XCLIB library was not installed in the default location,
  you will also need to find the definition of the macro EPIX\_XCLIB\_DIR
  and change it to match the location that XCLIB was installed to.
  Please note that on Windows you must use escaped backslashes
  $(\backslash\backslash)$ in the filenames mentioned here.

  \item Now go to the top level source code directory \myfilename{mx}
  and type the command \mycommand{make depend}.
  This step constructs files named \myfilename{Makefile.depend} in each
  of the \myfilename{mx/libMx}, \myfilename{mx/motor}, \myfilename{mx/server},
  \myfilename{mx/update}, and \myfilename{mx/util} directories.
  These are used to determine which
  files must be recompiled when a given MX file is modified.
  This step is not strictly necessary, but it does no harm to do it.

  \item At this point, we are ready to compile and link MX.  To do this,
  type the command \mycommand{make} in the top level directory
  \myfilename{mx}.  If you are building a snapshot or a released version
  of MX, this should compile without any errors.  If you get any errors,
  this should be reported to the author.

  If you obtained the source code tree you are trying to compile from the
  {\it trunk} branch of the MX Subversion repository, not all revisions
  found there are guaranteed to compile or work correctly.  Normally, you 
  should only try the Subversion repository directly if you require some
  feature that is not already available in a released MX version or a
  snapshot version from the \myurl{http://mx.iit.edu/src/devel/} directory.

  \item The final step is to type \mycommand{make install} in the top level
  directory \myfilename{mx}.  You must make sure to do this using an account
  that has permission to write to the installation directory.  If this is
  a system directory, you will need to \mycommand{su} to root on Linux,
  or switch to an account with adminstrative privileges on Windows.  If you
  are merely installing a private copy into your own directory, then changing
  accounts will not be necessary.

\end{enumerate}

\subsection{Building MX for Client Computers}

Building MX on a client computer uses essentially the same process as building
it for the detector computer.  In fact, if you wish, you may copy the
version you built for the detector computer to your client computer.
On Linux, this should work without any changes,
since the EPIX XCLIB library is statically
linked to \myfilename{libMx.so} as long as the version of {\it glibc} on
the client computer is the same version or newer than the version on 
the computer you originally compiled MX on.
However, on Windows, if you want to do
this, you will need to copy the EPIX XCLIB DLL to the client computer.

If you wish to compile MX separately for the client computer, only a few
changes need to be made.  First, you must make the definition
\begin{verbatim}
        #define HAVE_EPIX_XCLIB                 0
\end{verbatim}
in the client's copy of \myfilename{mx/libMx/mxconfig.h}.  You must also
make sure that the INCLUDE, LIB\_DIRS, and LIBRARIES macros in your platform
specific makefile do not include any references to the EPIX libraries.
In addition, if you are compiling on a different platform,
you will need to change
MX\_ARCH in the top level Makefile to match your platform.
The client side version of MX should compile on any of the platforms
mentioned in Section~\ref{subsec:mxclients}.

\section{Configuring MX}
\label{sec:configuring}

If you are at a site that is using MX to control the entire beamline,
setting up the configuration files can be a fair amount of work and
will not be covered in this document.  However, if you are only using MX
to control your area detector, then you should be able to use the example
configuration files shown in this document essentially as is.

\subsection{Environment Variables}

For MX to operate, you must set up two or three environment
variables correctly.  These are:
\begin{description}
  \item \textbf{MXDIR} - This environment variable should contain the name
                of the top level installation directory for MX.  Typically,
		for Linux/Unix systems, this will be
		\myfilename{/opt/mx}.

		For Windows systems, this variable typically
		will be \myfilename{c:/opt/mx}.  Please note that
		for this case on Windows systems, you must use
		a forward slash (/).
  \item \textbf{PATH} - You must also add the application binary directory
                to the PATH environment variable.  For Linux/Unix systems,
		this will generally be \myfilename{\$MXDIR/bin}.

		On Windows, if \textbf{MXDIR} is \myfilename{c:/opt/mx},
		then the correct string to add to the path will be
		\myfilename{c:$\backslash$opt$\backslash$mx$\backslash$bin}.
		Note that for the \textbf{PATH} variable,
		you use backslashes ($\backslash$)
\end{description}
%
For Linux/Unix systems, there is generally one more environment variable
to set.
\begin{description}
  \item \textbf{LD\_LIBRARY\_PATH} - For most Linux and Unix platforms, this
  		environment variable tells the operating system where to find
		shared libraries.  Generally, it should be set to the value
		\myfilename{\$MXDIR/lib}.  However, a couple of supported
		MX platforms use an environment variable with a different 
		name for this purpose.
		On \mbox{MacOS X}, the correct environment variable to use is
		\myfilename{DYLD\_LIBRARY\_PATH}, while on \mbox{HP-UX} the
		correct environment variable is \myfilename{SHLIB\_PATH}.
\end{description}

In the MX source code tree, the file
\myfilename{mx/scripts/mxsetup.sh} is a full featured example of what
needs to be done on Linux/Unix systems with a shell using the
Bourne shell syntax.  On most systems, all you will need to do
is to define the environment variable MXDIR before sourcing
\myfilename{mxsetup.sh}.  Usually MXDIR should be defined to have
the same value as the MX\_INSTALL\_DIR from the top level MX makefile.
If you \mycommand{make install} to one location and then copy
the installed binary tree to a different location, you will need to
change the MXDIR environment variable to point to the top level directory
in the new location.

The \myfilename{mx/scripts} directory also contain briefer examples
of what to do for the Linux/Unix C shell (\myfilename{mxsetup.csh})
and for Windows (\myfilename{mxsetup.bat}).

\subsection{Configuring MX for Client Computers}

MX client computers generally need to setup one configuration file.
This file will have the same contents regardless of whether the server
manages a real area detector or a software emulated area detector.
Traditionally, this file has the name \myfilename{\$MXDIR/etc/motor.dat},
although you can actually use any filename you want as long as you pass
the correct filename to \myfunction{mx\_setup\_database()}.
A file like the following should work for most installations:
\begin{verbatim}
    adserver server network tcp_server "" "" 0x20000000 192.168.137.3 9727
    ad       device area_detector network_area_detector "" "" 8 adserver ad
\end{verbatim}

The first field is the \myfield{server\_flags} field.
Currently if you are using the software emulated area detector, you should
set this line to 0x20000000, which tells the client to use blocking I/O.
This is due to a limitation of the functionality of the software emulated
area detector and will not be necessary with a real area detector.
For a real area detector, you should set this field to 0x0 so that the
client can time out if the server fails.

The 192.168.137.3 field is the 
IP address of the server.  You can also specify a domain name like
{\it mxserver.example.com} here, but I generally recommend using 
numerical IP addresses here, since this means that you can skip 
doing a Domain Name Service lookup when your client starts.
The last argument 9727 is the port number of the MX server
on the remote computer.  Although most installations will use the standard
value of 9727, the port number is selectable so that you can run more
than one MX server on a given computer.

In the second line, the string {\it ad} at the start of the line is
the name of the MX record that controls your area detector.
This name must be passed to \myfunction{mx\_get\_record()} after you
invoke \myfunction{mx\_setup\_database()}.
At the end of the line,
the number 8 is the maximum number of software ROIs configured
for this area detector.  This value should match the value set in the 
server's configuration file.  {\it adserver} tells MX that this device
is controlled by the MX server defined on the first line, while the 
trailing {\it ad} entry is the name of the area detector record
on the remote MX server.

\subsection{Configuring MX for Area Detector Servers}

There are four files you may need to configure for an MX server.

\begin{enumerate}
  \item \myfilename{\$MXDIR/etc/mxserver.acl}

  This file contains a list of IP addresses or domain names that are
  permitted to connect to the MX server.  There should be one address
  per line.  Here is an example.
\begin{verbatim}
    192.168.137.3
    192.168.137.6
    192.168.238.*
    *.example.com
    beamline?.example.net
\end{verbatim}
  Note that the wildcard character ''*'' can match any string of characters,
  while the wildcard character ''?'' only matches a single character.
  Thus, for this example, any computer on the 192.168.238 subnet or
  at example.com can connect to the server.  In addition, any computer
  with a name like beamline1.example.net, beamline2.example.net, and
  so forth, can also connect.

  Please note that the MX server checks the address of the remote client
  before reading even a single byte from the client.  If the client's
  host IP is not on the access control list, the connection is dropped
  without sending any response back.

  \item \myfilename{\$MXDIR/etc/mxserver.dat}

  This file configures the devices used by the MX server and is described
  in detail below.

  \item \myfilename{\$MXDIR/etc/mxserver.opt}

  If it exists, this file supplies additional command line arguments
  to the MX server.  The most commonly used argument here is {\it -t},
  which tells the server to print out the name of each record, just before
  it starts to configure the hardware for that record.  This option is
  useful for cases where the MX server hangs during startup if you want
  to see which record is causing it to hang.  For a system with only
  a few records, such as an area detector, it is probably simplest to
  always specify {\it -t} here.

  If you want the MX server to support event callbacks, then you must
  add the {\it -c} command line argument as well.  Event callbacks are
  used to make it possible for dark current measurements and flood field
  measurements to complete asynchronously without blocking.  Event callbacks
  are not on by default since this is a fairly new feature of the 
  MX server.  After we have more experience with the new event callbacks,
  we will change the server so that event callbacks are on by default.

  \item \myfilename{\$MXDIR/etc/mxuser.dat}

  If it exists, this file lists the name of the user account that the
  MX server should be run under.  At present, this feature only works
  on Linux/Unix systems and only functions if the server startup
  script \myfilename{\$MXDIR/sbin/mx} is started as root.  In general,
  we recommend that the MX server be run as a non-root user such as {\it mx}
  to limit the scope of damage if someone were to break into your computer
  via the MX server.  So far this has never happened, but it is best
  to be prepared.

  \item \myfilename{\$MXDIR/etc/mxupdate.dat}

  If it exists, this file contains a list of MX variables to be saved
  by the \mycommand{mxupdate} program to a file at periodic intervals.
  After the \mycommand{mxserver} process starts, the \mycommand{mxupdate}
  program will restore the saved values to the newly running MX server.

\end{enumerate}

\subsection{Configuring mxserver.dat}

The contents of the \myfilename{\$MXDIR/etc/mxserver.dat} depend on 
which kind of area detector you are using.

\subsubsection{AVIEX PCCD-170170}

For the AVIEX PCCD-170170 CCD detector, you should use an
\myfilename{mxserver.dat} file that looks like this:
%
{\small
\begin{verbatim}
ready device digital_output soft_doutput "" "" 0
xclib interface generic epix_xclib "" "" /opt/mx/etc/pccd_170170_v9.fmt 0x0
port  interface camera_link epix_camera_link "" "" 9600 0.5 1
rs232 interface rs232 camera_link_rs232 "" "" 9600 8 N 1 N 0x0 0x0 -1 0x0 port
epix  device video_input epix_xclib_video_input "" "" 16384 1024 grey16 -1 xclib 1 ready 0x0 0x0
trigger device digital_output epix_xclib_doutput "" "" 0 epix
ad    device area_detector pccd_170170 "" "" 0 "" "" "" "" epix port trigger 0x1 0x8
\end{verbatim}
}
%
Let us describe in detail what each of these lines mean.

\begin{description}
\item Record \textbf{ready}\newline
This line defines a record \myfunction{ready} of
type \myfunction{soft\_doutput}.
The \myfunction{ready} record is a placeholder for
a ``ready for external trigger'' feature of the \myfunction{epix} record
used for debugging.  If this record is defined as a \myfunction{soft\_doutput}
record, the ready signal will be thrown away.

The fields in this record have the following meaning:
%
\begin{center}
\begin{tabular}{llll}
  \textbf{Name}  & \textbf{Value}  & \textbf{Datatype} & \textbf{Description} \\
  name             & \textit{ready}     & 1-d string   & Name of the record.\\
  mx\_superclass   & \textit{device} & recordtype   & Driver superclass.\\
  mx\_class        & \textit{digital\_output}   & recordtype   & Driver class.\\
  mx\_type         & \textit{soft\_doutput} &  recordtype  & Driver type.\\
  label            & \textit{``''}   & 1-d string  & Intended for use by GUIs.\\
  acl\_description & \textit{``''} & 1-d string    & ACLs not yet implemented.\\
  value            & \textit{0} & hex number & Initial output value.\\
\end{tabular}
\end{center}

\item Record \textbf{xclib}\newline
This line defines the record \myfunction{xclib} which
is of type \myfunction{epix\_xclib}.  This record manages the interface
to the EPIX XCLIB software library.  The fields in this record have
the following meaning:
%
\begin{center}
\begin{tabular}{llll}
  \textbf{Name}  & \textbf{Value}  & \textbf{Datatype} & \textbf{Description} \\
  name             & \textit{xclib}     & 1-d string   & Name of the record.\\
  mx\_superclass   & \textit{interface} & recordtype   & Driver superclass.\\
  mx\_class        & \textit{generic}   & recordtype   & Driver class.\\
  mx\_type         & \textit{epix\_xclib} &  recordtype  & Driver type.\\
  label            & \textit{``''}   & 1-d string  & Intended for use by GUIs.\\
  acl\_description & \textit{``''} & 1-d string    & ACLs not yet implemented.\\
  format\_file     & \textit{/opt/mx/etc/pccd\_170170\_v9.fmt}
  				& 1-d string    & Name of EPIX config file.\\
  epix\_xclib\_flags & \textit{0x0} & hex number
  				& \textit{epix\_xclib} option flags.\\
\end{tabular}
\end{center}
\textit{format\_file} is the name of an
EPIX configuration file created by XCAP that is used
to initialize the PIXCI E4 board when the MX server is started.
Such files normally have the file extension \myfilename{.fmt}.
In general, you should only use \myfilename{.fmt} files provide by Aviex.
You should normally leave \textit{epix\_xclib\_flags} alone.

\item Record \textbf{port}\newline
The \myfunction{port} record controls communication with the
Camera Link serial port.  The fields in this record have the following
meaning:
\begin{center}
\begin{tabular}{llll}
  \textbf{Name}  & \textbf{Value}  & \textbf{Datatype} & \textbf{Description} \\
  name             & \textit{port}     & 1-d string   & Name of the record.\\
  mx\_superclass   & \textit{interface} & recordtype   & Driver superclass.\\
  mx\_class        & \textit{camera\_link}   & recordtype   & Driver class.\\
  mx\_type         & \textit{epix\_camera\_link} &  recordtype  & Driver type.\\
  label            & \textit{``''}   & 1-d string  & Intended for use by GUIs.\\
  acl\_description & \textit{``''} & 1-d string    & ACLs not yet implemented.\\
  baud\_rate       & \textit{9600} & long          & Serial port speed.\\
  timeout          & \textit{0.5} & double & Communication timeout in seconds.\\
  serial\_index    & \textit{1}   & ulong 
  				& Camera Link serial port index number.\\
\end{tabular}
\end{center}
In general, you should not change any of these values.

\item Record \textbf{rs232}\newline
The \myfunction{rs232} record provides a way of communicating with a
Camera Link serial port via an MX RS-232 record.  The justification for
having such a record is so that RS-232 specific applications like
\mycommand{mxserial} or the \myfunction{rs232} command in \mycommand{motor}
can be used with Camera Link ports.
The fields in this record have the following meaning:
\begin{center}
\begin{tabular}{llll}
  \textbf{Name}  & \textbf{Value}  & \textbf{Datatype} & \textbf{Description} \\
  name             & \textit{rs232}     & 1-d string   & Name of the record.\\
  mx\_superclass   & \textit{interface} & recordtype   & Driver superclass.\\
  mx\_class        & \textit{rs232}   & recordtype   & Driver class.\\
  mx\_type         & \textit{camera\_link\_rs232}  & Recordtype & Driver type.\\
  label            & \textit{``''}   & 1-d string  & Intended for use by GUIs.\\
  acl\_description & \textit{``''} & 1-d string    & ACLs not yet implemented.\\
  speed            & \textit{9600} & long          & Serial port speed.\\
  word\_size       & \textit{8}    & long          & Serial port word size.\\
  parity           & \textit{N}    & char          & Serial port parity.\\
  stop\_bits       & \textit{1}    & long          & Number of stop bits.\\
  flow\_control    & \textit{N}    & char          & Serial port flow control.\\
  read\_terminators & \textit{0x0} & hex number    & Line read terminators.\\
  write\_terminators & \textit{0x0} & hex number   & Line write terminators.\\
  timeout          & \textit{-1} & double & Communication timeout in seconds.\\
  rs232\_flags     & \textit{0x0} & hex number & RS-232 option selection.\\
  camera\_link\_record & \textit{port} & record &
  	\begin{minipage}[t]{5cm}
  	Name of the record using the \textit{epix\_camera\_link} driver.
	\end{minipage}\\
\end{tabular}
\end{center}
In general, you should not change any of these values.

\item Record \textbf{epix}\newline
The \myfunction{epix} record controls the EPIX PIXCI E4 imaging board
used by the PCCD-170170 area detector.
The fields in this record have the following meaning:
\begin{center}
\begin{tabular}{llll}
  \textbf{Name}  & \textbf{Value}  & \textbf{Datatype} & \textbf{Description} \\
  name             & \textit{rs232}     & 1-d string   & Name of the record.\\
  mx\_superclass   & \textit{device} & recordtype   & Driver superclass.\\
  mx\_class        & \textit{video\_input}   & recordtype   & Driver class.\\
  mx\_type         & \textit{epix\_xclib\_video\_input}
  						& Recordtype & Driver type.\\
  label            & \textit{``''}   & 1-d string  & Intended for use by GUIs.\\
  acl\_description & \textit{``''} & 1-d string    & ACLs not yet implemented.\\
  framesize        & \textit{16384 1024} & 1-d array of length 2
					& Video input initial framesize.\\
  image\_format\_name & \textit{grey16} & 1-d string
  					& Image format (16-bit greyscale)\\
  byte\_order      & \textit{-1}        & long &
  		\begin{minipage}[t]{4.5cm}
  		Pixel byte order (-1 means automatically discovered)
		\end{minipage}\\
  xclib\_record    & \textit{xclib}     & record & XCLIB interface record.\\
  unit\_number     & \textit{1} & long & XCLIB board number.\\
  ready\_for\_trigger\_name & \textit{ready} & 1-d string &
  		\begin{minipage}[t]{4.5cm}
		The name of a digital output record that goes high when
		the PIXCI E4 is ready for an external trigger.
		\end{minipage}\\
  epix\_xclib\_vinput\_flags & 0x0 & hex number
  				& EPIX video input option flags.\\
  write\_test\_value & 0x0 & hex number & For debugging.\\
\end{tabular}
\end{center}
In general, you should not change any of these values.

\item Record \textbf{trigger}\newline
The \myfunction{trigger} digital output record is used by the
detector control computer to send a trigger signal to the camera head.
This signal is used to implement internal triggering for the PCCD-170170.
The fields in this record have the following meaning:
\begin{center}
\begin{tabular}{llll}
  \textbf{Name}  & \textbf{Value}  & \textbf{Datatype} & \textbf{Description} \\
  name             & \textit{trigger}     & 1-d string   & Name of the record.\\
  mx\_superclass   & \textit{device} & recordtype   & Driver superclass.\\
  mx\_class        & \textit{digital\_output}   & recordtype   & Driver class.\\
  mx\_type         & \textit{epix\_xclib\_doutput} & Recordtype & Driver type.\\
  label            & \textit{``''}   & 1-d string  & Intended for use by GUIs.\\
  acl\_description & \textit{``''} & 1-d string    & ACLs not yet implemented.\\
  value            & \textit{0}    & hex number & Initial output value.\\
  epix\_xclib\_vinput\_record & \textit{epix} & record &
  		\begin{minipage}[t]{5.5cm}
  		Name of the PIXCI driver board that has the attached
		digital output port.
		\end{minipage}\\
\end{tabular}
\end{center}
In general, you should not change any of these values.

\item Record \textbf{aviex}
\begin{center}
\begin{tabular}{llll}
  \textbf{Name}  & \textbf{Value}  & \textbf{Datatype} & \textbf{Description} \\
  name             & \textit{ad}     & 1-d string        & Name of the record.\\
  mx\_superclass   & \textit{device} & recordtype        & Driver superclass.\\
  mx\_class        & \textit{area\_detector} & recordtype & Driver class.\\
  mx\_type         & \textit{pccd\_170170} &  recordtype  & Driver type.\\
  label            & \textit{``''}   & 1-d string  & Intended for use by GUIs.\\
  acl\_description & \textit{``''} & 1-d string    & ACLs not yet implemented.\\
  maximum\_num\_rois      & \textit{8}   & long &
  					Maximum number of ROIs\\
  initial\_correction\_flags & \textit{0x100f} & hex number &
  		\begin{minipage}[t]{6.5cm}
		Initial setting for the area detector correction flags.
		\end{minipage}\\
  mask\_filename          & \textit{``''} & 1-d string &
				Name of the file containing the mask frame.\\
  bias\_filename          & \textit{``''} & 1-d string &
				Name of the file containing the bias frame.\\
  dark\_current\_filename & \textit{``''} & 1-d string &
  		\begin{minipage}[t]{6.5cm}
		Name of the file containing the dark current frame.
		\end{minipage}\\
  flood\_field\_filename  & \textit{``''} & 1-d string &
  		\begin{minipage}[t]{6.5cm}
		Name of the file containing the flood field frame.
		\end{minipage}\\
  video\_input\_record    & \textit{epix} & record & 
  					The name of the video input record.\\
  camera\_link\_record    & \textit{port} & record &
  					The name of the Camera Link record.\\
  internal\_trigger\_record & \textit{spare} & record &
  			\begin{minipage}[t]{6.5cm}
			This record is used to generate the trigger pulse
			sent to the camera head for the PCCD-170170's
			internal trigger mode.
			\end{minipage}\\
  initial\_trigger\_mode  & \textit{0x1} & hex number &
  			\begin{minipage}[t]{6.5cm}
	  		Select either internal trigger (0x1)
			or external trigger (0x2).\\
			\end{minipage}\\
  pccd\_170170\_flags & \textit{0x8} & hex number &
  				Configuration options for the PCCD-170170.\\
  geometrical\_spline\_filename & \textit{``''} & 1-d string &
  		Name of the geometrical correction spline file.\\
  geometrical\_mask\_filename & \textit{``''} & 1-d string &
  		Name of the geometrical correction mask file.\\
\end{tabular}
\end{center}
In general, you should not change any of these values.
%
\end{description}

For arbitrary drivers, you can get a fairly terse list of the field names and 
their datatypes by running the command
\mycommand{\$MXDIR/bin/mxdriverinfo -f pccd\_170170}, if you replace
\textit{pccd\_170170} with the name of the driver you are really interested in.
In general, we will not describe the detailed meanings of records that
you are not expected to change.

The first modifiable field in the \myfield{ad} record
is the \myfield{maximum\_num\_rois} field
which, as it says, sets the maximum number of
regions of interest available to the user.  
In the example above, it is set to 8.
In general, both the 
client and the server should be configured to use the same maximum
number of regions of interest.  Each region of interest uses enough memory
to hold a copy of the region of interest data.  If the region of interest
covers the entire frame, then it will use as much memory as an entire
frame.  However, the memory for a given region of interest is not allocated
until the first time it is used.

Next comes the \myfield{initial\_corrections\_flags} field which specifies
the initial value for the area detector \myfield{correction\_flags} field
when the program starts up.  The rightmost digit specifies the linear
image corrections to be performed on new image data.  You can find the 
definitions of the flag bits in Section~\ref{subsec:framebuffertypes}.
In addition, there is a geometrical correction flag 0x1000 that turns on
or off the geometrical correction stage of image correction.

Then come the \myfield{mask\_filename}, \myfield{bias\_filename},
\myfield{dark\_current\_filename}, and \myfield{flood\_field\_filename} fields
which specify the names of the initial files to be used for image correction.
If they are not set to empty strings, the contents of the specified file will
be loaded into the MX server at server startup time.  If a given correction
filename is set to ``'', then that correction will not be performed.

%\textit{(\FIXME
%The mxupdate program is almost in a state where it could automatically
%save and restore the correction filenames.  The only missing piece is the
%ability to explicitly set the value of the .load\_frame field several
%times at restore time.)}

The \myfield{video\_input\_record} and \myfield{camera\_link\_record} fields
should not be changed.  Setting the \myfield{initial\_trigger\_mode} field
to 0x1 tells the area detector record to start with internal trigger.
The \myfield{pccd\_170170\_flags} field should always be set to 0x8.  
You should not change the value of \myfield{pccd\_170170\_flags} unless
instructed to do so by AVIEX personnel.

The next field is the \myfield{geometrical\_spline\_filename}
field which contains spline parameters that are used by the
geometrical correction process to undistort the image frame.
The last field \myfield{geometrical\_mask\_filename} is an additional
mask frame used by the geometrical correction process.  If both of
these filenames are not specified, the geometrical correction process
will not work.

\subsubsection{Software Emulated Area Detector with Software Generated Images}

In order to test using an area detector emulated entirely in software,
you should use the following \myfilename{mxserver.dat} file:
%
{\small
\begin{verbatim}
video device video_input soft_vinput "" "" 4096 4096 grey16 -1 1
ad    device area_detector soft_area_detector "" "" 8 "" "" "" "" video 0x1
\end{verbatim}
}
%
In the record description for the \myfield{soft\_area\_detector} record,
the field containing the number 8 is the \myfield{maximum\_num\_rois}
field and the four fields following it are the various correction files,
just like for the \myfield{pccd\_170170} driver discussed above.  The last
two fields are the \myfield{video\_input\_record}
and \myfield{initial\_trigger\_mode} fields as described above.

The definition of the \myfield{soft\_vinput} record should probably be left
alone, unless you want to change the image framesize from 4096 by 4096
to something else.  The last field in this record is the 
\myfield{image\_type} field.  In the future, changing this field will allow
you to change the type of image generated.  At present, the only supported
value is 1, which causes the generated images to repeat with in a cycle of
four frames, with the maximum intensity in a different corner for each of
the four frames.

\subsubsection{Software Emulated Area Detector with Images from a
Directory of Frames}

The \myfield{file\_vinput} driver generates the image frames
sent to clients by reading them from a directory of already existing frames,
such as from another area detector.  
%
{\small
\begin{verbatim}
video device video_input file_vinput "" "" 4096 4096 grey16 -1 smv /opt/mx/etc/test_frames
ad    device area_detector soft_area_detector "" "" 8 "" "" "" "" video 0x1
\end{verbatim}
}
%
The driver returns the files in the
specified directory in alphanumeric order.  After reading the last file
in the directory, the driver loops back to the first file.  It is essential
that all of the files in the directory be image files in formats that
MX supports, since the MX driver assumes that all of the files are in the
format specified in the record definition.
At present, MX supports the SMV and PNM image formats.

\subsubsection{Software Emulated Area Detector
		with Video4Linux 2 Generated Images}

This mode of operation replaces the generation of image frames in software
with frames read in from a video camera or a TV capture card.  For this case,
you should use an \myfilename{mxserver.dat} that looks like this:
%
{\small
\begin{verbatim}
video device video_input v4l2_input "" "" 640 480 GREY8 -1 /dev/video0 1
ad    device area_detector soft_area_detector "" "" 8 "" "" "" "" video 0x1
\end{verbatim}
}
%
Although this driver makes many kinds of software testing easier, it is not
able to generate images as large as a typical area detector and most
consumer cameras do not support square images.
In addition, Video4Linux 2 only supports 8-bit greyscale.
Thus, it is a less faithful emulation of the real behavior of an area detector.

\subsection{Running the MX Server}

\subsubsection{Linux}

MX normally expects \mycommand{mxserver} and \mycommand{mxupdate}
to be run under a user account of its own called \textit{mx}.
The purpose of this is to limit the amount of damage that can be
caused by a hacker that breaks into the system.  It is possible
to run the server under another account, even \textit{root}, if you
specify the name of that account in the file
\myfilename{\$MXDIR/etc/mxuser.dat}.  On Linux systems, the \mycommand{mx}
account can be created with a command like this:
%
\begin{verbatim}
        useradd -c MX -m mx
\end{verbatim}
The \textit{mx} account should have a locked password.

For Linux and Unix systems, MX comes with a System V style startup script
which is installed at the location \myfilename{\$MXDIR/sbin/mx}.
To manually start, stop, or restart the MX server, you can use the
System V style syntax, assuming MXDIR=/opt/mx:
\begin{verbatim}
        /opt/mx/sbin/mx start
        /opt/mx/sbin/mx stop
        /opt/mx/sbin/mx restart
\end{verbatim}

To get automatic startup of the MX server when the machine boots,
all you need to do is to arrange that the 
\myfilename{\$MXDIR/sbin/mx} script be invoked at system startup time.
On a Linux computer that uses the System V style init,
you must go into the \myfilename{rc?.d} directories for each run level
that you want to run the MX server in and make a symbolic link to the
\myfilename{\$MXDIR/sbin/mx} script.

For example, on a Fedora or Red Hat Enterprise Linux
system with MXDIR=/opt/mx, you would go
into the directory \myfilename{/etc/rc.d/rc2.d} and make a symbolic link
with the following command
\begin{verbatim}
    ln -s /opt/mx/sbin/mx S99mx
\end{verbatim}
This tells the System V init system that you want to start the MX server
at the end of system startup for run level 2.  You would add similar
symbolic links to the other run levels that you want it to start in.

For system shutdown, you make similar symbolic links in the run level
directories for run levels 0 and 6.  For example,
\begin{verbatim}
    ln -s /opt/mx/sbin/mx K00mx
\end{verbatim}
tells {\it init} to shut down the MX server at the start of system shutdown
or reboot.

\subsubsection{Windows}

On Windows, you can start the MX server by running the batch file.
\myfilename{\$MXDIR/sbin/mx.bat}.  This file is merely a wrapper around
the \myfilename{\$MXDIR/sbin/mxserver.exe} binary to set up its command
line arguments correctly.  The simplest way to get the server to start
automatically when the Windows machine boots is to configure the Windows
machine to automatically log into the account you will be running the
MX server from and then configure the \myfilename{mx.bat} script as
a Startup item.  It may be possible to run the MX server as a service
using the \myfilename{srvany.exe} program from the Windows Resource Kit,
but we have not tested this.

