GP3 and Java

Note: The javax.comm library seems poorly supported. While RXTX is better, it has its own problems. Using the "native" GP3 libraries may be a simpler method for you.

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.

Update for Ubuntu/Kubuntu

AMD64 Ubuntu (as of 9.10) installs a librxtx that is broken. Reads cause issues (see this bug report). Here's what worked for me:

Remove RXTX using your package manager. If you've installed JVMs outside of package management you may need to manually go find RXTXcomm.jar and librxtxSerial.so and delete them.
Download 2.2pre2 of RXTX. The bug report mentioned earlier claims that 2.1-7r2 fixes this problem. As far as I can tell, it doesn't. The 2.2 works fine.
Copy the RXTXcomm.jar file to /usr/lib/jvm/XXXX/jre/lib/ext (where XXXX is your Java installation you are using; like java-6-sun, for example). Note: You have to do this as root (sudo).
Copy the librxtxSerial.so file from the directory matching your architecture to /usr/lib/jvm/XXXX/jre/lib/YYYY (where XXXX is the Java name and YYYY is the architecture; amd64, in my case).
In the GP3.java file, replace import javax.comm.* with import gnu.io.*.

Ubuntu has /var/lock owned by root with read/write/sticky set for everyone so you shouldn't need to mangle your groups with Ubuntu.

It is a shame that there is not more robust support for Java serial I/O.

Another Approach

I became so frustrated with the whole javax.comm and RXTX problems that I finally did something I should have done a long time ago. The "standard" library (see gp3lib.zip is easily built for Linux, Cygwin, or Windows and probably just about any other platform as well.

I was worried about doing JNI support for it though because my experience with JNI is it is a fair amount of work. Luckily, the JNA library makes JNI-like calls very simple.

First step is to snag the gp3lib.zip file and make a shared library from it. For Linux, for example (be sure to set DEMO=0 in gp3lib.c first):

gcc -fPIC -g -c gp3linux.c
gcc -fPIC -g -c gp3lib.c
gcc -shared -Wl,-soname,libgp3.so.1 -o libgp3.so.1.0.1 gp3.o gp3linux.o -lc
sudo cp libgp3.so.1.0.1 /usr/local/lib
sudo cp gp3lib.h /usr/local/include
sudo ldconfig

You'll also need to download the jna.jar file and install it. Here's the JNA-version of the GP3 library wrapper:

package com.awce.gp3;

import com.sun.jna.Library;
import com.sun.jna.Native;

public class GP3io {
	public interface GP3Library extends Library {
		GP3Library INSTANCE=(GP3Library)Native.loadLibrary("gp3",GP3Library.class);
		GP3Library SYNC_INSTANCE=(GP3Library)Native.synchronizedLibrary(INSTANCE);
	int gp3openport(String port);
	void gp3closeport();
	void gp3setLED(int onoff);
	int gp3ready();
	int gp3a2d(int chan);
	void gp3high(int pin);
	void gp3low(int pin);
	void gp3toggle(int pin);
	int gp3input(int pin);
	void gp3settris(int tris);
	int gp3gettris();
	void gp3setpins(int byt);
	void gp3writeee(int add, int byt);
	int gp3readee(int add);
	void gp3pwm(int chan, int dc, int dfreq);
	int gp3count(int pin, int ms);
	int gp3rctime(int pin, int state);
	int gp3pulsein(int pin, int state);
	void gp3pulseout(int pin, int duration);
	void gp3freq(int pin, int ms, int freq);
	void gp3setcounter(int prescale, int ext);
	int gp3counter();
	void gp3resetall();
	void gp3reset();
	void gp3repeat(int count);
	void gp3argincr();
	void gp3argdecr();
	int gp3check();
	}
}

And here's a simple example using the new class:

package com.awce.gp3;

import com.awce.gp3.GP3io.GP3Library;

public class GP3EZ {

	/**
	 * @param args
	 * @throws InterruptedException 
	 */
	public static void main(String[] args) throws InterruptedException {
		GP3Library GP3=GP3Library.INSTANCE;
		GP3.gp3openport(args.length==0?"/dev/ttyS0":args[1]);
		for (int i=0;i<100;i++) {
			GP3.gp3setLED(1);
			Thread.sleep(250);
			GP3.gp3setLED(0);
			Thread.sleep(250);
		}
		GP3.gp3closeport();
	}

}

Of course, you now need a shared library for each platform you plan to support (e.g., Windows, Linux/32, Linux/64, etc.) and you'll need to change the library load line in each case.

You can also use JNA Direct Mapping which is more efficient. Simply replace the INSTANCE and SYNC_INSTANCE lines with:

static { Native.register("gp3"); }

Then add "public static native" in front of each method declaration in GP3io.java. The main program also becomes simpler:

        . . . 
	public static void main(String[] args) throws InterruptedException {
		GP3io.gp3openport(args.length==0?"/dev/ttyS0":args[1]);
		for (int i=0;i<100;i++) {
			GP3io.gp3setLED(1);
           . . .

AWC Electronics - GP3 and Java

JavaScript First

Regular Java

More About Linux

Update for Ubuntu/Kubuntu

Another Approach