New Page 1

This is a guide to installing and setting up the software for the RCX Camera Controller. The system has been designed to be fairly platform independent, and should be able to run on both Linux and Windows. However, we have only used the system under Linux and thus are not able to offer any tips or advice for setting it up under Windows.

2 System Requirements

We ran the system on an Intel 1.8 GHz Pentium 4 processor, 512 MB RAM, running Red Hat Linux 7.2 (kernel release 2.4.18). Obviously you will also need a webcam (we used a Logitech webcam) in order to be able to use any of the imaging functionality.

3 Overview of Installation Process

4 Obtaining & Installing Required Software

Before our system can be used, the required software (Java SDK, JMF, LeJOS) needs to be installed. These softwares are not made by us, and so we have provided links to the relevant websites from which you will be able to download the required files and also find instructions. We have also provided some of our own additional instructions in order to help you.

Java SDK 1.4

As all of the source code for the RCX Camera Controller (RCX-CC) is written in Java, you will need the Java^TM 2 Platform Standard Edition (J2SE) environment installed on your computer in order to be able to compile and run all the necessary programs. We used the Java SDK v1.4. You can download and install the latest J2SE platform for your particular operating system, which is provided for free by Sun Microsystems © from:

This is the official web site for Java technologies and it provides installation and help guides, tutorials and frequently asked questions (FAQ) pages.

To be able to run the camera imaging component of the this software, which includes image streaming and capture, you will also have to download and install the Java Media Framework API (JMF) package. It enables audio, video and other time-based media to be used by Java applications, and is extensively used in the RCX-CC software.

Comprehensive information on the JMF package and download and installation instructions can be found at:

Please note that before downloading the latest JMF Software release, you will be asked to select a download format. You MUST select the designated ‘Performance Pack’ for your specific operating system from the given choices. It is not advisable to choose the ‘Cross-platform Java’ format as it is does not provide functionality for any of the standard capture devices and has not been extensively tested.

· The JMF home directory is set using JMFHOME. Set this to the path where you installed the JMF.

· We need to add the JMF lib directory to the Java classpath, by adding $JMFHOME/lib/jmf.jar to the CLASSPATH.

· We need to the $JMFHOME/lib directory to the LD_LIBRARY_PATH variable.

Much of our software is based on leJOS, and so you will also need to install the latest version of the leJOS environment on your machine, as this is needed for programs that will be under execution with your Lego RCX. Download and installation instructions for both Windows and Linux are provided at:

This web site also provides documentation and support pages, with links to the aforementioned J2SE.

· The LEJOS_HOME variable should be set to the path to the directory where leJOS was installed.

· We need to add the leJOS binary files to the PATH so that they can be run from anywhere. The directory is a subdirectory of the leJOS main directory, called bin. ie. $LEJOS_HOME/bin

· We need let leJOS know the location of the IR tower, by setting the RCXTTY variable. This will vary depending where it is plugged in and whether it is a USB or serial version. Our tower was a serial version, plugged into COM1, which under Linux is represented by /dev/ttyS0 .

· In order to be able to compile Java files that use the leJOS pcrxcomm, we need to add the Jar file to the Java classpath, represented by the CLASSPATH environment variable. The file we need to add is: $LEJOS_HOME/lib/pcrcxcomm.jar .

· We also need to add the leJOS bin/libirtrcx.so library to the LD_PRELOAD. Be warned that if you stuff up this line then all other commands may not work (eg. ls, cat).

MATLAB

