source: firmware/InterlockArduino/src/fact++interface/fact++interface.tex@ 18066

\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}