\chapter{Implementation}
\todo{more?}
This chapter describes the implementation that was used for the aforementioned
experiments. It consists of the measuring programs themselves, which use the
Wiselib Roomba Control, and are written in C++. Additionally, there are several
Bash and Perl scripts to help with the analysis of the measured data.

All code used for this thesis resides in the Wiselib source tree\footnote{see
\url{https://github.com/ibr-alg/wiselib/}, or the \acs{CDROM} attached at the
end of this book} in the directory \filepath{apps/pc\_apps/roomba\_tests}.

\section{Measuring}
\label{sec:impl:measuring}

The measuring implementation is a set of programs running on a x86-compatible
Linux system which uses the Wiselib to control a Roomba attached to the system
over a serial interface. It features a graphical user interface using the
Qt application framework. Basically, it carries out a movement with specified
parameters (velocity, and destination or angle, depending on the experiment),
then prompts the user to measure and input the actual destination or angle the
Roomba has moved after it has finished the movement. In this context, the user
can choose between two operation modes. In the manual mode, the user can control
the target values for the Roomba movement himself, in automatic mode, the
application uses a list of pre-programmed values for the target values, so the
user only has to input the measured data.

All measured data is written to a log file in the current directory whose name
is based on the type of experiment performed. Every line in that log file
describes one measurement made by the user, and consists of pairs of the form
\code{key=value}, separated of by whitespace. In particular, the data on each
line are (with key name, in the order of appearance on the line):
\begin{enumerate}
  \setlength{\itemsep}{1pt}
  \item\texttt{svn:} the \ac{SVN} or Git revision the program was compiled from
    (statically compiled into the program)
  \item\texttt{roomba\_id:} the ID of the Roomba the measurement was performed
    with (given by the user)
  \item\texttt{ground\_type:} the ground type used for measurement:
    \magicvalue{iz250flur} for laminated floor, \magicvalue{seminarraum}
    for carpet floor (given by the user)
  \item\texttt{diff\_ticks\_left:} the difference of encoder counts between the
    beginning and the end of the movement, on the Roomba's left wheel
    (packet~ID \magicvalue{0x2b} in the \ac{ROI} Specification)
  \item\texttt{diff\_ticks\_right:} the difference of encoder counts between the
    beginning and the end of the movement, on the Roomba's right wheel
    (packet~ID \magicvalue{0x2c} in the \ac{ROI} Specification)
  \item\texttt{raw\_ticks\_left:} the absolute value of the encoder count of the
    Roomba's left wheel (packet~ID \magicvalue{0x2b})
  \item\texttt{raw\_ticks\_right:} the absolute value of the encoder count of
    the Roomba's right wheel (packet~ID \magicvalue{0x2c})
  \item\texttt{batt\_charge:} the charge of the Roomba's battery in mAh
    (packet~ID~\magicvalue{0x19})
  \item\texttt{batt\_capacity:} the capacity of the Roomba's battery in mAh
    (packet~ID~\magicvalue{0x1a})
  \item\texttt{batt\_voltage:} the applied voltage of the Roomba's battery in mV
    (packet~ID~\magicvalue{0x16})
  \item\texttt{batt\_voltage:} the current going out of the Roomba's battery in
    mA (packet~ID~\magicvalue{0x17})
  \item\texttt{move:} movement type; \magicvalue{straight} for straight moves,
    \magicvalue{turn} for turn moves (given by the user while selecting the
    experiment type)
  \newcounter{logitems}\setcounter{logitems}{\value{enumi}+1}
\end{enumerate}
For straight moves (\magicvalue{move=straight}) follow:
\begin{enumerate}[start=\value{logitems}]
  \item\texttt{input\_distance}: the target distance in mm sent to the Roomba
    via the \ac{ROI} \cmd{Drive} command (given by the user in manual mode,
    or determined by the program in automatic mode)
  \item\texttt{velocity:} (the velocity in mm/s sent to the Roomba over the
    \ac{ROI} \cmd{Drive} command (given by the user in manual mode, or
    determined by the program in automatic mode)
  \item\texttt{measured\_x:} the actual covered distance in mm in the Roomba's
    original viewing direction (measured by the user)
  \item\texttt{measured\_y:} originally, the distance shift perpendicular to the
    viewing direction of the Roomba. Not used anymore.
  \item\texttt{deviation\_orientation:} originally, the shift in orientation of
    the Roomba. Not used anymore.
\end{enumerate}
For turn moves (\magicvalue{move=turn}) follow:
\begin{enumerate}[start=\value{logitems}]
  \item\texttt{turn\_angle:} the turn angle in degree sent to the Roomba via the
    \ac{ROI} \cmd{Drive} command (given by the user in manual mode, or
    determined by the program in automatic mode)
  \item\texttt{measured\_angle:} the actual turned angle of the Roomba in degree
    (measured by the user)
  \item\texttt{velocity:} (the velocity in mm/s sent to the Roomba over the
    \ac{ROI} \cmd{Drive} command (given by the user in manual mode, or
    determined by the program in automatic mode)
\end{enumerate}

\begin{figure}
  \centering
  \includegraphics[width=\textwidth]{images/Implementation-Diagram.pdf}
  \caption[File structure of the measuring implementation]{Simplified file
    structure of the measuring implementation\label{fig:impl:struct}\\
    yellow: common files used for all three experiments; green: files for
    Experiment~1; blue: files for Experiment~2; red: files for Experiment~3.\\
    An arrow from node $x$ to node $y$ means ``$y$ depends from $x$''.}
\end{figure}

Figure~\ref{fig:impl:struct} shows the file layout of the measuring
implementation. It reuses components whereever possible, and therefore
consists of three parts (green, blue, red) specific for the three performed
experiments (see Sections~\ref{sec:exp1}, \ref{sec:exp2} and~\ref{sec:exp3}), as
well as a common part (yellow), which contains the elements of the
implementation shared by the other three parts.

\subsection{Common part}
% no \file{} here please, we don't want "stuff.{cc,h}" in index...
The files \code{stuff.\{cc,h\}} and \code{target\_value\_input\_dialog.\{cc,h\}}
build up the general part of the implementation (shown with a yellow background
in Figure~\ref{fig:impl:struct}). These are included in all other three parts of
the implementation.

\paragraph{\file{stuff.cc} and \file{stuff.h}}
Both of these files contain global helper functions and variables,
implementation-specific data structures and all kinds of convenient typedefs. In
particular, there are functions for formatting and logging messages to a log
file, according to the format described above. While \file{stuff.h} contains the
declarations and typedefs, \file{stuff.cc} contains the appropriate definitions.
Besides, since \file{stuff.h} is included indirectly in most other source files,
it also includes the Wiselib headers needed for Roomba control.

\paragraph{\file{target\_value\_input\_dialog.cc} and
\file{target\_value\_input\_dialog.h}}
These files contain the class \code{TargetValueInputDialog}
\index{TargetValueInputDialog}, an implementation of a dialog box that allows
the user to input a measured angle (although the names mention a ``target
value'', it does that probably only to increase the confusion\ldots). This is a
typical Qt dialog which contains an input box with adjacent spin box for
entering the measured value, OK and Cancel buttons, and also information about
the target orientation and the current real orientation.

When the dialog is displayed, it obtains the orientation as it was before the
last movement, and the target angle, and sets the input box to the specified
target value. When the input box is changed, the dialog calculates the new
orientation from the last orientation and the value in the input box, and
displays this new orientation. This way, the user can simply enter the measured
angle by increasing or decreasing the value by operating the spin box, and
adjusting the value until the displayed orientation reflects the real
orientation of the Roomba.

To achieve this, the class uses the Qt signal-slot
mechanism~\cite{qt-signalslots}, and connects the \code{intValueChanged(int)}
signal of the input box to the method \code{turn\_dialog\_value\_changed(int)},
which performs the calculation and display of the new value.

\subsection{Implementation for Experiment~1}
The implementation for Experiment~1 is used to build the application
\prog{roomba\_test}. Its main part is constituted by the file \file{main.cc},
which uses the global definitions of \file{stuff.h} and the dialog box from

\subsection{Implementation for Experiment~2}
\subsection{Implementation for Experiment~3}

three single applications with same base: roomba\_test (main.cc),
mean\_correction\_test (mean\_correction.cc), soft\_start\_test
(soft\_start.cc).

1) open UART connection

2) register state callback for getting roomba sensor data

3) while(input values or cancel) { drive() / turn() }

