Java gets serial support with the new javax.comm package http://www.javaworld.com/javaworld/jw-05-1998/jw-05-javadev_p.

html

Advertisement: Support JavaWorld, click here!

May 1998 HOME FEATURED TUTORIALS COLUMNS NEWS & REVIEWS FORUM JW RESOURCES ABOUT JW

Java Developer

Java gets serial support with the new javax.comm

package
Sun's JavaSoft division provides support for RS-232 and parallel devices with standard
extensions
Summary
One of the most popular interfaces on a PC is the serial port. This interface allows computers to perform input and
output with peripheral devices. Serial interfaces exist for devices such as modems, printers, bar code scanners, smart
card readers, PDA interfaces, and so on. Sun's JavaSoft division recently has made available the javax.comm package
to add serial support to Java. This package provides support for serial and parallel devices using traditional Java
semantics such as streams and events. In order to communicate with a serial device using a serial port on a host
computer from a Java application or applet, an interface is required. This API allows you to transmit and receive data
from external devices connected to your serial port. In addition, the API provides a complete set of options for setting
all of the parameters associated with serial and parallel devices.

This article focuses on how to use javax.comm to communicate with a serial device based on RS-232; discusses what
the javax.comm API does and does not provide; and offers a small example program that shows you how to
communicate to the serial port using this API. We will end with a brief discussion of how this API will work with other
device drivers, and also go over the requirements for performing a native port of this API to a specific OS. (2,700
words)

By Shivaram H. Mysore and Rinaldo Di Giorgio

Co-authored by Shivaram H. Mysore

he Java Communications (a.k.a. javax.comm) API is a proposed standard extension that enables authors of communications
applications to write Java software that accesses communications ports in a platform-independent way. This API may be used
to write terminal emulation software, fax software, smart-card reader software, and so on.

Developing good software usually means having some clearly defined interfaces. The high-level diagram of the API interface layers
are shown in this figure.

1 of 7 8/4/2006 5:20 PM
Java gets serial support with the new javax.comm package http://www.javaworld.com/javaworld/jw-05-1998/jw-05-javadev_p.html

In this article we will show you how to use javax.comm to communicate with a serial device based on RS-232. We'll also discuss
what the javax.comm API provides and what it doesn't provide. We'll present a small example program that shows you how to
communicate to the serial port using this API. At the end of the article we'll briefly detail how this javax.comm API will work with
other device drivers, and we'll go over the requirements for performing a native port of this API to a specific OS.

Unlike classical drivers, which come with their own models of communication of asynchronous events, the javax.comm API
provides an event-style interface based on the Java event model (java.awt.event package). Let's say we want to know if there is
any new data sitting on the input buffer. We can find that out in two ways -- by polling or listening. With polling, the processor
checks the buffer periodically to see if there is any new data in the buffer. With listening, the processor waits for an event to occur
in the form of new data in the input buffer. As soon as new data arrives in the buffer, it sends a notification or event to the
processor.

Among the various serial interfaces available, two of the most popular are the RS-232C and RS-422 standards, which define the
electrical signal levels and the meaning of various signal lines. Low-speed serial interfaces typically clock data out as a square
wave, with clock coordination provided by start and stop bits.

RS-232 stands for Recommend Standard 232; the C simply refers to the latest revision of the standard. The serial ports on most
computers use a subset of the RS-232C standard. The full RS-232C standard specifies a 25-pin "D" connector, of which 22 pins are
used. Most of these pins are not needed for normal PC communications, and indeed, most new PCs are equipped with male D-type
connectors having only 9 pins. For more on RS-232, see the Resources section.

Note: For an understanding of what other drivers have done in the past, take a look at the Unix termio manual page or OpenBSD
Unix, a variation of the BSD Unix driver source. This is available free on the Internet. Please see the Resources section for more
information.

The javax.comm API: What is provided

The javax.comm API provides the following functionality to developers:

A complete API specification for serial and parallel communication ports. (In this article we consider serial ports only.)
Without a common API in your development efforts, workload will increase because you'll have to provide support to serial
devices.

