epic2_doc.tex.svn-base

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

\documentclass[11pt,oneside,english,a4paper]{article}

\usepackage{a4wide}
\usepackage[T1]{fontenc}
\usepackage{amsmath}
\usepackage{pxfonts}
\usepackage[latin1]{inputenc}
\usepackage{longtable}
\usepackage[pdftex]{hyperref}
\hypersetup{colorlinks=true,urlcolor=blue}

%\usepackage{textcomp}   % Give the degree symbol using \textcelsius
%\usepackage{epsfig}



%\usepackage{natbib}
%\usepackage{verbatim}
\usepackage[pdftex]{color,graphicx}

\setcounter{secnumdepth}{10}

\pagestyle{headings}

\setlength{\baselineskip}{2.0\baselineskip}
\renewcommand{\thesection}{\arabic{section}}

\newcommand{\InsFig}[4]{%
	\begin{figure}[!htb]%
	\begin{center}%
	\includegraphics[width=#2\linewidth]{#1}%
	\end{center}%
	\caption{#3\label{#4}}%
	\end{figure}}


\begin{document}
\title{ePic2 v2.1 Documentation}
\author{Julien Hubert \& Yannick Weibel}
%\date{}
\maketitle
\section{Introduction}
The ePic2 software is a toolbox to interface Matlab with an e-puck (for additional information see \href{http://www.e-puck.org}{http://www.e-puck.org}). It contains a graphical interface and a set of primitives allowing to send and receive commands between the e-puck and Matlab. It will be used in the laboratories of the course Robots Mobiles (\href{http://moodle.epfl.ch/course/view.php?id=261}{http://moodle.epfl.ch/course/view.php?id=261}). The goal of the software is to provide students with the necessary tools to explore the topic of mobile robotics while focusing on high level behaviors or strategies.
\par The next section will present the commands to interact with the e-puck available from the Matlab command line. Following, the graphical interface and its possibilities will be described.

\section{Quickstart}
This section intends to give you the quick steps needed to start working with ePic2.
\begin{enumerate}
\item \textbf{epic=ePicKernel;} creates a class containing all the variables needed to command the e-puck
\item \textbf{epic=connect(epic,'COMXX');} will connect epic to an e-puck accessible through the serial port COMXX
\item \textbf{epic=update(epic);} updates the status of the physical e-puck and of the epic class. It transfers data from and to the e-puck. 
\item \textbf{epic=disconnect(epic);} breaks the connection between the e-puck and Matlab.

\end{enumerate}

\section{Matlab Commands}
\subsection{The ePicKernel class}
ePic2 is based on a class containing all the information related to the e-puck. This class contains the values of the sensors, their rate of update, the commands that should be sent to the e-puck and the inner parameters of the ePic2 interface.
\par To act on the e-puck, the class contains a set of functions setting some inner variable related to its control. Those will be detailed in the following sections.
\par The class is created by calling \emph{epic=ePicKernel;}.

\subsection{Connection to the E-Puck}
Before sending commands to the e-puck, the function \emph{connect} must be called. This function takes as parameters an instantiation of the class ePicKernel and a string containing the COM port associated with the e-puck. For instance,  \emph{epic=connect(epic,'COM15')} opens a connection with the e-puck associated to port COM 15. The command returns a modified instance of the ePicKernel class. If the connection was successful, the command \emph{get(epic,'connectionStatus')} returns 1, otherwise 0.
\par Once connected, all the interactions will be done with the same robot. It is not possible to connect to more than one e-puck at a time due to Matlab limitations.
\par To disconnect, the command \emph{epic=disconnect(epic)} should be called. Afterward, Matlab can be connected to another e-puck on another port.

\subsection{Sending and Receiving Data}
All the interactions with the e-puck, with the exception of the camera, are centralized in one command \emph{epic=update(epic);}. This command updates the values of the sensors and sends the commands to the e-puck. 
\par All the transfers between the e-puck and Matlab are done simultaneously. First, all the commands are sent to the e-puck. Those can be a request for sensor values or a modification of the e-puck's wheel speed. Then, \emph{update} waits for the reception of the requested information and updates the variables of the class epic. Please read section \ref{sec:commands} to learn how to select which sensor to read and how to control the e-puck.
\subsubsection{Unrecommended method}
\par It is also possible to send custom commands to the e-puck using the low level functions to send and receive data. Those exist either in ASCII or in binary but their usage is the same. The difference resides in the way the data are encoded. In ASCII mode, the data sent by the e-puck are formatted as a string. The Matlab command \emph{str2num} has to be called to convert those into a Matlab variable. In binary mode, the data are formatted as they were on the e-puck and spread over different bytes. It is then necessary to reformat the values into their original format. This is generally more difficult to do as it requires a knowledge of the inner programming of the e-puck. The binary mode is nevertheless more advantageous when multiple commands have to be sent simultaneously. In ASCII mode, all commands are sent separately on the bluetooth channel while in binary the are all sent with one transfer only. This has the effect of speeding up the transfers between the e-puck and Matlab.
\par Sending a custom command is done through the functions \emph{write(epic,data);} or \newline \emph{writeBin(epic,data);} where data contains the commands to send. The first function uses the ASCII mode while the second the binary mode. Those commands are asynchronous and won't wait for the answer of the e-puck. To receive the result of the sent command, the functions \emph{data=read(epic);} or \emph{data=readBin(epic);} have to be called according to the type of writing you did previously. An alternate command to read binary data is \emph{data=readBinSized(epic,n);} where \emph{n} is the size in bytes of the data to be transfered. The function will wait until all the data has been received or for a timeout to occur.
\par The final command to know is \emph{flush(epic);} which resets the transmission and reception buffer of Matlab. It is useful to call before any communication with the e-puck as Matlab does not seem to do it by itself. If not called, there are risks that old information will remain in the buffers.

\subsection{Commanding the e-puck}
\label{sec:commands}
As mentioned earlier, the \emph{update} command handles all the information transfers between Matlab and the e-puck. All data sent or received is stored in the class' variables. By default, ePic2 reads the values of the accelerometer, the proximity sensors, the light sensors, the microphones, the motor speeds and the encoders. Those correspond to the basic functionalities of the e-puck.

\subsubsection{Gathering information - get}
\par To activate the reading of a sensor, the command \emph{epic=activate(epic, propName);} must be called where \emph{propName} is the name of the sensor to activate. To deactivate a sensor, the command \emph{epic=deactivate(epic, propName);} must be used.
\par A complementary function, \emph{epic=updateDef(epic, propName, frequency);} allows you to set the update frequency 0:no update (=desactivate), 1:allways update (=activate), 2:update once only. 
\par Once the information has been retrieved, it can be obtained with the function \newline \emph{[val,up]=get(epic,propName);} where \emph{val} contains the requested values and \emph{up} indicates those were refreshed during the last update.
\par The following table contains the values for \emph{propName} and should be used as Matlab strings.
\setlongtables
\begin{longtable}{|l|l|p{6.5cm}|}
\hline
\textbf{propName} & \textbf{Data} & \textbf{Supported Commands}\\
\hline \hline
accel & Accelerometers & get, activate, deactivate, updateDef\\
\hline
proxi & Proximity Sensors & get, activate, deactivate, updateDef\\
\hline
light & Light Sensors & get, activate, deactivate, updateDef\\
\hline
micro & Microphones & get, activate, deactivate, updateDef\\