2.4.8.7. - RS-232 Serial Interfaces
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 screen
of the configuration editor.
Each serial device is numbered, starting from zero,
and that number is the first parameter
addr
in the functions below.
Up to 21 serial devices can be configured, numbered from 0 to 20.
Do not configure a generic serial device when the associated device node is for a motor controller, counter/timer or other acquisition device that uses spec's built-in support. The serial device associated with such controllers is specified as part of the controller configuration
The default serial interface is through the built-in standard UNIX serial driver. However, the same user functions can access serial devices configured to use
EPICS, TACO, or
SOCKET interfaces.
Supported baud settings are 300, 600, 1200, 1800, 2400, 4800, 7200, 9600, 14400, 19200, 28800, 38400, 57600, 115200, 230400, 460800, 921600, 1000000, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000 and 4000000 baud. However, not all baud rates are supported by all platforms and by all serial interface hardware.
The baud rate setting is ignored for the
SOCKET type of interface.
See the documentation associated with a particular
Ethernet-to-serial device
for procedures to set the serial port parameters.
Serial interfaces have associated modes, some of which can be set in spec's configuration editor and some with the
ser_par() function.
There are many more mode parameters than those described below.
Only the parameters that have been found to be needed by spec users can be
configured.
The standard serial ports can be configured in either raw mode or several flavors of cooked mode. In raw mode, the kernel does minimal processing of the bytes transmitted and received, generally 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. The input data only becomes available to be read by spec when 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
TACO, EPICS and
SOCKET interface types
only support
raw
mode.
ser_get(addr)-
If the serial device
addris 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
addris in cooked mode, reads up to a newline, but no more thannbytes and returns the string so obtained. In cooked mode, no characters can be read until a newline is received. In raw mode, reads up toncharacters or until a timeout. Ifnis 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
eosand 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 ofddetermines 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
modeis the string"byte", reads and returns one unsigned binary byte. Ifmodeis the string"short", reads two binary bytes and returns the short integer so formed. Ifmodeis 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 bigendian . If the incoming data is littleendian , use"short_swap"or"long_swap". ser_put(addr, s)-
Writes the string
sto the serial device with addressaddr. Returns the number of bytes written. ser_put(addr, d, [, cnt])-
Writes the contents of the data array
dto the serial device with addressaddr. By default, the entire array (or subarray, if specified) will be sent. The optional third argumentcntcan 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 thearray_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, cmd [, arg ])-
Accesses various features for the given socket with values for
cmdas follows:"device_id"- Returns the name of the associated serial device or -1
if there is no serial device configured as
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. "drain"- Waits for pending output on the associated serial device
to be transmitted, but
can be interrupted with
^C. Use the"flush"option, described next, to empty the output queue. "flush"- Flushes the input and/or output queues for the serial device with address
addr. If the optional argumentargis zero or absent, the input queue is flushed. Ifargis one, the output queue is flushed. Otherwise, both queues are flushed. The input queue may contain characters if aser_get()times out before the read is satisfied, or if more characters arrive than are requested. "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. "timeout"- Returns or sets the read timeout for the serial device with address
addr. The units forargare seconds. A value of zero indicates no timeout - aser_get()will wait until the read is satisfied or is interrupted by a^C. The smallest allowed value of 0.001 will cause theser_get()to return immediately. A negative value resets the timeout to the default of two seconds. "baud"- Returns or sets the baud rate for the serial device with address
addr. Valid baud rates are from 300 to 4000000. The function returns the device's baud rate. Ifargisn't valid or if there was an error, the function returns -1. Reading the hardware config file resets the baud rate to the value in the file. spec cannot set the baud rate onSOCKETinterfaces. "stop_bits"- Returns or sets the stop-bits value for the serial device with address
.Co addr .
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.
This mode is not supported on
SOCKETinterfaces. "data_bits"- Returns or sets the data-bits value for the serial device with address
addr. 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 configfile (on start up and onreconfig). This mode is not supported onSOCKETinterfaces. "dtr"- Returns the current setting or sets or clears the Data Terminal Ready (DTR)
control line.
Only available on standard serial interfaces.
Reset on hardware reconfiguration.
"rts"- Returns the current setting or sets or clears the Request To Send (RTS)
control line.
Only available on standard serial interfaces.
Reset on hardware reconfiguration.
"dsr"- Returns the current setting of the Data Set Ready (DSR) control line. Only available on standard serial interfaces.
Values for any combination of the parameters"timeout","baud","stop_bits","data_bits","dtr", and"rts"can be set in one call ofser_par()by combining assignments in a comma-separated list, as inser_par(addr, "timeout=1.5,baud=28800,stop_bits=2,data_bits=8")
All theser_get()calls will store leftover bytes in a queue. Contents from the queue will be returned on a subsequentser_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 ofser_par()to clear the input queue, if needed.
To transfer binary byte streams containing null bytes, use the data-array versions ofser_get()andser_put()with byte arrays. Null bytes mark the end of a normal string. Reads a string of characters, up to and including a newline, from serial devicedev_numand returns the string so read. The routine will not return until the read is satisfied. Useser_get(dev_num, 0)to read up to a newline with a timeout.