Full control of all serial framing parameters (baud stop bits, parity, bits/frame) as well as manual or automatic control of the
flow control lines. Normally, in RS-232, there are two signal lines and the rest are intended for control lines. Depending on
the type of communication (synchronous or asynchronous), the number of control lines selected may vary. This API provides
access to the underlying control signals.

A brief diversion here may help you understand something about parity and start and stop bits. Parity was added to RS-232
because communication lines can be noisy. Let's say we send ASCII 0, which in hex equals 0x30 (or 00110000 in binary),
but along the way someone passes by holding a magnet, causing one of the bits to change. As a result, instead of sending 8
bits as intended, an additional bit is added to the first string of bits sent, making the sum total of bits sent even or odd.
voilà! You've got parity.

Start and stop bits were added to the serial communication protocol to allow the receivers to synchronize on the characters
being sent. One-bit parity does not allow error correction -- only detection. Solutions to this problem come from protocols
that are layered on top of the serial APIs. Most serial communication these days uses block protocols with checksums (a
mathematical function that can be generated on the receiver and compared to the transmitted checksum) that allow errors
to be detected on larger groups of bits. When you are communicating with your ISP over PPP, packets may be 128 bytes per
packet with a checksum. If they match, you are 99.999% sure the data is okay.

There are cases wherein this scheme doesn't work. For example, when sending critical commands to devices that are very
far out in the solar system, forward correcting protocols can be used. Forward correcting protocols are needed because there
may be no time for a retransmission, and space has a lot of electromagnetic noise.

Okay, back to the list of functionalities provided by the javax.comm API!

The basic I/O via a subclass of Java IO streams. For input and output, the javax.comm API uses streams; the concept of
streams should be familiar to all Java programmers. It is important to reuse Java concepts when building new functionality or
the APIs will become unwieldy.

Streams that can be extended to provide client flow control and threshold controls. For example, you may want an alert
when there are 10 characters in the buffer or when there are only 10 locations left for characters. Flow control is important
when the two devices connected via an interface cannot keep up with each other. Without flow control, you can have
overruns or underruns. In the overrun condition, you received data before it was processed so it was lost; in the underrun,
you were ready for data but it was not available. Usually these conditions occur at the USART (Universal Synchronous
Asynchronous Receiver Transmitter), which is hardware that converts bytes to a serial wave form with timing to match the
baud rate.

The javax.comm API uses the Java event model to provide notification of various signal line changes as well as buffer status.
State changes refer to well-defined signals specified in the RS-232 standard. For example, carrier detect is used by a modem

2 of 7 8/4/2006 5:20 PM
Java gets serial support with the new javax.comm package http://www.javaworld.com/javaworld/jw-05-1998/jw-05-javadev_p.html

to signal that it has made a connection with another modem, or it has detected a carrier tone. Making the connection or
detecting a carrier tone is an event. Event detection and notification of changes is implemented in this API.

What is not provided

The javax.comm API does not provide:

Line discipline type processing, dialer management, or modem management. Line discipline refers to additional processing of
input or output characters. For example, one common post-processing option is the conversion of CR to CR LF. These terms
have their origins in the early days of teletypes. CR (carriage return) means to simple-return the carriage to the left margin;
in the Arabic world, this would be the right margin. LF (line feed) advances the printing area up by one. When bitmap
screens and laser printers came along, these terms became less important.

Dialer management and modem management are additional applications that can be written using the javax.comm API.
Dialer management typically provides an interface to the modem management's AT command interface. Almost all modems
have an AT command interface. This interface is documented in modem manuals.

Perhaps a little example will make this concept clear. Suppose we have a modem on COM1 and we want to dial a phone
number. A Java dialer management application will query for the phone number and interrogate the modem. These
commands are carried by javax.comm, which does no interpretation. To dial the number 918003210288, for example, the
dialer management probably sends an "AT," hoping to get back an "OK," followed by ATDT918003210288. One of the most
important tasks of dialer management and modem management is to deal with errors and timeouts.

