From Rxtx

(Difference between revisions)
Jump to: navigation, search
(Fix vandalism)
Line 41: Line 41:
<a href="">4706c7</a> | [url=]b87a39[/url] | [link=]6f3715[/link] | | fa35da | [ 2f344c]
==== A. Japanese ====
Instructions are available in Japanese at
The instructions are fairly old but should help.
Thanks to Masayuki "Tencho" Yamashita <>
home page
A copy of these install instructions is provided in
We will gladly include instructions in any language provided.  Tencho
was the first to contribute instructions in another language.

Revision as of 14:30, 11 July 2007

|   rxtx is a native interface to serial ports in Java.
|   Copyright 1997-2004 by Trent Jarvi
|   This library is free software; you can redistribute it and/or
|   modify it under the terms of the GNU Library General Public
|   License as published by the Free Software Foundation; either
|   version 2 of the License, or (at your option) any later version.
|   This library is distributed in the hope that it will be useful,
|   but WITHOUT ANY WARRANTY; without even the implied warranty of
|   Library General Public License for more details.
|   You should have received a copy of the GNU Library General Public
|   License along with this library; if not, write to the Free
|   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

This is the INSTALL file for RXTX. Thu Jul 7 19:46:26 EDT 2005

If, while following the instructions, you find this file unclear or incorrect please make a note and email the details to

A note about rxtx 2.1:

rxtx 2.1 replaces the entire CommAPI. Every effort is made to conform to CommAPI but out of respect for our friends at Sun the package name of 2.1 has been moved to A script is offered in contrib/ that will switch source tree's between javax.comm and

See Sun's CommAPI license for more details on why this decision was made.

If you would like to use javax.comm, use rxtx 1.4 with Sun's CommAPI. </code>

A note on Mac OS X:

Go to the MacOSX file for install instructions.



A. Japanese

Instructions are available in Japanese at

The instructions are fairly old but should help. Thanks to Masayuki "Tencho" Yamashita <> home page

A copy of these install instructions is provided in install-japanese.html

We will gladly include instructions in any language provided. Tencho was the first to contribute instructions in another language.


The following is concerned with building and installing commapi support with Sun's CommAPI package. A full stand alone version of rxtx is in the CVS archive for interested developers.

Quick Install

The following packages are used to build rxtx:

autoconf-2.59 automake-1.9.5 libtool-1.5.18 gnu make-3.79.1 On some systems like FreeBSD this is called gmake jdk 1.3 or newer

With the packages installed, proceed to build and install rxtx.

		$ tar -xzvf rxtx-2.1.tar.gz
		$ cd rxtx-2.1
		$ ./configure  (follow the instructions)
		$ make install (gmake if your system uses that convention)
		Read "R.  How can I use Lock Files with rxtx?"

One catch that has showed up... you cannot have spaces in the path. for instance: /home/jarvi/test build/rxtx/... will cause problems.


If that does not work or you do not want a script messing with the system, read on..

Uninstalling Sun's comm.jar

Sun's comm.jar is not required. It is a valid option on some platforms. IT WILL CREATE CHAOS if you have it installed while trying to build rxtx 2.1.

Installing is not currently required by rxtx-2.1

Add RXTXcomm.jar to your CLASSPATH.


make sure /usr/local/java/lib/RXTXcomm.jar is in your CLASSPATH. If you want to use apps that require RXTXcomm.jar.

in bash:

$ export CLASSPATH=${CLASSPATH}:/usr/local/java/lib/RXTXcomm.jar:.

jdk-1.2 and newer:

No changes are needed.

Build and Install the jar.

configure configure supports build directories. configure requires javac in its path or JAVA_HOME set to grab some java system properties. make to build RXTXcomm.jar and the libraries make install to place the jar and libraries in the correct location

You may select the JDK you wish to build with using $JAVA_HOME For example: export JAVA_HOME=/usr/local/java Otherwise, configure grabs the JDK from your PATH.

Where did everything end up?

Lets assume the top java directory is /usr/local/java

jdk-1.2 the files go in


