Serial Communications Library

Developing Portable Applications

secom provides you the freedom to write portable applications at the cost of
some functionality, or write OS specific applications at the cost of portability.
The choice is yours.

Creating a Device

The following example shows how you might create a device. The device will
be set to 38400 baud, even parity, one stop bit, and 8 data bits, or 38400
8E1 for short. An overall timer is set to 2 seconds, and an inter-character
timer is set to 100 milliseconds. These timeout properties would be useful
to satisfy the following example requirements:

• Packets are between 1 and 256 bytes in length
• If more than 100 ms elapses between the reception of two characters
  then the packet is complete
• The arrival of a packet shall never take more than 2 seconds

The preceding function takes the name of a device, e.g. COM1 or /dev/ttyS0,
and returns an object representing that device. If the creation was successful
then is_open will be true.

This example will compile and execute on Posix or Windows operating systems.
There are two classes that are not members of the abstract cluster. They are
COM_DEVICE and COM_CONTROL_CONSTANTS. Both the posix and the
windows clusters have versions of these classes with the same name. Other
than these two classes you shouldn't have to deal with the concrete clusters
unless you want to use OS specific features of those classes.

In most cases you will probably pass the name of the device on the command
line. If this is possible then your application is completely portable across
Posix and Windows operating systems (see the write_port and read_port
examples). If, as part of your application, you must allow your user to select
the serial device from a list (as in Linux's minicom or Windows' Hyper Terminal)
then you will have to work a little harder. In a future version of secom I'd like to
provide a list of available serial devices. Unfortunately I don't know of any way
to do this reliably.

Once the device has successfully opened it is assumed to stay open. Thus any
future errors communicating with the device will result in an exception. These
cases may include applying settings or timeouts, reading from or writing to the
device. In these cases if the device was opened (the contract was satisfied) then
an error would probably indicate a failure rather than an anticipated occurence.
It seems then that throwing an exception is a reasonable course of action.

Reading From and Writing To a Device

Reading from and writing to a device is straight forward. Please browse the
interface of COM_ABSTRACT_DEVICE for details.

When a read is satisfied depends on the timeout properties and the count
parameter of read_data. read_data is used by all read operations. Please
see COM_ABSTRACT_TIMEOUTS for details on when a read operation
will timeout.

If a write operation times out, that means the data is still being transferred from
the driver's queue to the serial lines. As far as I know only Windows has write
timeouts. The abstract interface does not know about write timeouts but the
COM_TIMEOUTS class does. Using this class will make your application
non-portable.