The speed of the connection is measured in bits-per-second, although it's usually erroneously expressed as "baud rate." Baud refers to the frequency over telecommunications lines and since it's already measured in hertz, saying "rate" is redundant. Nevertheless, if you say something like "9600 baud" or ask "what baud rate" everyone understands what you mean.

So to send serial data, you need to set the UART to the configuration you'd like (number of bits per character, parity or not, baud rate, and any other specifics to that hardware), then pump data to it to be sent and read received data from it.

Palm OS Serial APIs
Palm OS has no implicit APIs (Application Programming Interfaces) to control the serial port; instead, they're implemented as library routines. This means you must ask the OS to load the library, which gets you a reference number, and then use that reference number in calls to the APIs within the library.

Once the serial communications library is loaded, you use the following APIs:

• SerClearErr
• SerClose
• SerGetSettings
• SerGetStatus
• SerOpen
• SerReceive
• SerReceiveCheck
• SerReceiveFlush
• SerReceiveWait
• SerSend
• SerSendWait
• SerSetReceiveBuffer
• SerSetSettings

When Palm OS 2 came out, several additional APIs appeared:

• SerReceive was renamed to SerReceive10 and a new SerReceive appeared.
• SerSend was renamed to SerSend10 and a new SerSend appeared.
• SerSendCheck, SerSendFlush, and SerControl were added.

Beyond these calls, there are a number of undocumented APIs. I'll get into those another time.

SerialEcho receives and sends characters
The listing (see http://www.component-net.com/pp-extras/serial.html) shows a simple program which receives characters from the serial port and then echos them back. As usual, SerialEcho is based on the Hello World application, so most of it will look familiar.

Near the beginning are five routines that talk to the serial port. These routines use the Palm OS 1 APIs, so no version checking is included.

Two header files are required: Pilot.h and SerialMgr.h. The library API (SysLibFind) is in Pilot.h, and the serial API prototypes are in the SerialMgr.h header file.

The first routine, serialOpenPort, loads the serial library and opens the port, setting a specific baud rate and default control settings. The serial library is included in the Palm device's ROM, so it's always available; you don't need to specially install it on the Palm device. This routine saves the reference number in a global variable for use by the other routines.

The corresponding serialClosePort waits until all the characters have been sent, and then closes the serial port.

To send characters, call serialPrintf with a string. This isn't a real printf function - it only accepts a single string without any printf-like formatting characters. The string is transmitted over the opened serial port. But calling it serialPrintf helps make it easier to remember and understand.