Index: firmware/InterlockArduino/src/fact++interface/fact++interface.tex
===================================================================
--- firmware/InterlockArduino/src/fact++interface/fact++interface.tex	(revision 14247)
+++ firmware/InterlockArduino/src/fact++interface/fact++interface.tex	(revision 14247)
@@ -0,0 +1,633 @@
+\documentclass{article}
+\usepackage{listings}
+\usepackage{color}
+
+ 
+\definecolor{dkgreen}{rgb}{0,0.6,0}
+\definecolor{gray}{rgb}{0.5,0.5,0.5}
+\definecolor{mauve}{rgb}{0.58,0,0.82}
+ 
+\lstset{ %
+  language=C++,                % the language of the code
+  basicstyle=\footnotesize,           % the size of the fonts that are used for the code
+  numbers=left,                   % where to put the line-numbers
+  numberstyle=\tiny\color{gray},  % the style that is used for the line-numbers
+  stepnumber=2,                   % the step between two line-numbers. If it's 1, each line 
+                                  % will be numbered
+  numbersep=5pt,                  % how far the line-numbers are from the code
+  backgroundcolor=\color{white},      % choose the background color. You must add \usepackage{color}
+  showspaces=false,               % show spaces adding particular underscores
+  showstringspaces=false,         % underline spaces within strings
+  showtabs=false,                 % show tabs within strings adding particular underscores
+  frame=single,                   % adds a frame around the code
+  rulecolor=\color{black},        % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. commens (green here))
+  tabsize=2,                      % sets default tabsize to 2 spaces
+  captionpos=b,                   % sets the caption-position to bottom
+  breaklines=true,                % sets automatic line breaking
+  breakatwhitespace=false,        % sets if automatic breaks should only happen at whitespace
+  title=\lstname,                   % show the filename of files included with \lstinputlisting;
+                                  % also try caption instead of title
+  keywordstyle=\color{blue},          % keyword style
+  commentstyle=\color{dkgreen},       % comment style
+  stringstyle=\color{mauve},         % string literal style
+  escapeinside={\%*}{*)},            % if you want to add a comment within your code
+  morekeywords={*,...}               % if you want to add more keywords to the set
+}
+
+\begin{document}
+\title{FACT Arduino ethernet communication Interface }
+\author{D.Neise}
+\maketitle
+\tableofcontents
+\newpage
+
+\section{Introduction}
+Arduino is the name of a series of open source 
+microcontroller equipped boards. The 
+microcontroller in use is out of Atmels ATmega family.
+The FACT telescope uses mostly the Arduino Ethernet board to 
+monitor and control certain auxiliary systems like the motors of the camera 
+shutter. 
+This board was chosen since the needed hardware for ethernet access, 
+like a dedicated ethernet controller (Wiznet W5100) and the jack, are already 
+in place. In addition the programming of the board as comparably easy.
+Setting up a TCP/IP server (using either a fix IP or a DHCP server) as well as 
+raw byte-stream communication with clients is handled by the Ethernet library,
+which comes with the Arduino IDE.
+There is a variety of open source extension boards available for the Arduino,
+both from the Arduino group as well as from unrelated developers. These
+extension boards are usually called shields.
+The shields can be connected to the ATmega port pins via 100mil headers,
+which can be used to quickly connect custom peripherals as well.
+Typical ATmega digital outputs can drive up to 10mA at 5.0V and thus allow for 
+quick connection of LEDs for software tests or similar quick hacks.
+There exists an open source C cross compiler for ATmega MCUs as well a std-lib 
+implementation. The Arduino group created not only a user friendly 
+(maybe not power user friendly) IDE but also supplies the beginner with a 
+bunch of useful libraries from serial communication to LCD interfacing. 
+
+\newpage
+\subsection{std C vs. Arduinos C++ dialect}
+The Arduino IDE provides the beginner with a simple programming enviroment.
+While a standard microcontroller program usually is composed of an init section
+and a never ending while loop which contains the actual job of the microcontroller,
+e.g. like this:
+\begin{lstlisting}
+void main (void){
+
+    // set up peripherals and I/O pins
+    // e.g:
+    DDRD |= 1<<PD6;  // define pin PD6 to be an output
+    
+    // here the actual 'job' is performed
+    while(1){
+        // toggle the output
+        PORTD ^= 1<<PD6;
+    }
+}
+\end{lstlisting}
+
+This would look like this in the Arduino C++ dialect:
+\begin{lstlisting}
+// On the Arduino board there are numbers printed 
+// next to the 100mil header sockets.
+// The ATmega pin PD6 is named '6' on the Arduino board.
+const int my_output_pin = 6;
+boolean output_pin_state = false;
+
+setup(){
+    pinMode( my_output_pin , OUTPUT);
+}
+
+loop(){
+    // toggle the variable...
+    output_pin_state = !output_pin_state;
+    // write the value of the variable, to the pin
+    digitalWrite( my_output_pin , output_pin_state);
+}
+\end{lstlisting}
+
+In many cases, the code written in the Arduino-C++ dialect does not 
+produce the optimal binary, but one can always fall back to standard C
+or even inline assembler, if needed.
+
+\subsection{ scheduling on microcontrollers }
+There is nothing like a scheduler running on a microcontroller, so one can not
+produce concurrent running code by using threads. The developer needs 
+in such a case to implement a form of time sharing himself.
+(Although there might be libraries easing the pain a little.)
+
+%Assume the following task:
+%The ATmegas internal ADC should be used to measure a voltage as soon
+%as an attached button is pressed. Since we expect some noise, the ADC should
+%sample the voltage 100 times and return the mean and the std deviation.
+%Since the user is expected to be slow, when pressing a button, 50 of the samples 
+%shoule be taken, before the user pressed the button.
+%We assume the CPU frequency is 16MHz. And the serial communication to run at
+%9600 baud. 
+%The ADC needs about 130us for a conversion. 
+
+\subsubsection{simple time sharing}
+
+The most prominent solution maybe looks like this
+\begin{lstlisting}
+loop(){
+    check_if_a_button_was_pressed();        // < 1us
+    check_if_the_ADC_has_a_valid_reading(); // < 1us
+    calculate_something();                  // approx 1ms
+    communicate(); //9600 baud              // 1ms per byte 
+}
+\end{lstlisting}
+Each of these functions \emph{might} run for a well know and limited amount
+of time.
+This is important in case one wants to ensure, the user experience is immediate.
+As an example, one might assume the button, which is checked in the first function, is a kind of emergency
+shutdown button. In this case, one has to ensure, that the communicate function
+will never block and thus inhibit the checking of the button and so inhibit 
+the emergency shutdown. 
+
+
+\subsubsection{Interrupts}
+Another solution is the use of hardware interrupts. The ATmega comes 
+with quite a lot of interrupt routines, such as:
+\begin{itemize}
+\item ADC ready
+\item timer overflow \\there are typically 3 timers
+\item timer reached certain value \\typically 2 values per timer
+\item special interrupt pin state changed \\good for emergency buttons
+\item serial transfer complete (USART) \\i.e. the Arduino USB connection
+\item SPI transfer complete \\the W5100 is connected via SPI
+\end{itemize}
+
+Each of these interrupt sources can stop the running program and let the controller
+jump to a special, often very tiny, so called interrupt service routine.
+In case the developer connected the emergency button to one of the dedicated 
+interrupt pins, the program might look like this:
+\newpage
+\begin{lstlisting}
+// global variables for data transfer 
+// between interrupt service routines
+// and 'normal' user code
+volatile boolean got_enough_adc_readings = false;
+char adc_buffer[ADC_BUFFER_SIZE];
+char adc_value_counter = 0;
+
+setup(){
+    enable_external_pin_irq();
+    enable_adc_irq();
+}
+
+loop(){
+    // this might take about 1ms
+    if (got_enough_adc_readings == true){
+        calculate_something();
+        enable_adc_irq();
+    }
+    // this might take several 10ms, since 9600 baud is so slow.
+    communicate(); //9600 baud serial communication
+}
+
+// this should take less than 16 cycles = 1us 
+adc_interrupt_service_routine(){
+    short reading = ADC_REGISTER;
+    adc_buffer[adc_value_counter] = reading;
+    adc_value_counter++;
+    if (adc_value_counter == ADC_BUFFER_SIZE){
+        got_enough_adc_readings = true;
+        disable_adc_irq();
+    }
+}
+// this should also take hardly any time ... 
+external_pin_toggle_service_routine(){
+    do_emergency_stuff();
+}
+\end{lstlisting}
+
+Writing the code in this manner does ensure, that even in case of very 
+long communication of several hundred bytes, the emergency button press is immediately
+reacted on. In addition, the ADC samples are aquired faster than in the previous
+solution, since the ADC is read when ever it finished a conversion (about every 100us)
+and not after each communication.
+
+This solution is not very complicated, however the use of interrupts is connected
+to some caveats, which are connected to non atomic access of 2-byte variables,
+and compiler optimizations.
+
+In addition this solution is clearly to be used, in case a developer needs to ensure
+a certain action is performed with a fixed rate, like monitoring the status 
+of a certain peripheral. This can be easily acomplished using one of the hardware 
+timer overflow interrupts.
+
+\section{Reliability}
+Having the previous considerations in mind, one should also not forget, 
+that a remote device might not even have an emergency button, since the 
+ethernet connection is the only way for the user to interact with the deivce.
+In such a case, the ethernet communication should be realiable and quick.
+
+Consider the flodding case:\\
+Flodding might be caused by impatient users or buggy client software.
+In such a case, the requests might come in faster, than they can be reacted on,
+so the ethernet input buffer starts to fill up.
+
+In such a case, the device should at least, realize that the client is flodding 
+and in addition to the normal command execution answer, send a warning, that 
+the input buffer is e.g. 50\% filled.
+
+The client software should at least understand such a warning and stop sending
+requests for a while.
+
+\section{Protocol}
+In order to be quick and reliable, the protocol should be fairly easy.
+Thus I recommend a fixed size binary, with unequal message sizes 
+for client to server requests and server to client messages.
+
+\subsection{client to server}
+While the client to server communication is merely used 
+to send commands and settings,
+the messages can be rather short. For example
+
+\begin{tabular}{|l|l|l|}
+\hline
+desc. & content & size \\
+\hline
+header      & 0xF1              & 1 char\\
+address     &                   & 1 char\\
+access type & \verb=SET|NAND|OR|XOR|READ=   & 1 char\\
+data        &                   & 1 char\\
+footer      & 0xB4              & 1 char\\
+\hline
+\end{tabular}
+
+All commands and other requests are handled via access to some (virtual) registers.
+Which are further pointed out in chapter \ref{sec_registers}. The registers space
+is devided into com-registers, which are used to control the communication interface
+itself, like activating automatic messaging or request certain register content,
+and user-registers.
+The address space looks like this
+
+\begin{tabular}{|l|l|}
+\hline
+0x00 & CSTR \\ \hline
+0x01 & CTDR \\ \hline
+0x02 & URNR \\ \hline
+0x03 & URCR \\ \hline
+0x04 & URER \\ \hline
+0x05 & CMDR \\ \hline
+0x06 & CSTR \\ \hline
+0x07 & start of user register address space \\ 
+ ... & ... \\
+0xFF & end of user register address space \\ \hline 
+\end{tabular}\\
+
+The access type may be used by the client to make sure not to accidentally
+alter registers content, which was not itendet to be changed. \\
+
+\textbf{examples:}
+
+\begin{tabular}{ll}
+\verb= 0xF1 0x06 OR   0x02 0xB4=      & set only bit 2 in CSTR register \\
+\verb= 0xF1 0x01 NAND 0x40 0xB4 =   & clear only bit 7 in CTDR register \\
+\verb= 0xF1 0x0A XOR  0xC0 0xB4 =    & toggle only bit 3 and 4 in a user register \\
+\verb= 0xF1 0x00 SET  0x00 0xB4 =    & set the entire CSTR register to zeros \\
+\verb= 0xF1 0x02 READ 0x12 0xB4 =   & read the URNR register \\
+\end{tabular}\\
+
+To encode the different register access types I propose:
+
+\begin{tabular}{|l|l|}
+\hline
+SET  & 0x00 \\ \hline
+NAND & 0x01 \\ \hline
+OR   & 0x02 \\ \hline
+XOR  & 0x03 \\ \hline
+READ & 0x05 \\ \hline
+n/a  & the rest \\ \hline
+\end{tabular}
+
+In case unknown codes are submitted for the access type, the request is discarded.
+the data field, for a READ access is discarded. 
+Each of the register access requests, triggers an answer, as long as the 
+request response (RR) bit in CPMR is set. 
+
+\subsection{server to client}
+Server to client communication on the other hand is meant to be rather informative.
+The client is not only interested whether the last command which was sent, was received
+and successfully executed, but also whether any other system status might have changed
+unforseen.
+Thus the client might be interested in:
+\begin{itemize}
+\item service messages, i.e. messages, which are sent in regular intervals
+\item process messages, i.e. messages, which are sent upon certain events like:
+    \begin{itemize}
+    \item request reception
+    \item successfull command execution
+    \item error occurenaces(?)
+    \end{itemize}
+\end{itemize}
+
+And in addition for the sake of speed, one might consider to define different sizes
+for different messages. While process messages might be rather short, service messages 
+might be the entire register content, at least in case one wants to debug something.
+
+\subsubsection{request response}
+    The request response is a special form of a process message. 
+    Process message in this context mean, any message send from the server
+    to the client, because something happened.
+    The request response is send back to the client automatically in order
+    to inform it about the reception of the request. The mere request response
+    does not mean, that the associated user command (in case there was one) execution
+    started.
+    
+    The request response protocol might look like this.
+    
+    \begin{tabular}{|l|l|l|}
+    \hline
+    start byte & content & size (byte)\\ \hline
+    0x00 & general header & 1 \\ \hline
+    0x01 & special request response header & 1 \\ \hline
+    0x02 & request counter & 2 byte\\ \hline 
+    0x04 & real time in ms& 4 byte \\ \hline
+    0x08 & address & 1 byte \\ \hline
+    0x09 & data & 1 byte \\ \hline
+    0x0A & crc(?) & 1 byte \\ \hline
+    0x0B & footer & 1 byte \\ \hline
+    \end{tabular}
+    
+    I am not sure what kind of crc I would like to implement or if I should
+    implement one at all, but the experience with the FSC shows ... I should.
+    
+\subsubsection{ process message protocol}
+    A process message can be send, because something happened. 
+    I guess in the most cases, the message is send, because the user code started
+    executing a user command, or the user code finished executing a user command.
+    Or in more technical terms,
+    a process message is sent, in case either the user command register (UCR) or the 
+    user execution registers(UER) are altered by the user code.
+    In addition a process message is send, in case the FACT++Interface detected an error.
+    
+    So for these process message I propose this protocol
+    
+    \begin{tabular}{|l|l|l|}
+    \hline
+    start byte & content & size (byte)\\ \hline
+    0x00 & general header & 1 \\ \hline
+    0x01 & special process message header & 1 \\ \hline
+    0x02 & real time in ms & 4 byte \\ \hline
+    0x06 & address & 1 byte \\ \hline
+    0x07 & data & 1 byte \\ \hline
+    0x08 & crc(?) & 1 byte \\ \hline
+    0x09 & footer & 1 byte \\ \hline
+    \end{tabular}
+    
+    The address points to the register, which was altered an so caused 
+    the sending of this message.
+    The data contains the data of that particular register.
+    I guess counting these messages makes no sense.
+    
+    
+\subsubsection{service message protocol}
+
+    The term service message referes to a form of message that is send in
+    regular time intervals (as regular as possible). These messages are send in 
+    order to inform the client about the system status. 
+    In addition by monitoring the system status carefully one might be 
+    able to track down bugs in the program.
+    So it seems feasible to sent down the entire register content.
+    
+    The protocol I propose is this
+    \begin{tabular}{|l|l|l|}
+    \hline
+    start byte & content & size (byte)\\ \hline
+    0x00 & general header & 1 \\ \hline
+    0x01 & special service message header & 1 \\ \hline
+    0x02 & real time in ms & 4 byte \\ \hline
+    0x07 & com registers & 7 byte \\ \hline
+    0x0E & user registers & URNR byte \\ \hline
+    0x08 & crc(?) & 1 byte \\ \hline
+    0x09 & footer & 1 byte \\ \hline
+    \end{tabular}
+    
+    The length depends on the user code.
+
+
+\section{Registers}
+\label{sec_registers}
+
+The registers are implemented as \\
+\verb=char register[NUMBER_OF_REGISTERS]=.
+There are two types of registers. The com-registers are members of the 
+Interface described in this document and the user-registers are entirely 
+in the hand of the user code. The interface just gets a pointer to the beginning
+of the user-register space and its size. In addidtion the interface is informed
+which of the user-registers are write-only, read-only and read-write registers.
+I currently do not support 2byte registers, because in case the client wants 
+to read a 2byte register, the interface would need to make a copy first,
+to ensure integrity at least to some extend.
+
+\subsection{Com Registers}
+The following com-registers exists
+
+\begin{tabular}{|l|l|l|}
+\hline
+CSTR & R & com status register \\ \hline
+CTDR & R & com time delay register \\ \hline
+CSMR & W & com service message register \\ \hline
+CPMR & R & com process message register \\ \hline
+URNR & R & user register number register \\ \hline
+URCR & R & address of user command register \\ \hline
+URER & R & address of user execution register \\ \hline
+
+\end{tabular}
+
+
+
+\subsubsection{CSTR - com status register(R)}
+    The com status register contains information about the status of the 
+    communication interface
+
+    \begin{tabular}{|c|c|c|c|c|c|c|c|}
+    \hline
+    7 & 6 & 5 & 4 & 3 & 2 & 1 & 0 \\ \hline
+    \multicolumn{3}{|c|}{NWR} & unused & unused & unused& unused& unused \\ \hline
+    \end{tabular}
+    
+\subsubsection{CTDR - com time delay register(R)}
+    The com time delay register can be used, to find out, how much 
+    time went by between two consecutive calls of FACT++Interface::com().
+    This might help debugging user code.
+
+    \begin{tabular}{|c|c|c|c|c|c|c|c|}
+    \hline
+    7 & 6 & 5 & 4 & 3 & 2 & 1 & 0 \\ \hline
+    \multicolumn{8}{|c|}{TIME} \\ \hline
+    \end{tabular}
+
+    TIME is in units of 5ms.
+
+\subsubsection{CSMR - com servive message register(RW)}
+    The com servive message register controls the behaviour of the interface 
+    regarding service messages
+
+    \begin{tabular}{|c|c|c|c|c|c|c|c|}
+    \hline
+    7 & 6 & 5 & 4 & 3 & 2 & 1 & 0 \\ \hline
+    SME & \multicolumn{7}{|c|}{SM\_INT} \\ \hline
+    \end{tabular}
+\\
+details
+
+    \begin{tabular}{|l|l|l|}
+    \hline
+    abbr & description & default value \\ \hline
+    SME & service message enable & 1 \\ \hline
+    SM\_INT & service message interval (unit 0.1 seconds) & 50 \\ \hline
+    \end{tabular}
+
+\subsubsection{CPMR - com process message register(RW)}
+ 
+    The com process message register controls the behaviour regarding 
+    process messages
+
+    \begin{tabular}{|c|c|c|c|c|c|c|c|}
+    \hline
+    7 & 6 & 5 & 4 & 3 & 2 & 1 & 0 \\ \hline
+    PME & CRME & CEME & RRME & unused&unused&unused&unused \\ \hline
+    \end{tabular}
+\\
+details
+
+    \begin{tabular}{|l|l|l|}
+    \hline
+    abbr & description & default value \\ \hline
+    PME & process message enable & 1 \\ \hline
+    CRME & command received message enable & 1 \\ \hline
+    CEME & command executed message enable & 1 \\ \hline
+    RRME & request response message enable & 1 \\ \hline
+    \end{tabular}
+
+\subsubsection{URNR - user register number register(R)}
+    The user-register number register stores the number of user registers
+    
+    \begin{tabular}{|c|c|c|c|c|c|c|c|}
+    \hline
+    7 & 6 & 5 & 4 & 3 & 2 & 1 & 0 \\ \hline
+    \multicolumn{8}{|c|}{number of user registers} \\ \hline
+    \end{tabular}
+
+\subsubsection{URCR - user command register address(R)}
+    The user-register number register stores the address of the user command register
+    
+    \begin{tabular}{|c|c|c|c|c|c|c|c|}
+    \hline
+    7 & 6 & 5 & 4 & 3 & 2 & 1 & 0 \\ \hline
+    \multicolumn{8}{|c|}{address} \\ \hline
+    \end{tabular}
+
+\subsubsection{URER - user-execute register address(R)}
+    The user-register number register stores the address of the user execute register
+    
+    \begin{tabular}{|c|c|c|c|c|c|c|c|}
+    \hline
+    7 & 6 & 5 & 4 & 3 & 2 & 1 & 0 \\ \hline
+    \multicolumn{8}{|c|}{address} \\ \hline
+    \end{tabular}
+
+
+
+
+\subsection{User Registers}
+The user registers are implemented outside of the scope of the FACT++Interface
+class. When constructed, the class gets a pointer to the beginning and the number
+of user registers.
+
+The User may define special user registers. The \emph{User Command Register} and
+the \emph{User Execution Register}.
+
+\subsubsection{User Command Register - UCR}
+Every User Register can be used to inform the user code, about a request 
+by the client. Since the FACT++Interface cannot know, when and if the User code 
+starts to react on that command, in cannot inform the client about it.
+
+The special User Command register(UCR) ist monitored by the FACT++interface.
+Assume the client requested to set a bit in the UCR. 
+Then the FACT++Interface sets this bit and makes an internal copy of the UCR.
+In each call of FACT++Interface::com() is checked, if the user code changed the UCR.
+In case the bit is cleared the FACT++Interface can inform the client, about the 
+starting execution of the requested command.
+
+\subsubsection{User Execute Register- UER}
+The User Execute Register(EUR) is used to inform the FACT++Interface about the 
+execution of a command. In this case the client gets a meesage about this,
+and the FACT++Interface cleares the bit, in order to inform the user code 
+and get a clean interface again.
+
+
+\section{Usage}
+
+Here I will give an example, which methods should be called when.
+It will look a little bit like this:
+\newpage
+\begin{lstlisting}
+#define NUMBER_OF_REGS 7
+
+byte mac[] = { 0xFA, 0xC7, 0xFC, 0xB1, 0x00, 0x01 };
+EthernetServer server(80);
+
+// this set of registers provides the interface 
+// between the FACT++interface class
+// and the user code.
+volatile char register[NUMBER_OF_REGISTERS];
+
+// set up the interface
+FACT++Interface interface(server, register, NUMBER_OF_REGS);
+// enable the sending of service messages
+interface.service_msg(true); 
+// set the delay between service messages to 100, i.e. 10sec
+interface.set_service_msg_delay(100);
+
+// inform the interface, that reg[6] & reg[7] serve as 
+// command interface between user code and FACT++Interface class
+interface.set_command_register(6,7);
+
+setup(){
+    Ethernet.begin(mac);
+    server.begin();
+    interface.begin();
+}
+
+loop(){
+    // here the ethernet communication takes place
+    // the method is ensured to take <100ms ... or so.
+    interface.com();
+}
+
+// ensured to run every 10ms
+timer_overflow_ISR(){
+
+    // the user code checks certain registers
+    // to find out, if the client send a command
+    if(register[6]&(1<<4)){
+        register[6] &= ~(1<<4); // clear the command bit
+        // other registers can be used, to return values to the client.
+        register[2] = do_someting();
+        register[7] |= 1<<4; // set the execution bit
+    }
+
+    if( !motors_ok() ){
+            stop_motors();
+            register[3] |= 1<<5;
+        }
+    }
+\end{lstlisting}
+
+\section{Implementation}
+
+Here I will explain a little more about certain details of the 
+implementation, in case I feel this is needed.
+
+Definitely I will say how the files are named, and how to get them...
+
+
+%\section{Summary}
+
+\end{document}