
  ---------------------------------------------------------------------
  MobileRobots Inc. Advanced Robot Navigation and Localization Software
  ---------------------------------------------------------------------

Copyright (c) 2004, 2005 ActivMedia Robotics, LLC. 
Copyright (c) 2006, 2007, 2008, 2009 MobileRobots Inc.
All rights reserved.
The license for use of this package is described in the LICENSE.txt file.


******************************************************************************
  Important Note for release version 1.5:                                
******************************************************************************

As of version 1.5, ARNL now uses the general robot acceleration,
deceleration and rotational velocity parameters to perform more accurate
path following. However, this means that your existing configuration must
be updated.  If rotational acceleration or deceleration, translational 
acceleration or deceleration, or rotational velocity maximum
are too low, the robot will drive more slowly than neccesary, especially
when turning; Some recommended values to try are max. rot. vel of 250,
rot. accel. of 300, rot. decel. of 300, trans. accel. of 600, trans. decel.
of 600, then adjust as neccesary.  Either the "Driving..." parameters
in "Path Planning Settings", or the ARCOS firmware parameters may be set. 
See Changes.txt for more discussion of this issue. 

******************************************************************************


Contents
========
  Introduction
  Quick Start
  Windows Installation
  Linux Installation
    Using the Correct Compiler
    Installing GCC
    Installing the Debugger
  Java and Python

  

Introduction
============

ARNL is the Advanced Robotics Navigation and Localization extension
to ARIA, MobileRobots' Advanced Interface for Applications software
development kit. All required components of ARIA and ArNetworking for
working with ARNL are included within this ARNL distribution (header
files, libraries, etc.)  Note: ARNL has been built with this version 
of ARIA; do not compile with a separate ARIA distribution.

This document provides essential information for using the ARNL software.  
More detailed reference manuals are available in the "docs" directories
of the software packages.  Manuals that provide an overview of using
the ARNL, MobileEyes, mapping software and robot together, including 
information on adding a SICK laser rangefinder to an existing robot if 
neccesary, also available as a printable PDF document from 
http://robots.mobilerobots.com/all_docs.

MobileRobots Inc's robot navigation software is provided as several 
seperate libraries.  The exact set of libraries that you have will
depend on which navigation package option your purchased.

BaseArnl:
  * All packages include the BaseArnl library. This library includes
    the path planning and following task, and a general infrastructure
    for running one or more localization methods. It also includes 
    ARIA and ArNetworking libraries licensed for use with ARNL, and
    of the correct version. 
  * On Linux, it is installed at /usr/local/BaseArnl
  * On Windows, it is installed at Program Files\MobileRobots\BaseArnl

Arnl:
  * The indoor laser navigation package includes the "Arnl" library.
    This library provides a localization method that uses a laser 
    rangefinder to localize the robot in a map.  It must be used
    together with the BaseArnl, Aria and ArNetworking libraries.
  * On Linux, it is installed at /usr/local/Arnl
  * On Windows, it is installed at Program Files\MobileRobots\Arnl

Mogs:
  * The outdoor navigation package (MOGS) includes the Mogs library.
    This library provides a localization method that uses data from
    the GPS to localize the robot.  It must be used together with
    with the BaseArnl, Aria and ArNetworking libraries.
  * On Linux, it is installed at /usr/local/MOGS
  * On Windows, it is installed at Program Files\MobileRobots\MOGS

SonArnl:
  * If you do not have one of the above optional navigation packages,
    you can use SONARNL.  The SonArnl library provides a localization
    method that uses the sonar to do approximate localization in a
    mapped area.  SONARNL is also available with the other package
    options.  It must be used together with with the BaseArnl, 
    Aria and ArNetworking libraries.
  * On Linux, it is installed at /usr/local/SonArnl
  * On Windows, it is installed at Program Files\MobileRobots\SonArnl

In addition to the ARNL packages, you'll need Mapper3(TM) to
create maps for your robot for use with ARNL or Mapper3Basic(TM) to
create maps for your robot for use with SONARNL. And for a remote GUI,
use the MobileEyes(TM) application, also downloadable as a separate
package. Find links to all these components from the robots support
website at:

     http://robots.mobilerobots.com

