SerialPort Install Notes

The Java Tool For Serial Ports
Version 6.1
WinXP/2K/NTx86/98/95, OS/2, Mac PPC OS9/OSX,
Solaris Sparc/x86, Linux x86/ARM, FreeBSD x86, HP/UX PA-RISC, SGI IRIX MIPS, IBM AIX PPC, SCO UnixWare IA32, Compaq Tru64 Alpha, Novell Netware, WinCE MIPS/SH3/SH4/ARM, EPOC32 ARM, PocketPC 2002 MIPS/SH3/SH4/ARM

Java compatability Note

This version was compiled with JDK 1.4.0. Due to enhancements in JDK 1.4.0, certain older code may not run as expected when run on older versions of the Java VM (1.1.8 in particular). If you plan to run on JDK 1.1.8 use the Serialio.jar in the ../Core/Jars/JDK118 folder.


The Java SerialPort tool provides access to the serial ports of the computer allowing you to communicate with barcode readers, modems, mice, printers, sensors, or any serial device.

The SerialPort tool should work with any Java Virtual Machine (VM) that is compliant with any of the following native method implementations provided we support that platform.

Sun’s ‘Classic’ native methods interface (JDK 1.0.2)
Sun’s JNI – Java Native Interface (JDK 1.x and later) 
Microsofts RNI1 (with J++ 1.0, 1.1, and MSJDK 1.0, 1.5, 1.51)
Microsofts RNI2 (with MSJDK 2.0)
Insignia EVM
NSICom CrEme

Examples of JNI compliant packages are Sun’s JDK 1.1.x and later, Symantec Visual Cafe, Borland JBuilder, IBM VisualAge for Java, ParcPlace Parts For Java, SuperCede 2.x, IBM JDK for OS/2, Apple’s MRJ 2.x. Any Sun JDK 1.1 or later port running on any platform.also support JNI.

The correct version of the shared library (or DLL) is loaded dynamically when the SerialPort object is created.

The default Serialio and JavaTerm classes are built for use with the JDK 1.1.x. Class files for Java 1.0.2 (supported on Win32 only) have also been provided if you’re still using JDK 1.0.2.

Note: The Microsoft JDK 1.0 jview does not correctly report an unsatisfied link error when it cannot find a DLL. If you launch JavaTerm.exe or use jview JavaTerm and you do not see the JavaTerm GUI window the most likely cause is jview cannot find the DLL(s). Also note that the JavaTerm.exe is not a true EXE file and will only run if you have the Microsoft VM installed.

Currently, the SerialPort package works with applications or applets. You must remember that to use SerialPort with an applet the applet must be ‘trusted’ i.e. digitally signed. 

If you purchased a Standard license, then to use SerialPort with a platform other than the one it was initially purchased for, the license for the other platform must be purchased. For Example if you purchase SerialPort for Windows and want to use it on a Linux system, you must purchase the Linux license. If you have a Platform, Professional or Enterprise license, support for multiple platforms is included.

Using Packages

Note that SerialPort is ‘packaged’ and therefore must be installed properly according to CLASSPATH package rules in order to function properly. If you wish to use SerialPort in a ‘unpackaged’ fashion you must purchase the DLL sources and modify them. Microsoft Java note: The Serialio classes are packaged only for Microsoft VM 2.x and later, if you using an ealier VM you will need to comment out the package and import statements in the source code.

Building Applets

If you are planning to build applets with SerialPort, our Termlet package can be purchased to aid your development. The Termlet package includes step-by-step instructions on how Termlet was created, the source code for Termlet, the supporting build files, and other useful information related to running applets that access the serial ports on the browsers machine.


This installation assumes you have installed the JDK (Java Developer Kit), or an equivalent product.

Distribution files are packaged in ZIP format (.zip). Use your favorite ZIP tool to unpack the zip files. If you don’t have a ZIP extractor you can get one for FREE from for almost any platform in existence. For a Windows specific version get an evaluation copy at

There are in essence two simple steps to the basic install, First install the core JAR, Second install the native library. Some platforms have installers that perform both of these steps.

