\chapter{Using \textit{motor} to Test an MX Area Detector}

\mxfn{Motor} is a command-line based MX application program used by
some beamlines to control many of their experiments.  It is not
anticipated that users of MX-controlled area detectors will use
the \mxfn{motor} program.  However, for initial testing by beamline
staff, it may be useful since it implements commands for controlling
area detectors.  In addition, it is the only significant user application
bundled with the core MX distribution.

If you have chosen the name \mxfn{\$MXDIR/etc/motor.dat} for
your MX client database and setup the MXDIR environment variable,
you can start up the \mxfn{motor} program by just typing the
command \texttt{motor} at a Linux/Unix shell prompt or Win32 DOS prompt.
The procedure should look something like this:
%
\begin{verbatim}
  id1:~$ motor

  MX version 1.4.0 (October 20, 2006)
  WARNING: Save file '/home/lavender/scan.dat' is empty.

  motor>
\end{verbatim}
%
You will not be using MX scans, so do not worry about the error message
concerning the \textit{scan.dat} file.

\ \newline
If you are using an MX server and the server is not running, you will get
a series of errors like the following.
%
\begin{verbatim}
  id1:~$ motor

  MX version 1.5.0 (August 7, 2007)
  WARNING: Save file '/home/lavender/scan.dat' is empty.

  MXE_NETWORK_IO_ERROR in mx_tcp_socket_open_as_client():
  -> connect() to host '192.168.137.3', port 9727 failed.  Errno = 111. >
    Error string = 'Connection refused'.
  MXE_NETWORK_IO_ERROR in mxn_tcpip_server_open():
  -> The MX server at port 9727 on the computer '192.168.137.3' is either >
    not running or is not working correctly.  You can try to fix this by >
    restarting the MX server.
  *** Reconnecting to server 'adserver' at '192.168.137.3', port 9727.
  MXE_NETWORK_IO_ERROR in mx_tcp_socket_open_as_client():
  -> connect() to host '192.168.137.3', port 9727 failed.  Errno = 111. >
    Error string = 'Connection refused'.
  MXE_NETWORK_IO_ERROR in mxn_tcpip_server_open():
  -> The MX server at port 9727 on the computer '192.168.137.3' is either >
    not running or is not working correctly.  You can try to fix this by >
    restarting the MX server.
  motor> 
\end{verbatim}

Some of the lines of output
are too wide to fit the page in this manual, so we have artificially
broken the lines of output so that all of the output can be seen.
The $>$ symbols above mark the places where we have broken the lines.
Note that \mxfn{motor} attempted to reconnect just in case the 
failure was a momentary failure.  This is a general feature of MX clients
such that if the connection to the server goes down, the client attempts
to reconnect to the server the next time that it wants to send a command
to the server.

\section{Motor Commands}

\mxfn{Motor} has a large number of commands for controlling a variety of
different classes of devices.  However, for area detector use, there are
really only three commands you should need to know about.

\subsection{exit}
The first command you should know about is the \texttt{exit} command
which allows you to leave the \mxfn{motor} program.  The procedure
should look like this:
%
\begin{verbatim}
motor> exit
id1:~$
\end{verbatim}

\subsection{show record}

The \texttt{show record} command is useful since it allows you to verify
that the MX runtime database is working.  Using this command should
look like this:
%
\begin{verbatim}
  motor> show record
  mx_database      list_head
  adserver         tcp_server "192.168.137.3" 9727
  ad               network_area_detector 8 0 (0,0,0,0) (0,0,0,0) adserver "ad"
  motor>
\end{verbatim}

If you see any error messages starting with prefixes like MXE\_\ldots,
then something is wrong with your configuration and you need to fix it.

\subsection{area\_detector}

The \texttt{area\_detector} command is the most important command that you
will use, since it allows you access to much of the functionality of
the area detector.  You can get help for the \texttt{area\_detector}
command by typing it at a \mxfn{motor} prompt with no arguments.
Generally you can abbreviate command names and command arguments to the
shortest unique string that matches.  In addition, you can use the
alias \texttt{ad} for \texttt{area\_detector}.

Thus, if your area
detector is named, for example, \texttt{aviex}, you can abbreviate a 
command like
\begin{verbatim}
    area_detector aviex set one_shot_mode 2.5
\end{verbatim}
down to something like this
\begin{verbatim}
    area aviex set one 2.5
\end{verbatim}
or something even shorter like this
\begin{verbatim}
    ad aviex se o 2.5
\end{verbatim}
\ \newline
\textbf{NOTE:}\ If the first thing you want to do with a new detector is
take an image with it, the quickest place to start is with the 
\texttt{snap} command described below.

