TeamBots^TM 2.0

The latest release is version 2.0e, built on 14 April 2000 (download).

In this document:

• Introduction
• Key features
• Example domains
• Application programs
• How to install
• Troubleshooting
• Documentation
• Compatibility and Customization
• Getting Help
• Website

Related information:

• Teambots credits and acknowledgments.
• TeamBots Users and Links
• The TeamBots FAQ
• Release Notes

TeamBots is a Java-based collection of application programs and Java packages for multiagent mobile robotics research. The TeamBots distribution is a full source-code release. The simulation environment is 100% Java. Execution on mobile robots sometimes requires low-level libraries in C, but Java is used for all higher-level functions. At present, TeamBots will run on the Nomadic Technologies' Nomad 150 robot and (very soon) on Personal Robotics' Cye robot.

TeamBots supports prototyping, simulation and execution of multirobot control systems. Robot control systems developed in TeamBots can run in simulation using the TBSim simulation application, and on mobile robots using the TBHard robot execution environment.

This is the root page for all TeamBots software. The complete documentation package is also included with the TeamBots distribution (this file is index.html in the root directory).

Provided proper acknowledgement is given, TeamBots may be used freely for education and research. Commercial use is permitted provided the user does not profit from the TeamBots software itself. Other uses are not permitted without written permission. The "TeamBots" trademark is owned by Tucker Balch. Please see the copyright.html file for detailed copyright and trademark information.

One of the most important features of the TeamBots environment is that it supports prototyping in simulation of the same control systems that can be run on mobile robots.

Real-time Control of Mobile Robots The TBHard application can be used to control Nomadic Technologies' Nomad 150 robots. These robots, Lewis and Clark, won the multiagent "Find Life on Mars" event at the AAAI-97 Mobile Robot Competition using TeamBots software. Support for Probotic's Cye robot is under development.	Simulation The same control systems can be tested in simulation and run on mobile robots. In this simulation two Nomad 150 robots (black) forage for red and blue attractors, which they collect and return to the color-coded bins. They are running the same control system used on Lewis and Clark.

The TeamBots simulation environment is extremely flexible. It supports multiple heterogeneous robot hardware running heterogeneous control systems. Complex (or simple) experimental environments can be designed with walls, roads, opponent robots and circular obstacles. All of these objects may be included in a simulation by editing an easily understandable human-readable description file.

Because the software is written in Java, it is extremely portable. TeamBots runs under Windows9x, Linux, MacOS and any other operating environment supporting Java 1.2 or later.

Concerns about Java: some researchers are concerned that Java is too slow to support real time robot control. Our experience contradicts this conclusion. As an example, in simulation (without graphics) our Java coded behavior-based control systems run at up to 30 KHz rates on conventional 200 MHz Pentium machines. The primary bottleneck to runtime efficiency on real robots is sensor and control I/O. On Nomad 150 robots for instance, we are limited to 10Hz control rates because this is the maximum rate control commands can be transmitted to the robot (control programs written in C cannot run any faster). In our experience the benefits of Java (correctness, ease of use, rapid development) far outweigh the negligible runtime overhead.

The TeamBots distribution includes several example systems that can run in simulation. They are included in the Domains subdirectory.
• Cye: this is a simulation of Probotic's Cye robot.
• SoccerBots: this is a simulation of RoboCup F-180 league soccer.
• Book: includes example exercises being developed for the book Designing Robot Behavior by Tucker Balch. These are primarily for the illustration of principles of behavior-based control.
• CTF: an implementation of Capture-The-Flag, a multiagent adversarial game.
• Forage: a basic implementation of multiagent foraging.
• ForageAAAI97: the actual source code used to win the AAAI-97 mobile robot competition.
• Roads: two example uses of simulation environments including roads. One example includes two different types of roads and a bridge. The other is an entire city map. Any arbitrarily comples environment including different traversablility constraints can be built.
• Walls: an example simulation environment with walls.

Four application programs are included in the TeamBots distribution:
• TBSim: the TeamBots simulator.
• TBHard: the real robot execution environment for control systems developed using TeamBots.
• RoboComm: RoboComm simplifies asynchronous robot to robot communication. Any Java object can be sent from one robot to another. The RoboComm server forwards messages between agents.
• JCye: These programs demonstrate how to use our Java package to control a Cye robot.

Note: these instructions are the same as for installing SoccerBots. If you install TeamBots, you have installed SoccerBots as well. If you are installing JCye, the instructions are a little bit different; go to the JCye installation instructions.
1. Required software: make sure you have Java 1.2 or later installed on your computer. The distribution will not run with earlier versions. If you have Java, but aren't sure of the version, type "java -version". You also need unzip to unpack the distribution. You will need gmake if you want to modify and recompile using the included makefiles.