SerialPort API:

Java 2 (aka JDK 1.2.x, 1.3.x, 1.4.x)

Step One: copy Serialio.jar into your $JavaLib/ext.
For example: for the JRE the default directory would be
(on Win32) “C:\Program_Files\JavaSoft\JRE\1.3.1\lib\ext”.
(on Win32) Note: With JDK1.4.0 the JRE folder changed to “C:\Program_Files\Java “.
(on RH Linux 7.3) /usr/java/jdk1.3.1_03/jre/lib/ext

Note: By default, when using the JDK on Windows 2000 the JRE directory is used. If you put the JAR file into C:\jdk1.3.1\jre\lib\ext you will get java.lang.NoClassDefFoundError for the Serialio classes. If you are going to use the Java compiler (javac) also put a copy of the JAR into C:\jdk1.3.1\jre\lib\ext. If you modify the Serialio classes, and don’t want to JAR them each time you test, set the CLASSPATH to include the directory to search for the Serialio files e.g. if the Serialio classes are in C:\jsp\Serialio then the CLASSPATH must include C:\jsp (remember Serialio is a package so JDK looks in the Serialio subdirectory for the classes).

Note: You will find that using CLASSPATH with JDK 1.3 and later is somewhat smarter than with previous JDKs. The classpath override appends the built-in CLASSPATH. For example when you use java classpath c:\jdev\jsp, that is the same as java classpath c:\jdk1.2\jre\lib\rt.jar;c:\jdev\jsp with JDK 1.2.

Note: If your using Visual Cafe 4, this folder would be something like C:\VisualCafe4\Java2\lib\ext. If you installed JDK 1.2.2 on Linux in /usr, the directory would be /usr/jdk1.2.2/jre/lib/ext. For Tru64 Unix this would typically be /usr/opt/java122/jre/lib/ext.

Java 1.1 (Desktop – Pocket devices differ)

The term $JAVA_HOME used hereafter indicates the default directory/folder where Java searches for the file. For example, if the JDK 1.1.7 is installed on Windows to the directory c:\jdk117, the default location of $JAVA_HOME is C:\jdk1.1.7\lib. If you install Symantec Visual Cafe PDE to the directory C:\VC2PDE, then the default location of $JAVA_HOME is C:\VC2PDE\Java\Lib.

1) Set CLASSPATH to point to the Serialio JAR. If you have installed SerialPort in a directory named C:\jsp then add the following to the CLASSPATH settingC:\jsp\core\Serialio\Serialio.jar

OR do the following (this is handy if making changes to Serialio sources):

1a)  Create a directory named Serialio (case sensitive) that is a subdirectory of where the main Java classes exist e.g. create the directory C:\jdk1.1.7\lib\Serialio. Note: Some Java implementations on Unix variants may require the Serialio files to be placed in the $JAVA_HOME/classes/Serialio directory (you may need to create $JAVA_HOME/classes). For Microsoft Java use the CLASSPATH option below, or figure out what the currently used base directory name is for the version of the MS Java VM that your using is and create a directory named Serialio there. At one time this name was  %SystemRoot%\Java\Classes where %SystemRoot% is generally C:\Windows for Win95/98 and C:\WinNT for WinNT.

1b) If you’re using Java 1.0.2, choose or create a directory that is in your current CLASSPATH. If your Java development will done in the same directory where the SerialPort files exist, then this directory need not be in CLASSPATH.

2) Copy the class files from the Serialio archive to the directory created in 1a/1b.

3) Set you CLASSPATH to the parent directory of the Serialio directory used in 1a). In this example CLASSPATH should include the following C:\jdk117\lib.Note: Serialio is a package so Java will look for it in the Serialio directory, if you point the CLASSPATH to the Serialio directory where the classes are, the classes won’t be found because Java will search for them in a subdirectory named Serialio of that directory.

Comm API:
First install the Serialio.jar as shown above, then follow same instructions as for Serialio.jar above, except use the file jspComm.jar

