portio Serial and Parallel Port Driver |
Java(TM) Edition |
Table of Contents |
Class Overview |
Example User Code |
Package Installation |
Known Bugs |
Forward...
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 Central Data's EtherLite(R)
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. Central Data is 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). 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. Such things as baud rate, character size, parity settings, etc. are affected by this method.
SerialPortStatus: This class holds information used by the Port.getStatus() and SerialPort.setStatus() methods. The status involves signal lines for the port (modem lines in the case of serial 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.
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.
Select the following links to either download portio.exe (a self-extracting file for X86 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.
If you downloaded portio.exe to an X86 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.exe or portio.sis file you downloaded.
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(R) 95 platform with EL-8+ and EL-16 devices. It has also been tested with Java 1.0.2 on the Solaris platform with EL-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.
EtherLite is a registered trademark of Central Data Corporation. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the U.S. and other countries.