2. Make a directory for the distribution (we'll call it tb).

3. Put the distribution (TeamBots.zip) in the directory.

4. unzip TeamBots.zip . Don't use the "-a" option, sometimes unzip will confuse class files as text. If, later on you find the source looks garbled, try 'unzip -a TeamBots.zip "*.java"' to just unzip the source. Not sure if Winzip supports this (if you have trouble, get the real unzip).

5. Set your CLASSPATH environment variable to point to the directory where you unzipped the distribution. So, for example, if you installed the distribution in /home/you/java and you use csh you would set CLASSPATH with the following commands:

           setenv CLASSPATH /home/you/tb:.
           setenv CLASSPATH ${CLASSPATH}:/home/you/tb/lib/collections.jar
           

   Note the "." on the end. This is important. Other shells and/or operating systems use similar commands to set the CLASSPATH.

   In Windows you can set the CLASSPATH by editing your C:\AUTOEXEC.BAT file as follows:

           SET CLASSPATH=C:\tb;C:\tb\lib\collections.jar:.
           

   You will probably have to reboot your machine before this command takes effect.

6. Run a few of the simulation demos.

           cd /home/you/java/SoccerBots
           ./demo
   
   	cd /home/you/java/Cye
   	./demo
   
   	cd /home/you/java/Forage
   	./demo
   
   	cd /home/you/java/Roads
   	./citydemo
           

Before attempting to troubleshoot TeamBots, make sure your computer is turned on. If that does not solve the problem, try this set of common solutions:

1. If you get the error message:

          Can't find class forage
   

   or something similar when you try to run the demos, your CLASSPATH probably does not include "." Try Step 5 of the installation again.

2. If you get the error message:

          java.lang.NoClassDefFoundError: TBSim/SimulationCanvas
                  at TBSim.TBSim.(TBSim.java:79)
                  at TBSim.TBSim.main(TBSim.java:199)
   

   Your CLASSPATH may not point properly to the /home/you/java directory. Try Step 5 of the installation again.

3. If you get the error message:

          error:  zipfile probably corrupt
   

   while trying to unzip the distribution, you probably either got a bad copy while downloading, or your version of unzip is too old. Unzip v5.12 works properly while v5.1 has been known to complain, but still unpack the distribution. The distribution was compressed with Zip v2.1, please let me know if you have this problem.

4. If you get the error message:

          Can't find class TBSim.TBSim
   

   then your CLASSPATH probably doesn't point properly to the /home/you/java directory. Try Step 5 of the installation again.

5. If you get the error message:

          Interface EDU.cmu.cs.coral.util.Collection of interface EDU.cmu.cs.coral.util.PriorityQueue not found.
   

   You are using a version of the JDK older than 1.2. You can either: install 1.2, or edit the source code to reference the collections jarfile (comments in the code will help you).

6. If you get the error message:

          java.lang.NoClassDefFoundError: TBSim/SimulationCanvas
                  at TBSim.TBSim.(TBSim.java:79)
                  at TBSim.TBSim.main(TBSim.java:199)
   

   Your CLASSPATH may not point properly to the /home/you/java directory. Try Step 5 of the installation again.

   This might also be caused by a corrupted download or unzip operation. Try getting a new copy of the distribution from the webpage or just unzipping again. You may have unzipped with the "-a" option, try it without.

7. If you get the error message:

          Unable to initialize threads: cannot find class java/lang/Thread
   

   then you are probably running Java 1.0.2 instead of Java 1.2.
   You can check that by typing "java -version".

8. If you get the error message:

          ./demo: java: not found
   

   make sure java is in your PATH somewhere, and that Java 1.2 is installed on your system.

9. If the program runs but the source code looks like gibberish, try unzipping again using the -a option (Step 4). This option may not be available on older versions of unzip or on WinZip. I suggest you get the real unzip.

10. Finally, try typing the contents of the demo file directly as a command line:

           java TBSim robocup.dsc 511 300
    

Nearly all the software is written in Java. Standard Java coding practices and conventions apply. Our development environment is RedHat Linux, but we have compiled and tested the software on Windows9x as well.

To make compiling with dependencies little easier, the distribution includes a gmake-based Makefile with the following functionality:

• make all To compile all Java. This is may not even necessary since the distribution includes Java 1.2 binaries.
• make clean To remove all junk not necessary to run programs.
• make documentation To javadoc-ify

For more information on how to develop code for TeamBots, see the README.developer file.

Currently TeamBots is documented primarily using javadoc. A more complete user guide is a future goal. Here are links to the javadoc-generated documentation:
• All Packages
• TBSim Simulation application in which abstractrobots can operate and be evaluated.
• TBHard Application in which abstractrobots can operate in the real world.
• SoccerBots Specialized version of TBSim for RoboCup soccer.
• clay Behavioral configuration system.

If you have any problems, send email to trb@cs.cmu.edu and I'll see what I can do.

The official TeamBots website address is http://www.teambots.org.