02/04/2018 GitHub - openmuc/jrxtx: The Java serial communication library.
openmuc / jrxtx
Dismiss
Join GitHub today
GitHub is home to over 20 million developers working together to host
and review code, manage projects, and build software together.
Sign up
The Java serial communication library.
# java # serial # rxtx
271 commits 4 branches 3 releases 5 contributors LGPL-2.1
Branch: develop New pull request Find file Clone or download
DirkZimmermann prepare new release 1.0.2-SNAPSHOT Latest commit 7fc5880 on 15 Jan
docs release v1.0.1 3 months ago
gradle/wrapper updated gradle wrapper and main build file 5 months ago
license changed license to LGPLv2.1 or later + linking exception a year ago
native removed annoying warning if stale lock file is removed a year ago
src Java 9 compatibility 3 months ago
.gitignore minor change to gitignore 10 months ago
.travis.yml update to jdk8 to gradle can use EC in travis 5 months ago
LICENSE add license to project root 5 months ago
README.adoc minor changes in readme 9 months ago
build.gradle updated version of bnd tool used by build script 5 months ago
configuration.gradle prepare new release 1.0.2-SNAPSHOT 3 months ago
gradlew updated gradle version to 4.0 and made build.gradle changes to be com… 9 months ago
gradlew.bat updated gradle wrapper scripts and build file 2 years ago
README.adoc
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.
https://github.com/openmuc/jrxtx 1/3
02/04/2018 GitHub - openmuc/jrxtx: The Java serial communication library.
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:
1. You can install the native library so that the Java virtual machine can find it.
2. 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.
https://github.com/openmuc/jrxtx 2/3
02/04/2018 GitHub - openmuc/jrxtx: The Java serial communication library.
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:
$ ./configure
$ make
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.
https://github.com/openmuc/jrxtx 3/3
