epic2_doc.tex.svn-base

这是一个用来控制机器人ePuck的matlab GUI.通过它

\hline
floor & Floor sensors & get, activate, deactivate, updateDef\\
\hline
speed & Motor Speeds & get, activate, deactivate, updateDef\\
\hline
pos & Encoders & get, activate, deactivate, updateDef\\
\hline
odom & Odometry Position & get, activate, deactivate, updateDef\\
\hline
external & LIS External Sensor Turret & get, activate, deactivate, updateDef\\
\hline
image & Camera Image & get, activate, deactivate, updateDef\\
\hline
custom & Custom Command & get, activate, deactivate, updateDef\\
\hline
connectionState & Connection Status & get\\
\hline
\end{longtable}

\paragraph{Update image}
The \emph{update} function cannot get an image from the camera of the e-puck. This is due to the long time needed to transfer the image from the robot to the computer and also to the specific processing done on it. To request an image, the command \emph{[epic, mode, sizexy]=updateImage(epic);} must be called. The returned values mode and sizexy are respectively the color mode of the camera and the size of the image. Once done, use the command \emph{[image,up]=get(epic,'image');} to retrieve the stored image from the class.

\paragraph{Update odometry}
ePic2 can compute the odometry of the robot. For that purpose, the function \emph{[epic]=updateOdometry(epic);}. As before, the function\emph{[pos,up]=get(epic,'odom');} returns the position of the robot. The function \emph{epic=reset(epic,'odom');} will reset the internal variables of the odometry. The command \emph{set} can also modify those variables. More details concerning its use have been given above.

\paragraph{Custom commands}
ePic2 supports the use of custom commands. A custom command is a vector containing Sercom instructions that will be sent to the e-puck during the next update. They will be executed at the end of the regular commands. The results can be retrieved with \emph{get(epic,'custom')}. Those will be raw data in a 8 bits format. It can be necessary to convert them to Matlab's format. Many examples of this can be found in the source code of the \emph{update} function and a function \emph{two\_complement} receiving two 8 bits values and returning their equivalent in 16 bits is provided with ePic2.

\subsubsection{Controlling e-puck - set}
\par The command \emph{epic=set(epic,varargin);} modifies some properties of the e-puck. \emph{varargin} is a set of parameters beginning with the name of the property to modify followed by a vector containing the new values. For instance, to set the speed of the two motors, the command \emph{epic=set(epic,'speed',[100 100]);} must be called. The following table details the supported properties and their arguments.
\setlongtables
\begin{longtable}{|l|l|p{6.5cm}|}
\hline
\textbf{propName} & \textbf{Arguments} & \textbf{Description}\\
\hline \hline
speed & [right\_motor left\_motor] & Change the motor speeds\\
\hline
ledOn & [led\_number] & Light on the led number led\_number\\
\hline
ledOff & [led\_number] & Light off the led number led\_number\\
\hline
odom & [x y theta] & Set the current position used by the odometry\\
\hline
camMode & [mode] & Set the camera mode (0: grayscale, 1:color)\\
\hline
camSize & [width height] & Set the width and the height of the camera\\
\hline
camZoom & [zoom] & Set the zoom factor (1, 4 or 8)\\
\hline
external & [options] & Select the external sensor and set its options\\
\hline
ledIR & [leds] & Set the leds to light on or off for the 5 leds external sensor\\
\hline
custom & [commands, bytes to receive] & Set a custom command to be executed by the e-puck\\
\hline
\end{longtable}



\subsection{The Filters}
It is sometimes interesting to apply some processing on the readings of a sensor. For instance, the calibration of the proximity sensors is necessary to use them. To allow this in a transparent way, some empty filters have already been created. The functions \emph{filter\_Accel, filter\_Light, filter\_Micro, filter\_Floor, filter\_Prox} and \emph{filter\_image2} are called every time a reading is done on respectively the accelerometer, the light sensors, the microphones, the proximity sensors and the camera. They receive as argument the data and return the filtered values of those. When no filter is implemented, the returned values are the same as the read values. In case of the need for a filter, those functions can be rewritten according to the user needs.

\section{The Graphical Interface}
The graphical interface has been developed to display the status of the e-puck in real-time. Its programming relies on the above mentioned commands but add some functionalities. The interface is refreshed on a regular interval and can show the values of the sensors in real time, it allows to command the movements of the robots using a joystick-like interface, it displays the camera snapshots before and after filtering and also plot the path of the robot using odometry. All those can be seen in figure \ref{fig:epic}.
\par The interface possesses a menu where sensor readings can be activated or deactivated.

\begin{figure}[htb]
	\centering
		\includegraphics[width=1\textwidth]{ePic2.pdf}
	\caption{The ePic2.1 Graphical Interface\label{fig:epic}}
\end{figure}

\subsection{The Controller}
One feature of the GUI is the implementation of a controller function to command the e-puck. This function is located in the file \emph{controller.m} and is initially empty. Once activated, it can be programmed to add a behavior to the e-puck.
\par The controller acts as a Matlab script. As such, all the above functions can be used to command the e-puck. The command \emph{update} does not need to be called as it is done automatically by the interface. It is nevertheless necessary to activate the sensors you need for your controller before executing it.
\par The controller is a finite state machine. It begins in state 1 and executes its initialization. Then it moves to state 2 or more to execute the body of the code. When stopped, it goes to state -1 where it executes the final part of the code before going to state -2. If the controller crashes for no precise reason, the interface detects it and stops its execution.

\subsection{Sensor Captures}
The interface always saves the values of the currently selected sensor. A box allows to choose how many samples have to be kept. For instance, if 1 is selected, the last value will always be kept in memory. When you want to transfer the saved values to Matlab, press the button \emph{Save} and the last readings will be transfered to Matlab's workspace. In some cases, this button will be disabled and colored in red. It means that the minimum amount of samples requested has not been attained yet. When it will be so, the button will turn green. It is possible to save an undefined number of samples by choosing \emph{Unlimited} as Save buffer size.
\par The Reset button will empty the Save buffer. 

\subsection{Driving the Robot}
To drive the robot, you have two choices using the interface. You can either set a speed for each motor in the area \emph{Speed} and press the button \emph{Set Speed} or you can use the visual joystick underneath. The white zone of the joystick allows you to set the motor speeds using a more intuitive way. For instance, if you click the top middle of the white zone, the e-puck will run at maximum speed in straight direction. If you press a bit on the right, it will start to turn right. If you press below the button \emph{Stop} it will run backward. The \emph{Stop} button is used to stop the robot. 

\subsection{The Camera}
The camera area is composed of two displays. The first is the current view coming from the robot while the one on the right is the same view after filtering. The camera works in two modes: color or gray scale. The height and the width can be chosen but it should be carefully considered as the e-puck is quite limited in memory. The value 40x40 is an adequate value. The zoom factor describes a zoom out from the center of the image. By choosing 1, the image will be very neat but very focused while 8 gives a wider view with a reduced quality. The number that can be chosen are 1, 2, 4 and 8. After any modification of those values, the button \emph{Set param.} must be pressed to send them to the e-puck. When the button \emph{Capture} is pressed, a new snapshot is taken.

\section{Known issues}
The initial connection can take quite a long time sometimes. This is due to the Windows driver of some computers. Don't despair and wait. It will connect finally. When closing the connection, it is possible that Matlab crashes and has to be killed. This is also due to the Windows driver and occur only on some machines.

\section{Credits}
ePic2 was developed at the Laboratory of Intelligent Systems located in the Ecole Polytechnique F\'ed\'erale de Lausanne in Switzerland by Yannick Weibel and Julien Hubert.

\end{document}