\chapter{Introduction}

MX is a portable beamline control and data acquisition toolkit currently
in use at a number of synchrotron beamlines and laboratory X-ray generator
systems.  The purpose of this manual is to explain how to set up the
configuration files that control how MX works.

The most important step in configuring a new MX system is the
building of the MX configuration files which are generally found in the
directory \textit{\$MXDIR/etc} where \textit{MXDIR} is an environment
variable that points to the top of the MX directory tree.  If you use the
standard definition that \textit{MXDIR = /opt/mx}, then the configuration
files will be found in \textit{/opt/mx/etc}.  The most important
configuration files are:
\begin{center}
\begin{tabular}{ll}
\textit{/opt/mx/etc/motor.dat} & - The primary MX client-side database file. \\
\textit{/opt/mx/etc/mxserver.acl} 
	& - An access control list for the MX server. \\
\textit{/opt/mx/etc/mxserver.dat} & - The MX server-side database file. \\
\textit{/opt/mx/etc/mxautosave.dat} 
	& - The \textit{mxautosave} process's configuration file. \\
\end{tabular}
\end{center}
\ \newline
We will cover \textit{mxserver.acl} and \textit{mxautosave.dat} first since
they are simple and relatively easy to explain.

\section{\textit{mxserver.acl}}

\textit{mxserver.acl} is an access control list file that describes what
computers are allowed to connect to the local MX server.  It is a simple
text file with one entry per line.  The entries are either IP addresses
or Internet domain names.  I recommend the use of IP addresses since then
the MX server does not need to perform potentially time consuming DNS
lookups to find the IP address from the domain name, but it is your choice.
Here is an example \textit{mxserver.acl} file:
\begin{verbatim}
127.0.0.1
192.168.17.5
192.168.17.27
192.168.22.*
myhost.example.com
*.example.net
\end{verbatim}

This configuration files says that the individual IP addresses 127.0.0.1,
192.168.17.5 and 192.168.17.27 are allowed, that any host on the subnet
192.168.22.* is allowed, that \textit{myhost.example.com} is allowed,
and that any host in the domain \textit{*.example.net} is allowed.  You
will note that \textit{*} wildcards are allowed.  In addition, the 
\textit{?} wildcard, which stands for a single character, is also allowed
although it is not as easy to use.

At present, MX only does access control on a host level basis and allows
any username from a given machine to connect.  Although MX clients do transmit
their username to the remote MX server, this information is not used for
access control since it is trivially spoofed.  Support for user level
access control will be added once something along the lines of an
SSL/TLS certificate infrastructure has been added to MX.

\section{\textit{mxautosave.dat}}

The \textit{mxautosave} process exists to save and restore MX database variables
so that their values can be preserved when the MX server is stopped and
restarted.  It is another simple text file that contains the name of one
record field per line.  An example \textit{mxautosave.dat} file looks like:
\begin{verbatim}
edge_energy.value     1 0
d_spacing.value       1 0
beam_offset.value     1 0
shutter_policy.value  1 0
xafs_header1.value    1 0
xafs_header2.value    1 0
xafs_header3.value    1 0
sff_header1.value     1 0
sff_header2.value     1 0
sff_header_fmt.value  1 0
theta_enabled.value   1 0
momega_enabled.value  1 0
normpoly_enable.value 1 0
normal_enabled.value  1 0
id_ev_enabled.value   1 0
momega_params.value   1 0
normpoly_params.value 1 0
id_ev_harmonic.value  1 0
id_ev_offset.value    1 0
id_ev_params.value    1 0
\end{verbatim}
%
The first field on each line is the name of an MX record field.  For example,
\textit{edge\_energy.value} refers to the record called \textit{edge\_energy}
and the field within it called \textit{value}.  Any record field listed here
will have its value saved twice a minute and will have its value restored
the next time the MX server is started from the \textit{mxautosave} state files
called \textit{/opt/mx/state/mxsave.1} and \textit{/opt/mx/state/mxsave.2}.
When \textit{mxautosave} restores the values the next time the MX server is
started, \textit{mxautosave} will choose whichever of the two state files
which is both complete and most recent.

For the present, you should set the second and third fields on each line
above to 1 and 0 respectively.  These fields are not currently documented,
since they are scheduled to be changed in the future.

\section{The MX Record Database Files \textit{motor.dat} and
	\textit{mxserver.dat}}

The most important configuration files in MX are the client-side 
\textit{motor.dat} file and the server-side \textit{mxserver.dat} file.
These files describe the set of objects called \textit{MX records}
which are used to represent the motors, counter, MCAs, serial ports, 
and so forth that an MX client or server will manage.

The first thing you will note if you compare \textit{motor.dat} and
\textit{mxserver.dat} is that they have exactly the same format.
This is due to the fact that MX servers and clients actually use exactly
the same set of device drivers.  In fact, the only thing that marks a
process as being an MX client is the use of one of the device drivers that
send command requests across the network to a remote server rather than to
a device directly attached to the client process.

For example, suppose you have a Compumotor 6K motor controller that is
managed by an MX server and a remote MX client wants to move a motor
belonging to the 6K.  The MX server will have in its database a record
for the motor of type \textit{compumotor} which communicates via a directly
attached RS-232 port, while the MX client will
have a record of type \textit{network\_motor} which sends the request
across the network via a socket.  But other than the fact that the
server or client are using different low level drivers, they treat the
motor moves the same.

