spec

Software for Diffraction

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 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 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 bigendian . If the incoming data is littleendian , use "short_swap" or "long_swap".

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, cmd [, arg ])
Accesses various features for the given socket with values for cmd as 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 argument arg is zero or absent, the input queue is flushed. If argis 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.

"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 for arg 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.

"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. If arg isn'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 on SOCKET interfaces.

"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 SOCKET interfaces.

"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 on reconfig). This mode is not supported on SOCKET interfaces.

"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 of ser_par() by combining assignments in a comma-separated list, as in
ser_par(addr, "timeout=1.5,baud=28800,stop_bits=2,data_bits=8")


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. Reads a string of characters, up to and including a newline, from serial device dev_num and returns the string so read. The routine will not return until the read is satisfied. Use ser_get(dev_num, 0) to read up to a newline with a timeout.