[UPDATE: This library works with Mac OS X 10.6 Snow Leopard.]

In order to access a serial port in Java, you need the RXTX libraries compiled for your specific hardware. Java uses the Java Native Interface (JNI) to bridge between your platform-independent application code and the hardware-specific serial port drivers.

If you’ve tried this on an Intel Mac (perhaps to play with a Sun SPOT), you may be disappointed, since software keeps shipping from people that is either PowerPC only or isn’t compiled for 64-bit Intel. You’ve probably seen the UnsatisfiedLinkError message. Here you’ll find a librxtxSerial.jnilib file with support for both 32- and 64-bit PPC and Intel architectures, fitting the bill perfectly for both Java 5 and Java 6 on the Mac.

$ file librxtxSerial.jnilib
librxtxSerial.jnilib: Mach-O universal binary with 4 architectures
librxtxSerial.jnilib (for architecture x86_64):	Mach-O 64-bit bundle x86_64
librxtxSerial.jnilib (for architecture i386):	Mach-O bundle i386
librxtxSerial.jnilib (for architecture ppc7400): Mach-O bundle ppc
librxtxSerial.jnilib (for architecture ppc64):	Mach-O 64-bit bundle ppc64

The Need for the RXTX Library

Java’s “write once, run many” theory of operation works because the Java Virtual Machine (JVM), which must be made for each platform, abstracts away the underlying hardware. As a programmer you can draw circles, label buttons, and even play multimedia without specific knowledge of the host operating system.

A computer’s serial ports can be abstracted away in the same way, but the standard JVM does not provide a mechanism for this. Sun decided (reasonably, though regrettably, I think) that the serial port would not be a required component for a JVM, and so there are no built-in classes for working with serial ports.

Sun experimented, for a period of time, with a Java Communications API that would be a sort of plugin for working with things like serial ports (and parallel ports!), but the project and its javax.comm package died.

Thanks to the team at RXTX.org, we now have a gnu.io package modeled after Sun’s javax.comm package that is maintained and works. Thanks!

Why Doesn’t It Work for You?

If you’re reading this, it might be because you can’t get it to work on your Mac. Probably you have an Intel Mac and are using Java 6 or later which requires a 64-bit Intel processor. Perhaps you’ve seen error messages that say thinks like UnsatisfiedLinkError and so forth.

Software talking to the serial port must communicate with the host operating system, and so the underlying native library must be compiled per-platform. Presumably your librxtxSerial.jnilib file is not compiled for your platform. Here’s how to find out. Open the Terminal, navigate to the folder with a librxtxSerial.jnilib file, and use the file command. You’ll probably see this:

$ cd /Users/rob/SunSPOT/sdk/lib
$ file librxtxSerial.jnilib
librxtxSerial.jnilib: Mach-O universal binary with 2 architectures
librxtxSerial.jnilib (for architecture i386):	Mach-O bundle i386
librxtxSerial.jnilib (for architecture ppc7400): Mach-O bundle ppc

If you’re running Java 5 (which comes in 32- and 64-bit flavors on the Mac) you’re OK, but if you’re running Java 6, which is 64-bit Intel only, it won’t work.

A Library with the Right Architectures

No problem; all you have to do is re-compile RXTX from sources for your platform, right? I wish. I can’t even remember all the contortions I went through before I finally got it compiled.

You’re welcome to follow the various instructions online for compiling it yourself, but it gave me a lot of grief, so I’m placing a copy on this site (if you trust me not to insert nefarious code). I finally had to patch SerialImpl.c and SerialImpl.h (manually) based on the patch instructions here and blog posting here.

At the end of the day, we have a librxtxSerial.jnilib file that has 32- and 64-bit PPC and Intel architectures.

Find all instances of librxtxSerial.jnilib on your Mac and replace them with the one you downloaded from here (or compiled yourself). Try the command locate librxtxSerial.jnilib in the Terminal to find extra copies hidden in various Java applications.