/*-------------------------------------------------------------------------
|   rxtx is a native interface to serial ports in Java.
|   Copyright 1997-2000 by Trent Jarvi trentjarvi@yahoo.com.
|
|   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
|   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
|   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.  Tue Jan  9 00:52:36 MST 2001

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

1.  INSTALL INSTRUCTIONS IN OTHER LANGUAGES

	A. Japanese 

2.  BUILDING COMMAPI SUPPORT

	A.  Quick Install
	B.  Installing Sun's comm.jar
	C.  installing javax.comm.properties.
	D.  Add comm.jar to your CLASSPATH.
	E.  Build and Install the jar.
	F.  Add jcl.jar to your CLASSPATH
	G.  Where did everything end up?
	H.  Cross Compiling for Win32 support

3.  COMMON PROBLEMS

	A.  java.lang.UnsatisfiedLinkError: nSetOwner while loading driver
	    gnu.io.RXTXCommDriver
	B.  Exception in thread "main" java.lang.UnsatisfiedLinkError: 
	    no Serial in java.library.path
	C.  No serial ports found!
	D.  I Can Not Open the Port.
	E.  java.lang.NoClassDefFoundError: javax/comm/CommPort
	F.  The Compiler Cannot Find Java Include Files
	G.  Configure says 'unterminated sed command' and stops 
	H.  Java Can Not Find libstdc++-libc6.0-1.so.2 
	I.  BlackBox Can Not Handle all the ports!
	J.  Illegal use of nonvirtal function call!
	K.  My libc5 Linux system is generating SIGSEGV
	L.  AM_PROG_LIBTOOL not found in library
	M.  Problems with RMISecurityManager()
	O.  Which Wires Should be Connected?
	P.  Which Device Should be Used?
	Q.  It Did Not Work! 
	R.  Which jdk should be used? 
	S.  How does rxtx detect ports?  Can I override it?
	T.  How can I use Lock Files with rxtx?
	U.  How can I tell which version of rxtx is installed?
	V.  What Type of Latency can I expect with RXTX

-------------------------------------------------------------------------------
1.  INSTALL INSTRUCTIONS IN OTHER LANGUAGES
A.  Japanese

	Instructions are available in Japanese at

	http://www.geocities.co.jp/Technopolis/4789/settei.htm#id1
	Thanks to Masayuki "Tencho" Yamashita <tencho@venus.kanazawa-it.ac.jp>
	home page http://www.geocities.co.jp/Technopolis/4789/ 

	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.

2.  BUILDING COMMAPI SUPPORT

	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.

	A.  Quick Install

	The following packages are used to build rxtx:

		autoconf-2.13
		automake-1.4a
		libtool-1.2f
		gnu make-3.77
		jdk 1.2+ or 1.1 	Preferably the native threads version of
		                        jdk. 
		commapi 2.0             the x86 Solaris version

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

		$ tar -xzvf rxtx-1.4.tar.gz
		$ cd rxtx-1.4
		$ ./configure  (follow the instructions)
		$ make install

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

	B.  Installing Sun's comm.jar

		http://java.sun.com/products/javacomm/index.html
		
		Obtain javacomm20-x86.tar.Z from Sun.

		This is the x86 Solaris version of commapi.
		Do not try to use the win32 version.  It will not work.

		extract the files from the archive

		$ tar -xzvf javacomm20-x86.tar.Z

		Place comm.jar in the proper directory.  Everyone likes to 
		put Java in different locations.  I'll use /usr/local/java
		throughout this document.

		jdk-1.1:

			/usr/local/java/lib/comm.jar

		jdk-1.2 and newer:

			/usr/local/java/jre/lib/ext/comm.jar

	C.  Installing javax.comm.properties.

		javax.comm.properties needs the following text in it:

		Driver=gnu.io.RXTXCommDriver

		Some people have said it requires a blank line after the text.

		The file goes in different locations depending upon your jdk
		version

		jdk-1.1:

			/usr/local/java/lib

		jdk-1.2 and newer:

			/usr/local/java/jre/lib
	
		SEE: commapi/PlatformSpecific.html from Sun's commapi package 
		for details.

	D.  Add comm.jar to your CLASSPATH.

		jdk-1.1:

			make sure /usr/local/java/lib/comm.jar is in your
			CLASSPATH.

			in bash:

			$ export CLASSPATH=/usr/local/java/lib/comm.jar:.

		jdk-1.2 and newer:

			No changes are needed.

	E.  Build and Install the jar.

		make 	 	to build jcl.jar and the libraries
		make install 	to place the jar and libraries in the correct 
		                location

	F.  Add jcl.jar to your CLASSPATH
		
		jdk-1.1:

			make sure /usr/local/java/lib/jcl.jar is in your
			CLASSPATH. 

			in bash:

			$ export CLASSPATH=/usr/local/java/lib/comm.jar: \
				/usr/local/java/jcl.jar:.


		jdk-1.2 and newer:

			No changes are needed.
		
		This completes the process.

	G.  Where did everything end up?

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

		jdk-1.2 the files go in
		
			/usr/local/java/jre/lib/ext/jcl.jar
			/usr/local/java/jre/lib/ext/comm.jar
			/usr/local/java/jre/lib/$(ARCH)/libSerial.so.
			/usr/local/java/jre/lib/$(ARCH)/libParallel.so.
			/usr/local/java/jre/lib/javax.comm.properties

		jdk-1.1.* the files go in 

			/usr/local/java/lib/jcl.jar
			/usr/local/java/lib/comm.jar
			/usr/lib/libSerial.so.
			/usr/lib/libParallel.so.
			/usr/local/java/lib/javax.comm.properties

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

	H.  Cross 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. 

		Instructions unique to win32 builds.

		Grab ming32:

		Wayne Roberts contributed the version used by the maintainer.
		(Wayne is largely responsible for bringing rxtx back to win32.)
		http://www.linuxgrrls.org/~taj/crossmingw32-2.95-1.i386.rpm

		I built the dll with jdk-1.2.2 for linux using jdk-1.2.2 
		include files from the win32 JDK.

		Make sure that ming32 bin dir is the first in your path (at 
		least before /usr/bin/gcc)

			$ export PATH=" \
				/usr/local/cross-tools/i386-mingw32/bin/: \
				$PATH:/usr/X11R6/bin:/usr/local/java/bin: \
				/usr/local/java/jre/bin/:"

		Place Sun jdk 1.2.2 win32 include files in a known location.

			$ mkdir /home/jarvi/win32java
			$ cp -r /mnt/win98//java/include /home/jarvi/win32java

			If you are developing win32 support you may want to
			export the location to make the config script
			non interactive

			$ export WIN32INCLUDE=/home/jarvi/tools/win32-include

		run configure to generate a Makefile

			$ cd /home/jarvi/rxtx-*
			$ mkdir build
			$ cd build
			$ ../configure --target=i386-mingw32  \
				--host=i386-redhat-linux

		build the class files and dll.

			$ make

		the files will be located in

			rxtx-*/build/...

		If your looking at rxtx as an example of cross-compiling you 
		may be interested in looking at the examples provided at:

			ftp.xraylith.wisc.edu
			/pub/khan/gnu-win32/mingw32/misc/java-jni-examples.zip

