Java Comm Serial API How-To for Linux

Preface

Special thanks to Trent Jarvi and Kevin Hester for putting together RXTX and JCL.  These two gentlemen have done an excellent job of porting the original Sun Java Comm API to the Linux OS.  However, with all due respect, and not to be insulting, their installation documentation leaves much to be desired.  This is the primary reason I have chosen to put this document together.

Getting Started

Before insalling the Comm API on your Linux box, be sure you have a JSDK installed.  You can obtain a JSDK for your version of linux from Blackdown.org or Sun Microsystems.  To install and configure Java in Linux, please follow the instructions provided here.

For the purposes of this paper, it will be assumed that you have installed a JSDK and it is located in:

/usr/java/j2sdk1.4.0/

And java is then located in:

/usr/java/j2sdk1.4.0/bin/

If your setup is different, please adjust accordingly. 

Installing RXTX

First, obtain the RXTX bins package from:

http://www.linux.org.uk/~taj/rxtx-bins.1.tar.gz
                        (In IE, right click and "Save Target As")

Decompress and Untar this package:

/bin/gzip --decompress rxtx-bins.1.tar.gz

/bin/tar xf rxtx-bins.1.tar

At this point, you'll have an rxtx-bins.1 directory.  Next, you'll need to copy the shared objects into your java installation:

cp rxtx-bins.1/1.4/i386-pc-linux/libParallel.so /usr/java/j2sdk1.4.0/jre/lib/i386/

cp rxtx-bins.1/1.4/i386-pc-linux/libSerial.so /usr/java/j2sdk1.4.0/jre/lib/i386/

If you are installing on an architecture other than an x86, you'll need to adjust both the /i386-pc-linux/ and the /i386/ accordingly.

Next, you'll need to install the jcl.jar file:

cp rxtx-bins.1/1.4/jcl.jar /usr/java/j2sdk1.4.0/jre/lib/ext/

At this point, the RXTX installation is complete.

Installing Comm

The final step to getting the Java Comm API working under Linux, is to install the Comm API itself.  At this point, you have all of the necessary kernel-level drivers installed.  Because Linux is a form of Unix, the authors of RXTX and JCL have wisely decided to reuse sun's solaris (unix) comm library.  At this point, you must download and install this library:

http://java.sun.com/products/javacomm/  

Make sure you choose the Solaris/Sparc^TM version.  Next, you must Decompress and Untar this package:

/bin/gzip --decompress javax_comm-2_0_2-solsparc.tar.Z

/bin/tar xf javax_comm-2_0_2-solsparc.tar

Next, you'll need to install the comm.jar file:

cp commapi/comm.jar /usr/java/j2sdk1.4.0/jre/lib/ext/

At this point, we are almost finished.  We just need to create the properties file that the Comm API will use to load the drivers (.so files).  To create this file, type the following command:

/bin/echo Driver=gnu.io.RXTXCommDriver > /usr/java/j2sdk1.4.0/jre/lib/javax.comm.properties

Congratulations!  You have installed the Linux Comm API.

Tips

While windows uses COM and LPT designators for port identifiers, Linux is a bit different.  Use the following table to identify your ports:

Troubleshooting

Several people have emailed me and reported that they get the following error:

Exception in thread "main" java.lang.VerifyError: (class:
gnu/io/RXTXPort$SerialOutputStream, method: write signature: ([BII)V) Illegal
use of nonvirtual function call
at gnu.io.RXTXPort.<init>(RXTXPort.java)
at gnu.io.RXTXCommDriver.getCommPort(RXTXCommDriver.java)
at javax.comm.CommPortIdentifier.open(CommPortIdentifier.java:547)

I personally have not experienced this problem, but if you encounter this error, you can work around it by adding -noverify to your command line:

java -classpath your classpath -noverify your class

Also, it has been suggested that recompiling the jcl with the java compiler you have chosen will resolve this issue.  As I have never experienced this verification problem, I have no way to test this.  It should also be noted that the purpose of this paper is to be a quick and easy way to get serial and parallel port access in Java on Linux.  Most of the instructions on this page as well as the VerifyError are irrelevant if you chose to download the RXTX source and do a manual compile and installation.

Other Resources

1. Trent Jarvi's RXTX Homepage.  (http://www.rxtx.org)
2. Kevin Hester's JCL Homepage.  (http://www.geeksville.com/~kevinh/linuxcomm.html)
3. Sun Microsystem's Java Comm FAQ.  (http://java.sun.com/products/javacomm/reference/faqs/index.html)