GUI for serial port management. Normally, serial ports have a dialog box that configures the serial ports, allowing users to
set parameters such as baud rate, parity, and so on. The following diagram depicts the objects involved in reading and/or
writing data to a serial port from Java.

Support for X, Y, and Z modem protocols. These protocols provide support error detection and correction.

The programming basics

Too often, programmers dive right into a project and code interactively with an API on the screen without giving any thought to
the problem they are trying to solve. To avoid confusion and potential problems, gather the following information before you start
a project. Remember, programming devices usually requires that you consult a manual.

1. Get the manual for the device and read the section on the RS-232 interface and RS-232 protocol. Most devices have a
protocol that must be followed. This protocol will be carried by the javax.comm API and delivered to the device. The device
will decode the protocol, and you will have to pay close attention to sending data back and forth. Not getting the initial
set-up correct can mean your application won't start, so take the time to test things out with a simple application. In other
words, create an application that can simply write data onto the serial port and then read data from the serial port using the
javax.comm API.

2. Try to get some code samples from the manufacturer. Even if they are in another language, these examples can be quite
useful.

3. Find and code the smallest example you can to verify that you can communicate with the device. In the case of serial
devices, this can be very painful -- you send data to a device connected to the serial port and nothing happens. This is often
the result of incorrect conditioning of the line. The number one rule of device programming (unless you are writing a device
driver) is to make sure you can communicate with the device. Do this by finding the simplest thing you can do with your
device and getting that to work.

4. If the protocol is very complicated, consider getting some RS-232 line analyzer software. This software allows you to look at

3 of 7 8/4/2006 5:20 PM
Java gets serial support with the new javax.comm package http://www.javaworld.com/javaworld/jw-05-1998/jw-05-javadev_p.html

the data moving between the two devices on the RS-232 connection without interfering with the transmission.

Using the javax.comm API successfully in an application requires you to provide some type of interface to the device protocol using
the serial API as the transport mechanism. In other words, with the exception of the simplest devices, there is usually another
layer required to format the data for the device. Of course the simplest protocol is "vanilla" -- meaning there is no protocol. You
send and receive data with no interpretation.

Overview of suggested steps for using javax.comm

In addition to providing a protocol, the ISO layering model used for TCP/IP also applies here in that we have an electrical layer,
followed by a very simple byte transport layer. On top of this byte transport layer you could put your transport layer. For example,
your PPP stack could use the javax.comm API to transfer bytes back and forth to the modem. The role of the javax.comm layer is
quite small when looked at in this context:

1. Give the javax.comm API control of some of the devices. Before you use a device, the javax.comm API has to know about it.

2. Open the device and condition the line. You may have a device that requires a baud rate of 115 kilobits with no parity.

3. Write some data and/or read data following whatever protocol the device you are communicating with requires. For example,
if you connect to a printer, you may have to send a special code to start the printer and/or end the job. Some PostScript
printers require you to end the job by sending CTRL-D 0x03.

4. Close the port.

Initializing the javax.comm API registry with serial interface ports

The javax.comm API can only manage ports that it is aware of. The latest version of the API does not require any ports to be
initialized. On start-up, the javax.comm API scans for ports on the particular host and adds them automatically.

You can initialize the serial ports your javax.comm API can use. For devices that do not follow the standard naming convention,
you can add them explicitly using the code segment below.

// Register the device

CommPort ttya = new javax.comm.solaris.SolarisSerial("ttya","/dev/ttya");
CommPortIdentifier.addPort(ttya,CommPortIdentifier.PORT_SERIAL);
CommPort ttyb = new javax.comm.solaris.SolarisSerial("ttyb","/dev/ttyb");
CommPortIdentifier.addPort(ttyb,CommPortIdentifier.PORT_SERIAL);

Opening and conditioning devices