3.  COMMON PROBLEMS

A.  I get java.lang.UnsatisfiedLinkError: nSetOwner while loading driver
    gnu.io.RXTXCommDriver when using rxtx.

	SetOwner appears to be some win32 call.
	Do not use Sun's win32 CommAPI files.  Get Sun's Solaris version.
	"javacomm20-x86.tar.Z" 

	See Also: 2-B.  Installing Sun's comm.jar

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

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

	$ mv /usr/local/java/jre/lib/i386/libSerial* /usr/local/lib
	$ java BlackBox
	Exception in thread "main" java.lang.UnsatisfiedLinkError: no Serial 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 javax.comm.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.

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

C.  No serial ports found!

	There are three ways this can be generated.  

		1.  deleting or misplacing javax.comm.properties
		2.  a typo in javax.comm.properties
		3.  forgetting to put jcl.jar in CLASSPATH

	see also D.  I Can Not Open the Port.

	now for an example of each.

	1. deleting or misplacing javax.comm.properties

	assume the following is working:

	/usr/local/java/jre/lib/ext/comm.jar
	/usr/local/java/jre/lib/ext/jcl.jar
	/usr/local/java/jre/lib/ext/BlackBox.jar
	/usr/local/java/jre/lib/javax.comm.properties

	Deleting javax.comm.properties or placing it in 
	/usr/local/java/lib/javax.comm.properties results in

	$ java BlackBox
	No serial ports found!

	2.  a typo in javax.comm.properties

	lets break the properties files
	$ vi /usr/local/java/lib/javax.comm.properties
	>place intentional typo in the file<
	$ java BlackBox
	Caught java.lang.ClassNotFoundException: gnu.io.rXTXCommDriver 
	while loading driver gnu.io.rXTXCommDriver
	No serial ports found!
	      note------------------^

	$ vi /usr/local/java/lib/javax.comm.properties
	>fix typo<

	--
	For some, it is not clear what was being done here.  There is a single
	line in the file javax.comm.properties that contains
	"gnu.io.RXTXCommDriver" when properly installed.  We replaced the R with
	r in "gnu.io.RXTXCommDriver" to force an error.  After seeing the error
	we replaced the r with an R to fix it.

	3.  forgetting to put jcl.jar in CLASSPATH

	export CLASSPATH=./java/lib/comm.jar:.:./java/lib/classes.zip
	$ java BlackBox
	Caught java.lang.ClassNotFoundException: gnu.io.RXTXCommDriver 
	while loading driver gnu.io.RXTXCommDriver
	No serial ports found!
 