In the docs directory of each library, you will find the reference
manual for the libraries.  Programming examples are in the examples/
directory (see the README in that directory for directions).  The
include/ directory contains files for ARNL as well as for ARIA and
ArNetworking.  The required ARNL, ARIA and ArNetworking libraries are
in the lib/ directory.  In src/ there is the ArServerClasses file that
shows ways of controlling the robot.

Specially note the params/arnl.p and params/sonarnl.p files (for ARNL
and SONARNL repsectively). One is loaded at startup and used by
ARNL/SONARNL for localization and path planning.  Modify the file to
tailor ARNL/SONARNL and your robot for its operating behaviors and
environment.  There also is a backup copy of these parameters in
params/default-arnl.p and params/default-sonarnl.p.  arnl.p and
sonarnl.pcan be edited from MobileEyes(TM) with a GUI that can also
restore sections from the default.

A special section describing ARNL installation on a Linux-based system
is at the end of this README.  If developing Linux-based ARNL
programs, make sure you read and follow those directions or ARNL
simply won't work or it will give you odd crashes.

For Windows you must use Microsoft Visual C++ .net 2003 for compiling
your projects as this is what the library was built with.

Quick Start 
===========

To localize and plan navigation paths, ARNL and SONARNL need a map of
its operating environment. Although easy to do, it takes some time to
make and edit a map. Instead, you could also use MobileSim
with sample maps provided in Arnl/examples to quickly see how the
various ARNL, ArNetworking and MobileEyes components work.

MobileSim is in a seperate distribution.  Sample maps are in the
Arnl/examples directory. For example, with Linux (requires X-Windows):

% cd /usr/local/MobileSim/
% ./MobileSim -map /usr/local/Arnl/examples/columbia.map

Like ARNL with Windows, MobileSim typically gets installed in
C:\Program Files\MobileRobots\MobileSim.  At startup the
simulator will ask you which map to use or if you want to use no map
and offer you a dialog box to choose the map.  At startup you may also
choose a different robot other than the Pioneer DX.  There are also
command line arguments, see much more details in the MobileSim docs.

Detailed instructions for making maps with your real robot are in
docs/Mapping.txt for ARNL and docs/SonarMapping.txt for SONARNL.  

To operate your robot (or simulated one) through MobileEyes with ARNL,
start the ARNL guiServer application, passing it, as an argument, the
map name.  For example:

% cd /usr/local/Arnl/examples
% ./guiServer -map columbia.map

Or for SONARNL:

% cd /usr/local/Arnl/examples
% ./guiServerSonar -map columbia.map

Make the proper path and filename substitutions as needed for your own
maps, of course. The guiServer automatically connects with the
simulator, if it is running on the same machine, or will connect with
your robot's controller, if it is attached to the default serial port.

Now start MobileEyes from the same computer or elsewhere on your
LAN. MobileEyes communicates with your ARNL/ArNetworking-enabled robot
via TCP/IP networking even if they're all run on the same computer. So
when MobileEyes starts up, you need to tell it where the robot's
network server is located: Type in or click to select from the
adjacent drop-down menu, the Server Name for the network location of
the robot's computer. The Server Name is either an IP address, such as
"192.168.100.1", or a hostname ("pioneer" or "pioneer.local.net", for
example).  If the robot server is running on the same machine as your
MobileEyes, as might be the case with the simulated robot, simply
enter "localhost" as the hostname.  (Hostnames and IP addresses, once
entered, get stored automatically into MobileEye's drop-down list of
Server Names.)

Now click the Connect button to access the robot over the
network. With the real robot, MobileEyes won't connect until the
robot's laser is fully powered up.  So you might have to Wait a few
moments before trying to connect again.

The first thing guiServer does in response to a MobileEyes connection
is send out its map, which subsequently appears in the MobileEyes
display.  Thereafter, you may send your robot from its current
position to some goal that had been embedded in the map by
double-clicking the goal's name in the goal box at the left of the
MobileEyes display. Otherwise, click to highlight the goal name, and
then click the Go To button to have your robot plan a path and
automatically drive to that goal.

