/*-------------------------------------------------------------------------
|   RXTX License v 2.1 - LGPL v 2.1 + Linking Over Controlled Interface.
|   RXTX is a native interface to serial ports in java.
|   Copyright 1997-2007 by Trent Jarvi tjarvi@qbang.org and others who
|   actually wrote it.  See individual source files for more information.
|
|   A copy of the LGPL v 2.1 may be found at
|   http://www.gnu.org/licenses/lgpl.txt on March 4th 2007.  A copy is
|   here for your convenience.
|
|   This library is free software; you can redistribute it and/or
|   modify it under the terms of the GNU Lesser General Public
|   License as published by the Free Software Foundation; either
|   version 2.1 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
|   Lesser General Public License for more details.
|
|   An executable that contains no derivative of any portion of RXTX, but
|   is designed to work with RXTX by being dynamically linked with it,
|   is considered a "work that uses the Library" subject to the terms and
|   conditions of the GNU Lesser General Public License.
|
|   The following has been added to the RXTX License to remove
|   any confusion about linking to RXTX.   We want to allow in part what
|   section 5, paragraph 2 of the LGPL does not permit in the special
|   case of linking over a controlled interface.  The intent is to add a
|   Java Specification Request or standards body defined interface in the
|   future as another exception but one is not currently available.
|
|   http://www.fsf.org/licenses/gpl-faq.html#LinkingOverControlledInterface
|
|   As a special exception, the copyright holders of RXTX give you
|   permission to link RXTX with independent modules that communicate with
|   RXTX solely through the Sun Microsytems CommAPI interface version 2,
|   regardless of the license terms of these independent modules, and to copy
|   and distribute the resulting combined work under terms of your choice,
|   provided that every copy of the combined work is accompanied by a complete
|   copy of the source code of RXTX (the version of RXTX used to produce the
|   combined work), being distributed under the terms of the GNU Lesser General
|   Public License plus this exception.  An independent module is a
|   module which is not derived from or based on RXTX.
|
|   Note that people who make modified versions of RXTX are not obligated
|   to grant this special exception for their modified versions; it is
|   their choice whether to do so.  The GNU Lesser General Public License
|   gives permission to release a modified version without this exception; this
|   exception also makes it possible to release a modified version which
|   carries forward this exception.
|
|   You should have received a copy of the GNU Lesser 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
|   All trademarks belong to their respective owners.
--------------------------------------------------------------------------*/
This is README Wed Apr 25 22:37:26 MDT 2007

See Also:

INSTALL:   install instructions and solutions to common problems
TODO:      Comments for developers
COPYING:   The LGPL license
PORTING:   hints for people trying to port rxtx
Authors:   who wrote what.
ChangeLog: when they wrote it.
RMISecurityManager.html:  Comments for people using RMISecurityManager
SerialPortInstructions.txt:  HOWTO on read/writing to your com ports on linux for beginners

There are numerous possibilities for projects that involve serial communication.
Java is an excellent language for putting GUI apps together.  Well have fun.
Send back stories.

Copies of the latest RXTX will be on http://www.rxtx.org/download
The primary source for information/support is http://www.rxtx.org.
The rxtx mail-list is at Majordomo@hex.linuxgrrls.org.
Send email with "subscribe rxtx" in the subject without the quotes to join.

This is a native lib for jdk 1.1.* and newer.  If you find changes required
for different platforms or OS's please pass them back this way so we may share
it with others.  Credit will be given unless one specifically requests no
credit.

We chopped rxtx out of my program and tried to put a small example together.
There is plenty of room for configurability, safe guarding and error reporting.
If you have some time please contribute some improvements.

We are interested in sharing this code in hopes that a more versatile lib may
be developed and released with minimal restrictions.  Please send any patches
back my way if you like.

If you are interested in using rxtx for things like RS485, I2C or raw IO Please
get the latest CVS version.  Some work has been done for each of them.  The
latest development version is a stand alone implementation of CommAPI.

For bug reports please follow the directions in INSTALL