\ \newline
The following sections describe the commands listed by the
\texttt{area\_detector} command's help message 
with explanatory comments inserted.
%
Most of these commands are one-to-one matches to the MX Area Detector API
described in Chapter~\ref{ch:areadetectorapi}.
%
\subsubsection{Configuration Commands}
%
\begin{verbatim}
motor> ad
Usage:
  area_detector 'name' get bytes_per_frame
  area_detector 'name' get bytes_per_pixel
  area_detector 'name' get bits_per_pixel
  area_detector 'name' get format
  area_detector 'name' get framesize
  area_detector 'name' set framesize 'x_framesize' 'y_framesize'
  area_detector 'name' get maximum_framesize
\end{verbatim}
%
The commands above return information about the current format of image frames
in the detector computer.
%
\begin{verbatim}
  area_detector 'name' get trigger_mode
  area_detector 'name' set trigger_mode 'trigger mode'
\end{verbatim}
%
The trigger commands are used to switch between internal trigger
and external trigger modes.
%
\begin{verbatim}
  area_detector 'name' get correction_flags
  area_detector 'name' set correction_flags 'correction flags'
\end{verbatim}
%
The correction flags commands are used to change the list of corrections
applied to image frames, using a hexadecimal format for displaying the
individual bits in the flags value.  For each bit that is set to 1, the
corresponding correction will be applied.  The bit values are defined
in Section~\ref{subsec:framebuffertypes}.
%
\begin{verbatim}
  area_detector 'name' get register 'register_name'
  area_detector 'name' set register 'register_name' 'register_value'
\end{verbatim}
%
Each area detector has internal registers that are specific to that
model of area detector.  The above commands
are used to read and write these values.  Each internal register is 
first given an ASCII name.  Then, if the register has a value that can
be represented as a long integer, then the \textit{register}
commands can be used to change it.

%
\subsubsection{Sequence Commands}
%
\begin{verbatim}
  area_detector 'name' get sequence_parameters
  area_detector 'name' set one_shot_mode 'exposure time in seconds'
  area_detector 'name' set continuous_mode 'exposure time in seconds'
  area_detector 'name' set multiframe_mode '# frames 
                                                 'exposure time' 'frame_time'
  area_detector 'name' set circular_multiframe_mode '# frames'
                                                 'exposure time' 'frame_time'
  area_detector 'name' set strobe_mode '# frames' 'exposure time'
  area_detector 'name' set bulb_mode '# frames'
  area_detector 'name' set geometrical_mode '# frames'
          'exposure time' 'frame_time' 'exposure multiplier' 'gap multiplier'
  area_detector 'name' set streak_camera_mode '# lines' 'exposure_time'
  area_detector 'name' set subimage_mode '# lines per subimage' '#subimages'
          'exposure time' 'subimage_time' 'exposure multiplier' 'gap multiplier'
\end{verbatim}
%
The sequence commands above can be used to control the type of 
imaging sequence that is to be performed by the detector.
A description of the available sequence types can be found
in Section~\ref{sec:sequences}.
%
\subsubsection{Binsize and ROI Configuration Commands}
%
\begin{verbatim}
  area_detector 'name' get binsize
  area_detector 'name' set binsize 'x_binsize' 'y_binsize'
\end{verbatim}
%
The \textit{binsize} commands are used to control the binning of
pixels in the area detector.  In general, the allowed bin sizes are
powers of two.  Typically, the X and Y bin sizes have the same
values, but not all area detectors require this.
%
\begin{verbatim}
  area_detector 'name' get roi 'roi_number'
  area_detector 'name' set roi 'roi_number' 'xmin' 'xmax' 'ymin' 'ymax'
\end{verbatim}
%
The ROI commands are used to set the boundaries of regions of interest.
The implementation of the ROIs is all managed in software on the 
detector computer, so the maximum number of ROIs is limited only by
the configuration of the area detector record in the detector computer's
database.

Please note that the rows and columns specified for the X and Y
minima and maxima are included within the returned ROI data.
In other words, a command like this
\begin{verbatim}
                    ad aviex set roi 5 1000 2000 200 500
\end{verbatim}
will return a 1001 column by 301 row array including columns 1000 and 2000
and rows 200 and 500 in the data returned for ROI 5.
%
\subsubsection{Action Commands}
%
\begin{verbatim}
  area_detector 'name' snap 'exposure_time' 'file_format' 'filename'
\end{verbatim}
%
The \texttt{snap} command is the simplest way to get the detector
to acquire and correct a single frame and then transfer the frame to 
a disk file on the client computer.
%
You can choose to save the 
image in any of the file formats supported by MX.  However, at the moment,
the only file format that has been implemented already is PNM format.

