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