The software was designed such that Matlab (see http://www.mathworks.com) can be used as an interface tool between the user and the underlying Java implementations of the camera controller. This was done in view of Matlab’s considerable image processing and manipulation capabilities. It is strongly recommended (but not essential) that the user has the latest version of Matlab available for use to ensure the correct operation of the software.

We used Matlab version 6.5 for Linux. Matlab actually comes with its own Java Virtual Machine and support for running Java programs. The Matlab we used had version 1.3.1 of the Java Runtime Environment, which actually caused some problems, as some of the code we wrote used version 1.4 features.

While Matlab has the ability to run Java classes, we must explicitly tell it which classes to add to its classpath, so that they can be used. Normally, there is a text file called classpath.txt file, that resides somewhere in the Matlab directory, that tells Matlab exactly what Java packages to include for potential use. By adding the paths to other .jar’s to this classpath.txt file, we can allow the use additional Java classes.

Rather than modifying the existing classpath.txt file, copy it into the directory from which you will be working and running Matlab. Whenever Matlab is started, it checks the current directory and if there is a classpath.txt file present, it uses this instead of the default one.

1. Absolute path to the pcrcxcomm.jar file. This is in the lib directory in the leJOS directory.

2. Absolute path to the jmf.jar file. This is in the lib directory under the JMF directory.

3. Absolute path to the Jar archive that contains the compiled classes from our source code.

After compiling all the Java source files in the pc/ directory into .class files, you will need to create the .jar archive for (3) using the jar command.

Example: .zshrc file

The computer we were using for development was running Red Hat Linux 7.2 with the zsh shell, and so we placed the appropriate statements to set these variables in the .zshrc startup script (which is in the user’s home directory, and gets run each time you log in). Below is a section from our .zhsrc configuration file, containing the relevant lines of code. Note that your absolute paths will be different to the ones show here, this is simply an example to assist you. Note that we have installed leJOS to $PC307M/lejos, and the JMF to $PC307M/jmf, and no doubt these will be different for your installation.

# set the location of our groups directory on projects server

export PC307M=/home/projects/pc307m

# set the location of the lejos home directory

export LEJOS_HOME=$PC307M/lejos

# add lejos bin directory to the path

export PATH=$LEJOS_HOME/bin:$PATH

# set the location of the IR tower

export RCXTTY=/dev/ttyS0

# add lejos pcrcxcomm package to Java classpath

export CLASSPATH=.:..:$LEJOS_HOME/lib/pcrcxcomm.jar:$CLASSPATH

# leJOS libraries

export LD_LIBRARY_PATH=$LEJOS_HOME/bin

export LD_PRELOAD=$LD_PRELOAD:$LEJOS_HOME/bin/libirtrcx.so

# JMF stuff

export JMFHOME=$PC307M/jmf/JMF-2.1.1e

export CLASSPATH=$CLASSPATH:$JMFHOME/lib/jmf.jar

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JMFHOME/lib

Note: Because the software was developed under Linux, it was decided that we could provide some detailed help information in relation to certain operating system settings exclusive to Linux users. This is also due to the fact that detailed information is likely to assist users in troubleshooting potential problems and system errors, should they arise during installation or operation of the software.

Note: Although the RCX-CC software was developed and tested entirely in a Linux environment the platform independence of the Java programming language should allow you to work with the software equally well under a Windows based operating system. Please follow carefully the installation instructions for your particular operating system as given at the abovementioned web sites.

Also you should make sure that your system meets the minimum hardware specifications as outlined in the respective installation manuals.

5 Compiling and Running Our Code

Assuming all you have successfully set up your machine with all the required software (J2SE and JMF, leJOS, Matlab) you can proceed to download, compile and begin to use the RCX-CC program. Also note that at this point it is assumed that the robot

1 Download the source code, which is in the form of a TAR archive called rcxcam.tar.

2 Extract the TAR archive to an appropriate directory. It will create a subdirectory rcxcam/, which will contain three further subdirectories: rcx/, pc/, and matlab/, for the RCX code, PC code, and Matlab scripts respectively. .

3 The source code in the /rcxcam/pc directory needs to be compiled with the Java compiler. Typically you should invoke the following command at your command prompt:

This will generate all the required class files. If you receive an error on compilation, it will most likely refer to an incorrectly set class path variable. Note that some files compiled here need the pcrcxcomm library.

4 Ensure that the RCX is switched on and IR tower properly plugged into your computer. In order to be able to run our programs on the RCX, you will need to download the leJOS firmware onto it. Invoke the following command at the prompt:

You will see a percentage counter on the screen starting from 0% and increasing, once it has reached 100%, the RCX will beep. Now you can proceed to download the actual program to the RCX.

5 In the /camcontrol/rcx you we now compile, link, and download the code for the RCX brick. To compile the leJOS classes, invoke the following command at your command prompt:

This will generate all the class files for the RCX. Now we link these class files into a binary for the RCX. Type:

This will create RCX.bin binary file. Now we need to download the binary onto the RCX. Make sure the RCX has the firmware on it, and is on, and then invoke:

As with the previous step, once the download process is complete the RCX will beep. You are now ready to run the program by pressing the ‘Run’ button on the RCX.

6 At this point the system is basically ready for use. To use it from Matlab, you need to start Matlab from the matlab/ folder, which contains the classpath.txt file. You will then have the ability to create instances of our Java objects.

Note: If you encounter problems during steps 4 and 5, there are a number of causes to these and you should consult the leJOS web site for troubleshooting tips and hints as well as frequently asked questions. The most valuable advice we can give it to always make certain that the batteries in both the RCX brick and IR tower are relatively new. We encountered numerous problems during development only to realise it was because our batteries had become depleted. Also, communications to the RCX will fail if you have more than one program running that uses the IR port. For example, if you running a Java class that uses pcrcxcomm and instantiates an RCXPort object, you will get strange errors if you try to download the firmware.

1.	Install all necessary software, including Matlab, the Java SDK, the JMF, and leJOS. Set all these up as per instructions in the respective websites or manuals. This may involve setting environment variables.
2.	Download the leJOS firmware onto the RCX.
3.	Download our source code, which is in the form of a TAR archive, and extract it somewhere.
4.	Compile all the PC-side Java source code.
5.	Create JAR file from all the compiled PC-side classes.
6.	Copy JAR file into matlab subdirectory.
7.	To the Matlab classpath, add the leJOS pcrcxcomm Jar file, the JMF Jar file, and our Jar file from step 6.
8.	Compile and link the RCX source code, and download it onto the RCX.
9.	Try it!

RCX Camera Controller Software

USER MANUAL

1 Introduction