jdk-1.1.* the files go in


			The are placed in 
			/usr/lib so people don't have to change with their 

Compiling for Win32 support

Get the Sun CommAPI if you want a plug-in solution. The code is provided for people that may have demanding needs and coding ability.

There is only serial port code at this time.

Three ways of compiling win32 libraries are offered:

mingw32 tools in DOS lcc tools in DOS cross-compiling from Linux

mingw32 tools in DOS

Install mingw32 Install a jdk Make sure the ming32\bin and jdk\bin directories are in your path. In the rxtx top directory to the following: mkdir build copy Makefile.mingw32 build\Makefile cd build edit the Makefile and make sure the directories are correct. execute the following: make make install

lcc tools in DOS

Install a jdk Install lcc

A make file (Makefile.lcc) for compiling rxtx with lcc contributed by Valentin Pavlov

You will need a config.h file in the src directory. Other builds usually generate them automatically. The following should work.


if you know how to create the above in a dos Makefile send in the changes.

the following commands should then work fine on the command line.

cd src make -f ..\Makefile.lcc


The Compiler Cannot Find Java Include Files

Check to top of the Makefile to make sure we agree on the location of the include files that came with the jdk. Specifically:

JAVAINCLUDE = -I /usr/local/java/include/ JAVANATINC = -I /usr/local/java/include/genunix also check the classpath CLASSPATH = ...

Configure says 'unterminated sed command' and stops

Unterminated sed command errors usually result from `find` producing unexpected results. If you are unsure remove all comm.jar and configure to place in in the correct place.

I feel like a complete blank. That's how it is. I can't be bothered with anything recently.

does propecia work | propecia | ambien | soma

BlackBox Can Not Handle all the ports!

BlackBox has a hard coded limit in that prevents it from running if you don't specify a port. We are considering alternative ways of handling the large number of port names in Unix. The line in question


portDisp = new SerialPortDisplay[50];

just change 50 to say 256.

Illegal use of nonvirtal function call!

	Exception in thread "main" java.lang.VerifyError: (class: 
	gnu/io/RXTXPort$SerialOutputStream, method: flush signature: ()V) 
	Illegal use of nonvirtual function call
		at Code)
		at Code)
		at SerialPortDisplay.openBBPort(Compiled Code)
		at SerialPortDisplay.<init>(Compiled Code)
		at BlackBox.addPort(Compiled Code)
		at BlackBox.main(Compiled Code)

"1.1 compilers sometimes generate code that won't verify under 1.2.

If you don't have the sources for the offending class to recompile with a 1.2 javac, the only solution I know of is to launch the VM with the -noverify option.


In other words start with a fresh build directory, rebuild, and reinstall to avoid the problem.

My libc5 Linux system is generating SIGSEGV

Older Linux Systems (libc5) should upgrade to a glibc system with libpthread-0.7 or newer. We have run into many problems with older libraries. SIGSEGV was the most common symptom. Reported by Peter Bennett <bencom at>

AM_PROG_LIBTOOL not found in library

cd. && aclocal 23: macro 'AM_PROG_LIBTOOL' not found in library make:***[aclocal.m4]Error 1

If you're positive things are setup right you may try the script to try regenerating the scripts with your tools.

Problems with RMISecurityManager()

Please see the file RMISecurityManager.html

Which Wires Should be Connected

With the DB25 use 2 (TX), 3 (RX) and 7 (GD) to connect to the device. With the DB9 use 2 (RX), 3 (TX) and 5 (GD) to connect to the device.

You will need to hook up more than that for hardware flow control.

Which Device Should be Used?

  • Linux serial ports should use /dev/ttyS*., specialx, cyclades and isdn4 linux have been reported to work. As many as 64 ports have worked at one time.
  • FreeBSD uses cuaa*
  • netbsd uses tty0*
  • Irix uses ttyd* ttym* ttyf*
  • HP-UX uses tty0p* tty1p*
  • BeOS uses /dev/ports/serial*
  • Win32 uses COM*

It Did Not Work!

There are sure to be bugs. The goal is to make the install as painless as possible. Send back comments if something could be easier.

