Serial Port Communication
Waba supports serial communication through the SerialPort class
located in the waba.io package.
Let's begin by examining some sample code that connects to a device's
serial port, then reads and writes some data to it.
Opening a Serial Port
To start out, we'll create a connection to a serial port:
SerialPort port = new SerialPort(0, 9600);
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;
buf = 100;
buf = 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
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
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.
Serial ports support flow control through various hardware or
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
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:
Similarly, if you need to turn flow control on, you can pass true
to the setFlowControl() method.
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):
The read timeout specifies how much time we will wait before giving
up when nothing is happening on the serial line. The default is
If you want a read() call to return immediately when there is no data
pending, you can set the read timeout to 0:
PalmPilot Serial Port Communication
There are some "features" you should
be aware of when using a PalmPilot 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.
Debugging a serial port
This feature and some others are documented on 3Com's web site on
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.
A web site that explains everything from the basics of serial
ports to how they work at the hardware level can be found at:
Copyright (c) 1999 - 2001 Wabasoft. Waba, WabaVM and WabaSDK are trademarks of