4) drive() / turn() use wiselib::ControlledMotion<OsModel,
wiselib::RoombaModel> for moving specified angle/distance; and ask for measured
values and write to log

additionally, mean correction test uses
CorrectedMeanMotion from corrected\_mean\_motion.h, implements same concept like
wiselib::ControlledMotion and takes care of target value by using the
calculated fit function .

additionally, soft start/stop test uses
SoftStartMotion from soft\_start\_motion.h, implements same
concept like wiselib::ControlledMotion and takes care of increasing/decreasing
velocity via timer.

\section{Evaluation}
\label{sec:impl:eval}
\todo{}

bash/perl scripts in wiselib/trunk/pc\_apps/roomba\_tests/logs, using gnuplot

graph.sh: create 3d plots (input value, input velocity, measured value) from
original behvaiour data, including fit function calculated by GNU R statistics
software, for {carpet floor, laminate floor} $\times$ {drive straight, turn on
spot}

graph-mean.sh: do the same for mean correction data, including fit function from
original data

graph-soft.sh: do the same for soft start/stop data, including fit function from
original data

graph-mean-soft.sh: 3d plot with mean correction and soft start/stop data, for
comparison of both

graph-errorlines.sh: create 2d plots input value -> measured value, with
multiple velocities in each graph. also split graphs up for {carpet floor,
laminate floor} $\times$ {drive straight, turn on spot}. no fit function.