Note: Other tools may install the Sun Comm API JAR file int $JavaLib/ext (e.g. Dallas Semiconductor’s iSite toolkit). Be sure to remove the Sun JAR file when using this implementation (i.e. in the above example be sure you have c:\jdk1.2\jre\lib\ext\jspComm.jar and NOT c:\jdk1.2\jre\lib\ext\comm.jar.

If you are modifying the serialio, or javax.comm.SerialPort source code files it is quicker to create a Serialio and javax.comm directories in the CLASSPATH instead rebuilding the JAR(s) each time you want to test. A Caveat with Java2 if you have jspComm.jar in thejre\lib\ext folder and you remove the Serialio.jar file from jre\lib\ext folder, then you will likely get a java.lang.NoClassDefFoundError: Serialio/SerialPortLocal error even when you have the proper CLASSPATH setting and the Serialio class files in the proper directory. Apparently (at least with JDK 1.2.2) you cannot have the jspComm.jar in the jre\lib\ext folder and the Serialio classes in a directory on the CLASSPATH. If you want to use the directory method you must have the proper javax.comm classes in the javax.comm directory, and Serialio classes in the Serialio directory.

If you get an error similar to the following when trying to build the SerialPort classes, your CLASSPATH is probably not set correctly. Class Serialio.SerialConfig not found in type
        public void configure(SerialConfig cfgObj) throws IOException;
1 error

Depending on what Java platform you’re using you may need to include the current directory in your CLASSPATH statement. The above example installation for Windows would be as follows CLASSPATH=.;C:\jdk117\lib (the ‘.’ indicates the current directory).

Note: It is a common mistake to think that the CLASSPATH entry “C:\jdk117\lib\” is the same as “C:\jdk117\lib;”. The functionality of these two entries is not the same unless you have added all classes existing in the C:\jdk117\lib directory tree to Java searches the classpath for directory names to match package names, thus for the Serialio package, if it cannot find the class(es) in it will look in C:\jdk117\lib\Serialio.

If you wish to put the Serialio files other than the default location (i.e. $JAVA_HOME/lib/Serialio) be sure to add that location to your classpath. For example if you put the Serialio classes in the C:\MyJavaStuff\Serialio, you will need to add C:\MyJavaStuff to your classpath.

Java2 Notes:

When using packages, that the CLASSPATH settings may not behave as expected. For example suppose you run the JavaTerm demo using JDK 1.2 (Java 2) and the unpackaged class files (as the demo is shipped) and every thing works fine. Next you create a jTerm.jar containing all the JavaTerm class files and put this in the jre\lib\ext folder then find that you get an error similar to the following when trying to run JavaTerm.

D:\Some Folder Not Containing The JavaTerm Classes>java JavaTerm

java.lang.NoClassDefFoundError: Serialio/SerialPortLocal
        at JavaTerm.initPort(
        at JavaTerm. <init>(
        at JavaTerm.main(

The reason for this is due to CLASSPATH search behavior. The solution in this example is to copy Serialio.jar to the jre\lib\ext folder.

Windows CE and Pocket PC 2002 / Sun Personal Java Notes:

Sun’s Personal Java (pJava) should be available from a link on this page

Supports MIPS, SH3, SH4, ARM, X86

The pJava CLASSPATH bahavior on WinCE is not the same as the desktop. If you wish to use the SerialPort package for applications that start by double-clicking on the .CLASS file, you need to do one of the following:

A) Create the directory $JDK_HOME\Classes\Serialio. This is normally “My Handheld PC\Program Files\Java\Classes\Serialio”. This is recommended.

B) Create a Serialio directory in the directory of your application, and place the Serialio classes there. Caveat: this way only allows the Serialio classes to be seen from the application directory where Serialio is installed.

C) Copy Serialio.jar to a location of your choice, and modify the registry entry as outlined in the pJava readme file. For example: copy Serialio.jar to “\Program Files\Java\lib” then change the registy setting to:
“\Program Files\Java\bin\pjava.exe” -classpath “\Program
Files\Java\lib\Serialio.jar” -file “%1”

Note: The SerialPort classes can be obtained by unpacking Serialio.jar or rebuilding the sources.

We discovered a bug in pJava beta2 (which has been reported to Sun, and they say should be fixed in FCS) where the method System.getProperty(“os.arch”) returns “unknown” for both SH3 & SH4 platforms. To use SerialPort on an SH3 or SH4 CPU with beta2 you will need to modify to force loading the DLL name for your platform e.g. jspLib = “jspWceSh3”

Native Lib: Windows XP/2K/NT/Me/98/95

There are 4 DLLs for Win95, Win98 and WinNT.
jspWin.DLL, jspWinNm.DLL, jspWinRni.DLL,  jspWinRnia.DLL

Only jspWin.DLL is required if your using a JNI compliant VM

Win95/Win98/Me: Copy the DLL(s) to the Windows\System directory.

WinNT/Win2K: Copy the DLL(s) to the Winnt\System32 directory.

WinXP: Copy the DLL(s) to the Windows\System32 directory.

Note: Only one of these DLLs is used depending on what Java vendor/version is running. For example jspWin.DLL provides the JNI support for SerialPort so if you using the Sun JDK or a JNI compliant Java product like Symantec Visual Cafe you only need this DLL.

Note:: You can put the DLL can be in any directory if you add that directory to the PATH statement.

Netscape Note: If you plan to use SerialPort with a Netscape Communicator applet you will need to put the JNI dll Netscape\Communicator\Program\java\bin folder.

If your using Windows Explorer with the default settings you will not be able to see the .DLL files. To see the DLL files with Windows Explorer, verify the following on the View panel under View | Options: 1) “Show all files” is checked, 2) “Hide file extensions for known file types” is not checked.

