Using a GP3 with Java or JavaScript

You can easily use the GP3 with Java -- or even JavaScript. If you know Java, you'll find this a useful technique. However, even if you don't know Java, you may find using JavaScript -- which is a simplified version of Java a handy way to try out new ideas. You can download the Java files in this zip file.

JavaScript First

The JavaScript interpreter is built into the Java files mentioned above. In addition to the files in the ZIP file, you also need a working JVM (Java Virtual Machine) for your computer as well as the javax.comm libraries. Sun provides these for Windows and Solaris. If you are using Linux or a Mac, you will need to get the libraries from another source.

If you plan on doing Java development, you might as well get the Java software development kit. It is free, has everything you need, and will even allow you to develop Java programs. If you only want to run the interpreter, you really only need the JRE which is just the runtime parts of the Java system.

You can usually find what you want at http://java.sun.com. As I write this, here are the links you'll need:

http://java.sun.com/j2se/1.4.1/download.html - Pick the J2SE for the platform you are using. You don't need the Java ONE studio unless you want a graphical interface. Notice the downloads are divided into JRE and SDK. The JRE is what you need if you don't plan on doing regular Java development. The SDK has all the development tools and files you need. Of course, your system may already have the JRE installed. If so, you can use what you already have installed.

http://java.sun.com/products/javacomm/ - The Java comm libraries for Solaris or Windows. If you are using Linux, read http://wass.homelinux.net/howtos/Comm_How-To.shtml (and see below). If you are using the Mac, read http://homepage.mac.com/pcbeard/javax.comm.MRJ/. Note that some versions of the GP3 zip file has copies of the Win32 comm.jar and DLL file, but you will probably need to download the full version and install it so that everything is installed properly for your setup. For Linux you need the javax.comm version of RXTX (Version 2.0 not 2.1 at www.rxtx.org).

You need to install the Java runtime and javax.comm software as instructed by Sun (or where ever you got it). The javax.comm library for Windows is particularly fussy about its file locations. If the DLL file is on a different drive than the JAR file, the library will not work properly.

The next step is to set up your environment to match your setup. In the GP3 Java files, you'll find a batch file, setenv.bat in the zip archive. You need to modify it to suit your changes. Here's my copy:

REM Change below to fit your directory
set GP3ROOT=c:\user\awce\gp3\java
set JDK=c:\jdk1.3\bin

set PATH=%JDK%;%PATH%
set CLASSPATH=%GP3ROOT%;%GP3ROOT%\GP3.jar;%GP3ROOT%\comm.jar;%GP3ROOT%\js.jar

Notice the GP3ROOT directory is simply used to make the rest of the script easier to read. The program doesn't require this variable, but this script uses it extensively. You should set this to the directory where you unpacked the GP3 files. The JDK variable points to your JDK for the same reason.

The next two variables set the system path and the classpath. The PATH statement simply puts the JDK executable directory into your PATH. This directory contains the JVM (java.exe or java depending on your platform). The CLASSPATH variable tells Java where to find classes. You need to set it to the GP3 directory and also to the three jar files: GP3.jar (the GP3 classes), comm.jar (the communications library), and js.jar (the JavaScript interpreter).

Now you are ready to go! Enter the command:

java GP3Script

The program should respond with a prompt:

IO>

Here's a transcript of a session with the interpeter:

IO> io=createGP3();
IO> io.openPort("COM7");
IO> io.setLED(1);
IO> exit();

Of course, replace COM7 with the right value for your setup. This little program will turn on the onboard LED. You can find all the documentation in the HTML files found in the javadoc.zip file (included in the zip file). You can also feed the interpreter a file name:

java GP3Script gp3test.js

Here is the sample script:

// Test script for GP3
// To run: java GP3Script gp3test.js

io=createGP3();
io.openPort("COM7");  // change to match your COM port!

function readvolt(n)
{
  return io.a2d(n)/1023.0*5.0;
}

for (i=0;i<1000;i++)
{
  io.toggle(0);
  print(readvolt(0));  // print voltage on analog in 0
  io.setLED(i%2);
  pause(500);
}

Regular Java

Of course, all the script does is creates a regular Java object and accesses it. You can do this from a normal Java program if you prefer. In fact, the GP3Script.java file is included if you want to see how it works. The basic idea is simple:

GP3 obj = new GP3();

obj.openPort("COM7"); // etc...

Again, the javadoc files are in javadoc.zip and you can read about all the methods there.

More About Linux

The instructions at http://wass.homelinux.net/howtos/Comm_How-To.shtml don't use the latest RXTX libraries because the latest ones aren't released as binaries yet. But it is still useful. Here are the steps I took to install under Linux (as root):

	Download J2SE v1.4.2 SDK for Linux RPM (self-extracting) at http://java.sun.com/j2se/1.4.2/download.html
	Run the J2SE .bin file. This generates the RPM file.
	Install the RPM (rpm -U j2sdk-1_4_2-linux-i586.rpm)
	Add /usr/java/j2sdk1.4.2/bin to the PATH.
	Download Version 2.0 of the JCA for Solaris/x86 (not SPARC) from http://java.sun.com/products/javacomm
	Untar the JCA and copy comm.jar to /usr/java/j2sdk1.4.2/jre/lib/ext/comm.jar
	Download version 2 of RXTX from http://www.rxtx.org
	Untar and run ./configure then "make install"
	Get the GP3 files and unpack them - remove the comm.jar and win32com.dll file if present
	set CLASSPATH to something like (replace XYZ, of course):

    export CLASSPATH=/home/XYZ/gp3:/home/XYZ/gp3/GP3.jar:/home/XYZ/gp3/js.jar

If you don't have the comm.jar file in the "right" place you'll need to add it to the CLASSPATH as well. Now you are ready to go. Open gp3test.js and change COM7 to /dev/ttyS0 (assuming you are connected to your first COM port). Then run:

	java GP3Script gp3test.js

Note: the RXTX libraries requires you to have access to /var/lock. If you run as root, you won't have any problems. In theory, if your user ID is in the lock group (RedHat) or uucp group (some other Linux distributions) you should be able to create files in /var/lock. You can do this by editing the /etc/group file or using the -G option of usermod. Be sure to log out and log back in for the change to take effect.

If all else fails, try running (as root): chmod 777 /var/lock. This could be a mild security hole, of sorts, since anyone could then delete a lock file, so be sure you understand how this will affect your system.