Trent Jarvi
taj@www.linux.org.uk

  Here's what I came up with as far as documentation.  First, I'm mainly a
  windows person... ewww.. but, as such.. some things are probably not
  solved optimally.

  ---
  Getting the Comm API working on an Ipaq
  Thomas O'Connell (thomas@cc.gatech.edu)

  For the most part, things go pretty much according to the documents
  provided by: http://www.interstice.com/~kevinh/linuxcomm.html

  I'll just cover the gotchas:

  1) Getting Java itself to run:  This was actually the most complicated
  part (for me).  You can download a JRE 1.3 from Blackdown for the ARM
  processor, but no JDK.  But you can tease a javac, jar, javah, etc.. out
  of a tools.jar file from some other distro(i went with an i386 linux
  sdk, same version as the JRE), and writing scripts to emulate the
  behaviors (and adding tools.jar to your classpath).

  Example:
  javac is:
  #! /bin/sh
  java com.sun.tools.javac.Main $@

  The rest can be created similarily.  I kept pulling as many as those out
  until the .configure of rxtx stopped complaining.

  - include files: in addition to pulling tools.jar from another linux
  jdk, I brought over the <jdk>\include files too.  Dumped it in the
  <j2re1.3.1> directory.

  - sim link: in the j2re1.3.1 directory, I created a jre sub directory,
  and beneath that I sym linked a j2re1.3.1\jre\lib to j2re1.3.1\lib.
  Also, both my JDK_HOME and JAVA_HOME were set to the j2re1.3.1 location.


  After all this, the rxtx package built correctly.  I added jcl.jar to my
  classpath as well.

  Your mileage may vary here, since I'm doing this all from recollection.
  I imagine I'll have to reformat at some point and pay more attention the
  next time I have to set it up.  Lots of trial and error here, and I'm no
  script kiddie.. I imagine some of this could be fixed up internally.


  2) Killing getty -  So there's the console terminal running on the comm
  port.  You need to be able to kill this in order for the comm port to be
  released.  Since you don't want to entirely kill getty (since,
  networking is often flaky on these things), I just changed the
  /etc/inittab with regards to getty.

  Changed: T0:2:respawn:/sbin/getty -L tts/0 115200 vt100
  To: T0:2:boot:/sbin/getty -L ttySA0 115200 vt100

  This keeps the ipaq from respawning getty everytime you kill it, but
  does activate it upon boot.


  3) Fixing RXTXCommDriver.java.   Based on OS, the code tried to find the
  serial ports.  This will fail because of a naming convention that
  Intimate/?Debian? uses for the com ports.  Need to add a prefix that
  includes ttySA.  By default the code looks like:


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

  4) Cable:  The hotsync cable that the ipaq comes with is a null modem
  cable.  compaq does sell a RS-232 cable for the hotsync port, if you're
  trying to control a serial device like me.  $26 though..

  --
  Thomas O'Connell               Georgia Institute of Technology
  Aware Home Lab ManagerCollege of Computing
  www.cc.gatech.edu/fce/ahri           www.cc.gatech.edu/~thomas

$Id: README.OSX,v 1.1.2.2 2006-06-20 09:46:47 jarvi Exp $

For uptodate information about RXTX goto http://www.rxtx.org


------------------------ Installation on MacOSX -----------------------

WARNING: Please read this section until the end.

----
The unsafe way of using RXTX on OS X:
----

RXTX can be installed by putting the files
  libSerial.jnilib
  RXTXcomm.jar
into the folder
  /Library/Java/Extensions

This is NOT RECOMMENDED as it creates versioning conflicts among applications.
However you may be forced to install it this way if an application was written
for Windows or Linux, requires RXTX and you are not able to change its starter.


----
The safe way of using RXTX on OS X:
----

Make sure that you have no (older) version of RXTX installed in
  /Library/Java/Extensions
  /System/Library/Java/Extensions
  /usr/lib/java

Put
  libSerial.jnilib
in the directory of the application (the JavaVM will find it there). Add
  RXTXComm.jar
to the application classpath or include the classes in the application jar.
(Some applications already include the RXTX classes in their application jar,
in which case only the file libSerial.jnilib is required).



----
History
----

Up to version 2.0.7/2.1.7 RXTX used lockfiles on MacOSX. The creation of lockfiles
required special permissions for the user executing an application based on RXTX.
To simplify the setup RXTX came with an installer modifying group permissions
and installing RXTX in the global location /Library/Java/Extensions. However
this was prune to versioning conflicts and is no longer recommended.

