[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Libirobot-create-patches] libirobot-create b1e17b8: Add user manual
|
From: |
Thomas Moulard |
|
Subject: |
[Libirobot-create-patches] libirobot-create b1e17b8: Add user manual |
|
Date: |
Fri, 29 Aug 2008 11:00:49 -0700 |
URL: git://git.sv.gnu.org/libirobot-create.git
Git branch: master (HEAD: 4d01310)
ChangeLog:
2008-08-29 Thomas Moulard <address@hidden>
Add user manual.
* doc/userguide/faq.tex: New.
* doc/userguide/installation.tex: New.
* doc/userguide/introduction.tex: New.
* doc/userguide/remote-control-example.tex: New.
* doc/userguide/tutorial.tex: New.
* doc/userguide/userguide.bib: New.
* doc/userguide/userguide.tex: New.
---
ChangeLog | 11 ++
doc/userguide/faq.tex | 213 ++++++++++++++++++++++++++++++
doc/userguide/installation.tex | 195 +++++++++++++++++++++++++++
doc/userguide/introduction.tex | 76 +++++++++++
doc/userguide/remote-control-example.tex | 179 +++++++++++++++++++++++++
doc/userguide/tutorial.tex | 171 ++++++++++++++++++++++++
doc/userguide/userguide.bib | 35 +++++
doc/userguide/userguide.tex | 175 ++++++++++++++++++++++++
8 files changed, 1055 insertions(+), 0 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 87119ac..cf91222 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2008-08-29 Thomas Moulard <address@hidden>
+
+ Add user manual.
+ * doc/userguide/faq.tex: New.
+ * doc/userguide/installation.tex: New.
+ * doc/userguide/introduction.tex: New.
+ * doc/userguide/remote-control-example.tex: New.
+ * doc/userguide/tutorial.tex: New.
+ * doc/userguide/userguide.bib: New.
+ * doc/userguide/userguide.tex: New.
+
2008-08-28 Thomas Moulard <address@hidden>
Fix RPM generation.
diff --git a/doc/userguide/faq.tex b/doc/userguide/faq.tex
new file mode 100644
index 0000000..f854964
--- /dev/null
+++ b/doc/userguide/faq.tex
@@ -0,0 +1,213 @@
+%% Copyright (C) 2008 by Thomas Moulard, the University of Southern California
+%% (USC), and iLab at USC.
+%%
+%% This file is part of the iRobot Create library.
+%%
+%% libirobot-create is free software: you can redistribute it and/or modify
+%% it under the terms of the GNU General Public License as published by
+%% the Free Software Foundation, either version 3 of the License, or
+%% (at your option) any later version.
+%%
+%% libirobot-create is distributed in the hope that it will be useful,
+%% but WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+%% GNU General Public License for more details.
+%%
+%% You should have received a copy of the GNU General Public License
+%% along with libirobot-create. If not, see <http://www.gnu.org/licenses/>.
+
+\chapter[FAQ]{Frequently Asked Questions}
+
+\section{Why is the program failing when I use serial port communication?}
+
+If you try to use the serial port communication without having the LibSerial
+support, the constructor will fail and throw a LibSerialNotAvailable
+exception. It means that when the configure script has not detected the
+LibSerial library on your computer. Check your config.log, it should
+contain something like that:
+
+\begin{lstlisting}[caption={\texttt{config.log} sample},
+ label=shell:config]
+ configure:XXX: checking for main in -lserial
+ [...]
+ configure:XXX: result: yes
+\end{lstlisting}
+
+If the result is \emph{no}, please specify the header and library path in
+\texttt{CPPFLAGS} and \texttt{LDFLAGS}. For instance, if you are using gcc
+(which is usually the case), it should be something like that:
+
+\begin{lstlisting}[caption={Invoking \texttt{configure} when using
non-standard paths},
+ label=shell:configpath]
+ ./configure CPPFLAGS=-I/my/path/to/libserial \
+ LDFLAGS=-L/my/path/to/libserial
+\end{lstlisting}
+
+\emph{Note: if you have installed a package to get this library, please ask the
+ maintainer of the package for your distribution to enable the LibSerial
+ support.}
+
+
+\section{Why does the communication through the serial port not work?}
+
+If you have opened the serial port through a std::fstream, \emph{it will not
+ work}. Always use the \ls library (or another 3rd party serial
+library). Failing to do so may lead to random errors, wrong values for the
+sensors, etc.
+
+\section{The sensor I'm using is never updated, why?}
+
+If you want an updated value of a sensor, you have to explicitly ask for an
+update. It can either be done with the \texttt{Create::sendSensorsCommand} or
+the \texttt{Create::sendQueryListCommand command.}
+
+If you are using the sensors frequently, you probably want to use the\\
+\texttt{Create::sendStreamCommand} that will ask the robot to send the sensor's
+value each 15ms. It is the only way to keep a sensor updated automatically. If
+you are using a connection with poor real-time characteristics (such as a
+wireless network using the BAM for instance), the solution recommended by
+iRobot is to use the stream command.
+
+\begin{lstlisting}[caption={Sensor reading sample},
+ label=src:sensor]
+ iRobot::Create robot (...);
+
+ robot.wall (); // Always false, no update.
+ // [...]
+ robot.wall (); // Always false, no update.
+
+ Create::sensorPackets_t sensors;
+ sensors.push_back (Create::SENSOR_BUMPS_WHEELS_DROPS);
+
+ robot.sendQueryListCommand (robot);
+
+ robot.wall (); // Updated value.
+ robot.wall (); // *NO* update here.
+ robot.wall (); // *NO* update here.
+ // etc.
+
+ robot.sendStreamCommand (robot);
+
+ robot.wall (); // Updated value.
+ robot.wall (); // Updated value.
+ robot.wall (); // Updated value.
+ // etc.
+\end{lstlisting}
+
+
+\subsection{How to use the Bluetooth adapter module (BAM)?}
+
+To use the BAM with this library, you will need two tools:
+\begin{itemize}
+\item \texttt{hcitool}
+\item \texttt{rfcomm}
+\end{itemize}
+
+Both tools are provided by the \texttt{bluez} package.
+
+Install the Bluetooth adapter module and start the robot.
+Then, execute the following command:
+
+\begin{lstlisting}[caption={Scanning for Bluetooth devices in command line},
+ label=shell:btscan]
+hcitool scan
+\end{lstlisting}
+
+
+You should see something that looks like that:
+\begin{lstlisting}[caption={Bluetooth scan result sample},
+ label=shell:btscanres]
+ Scanning ...
+ 00:0A:3A:26:49:AF Element Serial
+ [...]
+\end{lstlisting}
+
+
+The \emph{Element Serial} is the iRobot Create. Remember the address as it will
+be required for the next step. If it fails, check that your kernel supports
+bluetooth (check your distribution's documentation).
+
+
+Execute the following command:
+\begin{lstlisting}[caption={Connecting to the robot},
+ label=shell:btconnect]
+rfcomm connect 1 '00:0A:3A:26:49:AF'
+\end{lstlisting}
+
+
+You should then see:
+\begin{lstlisting}[caption={Result of a Bluetooth robot connection},
+ label=shell:btconnectres]
+Connected /dev/rfcomm1 to 00:0A:3A:26:49:AF on channel 1
+Press CTRL-C for hangup
+\end{lstlisting}
+
+You are now connected to the robot and you can read the
+\texttt{/dev/rfcomm1} file to communicate with it.
+
+If the connection fails, wait for a couple of seconds and retry.
+
+
+\subsection{How to compile my project with libirobot-create?}
+
+Basically, if the library and the headers are installed in standard
+directories, you only have to link against the library. If you are
+using GCC, you probably want:
+
+\begin{lstlisting}[caption={Compiling a project using the library},
+ label=shell:compile]
+g++ myproject.cc -lirobot-create
+\end{lstlisting}
+
+
+If you have not installed the library in a standard directory, you
+have to indicate the header directory when compiling and the
+library directory when linking. With GCC:
+
+\begin{lstlisting}[caption={Compiling a project using the library with
non-standard paths},
+ label=shell:compilepath]
+ g++ myproject.cc -I/my/include/path \
+ -L/my/library/path -Wl,-R/my/library/path \
+ -lirobot-create
+\end{lstlisting}
+
+The \texttt{-Wl,-R/my/library/path} flag adds the library directory to the list
+used to search dynamic libraries at run-time (\texttt{-L} is only used at
+compile-time).
+
+If you are using the Autotools, see the next section.
+
+
+\subsection{How to integrate this library to my Autotools software?}
+
+A m4 file is provided with the macros required to check for this library.
+
+Here is a sample configure.ac that check for the library:
+
+\begin{lstlisting}[caption={Library detection with Autoconf},
+ label=shell:autoconftest]
+ AC_INIT([test], [0.1])
+ AM_INIT_AUTOMAKE
+
+ AC_LANG([C++])
+ AC_PROG_CXX
+
+ LIBIROBOT_CREATE_ARG_WITH
+
+ AC_CONFIG_HEADERS([config.h])
+
+ AC_CONFIG_FILES([Makefile])
+ AC_OUTPUT
+\end{lstlisting}
+
+
+It also define the boolean \texttt{LIBIROBOT\_CREATE} that can be used in
+Automake files.
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% ispell-local-dictionary: "american"
+%%% fill-column: 76
+%%% End:
diff --git a/doc/userguide/installation.tex b/doc/userguide/installation.tex
new file mode 100644
index 0000000..45b536d
--- /dev/null
+++ b/doc/userguide/installation.tex
@@ -0,0 +1,195 @@
+%% Copyright (C) 2008 by Thomas Moulard, the University of Southern California
+%% (USC), and iLab at USC.
+%%
+%% This file is part of the iRobot Create library.
+%%
+%% libirobot-create is free software: you can redistribute it and/or modify
+%% it under the terms of the GNU General Public License as published by
+%% the Free Software Foundation, either version 3 of the License, or
+%% (at your option) any later version.
+%%
+%% libirobot-create is distributed in the hope that it will be useful,
+%% but WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+%% GNU General Public License for more details.
+%%
+%% You should have received a copy of the GNU General Public License
+%% along with libirobot-create. If not, see <http://www.gnu.org/licenses/>.
+
+\chapter{Installation}
+
+\section{Specific instructions for the Bluetooth Adapter Module (BAM)}
+
+Bluetooth has to be working on your computer, it includes kernel support and
the installation
+of the \texttt{bluez} package which provides useful command line tools. You
may also want to
+install a graphic user interface such as \texttt{kdebluetooth}.
+
+
+\section{Versions and dependencies}
+
+
+This library has an (optional but \emph{strongly} recommended) dependency on
+\ls \footnote{More information on LibSerial website
+ \url{http://libserial.sourceforge.net/}.}, please make sure that this
+library is installed on your system before trying to use this library using
+serial port communication.
+
+
+
+\section{Installation from a package}
+\subsection{Ebuild (Gentoo)}
+
+An ebuild is provided in the download area, however it is not included in
+Portage which means you can not directly type \texttt{emerge
+ libirobot-create}.
+
+You first have to setup a local Portage overlay. The process is explained on
+Gentoo-wiki.com\footnote{A complete tutorial is available here:
+ \url{http://gentoo-wiki.com/HOWTO_Installing_3rd_Party_Ebuilds}}.
+
+When your local overlay is ready, download the ebuild and copy it in your
+overlay. You can then install the package normally.
+
+
+\subsection{Deb (Debian)}
+
+A deb file is provided in the download area, to install it follow the
instructions of
+the \autoref{shell:deb}.
+
+\begin{lstlisting}[caption={Installing a debian package (root privileges
required)},
+ label=shell:deb]
+dpkg -i filename.deb
+\end{lstlisting}
+
+
+\subsection{RPM}
+
+RPMs are available for the \ls library. A 32 bits
+\footnote{\url{http://rpm.pbone.net/index.php3/stat/4/idpl/2893519/com/libserial-0.5.2-FC5.i386.rpm.html}}
+version can be found on internet, a 64 bits is available in the download
+area
+\footnote{\url{http://download.savannah.gnu.org/releases/libirobot-create/libserial-0.5.2-0.x86_64.rpm}}
+of the project.
+
+\begin{lstlisting}[caption={Installing \ls from an RPM},
+ label=shell:rpmlibserial]
+rpm -i libserial-0.5.2-FC5.i386.rpm # For 32-bits.
+# *OR*
+rpm -i libserial-0.5.2-0.x86_64.rpm # For 64-bits.
+\end{lstlisting}
+
+
+However, this RPM does not provide the libtool library, so you'll have to
+execute the following command to indicate that you don't want to check this
+dependency (libtool libraries are optional so it is not a real problem).
+
+\begin{lstlisting}[caption={Remove \texttt{libserial.la} dependency},
+ label=shell:rpmlibtool]
+echo "libtool(/usr/lib/libserial.la)" >> /etc/rpm/sysinfo
+\end{lstlisting}
+
+
+You can then download a rpm for the \lic from the project homepage.
+
+\begin{lstlisting}[caption={Remove \texttt{libserial.la} dependency},
+ label=shell:rpmlic]
+rpm -i libirobot-create-0.1-1.i386.rpm # For 32-bits.
+# *OR*
+rpm -i libirobot-create-0.1-1.x86_64.rpm # For 64-bits.
+\end{lstlisting}
+
+
+\section{Installation from a tarball}
+
+To compile from a tarball and install the library, follow the instructions
+of \autoref{shell:compiledef}.
+Invoke \texttt{configure} without the \texttt{prefix} flag to install
+the library in \texttt{/usr/local}.
+
+
+\section{Installation from the Git repository}
+
+If you do not have libserial, install it (from a package or from
+source)\footnote{More information on LibSerial website
+ \url{http://libserial.sourceforge.net/}.}.
+
+
+\subsection{Checking out}
+
+\begin{lstlisting}[caption={Anonymous check-out of the project repository},
+ label=shell:gitcheckout]
+git clone git://git.savannah.nongnu.org/libirobot-create.git
+\end{lstlisting}
+
+
+\subsection{Building the library}
+
+To compile, follow the instructions of the \autoref{shell:compiletmp}. If you
+want to install definitively the package on your computer, follow the
+instructions of \autoref{shell:compiledef}.
+
+\begin{lstlisting}[caption={Compiling the sources},
+ label=shell:compiletmp]
+./bootstrap
+mkdir _build
+cd _build
+../configure
+make
+# To install *temporarily* (optional):
+make install DESTDIR=/my/tmp/install/directory
+\end{lstlisting}
+
+\begin{lstlisting}[caption={Compiling the sources and definitive installation},
+ label=shell:compiledef]
+./bootstrap
+mkdir _build
+cd _build
+../configure --prefix=$HOME/.local
+mkdir $HOME/.local
+make install
+# Check if it has been installed successfully:
+ls -R $HOME/.local # You should see all the installed files.
+\end{lstlisting}
+
+
+\emph{Note:} these instructions are working for any other Autotools package.
+
+
+You can change the prefix to whatever you want, however it is \emph{usually
+ a bad idea} to install a source package in usual prefixes such as
+\texttt{/usr} or \texttt{/usr/local}.
+
+
+\section{Documentation}
+
+The installation process install the Doxygen documentation on your
+computer. If you are installing from the tarball and you have kept the
+default installation paths, you can find it here:
+\texttt{/usr/share/doc/libirobot-create}.
+
+For packages, it is usually in \texttt{/usr/doc/libirobot-create}.
+
+
+If you are compiling from source, you can compile the Doxygen documentation
+yourself using the commands of the \autoref{shell:compiledoc} for html
+version or of \autoref{shell:compiledocpdf} to generate a PDF.
+
+\begin{lstlisting}[caption={Building Doxygen documentation},
+ label=shell:compiledoc]
+cd _build
+make doc
+\end{lstlisting}
+
+\begin{lstlisting}[caption={Building Doxygen documentation},
+ label=shell:compiledocpdf]
+cd _build/doc/latex
+make pdf
+\end{lstlisting}
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% ispell-local-dictionary: "american"
+%%% fill-column: 76
+%%% End:
diff --git a/doc/userguide/introduction.tex b/doc/userguide/introduction.tex
new file mode 100644
index 0000000..81e9e3f
--- /dev/null
+++ b/doc/userguide/introduction.tex
@@ -0,0 +1,76 @@
+%% Copyright (C) 2008 by Thomas Moulard, the University of Southern California
+%% (USC), and iLab at USC.
+%%
+%% This file is part of the iRobot Create library.
+%%
+%% libirobot-create is free software: you can redistribute it and/or modify
+%% it under the terms of the GNU General Public License as published by
+%% the Free Software Foundation, either version 3 of the License, or
+%% (at your option) any later version.
+%%
+%% libirobot-create is distributed in the hope that it will be useful,
+%% but WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+%% GNU General Public License for more details.
+%%
+%% You should have received a copy of the GNU General Public License
+%% along with libirobot-create. If not, see <http://www.gnu.org/licenses/>.
+
+\chapter{Introduction}
+
+The ``\iccl'' (or \lic) provides a complete implementation of the \oitwo
+\cite{ircois} in \cxx.
+
+The \ic \cite{ircog} targets developers, educators and hobbyist. It eases
+the work by providing a pre-assembled plat-form and a set of
+accessories. However, no software is provided by \ir to control the robot
+remotely.
+
+
+This library supports:
+\begin{itemize}
+\item Direct connection through a serial cable.
+\item Bluetooth connection using a \bam (BAM).
+\end{itemize}
+
+It allows complex software running on a remote computer to drive the robot.
+
+The main drawback of the \bam is the time lag introduced by the wireless
+connection, the bluetooth range can also be a problem. If a cable is used,
+there is no lag but the robots' movements are limited.
+
+\begin{figure}
+ \begin{center}
+ \begin{tabular}{|c|c|c|}
+ \hline
+ \emph{Connection type?} & Time lag? & Range? \\
+ \hline
+ \emph{Direct connection} & none & cable length \\
+ \emph{Bluetooth} & yes & 100 meters (class 1 devices)\\
+ \hline
+ \end{tabular}
+ \end{center}
+ \caption{Advantages and drawbacks of each conncetion. \label{tbl:ct}}
+\end{figure}
+
+
+If the robot \emph{has} to be totally autonomous, a good solution may be to
+setup a small laptop on the robot and use a direct serial connection.
+
+
+\emph{Important:} \ir also sell a ``command module'' \cite{ircmom} which is
+a 8-bit, 18MHz microcontroller, this library does \emph{not} support it.
+
+
+\vspace{1cm}
+
+The library, the documentation and all associated files are available on the
+project's homepage:
+\url{https://savannah.nongnu.org/projects/libirobot-create/}.
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% ispell-local-dictionary: "american"
+%%% fill-column: 76
+%%% End:
diff --git a/doc/userguide/remote-control-example.tex
b/doc/userguide/remote-control-example.tex
new file mode 100644
index 0000000..7727945
--- /dev/null
+++ b/doc/userguide/remote-control-example.tex
@@ -0,0 +1,179 @@
+%% Copyright (C) 2008 by Thomas Moulard, the University of Southern California
+%% (USC), and iLab at USC.
+%%
+%% This file is part of the iRobot Create library.
+%%
+%% libirobot-create is free software: you can redistribute it and/or modify
+%% it under the terms of the GNU General Public License as published by
+%% the Free Software Foundation, either version 3 of the License, or
+%% (at your option) any later version.
+%%
+%% libirobot-create is distributed in the hope that it will be useful,
+%% but WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+%% GNU General Public License for more details.
+%%
+%% You should have received a copy of the GNU General Public License
+%% along with libirobot-create. If not, see <http://www.gnu.org/licenses/>.
+
+\appendix
+\chapter{Remote control example}
+
+This example implements a simple remote controller for the robot using the
+arrows keys of the keyboard.
+
+This example \emph{requires} the library
+\texttt{ncurses}\footnote{\url{http://www.gnu.org/software/ncurses/}}.
+
+
+To compile this example, use the command described in the \autoref{shell:crca}
+where \texttt{remote-control.cc} is the file described in the
+\autoref{src:rce}.
+
+
+\begin{lstlisting}[caption={Compiling the remote control example},
+ label=shell:crca]
+ $ g++ remote-control.cc -lirobot-create -lncurses
+\end{lstlisting}
+
+\begin{lstlisting}[caption={Remote control example source},
+ label=src:rce]
+#include <sstream>
+#include <SerialStream.h>
+#include <irobot-create.hh>
+
+#include <ncurses.h>
+
+using namespace iRobot;
+using namespace LibSerial;
+
+static int speed = 0;
+static const int speedStep = 100;
+
+static int radius = 0;
+static const int radiusStep = 100;
+
+bool isStopped ()
+{
+ return (speed < speedStep && speed > -speedStep);
+}
+
+void handleRemoteControl (Create& robot)
+{
+ int ch = getch ();
+
+ bool stop = isStopped ();
+
+ if (ch == KEY_UP)
+ {
+ speed += speedStep;
+ if (!stop && isStopped ())
+ radius = 0;
+ }
+ if (ch == KEY_DOWN)
+ {
+ speed -= speedStep;
+ if (!stop && isStopped ())
+ radius = 0;
+ }
+
+ if (ch == KEY_LEFT)
+ {
+ if (radius < 0)
+ radius += radiusStep;
+ else if (radius == 0)
+ radius = Create::RADIUS_MIN;
+ else
+ radius = 0;
+ }
+ if (ch == KEY_RIGHT)
+ {
+ if (radius > 0)
+ radius -= radiusStep;
+ else if (radius == 0)
+ radius = Create::RADIUS_MAX;
+ else
+ radius = 0;
+ }
+
+ if (speed >= Create::VELOCITY_MAX)
+ speed = Create::VELOCITY_MAX;
+ if (speed <= Create::VELOCITY_MIN)
+ speed = Create::VELOCITY_MIN;
+
+ if (radius >= Create::RADIUS_MAX)
+ radius = Create::RADIUS_MAX;
+ if (radius <= Create::RADIUS_MIN)
+ radius = Create::RADIUS_MIN;
+
+ if (robot.bumpLeft () || robot.bumpRight ())
+ speed = 0, radius = 0;
+
+ std::stringstream ss;
+ ss << "Speed: " << speed << ", Radius: "
+ << radius << std::endl;
+ mvprintw(0, 0, ss.str ().c_str ());
+ refresh ();
+
+ if (radius < radiusStep && radius > -radiusStep)
+ robot.sendDriveCommand (speed,
+ Create::DRIVE_STRAIGHT);
+ else if (speed < speedStep && speed > -speedStep)
+ {
+ int s = 0;
+ if (radius > 0)
+ s = (Create::RADIUS_MAX - radius) / 4;
+ else
+ s = (Create::RADIUS_MIN - radius) / 4;
+
+ robot.sendDriveCommand (s,
+ Create::DRIVE_INPLACE_CLOCKWISE);
+ }
+ else
+ robot.sendDriveCommand (speed, -radius);
+}
+
+int main (int argc, char** argv)
+{
+ if (argc < 2)
+ return 1;
+
+ initscr ();
+ keypad (stdscr, TRUE);
+ noecho ();
+
+ SerialStream stream (argv[1]);
+
+ try
+ {
+ Create robot (stream);
+ robot.sendFullCommand ();
+
+ while (true)
+ {
+ handleRemoteControl (robot);
+
+ usleep(100 * 1000);
+ }
+
+ endwin ();
+ }
+ catch (InvalidArgument& e)
+ {
+ std::cerr << e.what () << std::endl;
+ return 3;
+ }
+ catch (CommandNotAvailable& e)
+ {
+ std::cerr << e.what () << std::endl;
+ return 4;
+ }
+}
+\end{lstlisting}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% ispell-local-dictionary: "american"
+%%% fill-column: 76
+%%% End:
diff --git a/doc/userguide/tutorial.tex b/doc/userguide/tutorial.tex
new file mode 100644
index 0000000..571e85f
--- /dev/null
+++ b/doc/userguide/tutorial.tex
@@ -0,0 +1,171 @@
+%% Copyright (C) 2008 by Thomas Moulard, the University of Southern California
+%% (USC), and iLab at USC.
+%%
+%% This file is part of the iRobot Create library.
+%%
+%% libirobot-create is free software: you can redistribute it and/or modify
+%% it under the terms of the GNU General Public License as published by
+%% the Free Software Foundation, either version 3 of the License, or
+%% (at your option) any later version.
+%%
+%% libirobot-create is distributed in the hope that it will be useful,
+%% but WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+%% GNU General Public License for more details.
+%%
+%% You should have received a copy of the GNU General Public License
+%% along with libirobot-create. If not, see <http://www.gnu.org/licenses/>.
+
+\chapter{Tutorial}
+
+iRobot Create uses a specific protocol which is implemented by this library.
+It is called Open Interface (OI) version 2. When instantiating the robot
+class (iRobot::Create) you have to indicate which stream is used to
+communicate with the robot.
+
+Typically you probably want to use a serial port device for the
+communication such as:
+
+\begin{itemize}
+\item \texttt{/dev/ttySX} (where \texttt{X} is the serial port number),
+\item\texttt{/dev/rfcommX} (where \texttt{X} is the serial-over-bluetooth port
number).
+\end{itemize}
+
+The last solution requires the Bluetooth adapter module (BAM).
+
+
+To communicate with the robot, you \emph{need} the serial port support. To
+enable this, you have to use the
+\ls\footnote{\url{http://libserial.sourceforge.net}} library (it library has
+to be installed on your computer).
+
+
+\section{Serial port communication tutorial}
+
+The \autoref{src:tutorial} provides the entire code source of the tutorial.
+
+
+\begin{lstlisting}[caption={Tutorial sources},
+ label=src:tutorial]
+#include <SerialStream.h>
+#include <irobot-create.hh>
+
+int main (int argc, char** argv)
+{
+ using namespace iRobot;
+ using namespace LibSerial;
+
+
+ if (argc < 2)
+ return 1;
+ SerialStream stream (argv[1]);
+
+ try
+ {
+ Create robot (stream);
+
+ // Swith to full mode.
+ robot.sendFullCommand ();
+
+ // Let's stream some sensors.
+ Create::sensorPackets_t sensors;
+ sensors.push_back (Create::SENSOR_BUMPS_WHEELS_DROPS);
+ sensors.push_back (Create::SENSOR_WALL);
+ sensors.push_back (Create::SENSOR_BUTTONS);
+
+ robot.sendStreamCommand (sensors);
+
+ // Let's turn!
+ int speed = 200;
+ int ledColor = Create::LED_COLOR_GREEN;
+ robot.sendDriveCommand (speed,
+ Create::DRIVE_INPLACE_CLOCKWISE);
+ robot.sendLedCommand (Create::LED_PLAY, 0, 0);
+
+ while (!robot.playButton ())
+ {
+ if (robot.bumpLeft () || robot.bumpRight ())
+ std::cout << "Bump !" << std::endl;
+ if (robot.wall ())
+ std::cout << "Wall !" << std::endl;
+ if (robot.advanceButton ())
+ {
+ speed = -1 * speed;
+ ledColor += 10;
+ if (ledColor > 255)
+ ledColor = 0;
+
+ robot.sendDriveCommand (speed,
+ Create::DRIVE_INPLACE_CLOCKWISE);
+ if (speed < 0)
+ robot.sendLedCommand (Create::LED_PLAY,
+ ledColor,
+ Create::LED_INTENSITY_FULL);
+ else
+ robot.sendLedCommand (Create::LED_ADVANCE,
+ ledColor,
+ Create::LED_INTENSITY_FULL);
+ }
+
+ // You can add more commands here.
+ usleep(100 * 1000);
+ }
+
+ robot.sendDriveCommand (0, Create::DRIVE_STRAIGHT);
+ }
+ catch (InvalidArgument& e)
+ {
+ std::cerr << e.what () << std::endl;
+ return 3;
+ }
+ catch (CommandNotAvailable& e)
+ {
+ std::cerr << e.what () << std::endl;
+ return 4;
+ }
+}
+\end{lstlisting}
+
+The robot will start to turn clockwise, then if you push the advance button,
+it will change its direction. Each time you're pushing the button, the LEDs
+will also change.
+
+
+\section{What if I do not want to use \ls?}
+
+You can construct the object with any kind of \texttt{std::iostream}, it
+means that it can come from another serial library, it may be a
+\texttt{std::stringstream} or a std::fstream. However, do \emph{not} use a
+\texttt{fstream} to open a serial port device.
+
+
+
+The \autoref{src:logtutorial} is a simple example that displays on the
+standard output the binary command used to start the \emph{cover} demo
+(warning: this will display non-ascii characters to your term if you do not
+redirect the standard output, you may want to use a tool like hexdump to see
+the result).
+
+\begin{lstlisting}[caption={Logging tutorial},
+ label=src:logtutorial]
+#include <sstream>
+#include <irobot-create.hh>
+
+int main ()
+{
+ using namespace iRobot;
+
+ std::stringstream ss;
+ Create robot (ss);
+ robot.sendDemoCommand (Create::DEMO_COVER);
+ std::cout << ss.str ();
+}
+\end{lstlisting}
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% ispell-local-dictionary: "american"
+%%% fill-column: 76
+%%% End:
diff --git a/doc/userguide/userguide.bib b/doc/userguide/userguide.bib
new file mode 100644
index 0000000..212c5c7
--- /dev/null
+++ b/doc/userguide/userguide.bib
@@ -0,0 +1,35 @@
address@hidden,
+ author="iRobot",
+ title="iRobot Create Ownerâs Guide",
+ url=
+"\url{http://www.irobot.com/filelibrary/create/Create%20Manual_Final.pdf}";,
+ note=
+"\url{http://www.irobot.com/filelibrary/create/Create%20Manual_Final.pdf}";,
+}
+
address@hidden,
+ author="iRobot",
+ title="iRobot Create Open Interface Specification",
+ url=
+"\url{http://www.irobot.com/filelibrary/create/Create%20Open%20Interface_v2.pdf}";,
+ note=
+"\url{http://www.irobot.com/filelibrary/create/Create%20Open%20Interface_v2.pdf}";,
+}
+
address@hidden,
+ author="iRobot",
+ title="iRobot Command Module Quick Start",
+ url=
+"\url{http://www.irobot.com/filelibrary/create/CommandModuleGettingStarted.pdf}";,
+ note=
+"\url{http://www.irobot.com/filelibrary/create/CommandModuleGettingStarted.pdf}";,
+}
+
address@hidden,
+ author="iRobot",
+ title="iRobot Command Module Ownerâs Manual",
+ url=
+"\url{http://www.irobot.com/filelibrary/create/Command%20Module%20Manual_v2.pdf}";,
+ note=
+"\url{http://www.irobot.com/filelibrary/create/Command%20Module%20Manual_v2.pdf}";,
+}
diff --git a/doc/userguide/userguide.tex b/doc/userguide/userguide.tex
new file mode 100644
index 0000000..3c761a2
--- /dev/null
+++ b/doc/userguide/userguide.tex
@@ -0,0 +1,175 @@
+%% Copyright (C) 2008 by Thomas Moulard, the University of Southern California
+%% (USC), and iLab at USC.
+%%
+%% This file is part of the iRobot Create library.
+%%
+%% libirobot-create is free software: you can redistribute it and/or modify
+%% it under the terms of the GNU General Public License as published by
+%% the Free Software Foundation, either version 3 of the License, or
+%% (at your option) any later version.
+%%
+%% libirobot-create is distributed in the hope that it will be useful,
+%% but WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+%% GNU General Public License for more details.
+%%
+%% You should have received a copy of the GNU General Public License
+%% along with libirobot-create. If not, see <http://www.gnu.org/licenses/>.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Document class %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\documentclass{book}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Packages %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Fancy headers.
+\usepackage{fancyhdr}
+
+% Hyper references.
+\usepackage{hyperref}
+
+% Listings (code source).
+\usepackage{listings}
+
+% Index.
+\usepackage{makeidx}
+
+% URL inclusion.
+\usepackage{url}
+
+% Xspace
+\usepackage{xspace}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Package tuning. %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Page style.
+\pagestyle{fancy}
+
+% Too much room is wasted by default before and after listings.
+\lstset{language=C++,aboveskip=10pt,%
+ belowskip=10pt,showstringspaces=false,frame=leftline,
+ captionpos=b}
+
+% MetaPost support.
+\ifx\pdftexversion\undefined
+ \usepackage[dvips]{graphicx}
+\else
+ \usepackage{graphicx}
+ \DeclareGraphicsRule{*}{mps}{*}{}
+\fi
+
+% Index generation.
+\makeindex
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Use long titles in TOC. %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\makeatletter
address@hidden
address@hidden@chapter
address@hidden@chapter[#2]{#2}\chaptermark{#1}}
+\makeatother
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Nice URLs. %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Define a new 'leo' style for the package that will use a smaller font.
+\makeatletter
address@hidden
+ address@hidden
+\makeatother
+%% Now actually use the newly defined style.
+\urlstyle{leostyle}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Acronyms. %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Programming languages.
+\newcommand{\cxx}{\texttt{C++}\xspace}
+
+% iRobot
+\newcommand{\oi}{\texttt{Open Interface}\xspace}
+\newcommand{\oitwo}{\oi version 2\xspace}
+\newcommand{\ir}{iRobot\xspace}
+\newcommand{\ic}{\ir Create\xspace}
+\newcommand{\bam}{Bluetooth Adapter Module\xspace}
+
+% libirobot-create
+\newcommand{\lic}{\texttt{libirobot-create}\xspace}
+\newcommand{\iccl}{iRobot Create communication library\xspace}
+
+\newcommand{\ls}{LibSerial\xspace}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Hyphenation. %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Bibliography style. %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\bibliographystyle{plain}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Title. %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\title{iRobot Create library communication library}
+\date{}
+\author{Thomas Moulard, the University of\\ Southern California (USC),
+ and iLab at USC}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Document. %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{document}
+
+\frontmatter
+
+% Title
+\maketitle
+
+% Copyright notice.
+\chapter*{Copying this document}
+Copyright \copyright{} 2008 Thomas Moulard, the University of Southern
+California (USC), and iLab at USC.
+
+Permission is granted to copy, distribute and/or modify this document under
+the terms of the GNU Free Documentation License, Version 1.2 or any later
+version published by the Free Software Foundation; with the Invariant Sections
+being just ``Copying this document'', no Front-Cover Texts, and no Back-Cover
+Texts.
+
+A copy of the license is provided in the file COPYING.DOC.
+
+\mainmatter
+
+% Table of content.
+\tableofcontents
+
+% Content.
+\input{introduction}
+
+%\part{Getting started}
+\input{installation}
+\input{tutorial}
+\input{faq}
+
+
+% Bibliography.
+\bibliography{userguide}
+
+% Listings list.
+\lstlistoflistings
+
+\input{remote-control-example}
+
+\end{document}
+
+%%% userguide.tex ends here.
PGP.sig
Description: This is a digitally signed message part
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Libirobot-create-patches] libirobot-create b1e17b8: Add user manual,
Thomas Moulard <=