Further explore the MobileEyes application features to manually drive
your robot with the keyboard or from a joystick. Click in the map
directly to have your robot drive to that spot, if it can get there
from here, of course. MobileEyes displays the ARNL-planned path as
well as the localization points showing where ARNL thinks the robot
is.  ARNL will let you know if its robot gets lost. That should be
very rare, but happens, for instance, if you start your robot up
somewhere other than near its map HOME. Use the Tools: Robot Tools
Localizing features to reorient the robot.

For ARNL (ie with a laser) the easy way to make a map is to connect
with MobileEyes and then select 'Tools->Map Creation->Start Mapping'
and give it a file name, then drive the robot around, and then stop
mapping by selecting 'Tools->Map Creation->Stop Mapping'.  This map
won't be as good as other methods, see docs/Mapping.txt for more
information.  After stopping mapping you can start up Mapper3 and
'Open From Robot' and connect and then turn the .2d into a .map, edit
it, and 'Save to Robot' the file back onto your robot and then use
'Tools->Robot Config' to change your map file to your new map.

For SONARNL (ie just with sonar) you'll need to start up Mapper3Basic
and then select 'New Map' and then create a map yourself with a tape
measure.  Note that if you have a robot with a laser a map created
with the most recent Mapper3 will contain the line information needed
to use SONARNL and in a much easier fashion than making a map by hand.

NOTE: the default guiServer will allow you to make maps and put and
get files from the example directory, if you do not wish this to be
possible modify the guiServer code (search for ArServerFileLister).

You can also start up guiServer with an option for using user and
password information to allow connection.  To do this you should edit
examples/guiServer.userInfo and change the '.' for passwords to the
password you wish and then pass guiServer an additional '-userInfo
guiServer.userInfo' argument.


Windows Installation:
=====================

If you have a previous version of *either* ARNL or SONARNL, 
uninstall it now. 

Run the installer program to install ARNL or SONARNL in 
C:\Program Files\MobileRobots\Arnl.  Find shortcuts
to useful files and directories in the Start menu as well.

ARNL will only work as distributed with Microsoft Visual C++ 
version 7 (Visual Studio 2003).

To use Visual C++ 8 (Visual Studio 2005), rename the "bin" directory
to "bin-vc7", rename the "lib" directory to "lib-vc7", rename the
"bin-vc8" directory to "bin", and rename the "lib-vc8" directory
to "lib".  To build the example programs using VC8, you must install
the seperate Windows Platform SDK.  Open the  examples.sln file, and 
allow VC8 to convert the project files.  Then add the Platform SDK
include and lib directories to VC8's includes and libs directories
in its Options dialog.


Linux Installation:
===================

If you have a previous version of *either* ARNL or SONARNL, 
uninstall it now.  You cannot install both ARNL and SONARNL packages.
If you are upgrading from SONARNL to ARNL, uninstall SONARNL. ARNL
includes both the ARNL and SONARNL libraries, header files, etc.

-> On RedHat Linux, install the ARNL or SONARNL RPM package with the rpm tool.
   For example, "rpm -i ARNL-x.y-z.i386.rpm"

-> On Debian Linux, install the libarnl or libsonarnl DEB package with the dpkg tool.
   For example, "dpkg -i libarnl_x.y.z_i386.deb"

-> On other Linux systems, download the compressed TAR package (.tar.gz file).
Unpack with TAR (e.g. "tar -xzf ARNL-1.4-0.tar.gz"), enter the new directory
created, become the root user with "su", then run "make install" to install
Arnl in /usr/local/Arnl. Follow any additional instructions given by
"make install". 

To uninstall, use the rpm tool on RedHat (e.g. "rpm -e ARNL"), apt-get or synaptic
on Debian (e.g. "apt-get remove libarnl"), or rename or remove /usr/local/Arnl if you installed it manually
with "make install".


Using The Correct Compiler
--------------------------

The Arnl and SonArnl libraries were built with GCC 3.4.1, so you MUST use a
compatibile version to build C++ programs that use those libraries.
Other versions of gcc that are version 3.2 or newer MAY work but are not 
supported, versions earlier than 3.2 won't compile.

To check your current version use this command:

  g++ -v

To install GCC 3.4.1, either use your Linux distribution's prebuilt g++-3.4 
package, or download its source code archive from http://gcc.gnu.org.