If you run into a problem building the rxtx package please include the output generated by the following script.

which java
java -version
uname -a
autoconf --version
automake --version
libtool --version
make --version

Here's what's on my system for comparison. Older make is known to cause problems.

java 1.4 autoconf-2.53 automake-1.6.3 libtool-1.4.2 gnu make-3.79.1

mail any bugs to

Which jdk should be used?

This is dated.

Ideally any jdk would be fine. Here is a list of jdk's tried on RedHat 6.0/kernel 2.2.17pre13 with various versions of glibc.

                 Sun            IBM           Blackdown
                 2.1.2_006      1.3.0         1.1.8v1
                 green  native  green native  green native
glibc-2.1.1-6   | OK   | *1   | *2   | *2   | OK   | *3   |
glibc-2.1.2-11  | OK   | *1   | OK   | OK   | OK   | OK   |
glibc-2.1.2-17  | OK   | *1   | OK   | OK   | OK   | OK   |
glibc-2.1.3-15  | OK   | *1   | OK   | OK   | OK   | OK   |

1) BlackBox (a demo application shipped with CommAPI locks after multiple open()/close()

2) java wont start "Unable to load /usr/local/java/jre/bin/ symbol sem_wait, version GLIBC_2.1 not defined in file with link time reference Could not create the Java virtual machine."

3) java wont start "error in loading shared libraries: /usr/local/java/bin/../lib/i686/native_threads/ symbol sem_init, version GLIBC_2.1 not defined in file with link time reference"

Conclusion? Avoid Sun's native threads unless you can figure out whats going wrong. (this is dated)

How does rxtx detect ports? Can I override it?

rxtx tries to detect ports on by scanning /dev for files matching any of a set of known-good prefixes, such as 'ttyS', 'ttym', and so on. Any ones that exist, are supposed to be good for the current operating system, and that can be read and written are offered back from CommPortIdentifier.getPortIdentifiers(), and only these can be used as ports.

If you wish, you can set the system properties and If either of these is set, then no scanning will be carried out and only the specified ports will be available. You can use this to make one platform look like another, to restrict Java access to ports, or possibly for other reasons. For example


will look kind of like Solaris, if you have created the appropriate device nodes.

A note on Linux port enumeration. We have set most ports aside. Once the number of possible devices started getting into the thousands, checking them all made little sense. Look in and search for Linux.

You will see that only /dev/ttyS* is searched but the possible addition ports that can be used are listed under it. Just copy the few you need.

A brief note on How to add new enumeration to existing list of ports in Linux?

The RXTXcomm.jar file contains all the required classes that work with javax.comm API. One of them is RXTXCommDriver.class. is available in Download the In this code, you will find