PATH Notes:
Depending on what your system configuration is, you may have multiple Java VMs installed. Be sure your path is set up to find the VM you wish to use first. If for example, if you have Microsoft IE installed, and have also installed the Java VM option, you will have the Microsoft Java VM in your default path. If you then install another VM e.g. JDK1.1.8, you will need to modify your path to find the Sun VM. For example suppose you install JDK 1.1.8 into C:\jdk1.1.8 you would be sure your PATH is set such that C:\jdk1.1.8\bin comes before your Windows\System or WinNT\System directory. Note also that Java 2 (JDK1.2.x) installs a Java.exe in the default Windows directory, so if you wish to use another VM (say JDK 1.1.x) you would need to modify your path in a similar fashion.

Native Lib: Windows CE & Pocket PC

pJava beta2: Create the folder “My Handheld PC\Program Files\Java\Classes\Serialio” and copy the files from Serialio.jar there.

There is one DLL for each WinCE CPU architecture.

jspWceMips.dll, jspWceSh3.dll, jspWceSh4.dll, jspWceArm.dll

Copy the DLL to the “My Handheld PC\Windows” directory.

Native Lib: Psion EPOC32

If your using a Series 5MX or Series 7, you need to install the JVM on the device. To install the JVM do the following:

  1. Insure the Psion connectivity software has been installed from the PsiWin2 CD
  2. Connect your Psion device to the PC with the PsiWin2 CD loaded
  3. Double-click on the PsiWin2 CD file \Extras\Internet\PsionJVM.SIS

Manual class file install: Create the folder System\Java\ext and copy the Serialio.jar file there. If you don’t wish to use the JAR, then Create the folder System\Java\Classes\Serialio and copy the class files from Serialio there. If using the CommAPI, follow the same process for jspComm.jar that was done with Serialio.jar.

Currently only ARM CPU is supported under EPOC. The DLL is jspEpocArm.dll

Copy the DLL to the System\LIBS directory.

Linux x86
FreeBSD x86
Solaris Sparc
Solaris x86
SCO UnixWare IA32
Compaq Tru64 Alpha
Linux ARM 
Linux StrongARM: 

