If you have never run RP1 before, these notes should help you get started. The Rossum's Playhouse robot simulator is a work in progress. Consequently, the installation and operation of the program requires a little more work than a mature software package. But installing and running the program is not difficult. It can be summarized in three steps:
These notes also include information about two of the standard demos.
The RP1 robot simulator is written in Java. While you do not have to know Java in order to experiment with the simulator, you do have to have Java installed on your system.
Fortunately, there are plenty of places to get Java free of charge. For example, you can download it from the web. Two obvious sites are IBM which supports several operating systems (including a good JDK for Linux) and Sun Microsystems. Most of the free downloads do not provide fully featured Integrated Development Environments (IDE)... after all, they are free. They do, however, provide enough to let you run, complile, and even debug Java applications.
If you are new to Java, the RP1 Users Guide provides a very brief introduction to Java that introduces the major ideas. If you are interested in learning more about Java, there are a vast number of books on the subject. Unfortunately, most of them are not very good. So you should exercise some caution before making a purchase. There are several good web sites offering Java tutorials and other introductory material. Some of the best are offered by Sun Microsystems, which originally developed Java, and the IBM Corporation, which has made a substantial investment in Java technology. Here are some links to material we've found useful:
As with any other web resource, these links are subject to change. If you cannot find them, try visiting Sun’s main Java site at http://java.sun.com or the IBM site at http://ibm.com. Beyond that there are many, many other introductions, special-topic discussions, and tutorials on the web.
Java comes in two flavors. The Java Software Development Kit (SDK) includes a compiler, debugger, and other development tools. The Java Runtime Environment (JRE) includes only the minimal installation you need to run a Java application (program). If you don't plan on developing code in Java, then you will probably be content with the JRE. Certainly the JRE will save you download time.
Most of the Java downloads are pretty hefty (Sun's 1.4.2 Java SDK is almost 49 megabytes, its corresponding JRE just over 14). An alternative to getting Java on the net is to find it on CD. Since the JDK is free, some of these can be had quite cheaply. Naturally, vendors who offer Integrated Development Environments (IDE's) will charge more. If you want a simple JDL, you might also try the bookstore. I got my first JDK off a CD which was included with Horstman and Cornell's introductory text Core Java.
Anyone offering a Java download will also provide instructions for installing it. They will almost certainly do a better job of telling you how to configure your system than I could. I do recommend that, before you run the RP1 simulator, you try one of the vendor's demo's to verify that you have installed Java successfully.
The oldest version of Java we are currently using to test RP1 is 1.3. Although we no longer test on older versions, we believe that is will still work on versions as old as 1.2. In future releases of RP1, we may be depending on more recent versions of Java.
Once you have Java installed on your system, you are ready to download and unpack RP1.
First off, we should note that unpacking the downloaded archives is not absolutely necessary. You can run the RP1 application directly from the Java .jar or .zip files you download. The only problem is that you can only do that from a command-line interface (such as the Windows "Run" menu or a Linux terminal window). If you don't mind running from the command-line, you may skip the unpacking step. Of course, if you do want to look at the source code or other material included in the release, you will have to unpack the archive.
The first thing you should do before unpacking the archive, is to create a directory (folder) into which you wish to store it. We use usually name our download directories after the release, such as "RP1_060" for RP1 release 0.60. Placing all of the code and binaries into a single directory makes it very easy to remove the material from your system if you ever wish to do so. Removing the directory removes the RP1 software cleanly from your system (no uninstall procedure is required).
There are many extractors that can be used to unpack the contents of a .zip archive. If you have downloaded the .zip archive of RP1 (sim060.zip or lite.zip), you may use one of these (Winzip is one candidate). The RP1 distribution requires about 1 megabyte of disk space.
Java also supports its own archive format, the ".jar" file (for "Java
Archive"). The advantage of .jar files is that, just as Java is
intended to be portable across a variety of architectures, so is the
Java jar utility. If you have installed a version of Java on your system,
you will have also installed a version of jar. So if you are on a system
which does not have a .zip utility, you may
prefer to download the Java archive version of RP1 (sim060.jar) and
unpack the code from the command-line using the following command:
jar -xf sim060.jar
The Classpath is a setting on your computer that tells Java where to find its resources. Setting it correctly is key to running the RP1 software. In Java, Classpath information is set using a system environment variable called "CLASSPATH". While the idea of setting environment variables may be new to some users, especially those running Windows (where environment variables are less common than under Linux and Unix), it is not difficult.
Your CLASSPATH variable needs to be set to either specifiy or include the directory (folder) where you unpacked your RP1 source code. For example, if you dumped the contents of the RP1 jar file (or zip file) into a directory called RP1_060 on your C disk, your CLASSPATH would include the string "c:\RP1_060". A Java Classpath can be set to include multiple specifications and you can set it to refer to RP1 without interfering with other settings on your system.
Sun Microsystems has set up helpful web pages describing the process of Setting the Classpath. If you are running an Integrated Development Environment (IDE) that supports Java (such as Borland's JBuilder), you will find a Classpath setting as part of the IDE's "project" specifications. Under Windows XP, you can set it using the dialog under the Start menu by going to "My Computer/System Information/System Properties" and clicking on the "Advanced" tab. If you wish to make multiple entries for the CLASSPATH environment variable under Windows, separate the path specifications with semi-colons (under Unix/Linux, use colons).
To learn more about the ideas behind the Classpath (and perhaps resolve
some confusion in how to set them on your system), you can refer
to
How Classes Are Found at the Sun Microsystems web site.
Step 4: Running Rossum's Playhouse
Once you have unpacked the archived software, you are ready to run RP1.
Rev 0.60 simplifies the process of running the RP1 demo. You may run them either from an windowed environment (using Windows Explorer or the equivalent), from the "Run" dialog under the Windows Start menu, from a Linux/Unix terminal, or from a Windows DOS-style command prompt.
If you don't care for command-line interfaces, then you can run RP1 using Windows Explorer or the equivalent... You will, however, have to unpack the software archive first. One you unpacked the archive, look in the main folder for files called FireFighter.bat and LineTracker.bat. Double-clicking on these scripts will launch different RP1 demo applications (see "Interacting with the Demos" below).
If you have unpacked the software archive, change your directory to the main RP1 directory. From there, you may run the FireFighter.bat or LineTracker.bat scripts (which should work on most systems) or type the commands:
java rp1.Server -p FireFighter.ini
java rp1.Server -p LineTracker.ini
to launch the Fire-Fighter or Line-Tracker demos, respectively.
If you have not unpacked the archive, you may run the demo's using the commands:
java -classpath sim060.jar rp1.Server -p FireFighter.ini
java -classpath sim060.jar rp1.Server -p LineTracker.ini
The commands above will also work for .zip files. The file name
following the -cp option should be a valid path for the archive
file.
The demonstrator applications supplied with RP1 are intended to illustrate
the use of the system and provide code examples for developers. Therefore,
their implementation has been kept simple. Naturally, a complete set of
source code is provided.
Demo 1: The Trinity College Fire-Fighting Home Robot
|
The illustration at the left shows the Floor Plan for the
Trinity College
Fire-Fighting Home Robot Contest. The Server (simulator)
reads the floor plan at start up. By default, the Server
runs with a Graphical User Interface (GUI). If you are running
time trials or wish to treat the Server as a background process,
you can suppress the GUI by adjusting options in the RP1
properties file (see the
Users's Guide for more details.)
The simulated robot in the lower-left section of the display was uploaded by the client application when it connected to the Server. Although the Server provides a virtual world, the inhabitants of that world are provided by the client applications. The red circle with the letter "F" indicates the target, a candle representing the fire which the robot contestant is to extinguish. The green "homeplate" represents the home placement, the robot's starting position. |
|
The image to the right shows a simple control panel from the Demo
application provided with RP1. The fields to the right show the robot's
current disposition, those to the left provide rudimentary control.
Because it is intended as an example, the Demo application has been kept
to a minimal level of complexity.
In the display, the Choice Box is set to the Line Track option. In addition to Line Track, there are two other options: Curve Track and Auto Pilot. In Auto-Pilot mode, the robot navigates the floor plan use a network of roads and intersections that it downloads from the Server. In the Line-Track and Curve-Track modes, the robot responds to mouse clicks from the Server, allowing you to control its behavior. |
|
The use of mouse clicks is, of course, highly artificial. The RP1 simulator is intended to model real-life behavior of robots. Naturally, there is no real-life equivalent to a mouse-click event. RP1 supports mouse-clicks only as a testing and development aid. In the Demo application, the client requests that the Server send it mouse click events and interprets them as follows:
| Left Button |
Move robot simulacrum toward click point.
In line-track mode, the orientation of the robot does not change... it moves in the general direction of the mouse click, but not necessarily to the click position. In curve-track mode the robot follows a circular path toward the click point. It's final orientation will probably not be the same as if it had executed a pivot and faced the click point before beginning the motion. |
|
| Right Button | Pivot the simulacrum to face the click point. |
The definition of mouse-clicks in the Demo application is completely
arbitrary and should not be interpreted as recommended practice.
Feel free to implement your own applications as you see fit.
Demo 2: The Line-Following Robot
|
Line-following robot contests are popular in North America and Europe.
These robots are relatively simple and inexpensive implementations
which are designed to follow a track using optical or infrared sensors.
This example hows how the RP1 simulator might be used to evaluate logic
and physical layout for line-following robot applications.
A typical line-follower implementation features a pair of sensors that staddle a fixed-width track. When one sensor detects a change in intensity of relected light (indicating that it has crossed into the track area), the robot turns toward that sensor in an attempt to follow the curve. More elaborate implementations may feature multiple sensors. |
The floor-plan for the line-following robot demo shows an application of RP1's "Paint Sensor" capability. In RP1, a paint sensor is a downward looking sensor that can detect markings on the floor. The robot shown in the figure above features two sensors mounted near its front. The sensor to its right is shown in yellow, indicating that it is "hot" (has a detection). At the time this image was captured, the robot was rotating anti-clockwise and attempting to slow down its turn rate so that it would not oversteer the curve.
Frankly, the logic for this demo isn't very good. It was intended as a proof-of-concept and kept very minimal. Perhaps you can revise it to improve the robot's performance, speed, and accuracy. That is, after all, what an open-source project is about...