How to Access Your Serial Port using Java
This tutorial shows you how to access a local serial port using Java. It assumes that you have Java JDK 1.6.0_22 installed. Accessing the serial port in Java is not trivial because support is not built into the standard edition. Java does include an API called JavaComm that allows you to access serial ports, but no implementation for certain platforms like Linux or Windows. Thus, a 3rd party implementation must be used. In this tutorial, we use RXTX.
Contents |
Windows (32-bit)
Download and Install RXTX
- Determine which directory contains your java run time. Open a Cygwin terminal and type "
which java". You should see output like the screen shot below. In this case, the relevant directory isC:\Program Files\Java\jdk1.6.0_21\jre. If you see that your Java directory isC:\Windows\System32(which is Windows' built-in support for Java), you need to modify your path to point to the JDK
- Next download the rxtx package from the official RXTX download page. Get the pre-compiled binary version so you don't have to go through the trouble of compiling it yourself. As of this writing, the most recent version is rxtx-2.1-7-bins-r2.zip.
- Extract the archive using Windows' built-in zip support, or a fancier utility like 7-zip. You should see the following files and folders:
INSTALL Linux/ Mac_OS_X/ RXTXcomm.jar Solaris/ Windows/
- Open the INSTALL file using a text editor like Notepad++. Carefully read it, then close it.
- Install RXTX by doing the following:
- Copy
rxtx-2.1-7-bins-r2\RXTXcomm.jarintoC:\Program Files\Java\jdk1.6.0_21\jre\lib\ext. - Copy
rxtx-2.1-7-bins-r2\Windows\i368-mingw32\rxtxSerial.dllintoC:\Program Files\Java\jdk1.6.0_21\jre\bin.
- Copy
- This concludes the installation of RXTX on your Windows XP computer.
Test the Installation of RXTX on Windows
This section guides you to test the correct installation of RXTX. It uses code examples from the official RXTX wiki.
- Open Eclipse and create a new Project by clicking on File, New, Java Project. You should see the following window appear.
- For the project name, enter "SerialTest" as shown above, then click on "Next" then "Finish". You should now be back at the original Eclipse window with the Package Explorer on the left. Within this Package Explorer, right-click on the "src" folder and click on "New", "Class". The following window should appear:
- For the name of the class, enter "SerialPortLister" as shown above, then click "Finish".
- You can now follow the examples given here.
Windows (64-bit)
Get the 64-bit RXTX package here: http://www.cloudhopper.com/opensource/rxtx/
- Local copy of ch-rxtx-2.2-20081207-win-x64 (in case the above site goes down)
Linux (Ubuntu 10.04)
Download and Install RXTX
If you are running the desktop version of Ubuntu 10.04, go into Synaptic Package Manager and add the "eclipse" package as shown below. Eclipse is a powerful IDE for developing Java applications. Note that doing this will install a bunch of other packages like the Java SDK, which is what you want.
If you are running Ubuntu 10.04 Server and thus do not have the Synaptic Package Manager, execute the following command to install the Java JDK:
$ sudo apt-get install openjdk-6-jdk
Next, download the RXTX package. As of this writing, the file to download is called "rxtx-2.1-7-bins-r2.zip". You can download it using the following command:
$ wget http://rxtx.qbang.org/pub/rxtx/rxtx-2.1-7-bins-r2.zip
Unzip the rxtx archive and install it. The following commands assume your JVM is located in /usr/lib/jvm/java-6-openjdk/ and that you are using a 32-bit x86 computer. You will need to slightly modify these commands if you have a different JVM or system architecture (i.e., 64-bit).
$ sudo apt-get install zip $ unzip rxtx-2.1-7-bins-r2.zip $ cd rxtx-2.1-7-bins-r2 $ sudo cp RXTXcomm.jar /usr/lib/jvm/java-6-openjdk/jre/lib/ext/ $ sudo cp Linux/i686-unknown-linux-gnu/librxtx* /usr/lib/jvm/java-6-openjdk/jre/lib/i386/
Test the Installation of RXTX on Ubuntu Linux
To test the ability to access the serial ports using Java, download and run these test programs. You can do this using the following commands:
$ wget http://pharos.ece.utexas.edu/wiki/images/f/f1/Testserialjava.tar.gz $ tar zxvf Testserialjava.tar.gz $ cd TestSerialPort
If you list the contents of the "TestSerialPort" directory, you will find two programs: ListCommPorts and ReadSerialPort. Open ReadSerialPort.java and edit the serial port that is opened near the bottom of the file in the main method. After modifying the file, compile the programs using the following command.
$ javac *.java
You can now run each of the programs to test serial port functionality.
Here is example output of ListCommPorts.
ut@proteus:~/TestSerialPort$ java ListCommPorts Experimental: JNI_OnLoad called. Stable Library ========================================= Native lib Version = RXTX-2.1-7 Java lib Version = RXTX-2.1-7 /dev/ttyUSB1 - Serial /dev/ttyUSB0 - Serial /dev/ttyS1 - Serial /dev/ttyS0 - Serial
Here is example output of ReadSerialPort when a Cricket Mote is attached to the serial port that is being read from.
ut@proteus:~/TestSerialPort$ java ReadSerialPort Experimental: JNI_OnLoad called. Stable Library ========================================= Native lib Version = RXTX-2.1-7 Java lib Version = RXTX-2.1-7 Read line with 74 characters: "VR=2.0,ID=01:65:39:39:11:00:00:32,SP=pharos,DB=34,DR=1064,TM=1326,TS=84064" Read line with 74 characters: "VR=2.0,ID=01:65:39:39:11:00:00:32,SP=pharos,DB=37,DR=1158,TM=1612,TS=84384" Read line with 74 characters: "VR=2.0,ID=01:65:39:39:11:00:00:32,SP=pharos,DB=37,DR=1158,TM=1660,TS=85056" Read line with 74 characters: "VR=2.0,ID=01:65:39:39:11:00:00:32,SP=pharos,DB=37,DR=1155,TM=1609,TS=85376" Read line with 74 characters: "VR=2.0,ID=01:65:39:39:11:00:00:32,SP=pharos,DB=37,DR=1158,TM=1708,TS=85664" Read line with 74 characters: "VR=2.0,ID=01:65:39:39:11:00:00:32,SP=pharos,DB=37,DR=1158,TM=1660,TS=86016"
In addition to the above two programs work, you can also try some of the official RXTX examples.
Mac OSX
Download and Install RXTX
- For full instructions, see: http://rxtx.qbang.org/wiki/index.php/Installation_on_MacOS_X
First, download the RXTX re-compiled files from here: http://rxtx.qbang.org/wiki/index.php/Download
Extract the archive, then copy librxtxSerial64.jnilib to /Library/Java/Extensions/.
Troubleshooting
UnsatisfiedLinkError
If you get the following error when running your application:
java.lang.UnsatisfiedLinkError: /Users/liangfok/Documents/workspace/ScratchPad/jars/librxtxSerial.jnilib: no suitable image found. Did find: /Users/liangfok/Documents/workspace/ScratchPad/jars/librxtxSerial.jnilib: no matching architecture in universal wrapper thrown while loading gnu.io.RXTXCommDriver Exception in thread "main" java.lang.UnsatisfiedLinkError: /Users/liangfok/Documents/workspace/ScratchPad/jars/librxtxSerial.jnilib: no suitable image found. Did find: /Users/liangfok/Documents/workspace/ScratchPad/jars/librxtxSerial.jnilib: no matching architecture in universal wrapper at java.lang.ClassLoader$NativeLibrary.load(Native Method) at java.lang.ClassLoader.loadLibrary0(ClassLoader.java:1827) at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1742) at java.lang.Runtime.loadLibrary0(Runtime.java:823) at java.lang.System.loadLibrary(System.java:1045) at gnu.io.CommPortIdentifier.<clinit>(CommPortIdentifier.java:83) at MD03Controller.connect(MD03Controller.java:55) at MD03Controller.<init>(MD03Controller.java:21) at MD03Controller.main(MD03Controller.java:121)
This is most likely because you're running a 64-bit version of OSX and the librxtxSerial.jnilib is for 32-bit OS.
To see the system architectures supported by your version of librxtxSerial.jnilib, execute the following:
$ file librxtxSerial.jnilib librxtxSerial.jnilib: Mach-O universal binary with 2 architectures librxtxSerial.jnilib (for architecture ppc): Mach-O dynamically linked shared library ppc librxtxSerial.jnilib (for architecture i386): Mach-O dynamically linked shared library i386
Thankfully, the following website has a 64-bit version of librxtxSerial.jnilib: http://blog.iharder.net/2009/08/18/rxtx-java-6-and-librxtxserial-jnilib-on-intel-mac-os-x/
$ file librxtxSerial.jnilib librxtxSerial64.jnilib: Mach-O universal binary with 4 architectures librxtxSerial64.jnilib (for architecture x86_64): Mach-O 64-bit bundle x86_64 librxtxSerial64.jnilib (for architecture i386): Mach-O bundle i386 librxtxSerial64.jnilib (for architecture ppc7400): Mach-O bundle ppc librxtxSerial64.jnilib (for architecture ppc64): Mach-O 64-bit bundle ppc64
PortInUseException
If you get the following error:
Connecting to: /dev/tty.usbmodemfa141 Stable Library ========================================= Native lib Version = RXTX-2.1-7 Java lib Version = RXTX-2.1-7 Sending movement command: 128, 60 gnu.io.PortInUseException: Unknown Application at gnu.io.CommPortIdentifier.open(CommPortIdentifier.java:354) at MD03Controller.connect(MD03Controller.java:59) at MD03Controller.<init>(MD03Controller.java:21) at MD03Controller.main(MD03Controller.java:121) Exception in thread "main" java.lang.NullPointerException at MD03Controller.sendMovementCmd(MD03Controller.java:45) at MD03Controller.<init>(MD03Controller.java:28) at MD03Controller.main(MD03Controller.java:121) Experimental: JNI_OnLoad called.
Here are some possible causes:
- RXTX tries to store lock files in /dev/lock/ rather than the usual /var/spool/uucp. If this directory doesn't exist, create it then give it 777 permissions. Source: http://jgrasstechtips.blogspot.com/2008/04/rxtx-and-funky-portinuseexception-on.html
- You have another application that is accessing the serial port. For example, the Arduino IDE may be the culprit. Close the other application and try again.