You may have several versions installed with different command names, e.g.
gcc-3.2, g++-3.3, g++-3.4.  You can use "alias" in you shell to assign 
g++-3.4 to be invoked as "g++"; or change gcc, g++ and cpp symlinks if 
they exist; or set environment variables named CXX and CC in your shell 
to be used by 'make'.

Installing GCC from Source Code:
--------------------------------

This is a summary of the GCC installation instructions:

Become a superuser, and untar the archive into
/usr/src or other directory (*not* /usr/local):

# cp gcc-3.4.1.tar.bz2 /usr/src/
# cd /usr/src
# tar -zxvf gcc-3.4.1.tar.gz
(creates /usr/src/gcc-3.4.1/...)

According to the gcc documentation, you compile the gcc sources into
an adjacent "gcc-build" directory, and then install the gcc
executables and libraries into a third directory--the one you'll
eventually reference to make ARNL applications.

Assuming you are still in /usr/src, create, then enter the build directory:

# mkdir gcc-build
# cd gcc-build

Now configure gcc, compile its sources into that build directory, only
have it build c and c++ languages and install the results into a
third, working directory:

# ../gcc-3.4.1/configure --enable-languages=c,c++ --prefix=/usr/local/gcc-3.4.1
# make
# make install

To have that version of gcc be your default compiler, make its bin/
directory the first entry in your PATH environment variable, typically
by inserting it into your personal ~/.bashrc or into the system-wide
/etc/bashrc:

export PATH=/usr/local/gcc-3.4.1/bin:$PATH

You also need to have the libraries with this version of gcc be the
ones that are used with your application which you can do by setting
your LD_LIBRARY_PATH environment variable, typically by inserting it
into your personal ~/.bashrc or into the system-wide /etc/bashrc:

export LD_LIBRARY_PATH=/usr/local/gcc-3.4.1/lib:$LD_LIBRARY_PATH

Log out, then log back in again and check to see what gcc version you're using:

# gcc -v

If you want to make sure that your executable will be using the right
libraries from the right places then use the ldd command to check:

# ldd /usr/local/Aria/examples/demo

The libraries used for libgcc_s.so and libstdc++ should be the ones
from /usr/local/gcc-3.4.1/lib.. so the output should have something
like these two lines (the numbers in parentheses don't matter):

ibstdc++.so.6 => /usr/local/gcc-3.4.1/lib/libstdc++.so.6 (0x40192000)
libgcc_s.so.1 => /usr/local/gcc-3.4.1/lib/libgcc_s.so.1 (0x40295000)



Installing the debugger:
------------------------

You may not need to install a debugger if the debugger on your system
works, however if you have an older system your debugger may not work
with the new gcc and so here are instructions on installing a new
debugger.

If you do need a new debugger we have found that gdb 6.1.1 works,
you'll want to compile it with gcc-3.4.1 (see above for installation
instructions).

To install a new gdb, download its sources archive from
http://www.gnu.org/software/gdb/gdb.html 

Become a superuser, and untar the archive into /usr/src or other
directory, just *not* /usr/local:

# cp gdb-6.1.1.tar.bz2 /usr/src/
# cd /usr/src
# tar -zxvf gdb-6.1.1.tar.gz
(creates /usr/src/gdb-6.1.1/...)

Now go into the gdb directory and then configure gdb, having it
install the results into a second, working directory:

# cd gdb-6.1.1 
# ./configure --prefix=/usr/local/gdb-6.1.1
# make
# make install

To have that version of gdb be your default debugger, make its bin/
directory the first entry in your PATH environment variable, typically
by inserting it into your personal ~/.bashrc or into the system-wide
/etc/bashrc:

export PATH=/usr/local/gdb-6.1.1/bin:$PATH



Java and Python
===============

ARNL and SONARNL include "wrapper" libraries, which provide an interface
layer between a Java or Python API and the native C++ library, allowing
you to access the ARNL or SONARNL library enirely from the Python or Java
language. The APIs in those languages are very similar to the native
C++ library.  The Java wrapper library can be found in the 'java' subdirectory,
and the Python wrapper library (module) can be found in the 'python' 
subdirectory. For example programs and details on setting up your Java or 
Python environment to use the wrapper libraries, see the 'javaExamples' or 
'pythonExamples' directory.