D.  I Can Not Open the Port.

	If your 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.

	see also: C.  No serial ports found!

E.  java.lang.NoClassDefFoundError: javax/comm/CommPort

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

	for example, lets not include comm.jar

	export CLASSPATH=..java/lib/jcl.jar:.:../java/lib/classes.zip
	$ java BlackBoxException in thread "main"
	java.lang.NoClassDefFoundError: javax/comm/CommPort

F.  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 = ...

G. 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 
	javax.comm.properties files and use configure to place them in the 
	correct place. 

H.  Java Can Not Find libstdc++-libc6.0-1.so.2 

	jdk-1.2 on redhat systems may note that Java complains about not being
	able to find libstdc++-libc6.0-1.so.2.  A symbolic link can be used to 
	get around this feature.

	ln -s /usr/lib/libstdc++ /usr/lib/libstdc++-libc6.0-1.so.2
	ls -l /usr/lib/libstdc++-libc6.0-1.so.2
 	/usr/lib/libstdc++-libc6.0-1.so.2 -> libstdc++.so.2.8.0

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

J.  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 javax.comm.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.

K.  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@bencom.co.nz>

L.  AM_PROG_LIBTOOL not found in library

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

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

M.  Problems with RMISecurityManager()

	Please see the file RMISecurityManager.html 

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

P.  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?
  
Q.  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.

        ---------------clip-----------------
#!/bin/sh
which java
java -version
uname -a
autoconf --version
automake --version
libtool --version
make --version
        ---------------clip-----------------

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

		java 1.2
   		autoconf 2.13
   		automake 1.4a
   		libtool 1.2f
   		make 3.77


	mail any bugs to trentjarvi@yahoo.com.  

R.  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 wont 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 wont 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.

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

T.  How can I use Lock Files with rxtx?

Lock files are used to prevent more than one program accessing a port at a
time.  Rxtx intentionally avoids defaulting to lock files at this point because
the code has not been well tested and requires a bit of sysadmin most people
do not want to deal with.

Rxtx has preliminary support for lock files on Linux.  It may work on other
platforms but read the source before blindly trying it.  In order to use lock 
files you will need to configure rxtx with --enable-lockfiles.
ie  ./configure --enable-lockfiles

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

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

To add a user to the uucp group edit /etc/group as root and change the 
following:
	uucp::14:uucp
to something like:
	uucp::14:uucp,jarvi
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.

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

Be careful.  The lock file code does not support kermit style lock files or
lock files in /var/spool.  Its sure to fail if your using subdirectories in
/dev or do not have /dev.

U.  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 your 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.

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

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

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