NAME

DESCRIPTION

Generic user-level access to the serial ports is through the ser_get(), ser_put() and ser_par() functions described in the following sections. The generic serial devices are configured on the interfaces (I) screen of the configuration editor, as in the example below.

 SERIAL       DEVICE <>TYPE  <>BAUD                       <>MODE
 0  YES   /dev/ttyS0     <>   19200                          raw
 1  YES   /dev/ttyS1     <>    9600                 cooked igncr


The behavior of the serial functions depend on two configurable parameters. The first is the timeout value, which defaults to two seconds, but can be changed with the ser_par() function, described below. The second is the "tty mode", which is set in the config file and described next.

TTY MODES

The serial device tty modes refer to the kind of character processing the UNIX kernel inserts between the serial device and the spec program. (Depending on the platform, tty modes descriptions might be found in the termios(3), termio(7) or tty(4) sections of the UNIX man pages.) spec sets the tty modes for a particular serial device according to the selection in spec's hardware config file.

There are many more tty-mode parameters recognized by the serial device drivers than spec makes available to be configured. Only the parameters that have been found to be needed by spec users have been made available for configuration.

The standard serial ports can be configured in either raw mode or several flavors of cooked mode. In raw mode, the kernel does no processing of the bytes transmitted and received, passing all of the 256 possible values through. Also, the received bytes are available to spec as soon as they are received by the kernel. For transferring binary data, raw mode is essential. On some platforms, a seven-bit raw mode is available, where the eighth bit is used for parity.

In cooked mode, the kernel buffers the incoming data, making it unavailable to be read by spec until a newline or carriage return is received. Also, the kernel may do some processing of the data, such as converting tabs to spaces on output or processing delete or line-erase characters on input. The character processing makes cooked mode inappropriate for receiving binary data. The various flavors of cooked mode implemented in spec set whether to use even or odd parity or no parity, whether to disable software flow control and whether to ignore carriage returns on input.

spec does turn off input echoing in both raw and cooked modes.

Note, the ESRF (TACO) and EPICS implementations only support raw mode.

BUILT-IN FUNCTIONS

ser_get(addr)

If the serial device addr is in cooked mode, reads and returns a string of bytes, up to and including a newline character, or returns the null string if the read times out. If the device is in raw mode, the function reads and returns as many characters as are already available in the queue. If no characters are available, waits for a character and returns it, or returns a null string if no characters become available within the time-out period. The maximum string length in this mode is 8191 characters.

ser_get(addr, n)

If the serial device addr is in cooked mode, reads up to a newline, but no more than n bytes from the serial device with address addr and returns the string so obtained. In cooked mode, no characters can be read until a newline is received. In raw mode, reads up to n characters or until a timeout. If n is zero, the routine reads up to a newline or the maximum of 8191 characters, whichever comes first. In both cases, if the read is not satisfied before a timeout, the routine returns the null string.

ser_get(addr, eos)

Reads characters until a portion of the input matches the string eos and returns the string so obtained, including the end-of-string characters. If no match to the end-of-string characters is found within the timeout period, the null string is returned.

ser_get(addr, d)

Reads incoming bytes into the data array d. The size of d determines how many bytes are to be read. Sub-array syntax can be used to limit the number of bytes. The function returns the number of array elements read, or zero if the read times out. Note, no byte re-ordering is done for short- or-long integer data, and no format conversions are done for float or double data.

ser_get(addr, mode)

If mode is the string "byte", reads and returns one unsigned binary byte. If mode is the string "short", reads two binary bytes and returns the short integer so formed. If mode is the string "long", reads four binary bytes and returns the long integer so formed. The last two modes work the same on both big-endian and little-endian platforms. On both, the incoming data is treated as big endian. If the incoming data is little endian, use "short_swap" or "long_swap". (For spec versions prior to release 5.01.01, use int2 for short and int4 for long.)

ser_put(addr, s)

Writes the string s to the serial device with address addr. Returns the number of bytes written.

ser_put(addr, d [, cnt])

Writes the contents of the data array d to the serial device with address addr. By default, the entire array (or subarray, if specified) will be sent. The optional third argument cnt can be used to specify the number of array elements to send. For short and long integer arrays, the data will be sent using native byte order. The "swap" option of the array_op() function can be used to change the byte order, if necessary. No format conversions are available for float or double data. Returns the number of bytes written.

ser_par(addr, "device_id")

Returns the name of the associated serial device or -1 if there is no serial device configured as addr (as of of spec release 5.05.05-7).

ser_par(addr, "responsive")

Returns 1 if the associated serial device is open, 0 if the device could not be opened and -1 if there is no serial device configured as addr (as of of spec release 5.05.05-7).

ser_par(addr, "flush" [, how])

Flushes the input and/or output queues for the serial device with address addr. If how is zero or absent, the input queue is flushed. If how is one, the output queue is flushed. Otherwise, both queues are flushed. The input queue may contain characters if a ser_get() times out before the read is satisfied, or if more characters arrive than are requested.

ser_par(addr, "queue")

Returns the number of characters in the serial device's input queue. The input queue may contain characters if a ser_get() times out before the read is satisfied, or if more characters arrive than are requested.

ser_par(addr, "timeout" [, t])

Returns or sets the read timeout for the serial device with address addr. The units are seconds. A value of zero indicates no timeout - a ser_get() will wait until the read is satisfied or is interrupted by a ^C. The smallest allowed value of 0.001 will cause the ser_get() to return immediately. A negative value resets the timeout to the default of two seconds.

ser_par(addr, "stop_bits" [, bits])

Returns or sets the stop- bits value for the serial device with address addr (as of of spec release 5.06.05-7). Normal values are one or two. The default value of one is appropriate for nearly every serial device, and this command should very rarely be needed. Note, to set the non- default value, this command will need to be issued each time after reading the hardware config file.

ser_par(addr, "data_bits" [, bits])

Returns or sets the data- bits value for the serial device with address addr (as of of spec release 5.07.02-2). Accepted values are 5, 6, 7 and 8. The default values of seven if parity is enabled and eight if parity is disabled should work for nearly every serial device, and this command should very rarely be needed. Note, to override the default value, this command needs to be issued after reading the hardware config file (on start up and on reconfig).

All the ser_get() calls will store leftover bytes in a queue. Contents from the queue will be returned on a subsequent ser_get() call. Bytes are leftover if the read finishes with a timeout, if more bytes have arrived than are asked for or if more bytes are available after an end-of- string match. Use the "flush" option of ser_par() to clear the input queue, if needed.

To transfer binary byte streams containing null bytes, use the data-array versions of ser_get() and ser_put() with byte arrays. Null bytes mark the end of a normal string.

SEE ALSO