Ausarbeitung/implementation.tex

   1 \chapter{Implementation}
   2 \todo{more?}
   3 This chapter describes the implementation that was used for the aforementioned
   4 experiments. It consists of the measuring programs themselves, which use the
   5 Wiselib Roomba Control, and are written in C++. Additionally, there are several
   6 Bash and Perl scripts to help with the analysis of the measured data.
   7
   8 All code used for this thesis resides in the Wiselib source tree\footnote{see
   9 \url{https://github.com/ibr-alg/wiselib/}, or the \acs{CDROM} attached at the
  10 end of this book} in the directory \filepath{apps/pc\_apps/roomba\_tests}.
  11
  12 \section{Measuring}
  13 \label{sec:impl:measuring}
  14
  15 The measuring implementation is a set of programs running on a x86-compatible
  16 Linux system which uses the Wiselib to control a Roomba attached to the system
  17 over a serial interface. It features a graphical user interface using the
  18 Qt application framework. Basically, it carries out a movement with specified
  19 parameters (velocity, and destination or angle, depending on the experiment),
  20 then prompts the user to measure and input the actual destination or angle the
  21 Roomba has moved after it has finished the movement. In this context, the user
  22 can choose between two operation modes. In the manual mode, the user can control
  23 the target values for the Roomba movement himself, in automatic mode, the
  24 application uses a list of pre-programmed values for the target values, so the
  25 user only has to input the measured data.
  26
  27 All measured data is written to a log file in the current directory whose name
  28 is based on the type of experiment performed. Every line in that log file
  29 describes one measurement made by the user, and consists of pairs of the form
  30 \code{key=value}, separated of by whitespace. In particular, the data on each
  31 line are (with key name, in the order of appearance on the line):
  32 \begin{enumerate}
  33   \setlength{\itemsep}{1pt}
  34   \item\texttt{svn:} the \ac{SVN} or Git revision the program was compiled from
  35     (statically compiled into the program)
  36   \item\texttt{roomba\_id:} the ID of the Roomba the measurement was performed
  37     with (given by the user)
  38   \item\texttt{ground\_type:} the ground type used for measurement:
  39     \magicvalue{iz250flur} for laminated floor, \magicvalue{seminarraum}
  40     for carpet floor (given by the user)
  41   \item\texttt{diff\_ticks\_left:} the difference of encoder counts between the
  42     beginning and the end of the movement, on the Roomba's left wheel
  43     (packet~ID \magicvalue{0x2b} in the \ac{ROI} Specification)
  44   \item\texttt{diff\_ticks\_right:} the difference of encoder counts between the
  45     beginning and the end of the movement, on the Roomba's right wheel
  46     (packet~ID \magicvalue{0x2c} in the \ac{ROI} Specification)
  47   \item\texttt{raw\_ticks\_left:} the absolute value of the encoder count of the
  48     Roomba's left wheel (packet~ID \magicvalue{0x2b})
  49   \item\texttt{raw\_ticks\_right:} the absolute value of the encoder count of
  50     the Roomba's right wheel (packet~ID \magicvalue{0x2c})
  51   \item\texttt{batt\_charge:} the charge of the Roomba's battery in mAh
  52     (packet~ID~\magicvalue{0x19})
  53   \item\texttt{batt\_capacity:} the capacity of the Roomba's battery in mAh
  54     (packet~ID~\magicvalue{0x1a})
  55   \item\texttt{batt\_voltage:} the applied voltage of the Roomba's battery in mV
  56     (packet~ID~\magicvalue{0x16})
  57   \item\texttt{batt\_voltage:} the current going out of the Roomba's battery in
  58     mA (packet~ID~\magicvalue{0x17})
  59   \item\texttt{move:} movement type; \magicvalue{straight} for straight moves,
  60     \magicvalue{turn} for turn moves (given by the user while selecting the
  61     experiment type)
  62   \newcounter{logitems}\setcounter{logitems}{\value{enumi}+1}
  63 \end{enumerate}
  64 For straight moves (\magicvalue{move=straight}) follow:
  65 \begin{enumerate}[start=\value{logitems}]
  66   \item\texttt{input\_distance}: the target distance in mm sent to the Roomba
  67     via the \ac{ROI} \cmd{Drive} command (given by the user in manual mode,
  68     or determined by the program in automatic mode)
  69   \item\texttt{velocity:} (the velocity in mm/s sent to the Roomba over the
  70     \ac{ROI} \cmd{Drive} command (given by the user in manual mode, or
  71     determined by the program in automatic mode)
  72   \item\texttt{measured\_x:} the actual covered distance in mm in the Roomba's
  73     original viewing direction (measured by the user)
  74   \item\texttt{measured\_y:} originally, the distance shift perpendicular to the
  75     viewing direction of the Roomba. Not used anymore.
  76   \item\texttt{deviation\_orientation:} originally, the shift in orientation of
  77     the Roomba. Not used anymore.
  78 \end{enumerate}
  79 For turn moves (\magicvalue{move=turn}) follow:
  80 \begin{enumerate}[start=\value{logitems}]
  81   \item\texttt{turn\_angle:} the turn angle in degree sent to the Roomba via the
  82     \ac{ROI} \cmd{Drive} command (given by the user in manual mode, or
  83     determined by the program in automatic mode)
  84   \item\texttt{measured\_angle:} the actual turned angle of the Roomba in degree
  85     (measured by the user)
  86   \item\texttt{velocity:} (the velocity in mm/s sent to the Roomba over the
  87     \ac{ROI} \cmd{Drive} command (given by the user in manual mode, or
  88     determined by the program in automatic mode)
  89 \end{enumerate}
  90
  91 \begin{figure}
  92   \centering
  93   \includegraphics[width=\textwidth]{images/Implementation-Diagram.pdf}
  94   \caption[File structure of the measuring implementation]{Simplified file
  95     structure of the measuring implementation\label{fig:impl:struct}\\
  96     yellow: common files used for all three experiments; green: files for
  97     Experiment~1; blue: files for Experiment~2; red: files for Experiment~3.\\
  98     An arrow from node $x$ to node $y$ means ``$y$ depends from $x$''.}
  99 \end{figure}
 100
 101 Figure~\ref{fig:impl:struct} shows the file layout of the measuring
 102 implementation. It reuses components whereever possible, and therefore
 103 consists of three parts (green, blue, red) specific for the three performed
 104 experiments (see Sections~\ref{sec:exp1}, \ref{sec:exp2} and~\ref{sec:exp3}), as
 105 well as a common part (yellow), which contains the elements of the
 106 implementation shared by the other three parts.
 107
 108 \subsection{Common part}
 109 % no \file{} here please, we don't want "stuff.{cc,h}" in index...
 110 The files \code{stuff.\{cc,h\}} and \code{target\_value\_input\_dialog.\{cc,h\}}
 111 build up the general part of the implementation (shown with a yellow background
 112 in Figure~\ref{fig:impl:struct}). These are included in all other three parts of
 113 the implementation.
 114
 115 \paragraph{\file{stuff.cc} and \file{stuff.h}}
 116 Both of these files contain global helper functions and variables,
 117 implementation-specific data structures and all kinds of convenient typedefs. In
 118 particular, there are functions for formatting and logging messages to a log
 119 file, according to the format described above. While \file{stuff.h} contains the
 120 declarations and typedefs, \file{stuff.cc} contains the appropriate definitions.
 121 Besides, since \file{stuff.h} is included indirectly in most other source files,
 122 it also includes the Wiselib headers needed for Roomba control.
 123
 124 \paragraph{\file{target\_value\_input\_dialog.cc} and
 125 \file{target\_value\_input\_dialog.h}}
 126 These files contain the class \code{TargetValueInputDialog}
 127 \index{TargetValueInputDialog}, an implementation of a dialog box that allows
 128 the user to input a measured angle (although the names mention a ``target
 129 value'', it does that probably only to increase the confusion\ldots). This is a
 130 typical Qt dialog which contains an input box with adjacent spin box for
 131 entering the measured value, OK and Cancel buttons, and also information about
 132 the target orientation and the current real orientation.
 133
 134 When the dialog is displayed, it obtains the orientation as it was before the
 135 last movement, and the target angle, and sets the input box to the specified
 136 target value. When the input box is changed, the dialog calculates the new
 137 orientation from the last orientation and the value in the input box, and
 138 displays this new orientation. This way, the user can simply enter the measured
 139 angle by increasing or decreasing the value by operating the spin box, and
 140 adjusting the value until the displayed orientation reflects the real
 141 orientation of the Roomba.
 142
 143 To achieve this, the class uses the Qt signal-slot
 144 mechanism~\cite{qt-signalslots}, and connects the \code{intValueChanged(int)}
 145 signal of the input box to the method \code{turn\_dialog\_value\_changed(int)},
 146 which performs the calculation and display of the new value.
 147
 148 \subsection{Implementation for Experiment~1}
 149 The implementation for Experiment~1 is used to build the application
 150 \prog{roomba\_test}. Its main part is constituted by the file \file{main.cc},
 151 which uses the global definitions of \file{stuff.h} and the dialog box from
 152
 153 \subsection{Implementation for Experiment~2}
 154 \subsection{Implementation for Experiment~3}
 155
 156 three single applications with same base: roomba\_test (main.cc),
 157 mean\_correction\_test (mean\_correction.cc), soft\_start\_test
 158 (soft\_start.cc).
 159
 160 1) open UART connection
 161
 162 2) register state callback for getting roomba sensor data
 163
 164 3) while(input values or cancel) { drive() / turn() }
 165
 166 4) drive() / turn() use wiselib::ControlledMotion<OsModel,
 167 wiselib::RoombaModel> for moving specified angle/distance; and ask for measured
 168 values and write to log
 169
 170 additionally, mean correction test uses
 171 CorrectedMeanMotion from corrected\_mean\_motion.h, implements same concept like
 172 wiselib::ControlledMotion and takes care of target value by using the
 173 calculated fit function .
 174
 175 additionally, soft start/stop test uses
 176 SoftStartMotion from soft\_start\_motion.h, implements same
 177 concept like wiselib::ControlledMotion and takes care of increasing/decreasing
 178 velocity via timer.
 179
 180 \section{Evaluation}
 181 \label{sec:impl:eval}
 182 \todo{}
 183
 184 bash/perl scripts in wiselib/trunk/pc\_apps/roomba\_tests/logs, using gnuplot
 185
 186 graph.sh: create 3d plots (input value, input velocity, measured value) from
 187 original behvaiour data, including fit function calculated by GNU R statistics
 188 software, for {carpet floor, laminate floor} $\times$ {drive straight, turn on
 189 spot}
 190
 191 graph-mean.sh: do the same for mean correction data, including fit function from
 192 original data
 193
 194 graph-soft.sh: do the same for soft start/stop data, including fit function from
 195 original data
 196
 197 graph-mean-soft.sh: 3d plot with mean correction and soft start/stop data, for
 198 comparison of both
 199
 200 graph-errorlines.sh: create 2d plots input value -> measured value, with
 201 multiple velocities in each graph. also split graphs up for {carpet floor,
 202 laminate floor} $\times$ {drive straight, turn on spot}. no fit function.