To start out, we'll create a connection to a serial port:

SerialPort port = new SerialPort(0, 9600);
if (!port.isOpen())
  return; // error

The first parameter is the port number. We pass a 0 to open the default port. On small devices, such as a PalmPilot or Windows CE device, port 0 is most likely the only serial port the device will have.

The second parameter is the baud rate. In our case, we passed 9600. If you are communicating with another device, you need to make sure both are communicating at the same baud rate or the two devices won't be able to communicate properly.

Reading and Writing

Now that the port is open, we can read and write to it. Here we try writing 2 bytes (values 100 and 101) to the serial port:

byte buf[] = new byte[2];
buf[0] = 100;
buf[1] = 101;
if (port.writeBytes(buf, 0, 2) != 2)
	return; // error

And then try reading two bytes from the serial port:

if (port.readBytes(buf, 0, 2) != 2)
	return; // error

Closing the Serial Port

When you are done working with the serial port, you should close it.

port.close();

If you forget to close the port and it is freed by the garbage collector, the port will be closed properly before it is freed.

But it's best to close the port when you are done with it since handheld devices normally use up more power when the serial port is open and because when one program has a port open, it prevents other programs from opening the same port.

Bits and Bytes

At this point, if you're knowledgeable about serial ports, you're probably wondering where to set the byte size, parity, stop bits, CTS/RTS, XON/XOFF and timeouts for the port.

When developing the serial port API we had to strike a balance between flexibility and simplicity.

We've found that settings of 8 bit bytes, no parity and 1 stop bit are almost universally accepted for serial port communication. So, those are the settings used when accessing a serial port with the SerialPort class and there is currently no API to change them.

Flow Control

Serial ports support flow control through various hardware or software methods.

The SerialPort class does not include support for software flow control since it is not supported across platforms. The documentation for the PalmPilot, for instance, says that it does not have support for XON/XOFF flow control (software flow control).

Hardware flow control is supported. In fact, RTS/CTS flow control is automatically used for all serial communication on PalmOS and Win32 platforms. However, it is not automatically used for Windows CE platforms.

See the "Windows CE Serial Port Communication" section below for details on why hardware flow control is off by default for Windows CE.

Since hardware flow control is on by default for most platforms, you need to make sure that whatever device you are communicating with is also using hardware flow control.

If one device is using hardware flow control and another isn't, the one trying to communicate with the other will generally time out waiting for the other device to state it's ready to accept data.

If you need to communicate to a device without hardware flow control, you can turn it off for a SerialPort with:

port.setFlowControl(false);

Similarly, if you need to turn flow control on, you can pass true to the setFlowControl() method.

Timeouts

If you do a read operation and there is no data on the line, what happens? Does the program hang waiting for data?

The simple answer is no. The SerialPort class contains an API for setting a read timeout in milliseconds. In this line of code, we set the read timeout to 100 milliseconds (which is 0.1 second):

port.setReadTimeout(100);

The read timeout specifies how much time we will wait before giving up when nothing is happening on the serial line. The default is 100 milliseconds.

If you want a read() call to return immediately when there is no data pending, you can set the read timeout to 0:

port.setReadTimeout(0);

PalmPilot Serial Port Communication

There are some "features" you should be aware of when using a PalmPilot serial port.

Debugging a serial port

When the serial port of a PalmPilot running PalmOS 2.0 is opened it will write a backspace character (value 8) to the serial line. In addition, when the port is closed, it may send a delete character.

This feature and some others are documented on 3Com's web site on this page.

In addition, we've found that even with RTS/CTS hardware flow control set, a PalmPilot serial port may run into a software overrun when high baud rates are used (57600 baud).

A software overrun occurs when data is coming in too fast for a PalmPilot to read it.

Windows CE Serial Port Communication

When we attempted to use RTS/CTS flow control with Windows CE (tested on a Cassiopeia), the device would not communicate with a desktop machine which was using RTS/CTS flow control.

It appears that the Windows CE device waits for the PC to set RTS and is not able to read that RTS is actually set, causing it to get stuck when flow control is used.

So, hardware flow control is off by default for Windows CE.

Turning flow control off doesn't stop communication between a Windows CE device and a desktop machine using flow control.

By default, a SerialPort enables the RTS line on a Windows CE device. This allows the desktop machine using flow control to communicate with the Windows CE device without flow control.

In testing, we found that even with flow control off, the Windows CE device was able to easily keep up with a baud rate of 57600 from a desktop PC.

If you develop a desktop application that uses hardware flow control, it should be able to work with any device running Waba if you leave the flow control setting at its default.

Recommended Reading

A web site that explains everything from the basics of serial ports to how they work at the hardware level can be found at:

http://www.lvr.com/serport.htm