To make the example more concrete, let us display some example MX
configuration files.  First, here is an \textit{mxserver.dat} file
for an MX server managing a 4-axis Compumotor 6K motor controller:
\begin{verbatim}
6k_rs232  interface rs232 tty "" "" 9600 8 N 1 S 0x0d0a 0x0d0a /dev/ttyS1
6k interface controller compumotor_int "" "" 6k_rs232 0x0 1 1 4
m1 device motor compumotor "" "" 0  0 -1000000 1000000 0 -1 -1 0.04 0 urad 6k 1 1 1
m2 device motor compumotor "" "" 0  0 -1000000 1000000 0 -1 -1 0.04 0 urad 6k 1 2 1
m3 device motor compumotor "" "" 0  0 -1000000 1000000 0 -1 -1 .0188 0 um 6k 1 3 1
m4 device motor compumotor "" "" 0  0 -200000 200000 0 -1 -1 0.25 0 urad 6k 1 4 1
\end{verbatim}
For the moment, we will not go too deeply into the details of the format of
the lines.  The first thing to note here is that each line of the database
file corresponds to one MX record, whose name is the first item on the line.
Thus, there are six MX records in this database named \textit{6k\_rs232},
\textit{6k}, \textit{m1}, \textit{m2}, \textit{m3}, \textit{m4}.  There
is nothing special about these record names.  All that MX expects is that they
be unique, be ordinary printing ASCII characters, and be 15 characters 
long or less.

Going to a little lower level of detail, the second, third, and fourth fields
on each line describe the MX device driver that will be used to control
the underlying hardware.  The second field is called the 
\textit{mx\_superclass} field, the third field is the \textit{mx\_class} field,
and the fourth field is the \textit{mx\_type} field.  Typically the MX
driver as a whole will be referred to by the name of the \textit{mx\_type}
field.  For the example database above, this breaks down as follows:
\newline\ \newline
\begin{center}
\begin{tabular}{|c|c|c|c|p{72mm}|}
\hline
\textbf{Record Name} & \textbf{Superclass} & \textbf{Class}
		& \textbf{Type} & \textbf{Explanation} \\
\hline
6k\_rs232 & interface & rs232 & tty
	& This record uses the \textit{tty} driver for Posix serial ports. \\
\hline
6k & interface & controller & compumotor\_int
	& This record manages the 6K controller as a whole.\\
\hline
m1 & device & motor & compumotor
	& This record manages axis 1 of the 6K controller. \\
\hline
m2 & device & motor & compumotor
	& This record manages axis 2 of the 6K controller. \\
\hline
m3 & device & motor & compumotor
	& This record manages axis 3 of the 6K controller. \\
\hline
m4 & device & motor & compumotor
	& This record manages axis 4 of the 6K controller. \\
\hline
\end{tabular}
\end{center}
\ \newline

To finish the example, we now show the client side \textit{motor.dat} file
that matches the MX server database shown above:
\begin{verbatim}
serv server network tcpip_server "" "" 0x0 192.168.17.10 9727
m1 device motor network_motor "" "" 0 0 -1e+06 1e+06 0 -1 -1 1 0 urad serv m1
m2 device motor network_motor "" "" 0 0 -1e+06 1e+06 0 -1 -1 1 0 urad serv m2
omega device motor network_motor "" "" 0 0 -1e+06 1e+06 0 -1 -1 1 0 urad serv m3
chi   device motor network_motor "" "" 0 0 -1e+06 1e+06 0 -1 -1 1 0 urad serv m4
\end{verbatim}

In more verbose language, this breaks down as:
%
\begin{center}
\begin{tabular}{|c|c|c|c|p{72mm}|}
\hline
\textbf{Record Name} & \textbf{Superclass} & \textbf{Class}
		& \textbf{Type} & \textbf{Explanation} \\
\hline
serv & server & network & tcpip\_server
	& This record manages the connection to an MX server running
	  on port 9727 of host 192.168.17.10. \\
\hline
m1 & device & motor & network\_motor
	& This record requests server \textit{serv} to perform actions
	  on its behalf on the server's record \textit{m1}.\\
\hline
m2 & device & motor & network\_motor
	& This record requests server \textit{serv} to perform actions
	  on its behalf on the server's record \textit{m2}.\\
\hline
omega & device & motor & network\_motor
	& This record requests server \textit{serv} to perform actions
	  on its behalf on the server's record \textit{m3}.\\
\hline
chi & device & motor & network\_motor
	& This record requests server \textit{serv} to perform actions
	  on its behalf on the server's record \textit{m4}.\\
\hline
\end{tabular}
\end{center}

An important detail to notice here is that the name of the client's record
does not have to be the same as the name the server knows it by.  For example,
client record \textit{omega} sends requests to the server for server record
\textit{m3}.  However, it is common and convenient to give the records the
same name in the clients and in the servers.

One last detail to note is that an MX client is not restricted to only one
server connection.  If you had an MX client database that started with 
the following
\begin{verbatim}
serv1 server network tcpip_server "" "" 0x0 192.168.17.11 9727
serv2 server network tcpip_server "" "" 0x0 192.168.17.12 9727
serv3 server network tcpip_server "" "" 0x0 192.168.17.13 9727
\end{verbatim}
then the client would have three simultaneous connections to three different
MX servers.
