jRxTx - Java Serial Communication Library
jRxTx is a Java serial communication library licensed under the LGPLv2.1 or later + linking exception. It can be used to communicate using well known UART-based serial protocols such as RS-232, RS-422 and RS-485. The goal of jRxTx is to provide a lightweight, intuitive and well documented API.
jRxTx wraps the popular RXTX library for which development has been discontinued. jRxTx provides two kinds of APIs: 1) the original RXTX API and 2) a new improved API.
Original RXTX API
jRxTx can be used as a drop-in replacement for RXTX. The wrapped RXTX has some advantages compared to the last RXTX release (version 2.2pre2):
-
It includes several bug fixes that do NOT change its API though
-
The jar file is an OSGi Bundle
-
The jar file is published on maven central.
-
The Java build system is based on Gradle. This way it is easy to add the native libs to the jar.
Find the Javadoc of the most current release here: https://openmuc.github.io/jrxtx/javadoc/index.html.
New jRxTx API
In addition to the original RXTX API jRxTx provides a new API with the following advantages:
The InputStream implementation provided by the original RXTX violates the contract of the general java.io.InputStream interface. It has the following two problems:
-
A timeout does not throw an exception but instead returns -1. But according to the InputStream interface -1 should only be returned if the stream is closed (i.e. the end of stream is reached).
-
A thread blocking in InputStream.read() cannot be interrupted by closing the associated serial port. Trying to close the serial port while another thread is blocking in read() causes the close() function to block as well.
jRxTx provides an InputStream implementation that conforms to the java.io.InputStream interface and behaves very similarly to the stream provided by java.net.Socket used for IP communication.
The event listener available in RXTX was removed in jRxTx because it is not needed for data stream reading.
Java and Native Parts
jRxTx consists of a Java library and a native library written in C. The Java library calls the native library through JNI. The Java library (jrxtx-<version>.jar) is published on maven central. As published on maven central the Java jar file does not include the native library.
While the Java library is platform independent, the native part of jRxTx needs to be compiled separately for different processor architectures and operating systems. Because of the large variety of platforms jRxTx does not ship with any precompiled native libs.
The jRxTx java library is compatible with the original RXTX native library. Thus you can also use the old RXTX native library or the native library of other RXTX compatible projects such as NRJavaSerial.
You have two options to use the native library:
-
You can install the native library so that the Java virtual machine can find it.
-
You can rebuild the jrxtx jar file to include the native library of your choice.
The Java library first searches a native library inside the jar file. If no compatible lib can be found it tries to load the libary from the java.library.path (e.g. /usr/lib/jni).
Installation
Linux
The jRxTx native library is compatible to the RXTX native library. Therefore on Debian based distributions all you have to do is install the package ‘librxtx-java’:
$ sudo apt-get install librxtx-java
This will install the correct native library in /usr/lib/jni. Sometimes you might have to add a system property so that the JVM finds it: -Djava.library.path=/usr/lib/jni .
The serial ports /dev/tty* are only accessible to members belonging to groups dialout and tty. You therefore have to add your user to those groups. E.g. using:
sudo adduser <yourUserName> dialout sudo adduser <yourUserName> tty
Afterwards you have to log out and log back in in order for the group changes to become active.
Windows
On Windows you need to copy the native library of RXTX for your specific system to the folder that is in the java.libary.path. To figure out the actual Java library path in your system, you can write a Java program that prints System.getProperty(‘java.library.path’).
You can get the native library either from the last official RXTX distribution rxtx-2.2pre2-bins.zip or you can compile it on your own from the source code.
Compile jRxTx
Linux
To compile the jRxTx Java library run the following command:
$ ./gradlew clean build
The resulting jar can be found in build/libs.
To rebuild the native library on Linux enter the folder native. Then run:
$ ./BUILD.sh
The compiled library (librxtxSerial.so) can be found in the .libs/ folder.
Once you have compiled the native library you install it so that the JVM can find and load it. Alternatively you can compile the jar with the native lib included:
$ ./gradlew clean buildWithNative
This will create the jar file and include any librxtxSerial.so/.dll file found in the native folder. A jar file created this way can load the native library from the jar.