portio Serial and Parallel Port Driver

Table of Contents

Class Overview

Example User Code

Package Installation

Known Bugs

Foreword...
The portio package defines an API for accessing serial and parallel ports from Java applications and applets. Currently, there is only one implementation, which is for the EtherLite® product line. Due to the nature of the EtherLite products, the entire serial/parallel port driver for it can be implemented in Java, using no native methods. We are making portio source code available to the public, so that anyone may implement versions that support other serial or parallel port hardware in existence (see our Software License Agreement).

The book Java Native Interface (Essential Java) by Robert Gordon will be available mid-March, and includes versions of portio that will support native serial ports on both Win32 and POSIX platforms. It is also an excellent starting point for people interested in creating a version of portio for any other platform. Click here to order from Amazon.com.

Any comments or suggestions regarding portio should be sent to portio engineering.

The following list describes the different portio classes. The discussion only covers serial ports. Where applicable, a corresponding Parallel class can be used instead.

• PortDriver: This abstract class is extended to provide the functionality for an entire device, which may consist of one or more serial and/or parallel ports. (The class EtherLiteDriver is an implemented example such an extension, and TemplatePortDriver is provided to give a skeleton of what's needed for new implementers.) No SerialPort or ParallelPort objects may be created until the PortDriver which controls the ports has been successfully instantiated. This class is used to ensure that each port is only opened once, and can be used to regulate access to any resources which are shared by multiple ports on the device. The PortDriverInfo class can be populated by a call to the PortDriver.getDriverInfo() method, allowing the Java program to determine the number of serial and parallel ports supported by the device, among other things.

• PortPrivate: This abstract class is extended to provide the functionality for individual ports. This is where information related to each port is stored, input and output data is buffered, and all operations specific to an individual port are performed. (The class EtherLitePortPrivate is a working example of a PortPrivate class extension, with TemplatePortPrivate source available to review by new implementers.) This class is instantiated by the corresponding PortDriver whenever a port is opened.

• SerialPort: This is an extension of the Port class. It is instantiated with a reference to the PortDriver and the port number which is to be opened. After successful instantiation, the getInputStream() and getOutputStream() methods can be used to provide normal Java InputStream and OutputStream access to the port.

• SerialPortParams: This class holds information regarding the settings for a port. If you wish to change the settings, a SerialPortParams object should be created with the desired settings, and then it should be passed as a parameter to the SerialPort.setParams() method for the changes to take effect.

  The parameters which can be set include baud rate, character size, framing bits, and parity settings. Additionally, the flow control mode (hardware or software) is established, and the setting of various flags determines if the loss of Carrier Detect should cause an end-of-file indication for the port, and whether different receive errors (parity, overrun, framing, and break) will throw exceptions. Finally, a receiver enable and loopback mode are supported. All parameters are checked for acceptability to the underlying hardware, with an exception thrown if invalid parameters are set.

• SerialPortStatus: This class holds information used by the Port.getStatus() and SerialPort.setStatus() methods. The status involves signal lines for the port (the RTS, CTS, DSR, DTR, and CD modem lines in the case of serial ports, and the error, paperEmpty, and select lines for parallel ports).

• PortIOException: This is an extension of the standard Java IOException class. Many portio methods throw this exception if an error occurs.

Some example Java code which starts an EtherLiteDriver, opens a port, changes the baud rate and character size from the default, and sends out 256 bytes of data follows. Note that the only change needed to do the same operations with any other implementation of PortDriver would be to change the third line, which selects the specific PortDriver to be used.

// make driver for EtherLite device with host name "EtherLite1"
EtherLiteDriver driver = null;
try { driver = new EtherLiteDriver( "EtherLite1" ); }
catch( PortIOException e ) {
    System.out.println( "Failed making driver: " + e );
    System.exit(1);
}

// get information about the device
PortDriverInfo info = driver.getDriverInfo();
if( info.serialCount == 0 ) {
    System.out.println( "No serial ports on device" );
    System.exit(1);
}

// make some arrays to hold objects related to each serial port
SerialPort port[] = new SerialPort[info.serialCount];
InputStream in[] = new InputStream[info.serialCount];
OutputStream out[] = new OutputStream[info.serialCount];

// open the first serial port
try { port[0] = new SerialPort( driver, 0 ); }
catch( PortIOException e ) {
    System.out.println( "Failed opening port: " + e );
    System.exit(1);
}
in[0] = port[0].getInputStream();
out[0] = port[0].getOutputStream();

// choose settings we want and then change them at the port
SerialPortParams params = new SerialPortParams();
params.inBaud = params.outBaud = 115200;
params.charSize = 8;
try { port[0].setParams( params ); }
catch( PortIOException e ) {
    System.out.println( "Failed setting params: " + e );
    System.exit(1);
}

// create a block of data to send out and then send it!
byte outBuf[] = new byte[256];
for( int i = 0; i < 256; i++ ) outBuf[i] = (byte)i;
try { out[0].write( outBuf ); }
catch( IOException e ) {
    System.out.println( "Failed write to port: " + e );
    System.exit(1);
}

// close the port neat and clean after releasing objects
SerialPort thisPort = port[0];
port[0] = null;
in[0] = null;
out[0] = null;
try { thisPort.close(); }
catch( PortIOException e ) {
    System.out.println( "Failed closing port: " + e );
    System.exit(1);
}

This is a very simple example of accessing a serial port. More extensive operations can be performed, as detailed in the documentation for the portio package.

• Create directory

  You need to create a subdirectory named portio in your main class directory (the directory which contains the file classes.zip). This directory is probably the first one listed in your CLASSPATH setting.

• Download Package

  Select the following links to either download portio.zip (a ZIP file), portio.exe (a self-extracting file for Windows® 95 or X86 NT machines), or portio.sis (a self-extracting file for UNIX machines). When prompted by your browser, save the file to the portio directory you just created.

• Extract the Files

  If you downloaded portio.zip, just unzip it using the -d option to recreate the proper directory structure. If you downloaded portio.exe to a Windows 95 or X86 NT machine, execute the file to extract its contents. If you downloaded portio.sis to a UNIX machine, use the command sh portio.sis to cause the file to be executed and the files to be extracted. Upon successful extraction, you may delete the portio.zip, portio.exe, or portio.sis file you downloaded.

• Package Contents

  Of course, all of the .class files needed for the EtherLite version of portio are included. In addition, the file you are now reading as well as all JavaDoc documentation for the package are included. Finally, all Java source files except those that pertain specifically to our EtherLite devices are also included. Non-working templates of extensions to PortDriver and PortPrivate (named TemplatePortDriver and TemplatePortPrivate) are included as well. In theory, only these two files will need to be changed for new versions of portio to be created.

The portio package has been tested with Java 1.0.2 and 1.1 on the Windows 95 platform with EtherLite 8 and EtherLite 16 devices. It has also been tested with Java 1.0.2 on the Solaris platform with EtherLite 16 devices.

There are no known bugs at this time. If you experience a bug with the EtherLite implementation of portio, or if you have suggested improvements for this package, please email portio engineering.

There may be other Java serial port products available on the net which are named portio, but which are not related or compatible with our portio API.

EtherLite is a registered trademark of Digi Corporation. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the U.S. and other countries. Windows is a registered trademark or a trademark of Microsoft Corporation in the United States and/or other countries.