--------------------- Build instructions for OSX XCode -------------------

contributed by Joachim Buechse <joachim@buechse.de>
original version by Dmitry Markman <dmarkman@mac.com>

System requirements for building:
MacOSX 10.4
XCode 2.3

  open MACOSX_IDE/XCode/LibSerialUniversal.xcodeproj
  choose libSerial.jnilib target
  build

After the build you will find RXTXcomm.jar and libSerial.jnilib files in the
directory build/Development.

In case you can't find RXTXcomm.jar build the RXTXcomm target manually.
In case of (serious) problems feel free to contact joachim@buechse.de .

--------------------- Gnu Tool Builds -----------------------

If you are going to try building rxtx on Mac OS X, we recommend you use
rxtx 1.5.   1.4 would require substantial modification to the Makefile to
get the build to work.

Mac OS X has some issues with libtool at this time.  This makes building
rxtx much more difficult.

The current solution is to take an automatically generated Makefile and then
manually edit it.

One such Makefile is provided to help build rxtx.  The file will probably
need to be edited to match your system configuration.  If you would like to
add more information for other Mac OS X users please email

	taj@www.linux.org.uk.

We are sorry the build process is not easier.  A great deal of effort was
put into trying to automate the builds without luck.

This is README.SCO Last Modified Thu Oct 18 13:58:28 MDT 2001
UnixWare and OpenUNIX related Documentation

This document is the release notes From Caldera before the merge see notes.

Java Communications API Implementation for Caldera UNIX Operating Systems
Version 2.0 Beta-3
October 2, 2001

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

notes:

This was Version 2.0 Beta-3 notes.  The work is being merged into the rxtx CVS.
Some minor changes will happen and will be noted here.

Thanks to Jonathan Schilling <jls@caldera.com> and Caldera for the SCO port!

1)  RXTX does not ship with Sun's comm.jar.  It can be obtained from Sun.
2)  The Lockfile could use some work.  It possible to fix it at compile time
    but a run time solution would allow.  The current behavior is to use FHS
    locks.  This should be the same behavior as rxtx-1.4-8 as used in the
    original SCO port.
3)  in configure.in you will want to comment out 2 lines and run autoconf in
    the top rxtx directory before building.  The lines are:

	# Comment these two lines out when compiling on SCO
	AC_DISABLE_STATIC
	AM_PROG_LIBTOOL
	# end of SCO fixes

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

These are the Release Notes for the beta release of an implementation of
the Java Communications API (also known as javax.comm) for Caldera UNIX
operating systems.

The Java Communications API is described at
http://java.sun.com/products/javacomm/index.html.

This implementation is available for the following Caldera UNIX operating
systems:

	Open UNIX 8.00
	UnixWare 7.1.1
	OpenServer 5.0.6 with rs506a supplement

A prerequisite is that Java 2 Standard Edition v. 1.3.0 for Caldera UNIX
Operating Systems must already have been installed (including any
packages or ptfs required by J2SE 1.3.0).  This requirement may be met
by either the J2SE SDK (package java2sdk3) or the J2SE Runtime Environment
(package java2jre3).

While J2SE 1.3.0 for OpenServer does not require the rs506a release
supplement be installed, this javax.comm implementation does.

This implementation is a port of the open source RXTX implementation of
the Java Communications API.  Information about RXTX may be found at
http://www.rxtx.org.  This port has been done off of RXTX version 1.4-8.

RXTX includes part of the Sun Java Communications API implementation
for Solaris/x86, version 2.0.  This part (the comm.jar file) is included
in this distribution; you do not need to download it from the Sun web page.

To install this beta implementation, place the javaxcomm.ds file somewhere.
Go there, become root, and then do:

	# pkgadd -d 'pwd`/javaxcomm.ds

This will install package javaxcomm, which places the following files into
the J2SE 1.3.0 directory structure:

	/usr/java2/jre/lib/ext/comm.jar
	/usr/java2/jre/lib/ext/jcl.jar
	/usr/java2/jre/lib/x86at/libSerial.so
	/usr/java2/jre/lib/x86at/libParallel.so
	/usr/java2/jre/lib/javax.comm.properties
	/usr/java2/javax.comm-ReleaseNotes.txt [this file]