Here is an example \texttt{snap} command line that commands a
2.5 second exposure and then writes the image to \textit{``myimage.pgm''}.
%
\begin{verbatim}
                    ad aviex snap 2.5 pnm myimage.pgm
\end{verbatim}
%
Internally, the \texttt{snap} command selects One-shot mode, starts the
detector, waits for the detector to finish, gets the image data from
the detector computer, and then writes it to a file on the local disk.

\begin{verbatim}
  area_detector 'name' take frame
\end{verbatim}
%
The \texttt{take frame} command is somewhat different in that it starts
the detector in whatever sequencer mode it happens to be in, waits for
the sequence to finish, and then transfers the file to the memory
of the client.  It does not write the file to disk.
%
\begin{verbatim}
  area_detector 'name' write frame 'file_format' 'filename'
  area_detector 'name' write roiframe 'file_format' 'filename'
\end{verbatim}
%
The above commands do exactly what they say, namely, write out
the contents of either the primary image buffer or the ROI image buffer
on the client side.
%
\begin{verbatim}
  area_detector 'name' arm
  area_detector 'name' trigger
  area_detector 'name' start
  area_detector 'name' stop
  area_detector 'name' abort
\end{verbatim}
%
The above commands are the low level primitives for starting
and stopping the detector.
%
\begin{verbatim}
  area_detector 'name' get last_frame_number
  area_detector 'name' get status
  area_detector 'name' get extended_status
  area_detector 'name' get busy
\end{verbatim}
%
The commands above report on the current status of the area detector.
%
\begin{verbatim}
  area_detector 'name' get frame 'frame_number'
\end{verbatim}
%
The \texttt{get frame} command does an image readout,
image correction, and image transfer
to the client.  The available values for \textit{frame\_number}
are described in Section~\ref{subsec:framebuffertypes}.
%
\begin{verbatim}
  area_detector 'name' get roiframe 'roi_number'
\end{verbatim}
%
The \texttt{get roiframe} command transfers to the client the contents of the
specified ROI number.
You must have defined the boundaries for this particular ROI before
invoking \texttt{get roiframe}.  If you do not, you may end up with
the default ROI boundaries which only contain the single pixel (0,0)
in binned coordinates.
%
\begin{verbatim}
  area_detector 'name' readout 'frame_number'
\end{verbatim}
%
The \texttt{readout} command reads out
the requested frame number from the camera
hardware into the primary image buffer on the detector computer.
%
\begin{verbatim}
  area_detector 'name' correct
\end{verbatim}
%
The \texttt{correct} command performs mask, bias, dark current,
and flood field corrections to the contents of the primary image buffer
on the detector computer.  A given correction will only be performed if
the corresponding bit is set in the area detector correction flags
and if a correction frame has been loaded into the corresponding
image buffer on the detector computer.  You may find more information
about this operation in the function descriptions of
\mxfn{mx\_area\_detector\_set\_correction\_flags()} and
\mxfn{mx\_area\_detector\_correct\_frame()} as well as the
definition of the frame buffer types used in the correction flag bits
in Section~\ref{subsec:framebuffertypes}.
%
\begin{verbatim}
  area_detector 'name' transfer 'frame_type'
\end{verbatim}
%
The \texttt{transfer} command transfers the contents of the requested
frame buffer on the detector computer to the primary image buffer of
the client.  You may find the definitions of the frame buffer types
in Section~\ref{subsec:framebuffertypes}.
%
\begin{verbatim}
  area_detector 'name' load frame 'frame_type' 'filename'
  area_detector 'name' save frame 'frame_type' 'filename'
  area_detector 'name' copy frame 'src_frame_type' 'dest_frame_type'
\end{verbatim}
%
The above commands load frames, save frames, and copy frames between
the various image buffers on the detector computer.  The frame buffer types
are described in Section~\ref{subsec:framebuffertypes}.  The files that
frame buffers are loaded from or saved to are found on the detector computer.
%
\begin{verbatim}
  area_detector 'name' measure dark_current 'measurement_time' '# measurements'
  area_detector 'name' measure flood_field 'measurement_time' '# measurements'
\end{verbatim}
%
The above commands measure dark current and flood field images on the
detector computer.  At the end of the measurement, the resulting image frames
are left in the matching dark current or flood field image buffers
on the detector computer and are ready to be used immediately for
correction of new images as they are acquired.  However, the
contents of the correction frames will be lost when the detector computer's
server shuts down.
%
If you want to preserve the contents of the new dark current and flood field
correction frames, you must write them to disk using the
\texttt{save frame} command described above.

