RXTX - Full Java CommAPI implementation
=======================================

This package contains a full implementation of the Java CommAPI from Sun. To
use applications, written with the original CommAPI, with rxtx you have to
change references to javax.comm.* to gnu.io.*.

The rest of this file contains some useful information about problems with the
rxtx package found in the upstream INSTALL file. The unimportant sections are
left out.

-------------------------------------------------------------------------------
3.  COMMON PROBLEMS

[...]

B.  Exception in thread "main" java.lang.UnsatisfiedLinkError: no rxtxSerial in
    java.library.path

        librxtxSerial.so is located in the wrong directory.  Here is an example

        $ mv /usr/local/java/jre/lib/i386/librxtxSerial* /usr/local/lib
        $ java BlackBox
        Exception in thread "main" java.lang.UnsatisfiedLinkError: no rxtxSerial
        in java.library.path
                at java.lang.ClassLoader.loadLibrary(Compiled Code)
                at java.lang.Runtime.loadLibrary0(Compiled Code)
                at java.lang.System.loadLibrary(Compiled Code)
                at gnu.io.NativePort.<clinit>(NativePort.java:32)
                at gnu.io.RXTXPort.<init>(Compiled Code)
                at gnu.io.RXTXCommDriver.getCommPort(Compiled Code)
                at gnu.io.CommPortIdentifier.open(Compiled Code)
                at SerialPortDisplay.openBBPort(Compiled Code)
                at SerialPortDisplay.<init>(Compiled Code)
                at BlackBox.addPort(Compiled Code)
                at BlackBox.main(Compiled Code)

                ... lets fix it.

    Solution 1: move the file to a place that works

         $ mv /usr/local/lib/librxtxSerial.* /usr/local/java/jre/lib/i386/

    Solution 2: add the location of librxtxSerial to LD_LIBRARY_PATH

         $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/

    Solution 3: pass the location in on the command line

         $ java -Djava.library.path=/usr/local/lib/ ...

C.  I Can Not Open the Port.

        If you're not able to open the port (read the errors carefully) then you
        may not have permission to use the device.  Redhat Linux ships with the
        following permissions:

        crw-r--r--   /dev/ttyS?

        Users need to be able to read and write with serial communication...

        chmod 666 /dev/ttyS?

        should fix the problem.  Be sure to check the file CommAPI for common
        mistakes.

        Make sure that the user can create lock files.

D.  java.lang.NoClassDefFoundError: gnu/io/CommPort

        RXTXcomm.jar is probably not in your classpath or not located in
        the proper directory.

        for example, lets not include RXTXcomm.jar

        export CLASSPATH=../java/lib/classes.zip
        $ java BlackBoxException in thread "main"
        java.lang.NoClassDefFoundError: gnu/io/CommPort

[...]

H.  BlackBox Can Not Handle all the ports!

	BlackBox has a hard coded limit in BlackBox.java 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

	is:

		portDisp = new SerialPortDisplay[50];

	just change 50 to say 256.

I.  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 gnu.io.RXTXCommDriver.getCommPort(Compiled Code)
		at gnu.io.CommPortIdentifier.open(Compiled 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.

	Louis"

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

[...]

L.  Problems with RMISecurityManager()

	Please see the file RMISecurityManager.html

M.  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.

N.  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?

[...]

P.  Which jdk should be used?

	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 won't start "Unable to load /usr/local/java/jre/bin/libhpi.so: symbol
sem_wait, version GLIBC_2.1 not defined in file libpthread.so.0 with link time
reference Could not create the Java virtual machine."

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

Conclusion?  Avoid Sun's native threads unless you can figure out whats going
wrong.

Q.  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 gnu.io.rxtx.SerialPorts
and gnu.io.rxtx.ParallelPorts.  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

	java -Dgnu.io.rxtx.SerialPorts=/dev/cua/a:/dev/cua/b com.foo.MyApp

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 RXTXCommDriver.java 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.

[...]

S.  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:

        "RXTX-MAJOR.MINOR-PATCH".

an example would be:

        "RXTX-1.5-4"

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.

T.  What Type of Latency can I expect with RXTX

	frantz <fcapiez@club-internet.fr> 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.

U.  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 weird 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 http://www.pathname.com/fhs/
on linux.  I'm not positive what is normal on other OS's.

                more reading:

                The File System Hierarchy Standard
                http://www.pathname.com/fhs/

                FSSTND
                ftp://tsx-11.mit.edu/pub/linux/docs/linux-standards/fsstnd/

                Proposed Changes to the File System Hierarchy Standard
                ftp://scicom.alphacdc.com/pub/linux/devlock-0.X.tgz

                "UNIX Network Programming", W. Richard Stevens,
                Prentice-Hall, 1990, pages 96-101.
                more reading:

V.  My ThinkPad is Not Working!

	Scott Burleigh <Scott.Burleigh@jpl.nasa.gov> 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.

4.  APPLETS

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

A.  Using Applets

prashantg10@yahoo.com 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. Everything 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 <son@openbx.net> replied:

        Java applets run within 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.

-------------------------------------------------------------------------------

--
Mario Jou/3en <joussen@debian.org>