Alternatively, if you are installing the Java Communications API in
conjunction with the J2SE Runtime Environment rather than the J2SE SDK,
then use the jrexcomm.ds file instead:

	# pkgadd -d 'pwd`/jrexcomm.ds

which will install the following files as part of package jrexcomm:

	/usr/jre2/lib/ext/comm.jar
	/usr/jre2/lib/ext/jcl.jar
	/usr/jre2/lib/x86at/libSerial.so
	/usr/jre2/lib/x86at/libParallel.so
	/usr/jre2/lib/javax.comm.properties
	/usr/jre2/javax.comm-ReleaseNotes.txt [this file]

You can install both the javaxcomm and jrexcomm packages if you desire,
as long as you have both java2sdk3 and java2jre3 installed.

The installed binaries of either Java Communications API package are used
for all three Caldera UNIX platforms.  (On OpenServer, the native code
libraries are executed via the OSRcompat binary compatibility module,
just as the native code layers of J2SE 1.3.0 are.)

To use this implementation of Java Communications API, just compile and
run Java as you normally would.  Because the above files are installed
into the standard J2SE 1.3.0 extension space, there is no need to set
CLASSPATH or LD_LIBRARY_PATH to access the Java Communications API.

A simple test of the serial I/O part of this implementation can be
done as follows.  Set up a null modem RS-232 cable between two machines.
Become root.  Run the open source "minicom" tool
(see http://www.pp.clinet.fi/~walker/minicom.html) on each machine
and verify that the connection is working, by typing characters back
and forth between the two machines.  Caldera can make available
minicom-ou8-uw7 and minicom-osr5, ported versions of minicom for
the Caldera UNIX platforms.  (Note that you need to first do
"minicom -s" to tell it about the names and speeds of your serial ports.
When you then run "minicom", use the ctrl-A E and ctrl-A A commands to
turn on local echo and linefeed add.)

Once working serial communication has been verified, shut down minicom
on the machine that Java Communications API is installed on.  Untar the
Sun SerialDemo demo program, which is SerialDemo.tar and can be made
available by Caldera.  Change into the SerialDemo directory, and run

	# /usr/java2/bin/java SerialDemo
or
	# /usr/jre2/bin/java SerialDemo

This should bring up a GUI.  Change the serial device port name and speed
in the GUI if necessary, then click "Open Port".  (Contact Caldera if the
port name you are interested in does not appear in the GUI.)  Type into the
top pane and text should appear in the minicom window on the other machine.
Type into the minicom window on the other machine and text should appear
in the middle pane of the SerialDemo GUI.  Click "Close Port" to finish.

This implementation uses the normal UNIX "lock file" protocol to protect
serial ports from concurrent access.  This means that javax.comm will
not be able to access the port if it is already locked by another
serial application (whether javax.comm, non-Java, or a system command),
and vice versa.  In the case where javax.comm is locked out, you may get
a message containing the phrase "Port currently owned by unknown Solaris
Application"; for "Solaris" read the Caldera UNIX operating system you
are on.

Additional sample programs using the Java Communications API are available
as part of the Sun Solaris/x86 implementation and can be downloaded from
http://java.sun.com/products/javacomm/index.html.  (Do not use the
SimpleRead and SimpleWrite programs without modification, since they fail
to properly close the serial port at program completion.)

Known problems:

The lock files in Open UNIX 8 and UnixWare 7 will protect against
concurrent port access by multiple javax.comm applications, but will not
protect against concurrent access by other applications or system commands
that use the SVR4 serial lock file protocol (/var/spool/locks/LK.m.m.m).
This will be corrected in the final release.  On OpenServer, the lock files
protect against all concurrent access, assuming other applications are
using the standard protocol there (/usr/spool/uucp/LCK..tty?A).

The parallel I/O part of this implementation has not been tested at all
on any Caldera UNIX platforms.

RXTX is available under the GNU Library General Public License (LGPL).
Because this is still just an beta level implementation, the ported
source code for RXTX is not included with this distribution.  Once this
implementation is final, source code will be included.  If you would
like the source code for this beta implementation, please contact
Caldera and it will be sent to you.