Unix In General Note: If things don’t work or if things stop working after an upgrade, be sure to check that file privileges are set properly according to the access your trying to perform. For example: in general, you must install the shared libraries as root, however when doing so, you will typically need to change file privileges to allow other users access to the SerialPort files. Some upgrades will set file set privileges on all devices to read-only for root, typically you will need to set them for a+rw. For example you could create a script as shown below. Be sure to use the shared library name for your platform.

FTP Note: If you use FTP to transfer shared library files, CLASS, or JAR you MUST use BINARY mode or the resulting files will not work properly.

CLASSPATH Note: On later versions of the JDK (on Linux at least) the install is very nice in that you don’t need to set anything to use the JDK, you simply unpack it. Note however the CLASSPATH search does not work identical to that of earlier JDK installs where the CLASSPATH and JAVA_HOME settings were required. e.g. If you elected to install the Serialio class files instead of using the Serialio.jar, you might put the Serialio classes into the JDK_HOME/lib directory, say jdk117_v3/lib/Serialio. If you do this without setting your CLASSPATH to include jdk117_v3/lib the classes will not be found by default as with earlier versions of the JDK. If you want to use the Serialio.jar file, and your using a JDK1.1.x VM, you can simply add this file to your classpath. For example if you have JDK on /myStuff/jdk117_v3 partition, and you unpack the SerialPort package into the /jsp directory add the following to your .bash_profile

export CLASSPATH=$JDK_HOME/lib:/myStuff/jsp/Core/Serialio/Serialio.jar

Shared Lib location note: Some Unix Java installations are more ‘sensitive’ to the location of the shared lib (esp Java 2). If you have linkage problems (i.e. java.library.path error) put the shared lib JRE_HOME/lib/xxx where xxx is the CPU architecture. For example on Linux x86 with put inJRE_HOME/lib/i386. Note on later versions of the JDK that support native threads (e.g.JDK 1.1.7) the CPU architecture directory is a symbolic link, so you would put the shared library in the thread model directory of the CPU architecture directory, e.g. JRE_HOME/lib/i686/green_threads.

Another example would be on Tru64 Unix using JDK 1.2.2 (installed to default location) the shared library would go into the /usr/opt/java122/jre/lib/alpha folder.

Shared library: There is one shared library for each platform. There may be more than one .so for a particular platform, use the appropriate version number for the instructions below.

Linux StrongARM: 
Linux x86:
Linux ARM:
Solaris Sparc:
Solaris x86:
HP/UX PA-RISC: (HP uses .sl not .so)
IBM AIX PPC: (bitrate currently limited to 38400)
SCO UnixWare IA32:
Compaq Tru64 Alpha:

Java 2: Copy the shared library to $JRE_HOME/lib/i386. For example, on RedHat 7.3 Linux X86 this is typically /usr/java/jdk1.3.1_03/jre/lib/i386
In this case the command would be
cp /usr/java/jdk1.3.1_03/jre/lib/i386/


Copy the shared library to some folder of your choice, and rename it from .so.x.y, to .so, (or use symbolic links as Copy the shared library to some directory (if Java 2 use JRE_HOME/lib/i386) and rename it from .so.x.y, to .so, (or use symbolic links as shown below) then export the directory name in the LD_LIBRARY_PATH environment variable.
On Linux this would look like this:

#! bin/sh
ln -s
ln -s

Note: the double link shown is based on the traditional way to link major & minor revisions in Unix. If you want, you can directly link to the shared lib i.e. ln -s or you can simply rename the shared lib to

Linux Java Plug-in Note:

SerialPort version 6 works with Java Plug-in under Netscape 7. The Termlet demo on the website should also work if your machine is configured properly.

1) Install the Java Plug-in. This can be done by selecting the Complete install when installing Netscape 7.

2) Copy the shared lib to /usr/local/netscape/plugins/java2/lib/i386

3) Modify the Netscape7 Java file /usr/local/netscape/plugins/java2/lib/security/java.policy to include the following.

