\documentclass{howto}

\title{Microscope Networking Protocol Specification}

\release{2.0alpha1}

\author{A.M. Kuchling}
\authoraddress{\email{akuchlin@mems-exchange.org}}

\begin{document}
\maketitle


\section{Introduction}

The microscope's control protocol is designed to be human-readable,
consisting of single lines of ASCII text sent back and forth.  Images
are transmitted in binary form as a series of messages over a separate
TCP connection.

Client and server both send messages to each other.  These messages
are sent asynchronously; there is no call-and-response relationship
between messages.  Instead, the client will send a message to the
server, the server will process the message in whatever way is
desired, and may silently ignore it or generate new messages to be
sent back to the client.

Messages are single lines of ASCII text, ending with a newline.  The
first word of the line is the message name, followed by any parameters
required by the command.  Parameters are of the form
\var{parameter_name}=\var{value}, where \var{value} can be a single
word or number, or a quoted string.

Some example messages are:

\begin{verbatim}
CHATDISPLAY id=amk msg="What's wrong with the wafer?"
MOVE x=1000 y=2000
\end{verbatim}

Command names and parameter names are case-insensitive.  The order of
parameters is not significant.


\section{Connection-related commands}

\begin{tableiii}{|c|p{2in}|p{3in}|}{code}{Server/Client}{Command}{Explanation}

\lineiii{C}{\code{AUTH value=\var{authtoken}}}{
Mark this connection as authorized.  
\var{authtoken} is a base64-encoded, compressed text string.  When
decoded and uncompressed, it contains a pickled 2-tuple, containing
(signature, info string).  
XXX need to define the format of the info string
}

\lineiii{C}{\code{CEDE}}{
        Cede control of the scope.
}

\lineiii{S}{\code{CEDE}}{
        Informing all clients that the controller has ceded control.
}

\lineiii{C}{\code{IMAGE_SOCKET port=\var{number}}}{
Inform the server of the port of the TCP connection to which the image
data should be sent.  It's assumed that the IP address is the same as
the IP address of the TCP connection over which this message is being
sent.
}

\lineiii{C}{\code{QUIT}}{
        Terminate the client's connection.
}

\lineiii{C}{\code{TAKE}}{
        Take control of the scope.
}

\lineiii{S}{\code{TAKE}}{
        Informing the single client that it now controls the scope.
}

\lineiii{S}{\code{TAKEN id=username}}{
        Informing all other clients that control has been assumed by the user
\var{username}.
}

\hline
\end{tableiii}


\section{User-related commands}

\begin{tableiii}{|c|p{2in}|p{3in}|}{code}{Server/Client}{Command}{Explanation}

\lineiii{S}{\code{USERLISTDELETE id=username}}{
        Delete a user from the client's list of connected users.  
If the ID is listed multiple times, only one occurrence should be
removed from the list. 
}

\lineiii{S}{\code{USERLISTADD id=username}}{
Add the specified user to the client's list of connected users.  Users
can be listed multiple times. 
}

\lineiii{C}{\code{FEEDBACK comments="{\ldots}"}}{
Send a feedback comment, which will be e-mailed to someone at the MEMS
Exchange.
}


\hline
\end{tableiii}


\section{Chat-related commands}

\begin{tableiii}{|c|p{2in}|p{3in}|}{code}{Server/Client}{Command}{Explanation}

\lineiii{C}{\code{CHATMSG msg="text goes here"}}{
A chat message from a client
}

\lineiii{S}{\code{CHATMSG id=username msg="text goes here"}}{
A chat message from the server; the client should display it.
}

\hline
\end{tableiii}


\section{Image-related commands}

\begin{tableiii}{|c|p{2in}|p{3in}|}{code}{Server/Client}{Command}{Explanation}

\lineiii{C}{\code{FRAMES num_frames=\var{n}}}{
Set the maximum number of frames per second to be sent to this client.
If \var{n} is zero, frames will be sent as fast as possible.
}

\lineiii{S}{\code{IMAGE x=\var{x} y=\var{y}}}{
Set the desired image size.  If the server's camera doesn't support
that exact size, then it can either choose the closest size it
supports, automatically scale images to that size, or ignore the directive.
}

\lineiii{C}{\code{EMAIL comments="text" email=foo@example.com}}{
Request a high-resolution image from the server, and e-mail it to the 
user. 
}

%\lineiii{C}{\code{HIRES action=save|email comments="text"}}{
%Request a high-resolution image from the server.  If the \var{action}
%argument is 'save', the file will be saved to the user's file storage
%area.  
%}

\lineiii{C}{\code{RECTANGLE x1=\var{x1} y1=\var{y1} x2=\var{x2} y2=\var{y2}}}{
"I just drew a rectangle!" notice from the client
}

\lineiii{S}{\code{RECTANGLE x1=\var{x1} y1=\var{y1} x2=\var{x2} y2=\var{y2}}}{
        Server bounce of the previous message
}

\lineiii{C}{\code{MEASURE x1=\var{x1} y1=\var{y1} x2=\var{x2} y2=\var{y2}}}{
        "I just measured a distance!" notice from the client
}

\lineiii{S}{\code{MEASURE x1=\var{x1} y1=\var{y1} x2=\var{x2} y2=\var{y2}}}{
        Server bounce of the previous message
}

\hline
\end{tableiii}


\section{Microscope-related commands}

\begin{tableiii}{|c|p{2in}|p{3in}|}{code}{Server/Client}{Command}{Explanation}

\lineiii{C}{\code{AUTOFOCUS}}{
   Enable the autofocus.
}
\lineiii{S}{\code{AUTOFOCUS value=on|off}}{
   Server message telling the clients whether autofocus is enabled or not.
}

\lineiii{C}{\code{MOVE 
        x=\var{x} y=\var{y} angle=\var{a} \newline
        magnification=5 $\mid$ 10 $\mid$ ... $\mid$ 100 \newline
        mode=brightfield $\mid$ darkfield $\mid$ icr \newline
        aperture= 1..6 \newline
        light=0..100 \newline
}}{
        Change the microscope's position and status, and take a new snapshot
of the resulting visible image.
}

\lineiii{S}{\code{MOVE 
x=\var{x} y=\var{y} angle=\var{a} \newline
        magnification=5 $\mid$ 10 $\mid$ ... $\mid$ 100 \newline
        mode=brightfield $\mid$ darkfield $\mid$ icr \newline
        aperture= 1..6 \newline
        light = 0..100 \newline
        x_scale = \var{x_scale} yscale = \var{y_scale}
}}{
Inform clients of the microscope's current position and settings.
x,y, and z are measured in microns.  When autofocus is turned on, z=0;
otherwise it contains the positive or negative displacement away from
the autofocus position.
}

\hline
\end{tableiii}


\end{document}