This next code sample demonstrates how to add, condition, and open a device. Details on the specific method calls are in the API
pages for javax.comm. This example sets the device called XYZSerialDevice to be accessible with name GenericSerialReader. The
device connected on this line has a baud rate of 9600, 1 stop bit, a character of 8 bits (yes, they can be smaller), and no parity.
The result of all of this is to provide two streams -- one for reading and another for writing.

InputStream input = null;

OutputStream output;

SerialPort serialPort = null;

public GenericSerialReader(String name, int baud,

int timeout) throws Exception {

CommPortIdentifier portId =
CommPortIdentifier.getPortIdentifier( name );
serialPort = (SerialPort)portId.openPort
( "GenericSerialReader", timeout );
serialPort.setSerialPortParams(9600, SerialPort.DATABITS_8,
SerialPort.STOPBITS_1,
SerialPort.PARITY_NONE); //
serialPort.setFlowcontrolMode( SerialPort.FLOWCTRL_NONE ); //
serialPort.enableRcvThreshold ( 1 );
serialPort.enableRcvTimeout ( timeout );
int rosStatus = 0;

System.out.println("Open device called");

output = serialPort.getOutputStream();
input = serialPort.getInputStream();

Writing and reading data

For javax.comm, this is no different than any other read and write method call to the derived output stream.

4 of 7 8/4/2006 5:20 PM
Java gets serial support with the new javax.comm package http://www.javaworld.com/javaworld/jw-05-1998/jw-05-javadev_p.html

For write:

try {
output.write ( outputArray, 0 , length );

For read:

try {
int b = input.read()

Closing the port

Closing the port with javax.comm is no different than with other requests to close a device. This step is very important to
javax.comm because it attempts to provide exclusive access. Multiplexing multiple users on a serial line requires a Multiplexor
protocol.

try {
inout.close();
output.close();
} ...

Additional example
A good example also is available when you download the javax.comm API package from the Java Developer Connection (see
Resources section).

Interfacing a serial device driver to javax.comm

You just picked up this little computer that runs Java and has serial ports. However, the manufacturer has not provided an
implementation. It did give you manuals about some calls you could make via native methods to access the serial port drivers
written in C. But how do you interface it to javax.comm so you can use your special hardware device? You guessed it: Implement an
interface that interfaces to the native methods.

The file SerialPort.java, which is included with the javax.comm API, expects that there will be other classes that realize the
implementation of the abstract methods declared by SerialPort. In our example, we call the implementation SolarisSerial.java. This
class requires the following native methods to implement the abstract methods called for in CommPort.java and SerialPort.java:

private native int openNativePort( ... )

private native void closeNativePort( ... )

private native int read( ... )

private native int write( ... )
private native byte readByte( ... )
private native void writeByte( ... )

private native void setNativeSerialPortParams( ... )

private native int getStatusFlags( ... )

public void setDTR( ... )

public native void nativeSetDTR( ... )

public void setRTS( ... )

public native void nativeSetRTS( ... )

private native void nativeSendBreak(...)

public native void setRcvFifoTrigger(...)

To support the javax.comm API on a system that currently does not have support, we need to provide implementations for all the
methods mentioned above.

Conceptually, we have to provide resource management via open and close; ability to configure and query the port via the set and
get methods; and, most importantly, the ability to read and write bytes to the port. In many cases, the above methods are almost
one-to-one mappings to the underlying native operating system. The following table lists the functions used on Solaris to
implement the native interface layer.

javax.comm native method call Unix OS mappings for javax.comm

private native int openNativePort( ... ) Open

private native void closeNativePort( ... ) Close

5 of 7 8/4/2006 5:20 PM
Java gets serial support with the new javax.comm package http://www.javaworld.com/javaworld/jw-05-1998/jw-05-javadev_p.html

private native int read( ... ) Read

private native int write( ... ) Write

private native byte readByte( ... ) Read

private native void writeByte( ... ) Write

private native void setNativeSerialPortParams( ... ) Termio/ioctl

private native int getStatusFlags( ... ) Termio/ioctl

public void setDTR( ... ) Termio/ioctl

public native void nativeSetDTR( ... ) Termio/ioctl

public void setRTS( ... ) Termio/ioctl

public native void nativeSetRTS( ... ) Termio/ioctl

private native void nativeSendBreak(...) Termio/ioctl

public native void setRcvFifoTrigger(...) Termio/ioctl

Conclusion
The javax.comm API provides a modern disciplined approach to serial communications and will move Java into new application
spaces, allowing devices like bar code scanners, printers, smart card readers, and hundreds of other serial devices to be connected
with ease. The API is easy to use, as demonstrated by the example. It is also easy to port to new hardware platforms. The API has
not been tested for high data rate and realtime applications; therefore, developers looking to use the API in those types of
environments should perform careful instrumentation with subsequent analysis of the code.

In determining whether the API is suitable for high data rate or mission sensitive applications, look for the following:

Characters lost on input

Characters lost in output
Frequency of flow control
Time it takes to deliver an event
Character processing times
Block processing times

When we first started our series on smart cards, we were lucky if we understood a few native method calls to send bytes to serial
devices. We end our smart card series with this article. The software APIs we have been discussing in this series come together
from a device point of view. For example, a user developing an application for smart cards can write to some well-defined APIs
such as OpenCard Framework or communicate directly using javax.comm -- or alternatively use javax.smartcard, which in turn
uses javax.comm.

The javax.comm API facilitates the interfacing of serial and parallel devices to Java. For more information on how javax.comm
works with smart cards, look at the iButtons article. Also, we have included several examples in the Resources section to get you
started.

About the author

Shivaram Mysore is a member of technical staff in JavaSoft's Java Commerce Group. There he designs and develops the client and
server side of Java Electronic Commerce Framework. Rinaldo Di Giorgio is a staff engineer in the research department at Sun
Microsystems. There he experiments with digital economies.

Resources
The javax.comm API reference at JavaSoft Developer Connection:
http://java.sun.com/products/javacomm/
Excellent discussion on flow control
http://www.embedded.com/98/toc9801.htm
You can access the RS-232 Serial Communications Tutorial published in PC Communications at
http://www.ridgewater.mnscu.edu/classes/dc/io/
The book Understanding Data Communications, by Gilbert Held and George E. Friend, provides details on data
communications
http://www.clbooks.com/sqlnut/SP/search/gtsumt?source=javaworld&isbn=0672309343
Serial line analyzers
http://www.bb-elec.com/catalog/software/serialte.html
Information and Source of OpenBSD Unix. This may be useful to look at how serial, parallel, and other device drivers are
written.
http://www.OpenBSD.org/
The smart card series in JavaWorld magazine began with the "Java smart card primer"

6 of 7 8/4/2006 5:20 PM
Java gets serial support with the new javax.comm package http://www.javaworld.com/javaworld/jw-05-1998/jw-05-javadev_p.html

http://www.javaworld.com/javaworld/jw-12-1997/jw-12-javadev.html
The January issue of JavaWorld ran the second article in the smart card series: "Smart cards and the OpenCard Framework"
http://www.javaworld.com/javaworld/jw-01-1998/jw-01-javadev.html
In JavaWorld's February issue, you can read "Get a jumpstart on the Java Card"
http://www.javaworld.com/javaworld/jw-02-1998/jw-02-javadev.html
Also in the February issue is "Giving currency to the Java Card API"
http://www.javaworld.com/javaworld/jw-02-1998/jw-02-javacard.html
For more on Java Card 2.0, see "Understanding Java Card 2.0" in the March issue of JavaWorld
http://www.javaworld.com/javaworld/jw-03-1998/jw-03-javadev.html

Advertisement: Support JavaWorld, click here!

HOME | FEATURED TUTORIALS | COLUMNS | NEWS & REVIEWS | FORUM | JW RESOURCES | ABOUT JW | FEEDBACK

Copyright © 2006 JavaWorld.com, an IDG company

7 of 7 8/4/2006 5:20 PM