grant codeBase “” {
permission java.lang.RuntimePermission “loadLibrary.jspLux86”;
permission java.util.PropertyPermission “*”, “read”;
permission java.util.PropertyPermission “*”, “write”;
permission java.lang.RuntimePermission “modifyThread”;

Note: If you have the JDK installed on the same machine, the java.policy file of the JDK has no affect on the Java Plug-in for Netscape7. If you get the following error when running the applet, it is most likely that the (proper) java.policy file has not been properly configured.

Serialio.SerialPortLocal: DEMO version 8.1
Copyright (c) 1996-2002, All Rights Reserved.
SerialPortLocal: Attempt to load: jspLux86 access denied (java.lang.RuntimePermission loadLibrary.jspLux86)

AIX Notes: We recommend using JDK 1.1.4 or later on AIX.

For AIX the shared library must be in the path pointed to by LIBPATH environment variable. The example above becomes:

#! bin/sh
ln -s
ln -s

.bash_profile example Below is one example of how you could make some the settings in your .bash_profile to take care of CLASSPATH and shared library settings when you login. This example assumes that JDK 1.1.7 is installed on the /myData partition. Also note some aliases are defined as shortcuts.

export PATH=$JDK_HOME/bin:$PATH
export CLASSPATH=$JDK_HOME/lib:/myData/jdev/JavaTerm
alias ‘jdev=cd /myData/jdev’
alias ‘jterm=cd /myData/jdev/JavaTerm’

Macintosh OS 8.5 – 9.2

Apple’s MRJ has now supplanted the variety of Java VMs which once existed on the Macintosh, and the Metrowerks Java VM for Macintosh is no longer supported. If you need to run the Serialio libary with the Metrowerks Java VM, please contact

The Serialio library for use with MRJ is “jspMac_MRJ_PPC”. The current version number of the library is version 3.5. It has been tested with Apple’s MRJ 2.2.5. This library should be placed in the MRJ Libraries folder, which is itself in the Extensions folder. The libraries will be available to the Java VM immediately; rebooting the computer is not necessary.

Macintosh OS X

The library file for Mac OS X is named “libjspMacOSX.jnilib”. In most cases, you will want to include this file as part of the application bundle for your Java application. With the exception of the Platform package, all the Serialio software distributions for the Macintosh have a sample project showing one way to do this. You will find the example in the “Projects” folder. More examples can be found in the developer’s section of Apple’s website. This software distribution also includes a file named “Mac OS X notes.html” which has additional tips for developing serial port applications using Mac OS X.

Macintosh Port Names

On the Mac port names for some devices (e.g. USB to RS-232 converters) provide the flexability to name the ports. This could be important if your software was not designed in a flexable way to allow the port name to be specified. If you need this flexability it has been reported that Keyspan model USA-28X B provides it.


There are 2 DLL’s for OS/2 sccomio.DLL, jspos2j.DLL

Copy the DLLs into a directory specified in the LIBPATH setting of the CONFIG.SYS file. Note that “.” is placed in LIBPATH by default when OS/2 is installed, so the current directory will work unless the “.” Specification has been removed from LIBPATH.

The OS/2 COMM DLL is licensed from Oberon Software.

Early releases of the IBM JDK 1.1.4 have a bug that causes the VM to report it is running on Window 95 even when running on OS/2. You will need to modify such that jspLib = “jspos2j” in the section of code where jspLib is determined.

If your using only the CommAPI you another option would be to consider the implementation from

Java Beans

If your using a Java Bean compliant tool like Visual Cafe or JBuilder, you can install the SerialioBean bean in the component library, or tool palette (or whatever your Java tool calls this). Note that the Bean JAR file does not contain the native shared library so the native shared library must be installed as outlined above.

JavaTerm Terminal Application

JavaTerm is a terminal application built using the Java SerialPort package.

Package Notes
Do not change the package name when importing the Serialio package into Visual Age for Java or other Java tools that allow you to import the package with another name. If you do this the application will fail to link properly when calling the SerialPort shared library.

Where to get JDKs
To get the Sun JDK visit

To get the IBM JDK for OS/2 visit
(The OS/2 JDK needs an HPFS disk for the long file name support)

To get the Microsoft JDK visit

More information on SerialPort
Be sure to read the document on using SerialPort.