if (osName.equals ("Linux")) { String[]Temp = { "ttyS", // linux Serial Ports "ttySA" // for the IPAQs }; CandidatePortPrefixes = Temp;

Replace this code with

if (osName.equals ("Linux")) { String[]Temp = { "ttyS", "ttyUSB", // linux Serial Ports "ttySA" // for the IPAQs }; CandidatePortPrefixes = Temp; }

Compile the and add the resulting RXTXCommDriver.class file to RXTXcomm.jar in /usr/java/jdk1.5.0_07/jre/lib/ext/RXTXcomm.jar

P.S. : RXTXcomm.jar has two sub directories. gnu->io->RXTXCommDriver.class. Make sure the new compiled file goes into the right place. One way is to extract all files from RXTXcomm.jar. Replace the RXTXCommDriver.class with the new file. Create a new RXTXcomm.jar file using the following command

  1. jar cvf RXTXcomm.jar gnu META-INF

Replace this new updated jar file with the old one. Then USB to Serial Converters should work great.

How can I use Lock Files with rxtx?

RXTX uses lock files by default. Lock files are used to prevent more than one program accessing a port at a time. Lock files may require a bit of sysadmin to work properly.

If you do not want to use lockfiles in RXTX, run 'configure' with option '--disable-lockfiles'. It is however strongly recommended that you do use lock files to prevent RXTX from stomping on other programs that might use the serial ports concurrently.

(Don't know if the following is still current. Trent?)

RXTX has support for lock files on Linux only. It may work on other platforms but read the source before blindly trying it.

The lock file code does not support kermit style lock files or lock files in '/var/spool'. It is sure to fail if you're using subdirectories in '/dev' or do not have '/dev'.

Before you use lock files you need to do one of two things:

  1. Be user 'root' or user 'uucp' on your machine whenever you use RXTX .. or ..
  2. Add the specific user that needs to use RXTX to the group 'uucp' (preferred)

(On Red Hat, use group 'lock' in addition to 'uucp', see further below.)

To add a user to the 'uucp' group edit '/etc/group' as 'root' (using 'vigr' or your preferred editor) and change the following:


to something like:


It may be simpler to just run

  usermod -G uucp jarvi

which does exactly the same.

In this case 'jarvi' is the login name for the user that needs to use lock files. Do not change the number (14). Whatever is in your group file is correct. (On Red Hat, do this also for group 'lock')

User 'jarvi' in this case can now use RXTX with lock files.

Red Hat users

In Red Hat, lock files are supposed to be handled by group 'lock' instead of group 'uucp'.

Why: from Red Hat 7.2 upwards. the directory into which lock files are written, '/var/lock', can only be written to by members of group 'lock'. On the other hand, the serial device files are owned by group 'uucp' and are not world-writeable by default.

Thus any user (which may or may not actually be using uucp ... do people still know what that was?) that accesses the serial device files must belong to group 'lock' (to create lockfiles) and to group 'uucp' (to access the device files proper). See also I cannot open the port.

Mandrake users

'/var/lock' needs to be owned by group 'uucp'.

Mac OS X users

You may need to create the lock directory with group 'uucp' ownership. There is a script in 'contrib' called '' to help with this on Mac OS X.

In 2.1-7r2(final) there is a mis-match between the lock file directory given in '' that in the source file SerialImp.h (/var/spool/uucp and /var/lock respectively). If you want the binaries to work, you need to replace /var/spool/uucp by /var/lock in, and run that as root.

Lock File server

As another option it is possible to use a Lock File Server. In this case, a server runs in group 'uucp' or 'lock' and rxtx then connects to localhost to lock and unlock the port. The server and install instructions can be found in 'src/lfd'. RXTX will need to be configured to use the server:

    configure --enable-lockfile_server

Any user can then lock the ports if they are not already locked.


Still cant get things to run under a root account?

Vadim Tkachenko writes:

"Maybe you remember - couple of months back I've run into inability to run the JDK 1.3+ from under root account.

Today, absolutely suddenly, something clicked in my head and the cause was found: libsafe. To make JDK work, it is enough to disable libsafe (unset LD_PRELOAD)."

How can I tell which version of rxtx is installed?

Version information is not documented in Sun's CommAPI so this is probably unique to RXTX.

As of rxtx-1.5-4 and rxtx-1.4-6 a class has been added to allow developers to check which version of rxtx is installed. The class is RXTXVersion.

The static method: System.out.println(RXTXVersion.getVersion());

will print the rxtx version as a String in the following format:


an example would be:


A change in the MAJOR version would suggest you're in trouble.

Odd MINOR version are reserved for development. Even MINOR versions are reserved for 'stable' releases.

PATCH is used to differentiate incremental releases of the MINOR releases.

CommPortIdentifier is expected to support getVersion() in the RXTX-1.5 series.

What Type of Latency can I expect with RXTX

frantz <fcapiez at> put RXTX under a scope and found the following:

RXTX currently has a latency of 150-200ms on a PII at 450mhz. The latency can be reduced to 70-80ms by reducing the usleep() value in SerialImp.c:eventLoop() to usleep(5000)).

Much lower latencies should be possible but the maintainer does not have equipment to test changes.

He is going to look at this further. He needs 20 ms or less latency.

I got rxtx working on a new OS but I can't read from the port

> Now my java program starts up nicely without complaining. However, it does
> never read any data from the serial port. It looks like it can write data,
> because if I start a terminal program after I tried to run my program, I get
> all the return stuff from the modem that my program wrote.
> I hacked around abit and found out that it hangs in the select() call which
> simply never returns.
On Sun, 28 Jan 2001, Baldur Norddahl wrote:
> HPUX 11:
> As I wrote to the mailinglist I had some wierd problems where it apparently
> could write data to the modem, but not read anything back. My terminal
> programs had no problem using the port. A few days after I reported the
> problem to the mailinglist, I had given up for now, but then I noticed that
> it suddenly worked! So it remains a mystery what was wrong as I did not
> change anything at all, neither in my program nor on the host.
> Baldur

I suspect two java applications had the port open. Its easy to do while developing. Perhaps <ctl> z instead of <ctl> c was entered.

This is the reason for adding lockfile support to rxtx. If another application has opened the port, a second application will appear to not be able to read or get only part of the data. ..because the first one is reading. Only one of the select()s are waken.

Its possible to put lockfile support in for HPUX if it is known where other applications place their lockfiles. The easiest way to find out where is to fire up minicom, kermit, ... and see where its lockfile is placed.

Here are the known suspects:

const char *lockdirs[]={ "/etc/locks", "/usr/spool/kermit",

               "/usr/spool/locks", "/usr/spool/uucp", "/usr/spool/uucp/",
               "/usr/spool/uucp/LCK", "/var/lock", "/var/lock/modem",
               "/var/spool/lock", "/var/spool/locks", "/var/spool/uucp",NULL

freebsd uses /var/spool/uucp/, linux uses /var/lock those are the only two I've done so far. Adding the support is trivial once a directory is decided upon.

Lockfiles are rather simple. when an application opens a port it first checks if there is a file with the ports name. If there is it grabs the PID from the file. If that PID is still active the application does not open the port.

If the PID is not active or there is no lockfile, the application creates one with its own PID in it.

The confusion starts when you have to decide where (see above) to put the lockfile, what the name format is for the file and how to store the PID.

rxtx follows The File System Hierarchy Standard on linux. I'm not positive what is normal on other OS's.

               more reading:
               The File System Hierarchy Standard
               Proposed Changes to the File System Hierarchy Standard
               "UNIX Network Programming", W. Richard Stevens,
               Prentice-Hall, 1990, pages 96-101.
               more reading:

My ThinkPad is Not Working!

Scott Burleigh <Scott.Burleigh at> writes:

For your files, and in case anybody asks in the future, IBM Thinkpads ship with the external serial port *disabled* by default. The Thinkpad configuration utility supplied with the machine (under Windows) says it's enabled, and the device manager in the System dialog of the Control panel says it's enabled, but they lie. In order to enable the port you have to use the old DOS ps2.exe bios configuration utility which, under Windows 2000, is in c:\Program Files\Thinkpad\utilities:

ps2 sera enable

Until you do, "setserial -ga /dev/ttyS0" will always tell you the UART is unknown.


More info is needed on signing applets. This is an exchange from the rxtx mail- list.

Using Applets

prashantg10 at asked:

Hi All !

I am trying to use applet on thin terminal which has Linux base Kernel.For testing I am using Linux machine.I have install all the required components. e.g. JDK, RXTX. Everthing is fine. BlackBox runs ,even my application runs. When It comes to applet, everything is halts. It does not even show the listing of ports. Is it because applet can't run under root account or what might be the reasons. Can anybody tell me solution.

Son To <> replied:

Java applets run withing the sandbox of the security manager. Applets must be signed to access the com port, but for development purposes you can put

user_pref("signed.applets.codebase_principal_support", true);

in your prefs.js located in ~/.mozilla/default/XYYrandomDirName

I didn't use Java applet for my application. I used XUL and CSS for the GUI development and used mozilla Javascript SOAP library to communicate with apache Axis webservice backend which uses RXTX to access the com port.

-- Trent Jarvi

You made it this far.. what is one more line.

Sun, Solaris and Java are registered trademarks of Sun Microsystems, Inc.


redhat 7.1 needs: export LD_ASSUME_KERNEL=2.2.5

Personal tools