Java developers and applications that access serial ports with RXTX on a Raspberry Pi, Beaglebone Black, or similar debian-based platform using non-standard serial port names (ie. /dev/ttyO1, /dev/ttyAMA0), need to do a bit of setup before things will work as expected.

Native Libraries

After install the JRE,  RXTX native libraries also need to be installed:

sudo apt-get install librxtx-java

This installs in /usr/lib/jni.  This path is automatically included in the Java Library Path on some platforms, but not all, so you need to update this property.  The library path can be set in code, but since the goal of Java is to ensure portability, it probably doesn’t make sense to hard-code paths into applications.  Instead, set the property at run time:

java -Djava.library.path=/usr/lib/jni <your-options-here>

Depending on your application, changing the library path may have other consequences, so you may want to set this only on some platforms.  See Shell Scripts below for one possible solution.

On-Board UART

RXTX automatically scans for serial ports using known-conventions for various platforms and will automatically detect standard serial ports (ie. /dev/ttySx) and USB serial devices (ie. /dev/ttyUSBx), but won’t enumerate ports using other names.

If you want to use the built-in UARTs to communicate directly with a device connected via GPIO header, you will need to tell RXTX about your port using the property.  Again, you could do this in your code if your application only targets one platform, but to keep things portable, you can set the property at run time:

java -Djava.library.path=/usr/lib/jni

The only problem with this approach is that it disables USB serial ports.  For a general, portable solution, see Shell Scripts below.

Raspbian Serial Console

There’s another gotcha when using the built-in UART:  by default, Raspbian starts a serial console on /dev/ttyAMA0, which may interfere with devices communicating on this port.  This issue is well known and the resolution is well documented.  I like the explanation on Adafruit how to disable the console.

Raspberry Pi Hardware Connection

Wiring a serial device directly to the Raspberry Pi is easy.  Here’s a chart I use to wire an XBee to the GPIO header:

Signal Pi XBee
3.3V 1 1
GND 6 10
TX/RX 8 3
RX/TX 10 2

Beaglebone UARTs

There are a few additional steps required to enable UARTs on the Beaglebone.  Here is a nice summary, including pinouts.

Shell Scripts

Starting Java applications using shell scripts is fairly common.  Here’s a script that will set the appropriate properties so RXTX will work properly on Raspbian and not interfere on other platforms:


Shell scripts may be fine when distributing applications, but have some limitations, like running from within an IDE, using Ant, invoking tests, or for Java libraries.  In this case, it may be best to tell RXTX about non-standard serial ports in the application or library code.

Since most applications using RXTX will take the port name as an argument anyway, use it to also set the property.  Here is a sample open() method in a library that uses RXTX:

public void open(String port, Integer baud) {
  Properties properties = System.getProperties();
  String currentPorts = properties.getProperty("", port);
  if (currentPorts.equals(port)) {
     properties.setProperty("", port);
  } else {
     properties.setProperty("", currentPorts + File.pathSeparator + port);
  /** do RXTX stuff here, like call, baud) **/

It is important to add the current port to the system property instead of overwriting it, especially in libraries that might be combined in an application using other serial ports at the same time.

Tagged with →  
Share →