--------------------------------------------------------------------- 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.