Home Contents | # rawio:setupComm | Rawio | Core4 Lua Event System

## SYNOPSIS

#include <lua/termios.lh>
setup = handle:setupComm([new_setup])

## DESCRIPTION

rawio:setupComm() allows querying and modifying the configuration of a serial port (TTY).

When called with no parameters, the current configuration is returned. When called with a table, the configuration is updated with the new values, and then the resulting final configuration is returned. Only the fields that are to be changed need to be passed in new_setup.

setup, new_setup is a table of key, value pairs holding the TTY setup:

Key | Description
--- | ---
ispeed | Receive speed in bits per seconds.
ospeed | Transmit speed in bits per seconds.
speed | For setting both speeds together.
cflag | Control flags
iflag | Input flags
lflag | Local flags
oflag | Output flags
vmin | Minimum received byte count before read event is signalled.
vtime | Read timeout in milliseconds.

The fields of this directly model the Unix style termios mechanism of the operating system.

### Flag fields

The fields cflag, iflag, oflag and lflag are bit fields consisting of the logical-or of zero or more flags.

cflag
CS5 | Five data bits
CS6 | Six data bits
CS7 | Seven data bits
CS8 | Eight data bits
CSIZE | Mask for filtering out the CSx value.
CSTOPB | Two stop bits when set, else one stop bit.
CREAD | Enable receiving.
PARENB | Enable parity bit when set.
PARODD | Odd parity when set, else even parity. Only used if PARENB is set.
HUPCL | Turn off DTR and CTS when the last file descriptor on that port is closed.
CCTS_OFLOW | Stop transmitting when CTS input is off. CTS half or RTS/CTS handshaking.
CRTS_IFLOW | Turn RTS on when receive buffer has enough room. RTS half of RTS/CTS handshaking.
CRTSCTS | Combination of CRTS_IFLOW and CCTS_OFLOW.
CDTR_IFLOW | Similar to CRTS_IFLOW, but uses DTR instead.
CDSR_OFLOW | Similar to CCTS_OFLOW, but uses DSR instead.
CCAR_OFLOW | Similar to CCTS_OFLOW, but uses DCD instead.
CHALF | Half duplex. While data is transmitted, the receiver ignores any incoming data.
C485 | Enable RS485 mode. Before data is being transmitted, the RS485 transmitter is enabled first and given time to stabilze. When the transmit buffer is empty, the RS485 transmitter is turned off again. You must also set one of CRTS_IFLOW or CDTR_IFLOW to select which line is controlling the RS485 transmitter. When unsure, set both.

(The more obscure flags are not shown.)

iflag
INLCR | Replace every received NL(10) by CR(13).
IGNCR | Ignore any received CR(13).
ICRNL | Replace every received CR(13) by NL(10).
IXON | Stop transmitter when Xoff is received, start when Xon is received.
IXOFF | Send Xoff when receive buffer becomes full, send Xon when it has room again.
IXANY | When transmitter was stopped by Xoff, start it again on reception of any character whatever.

(The more obscure flags are not shown.)

oflag
OPOST | All other oflag bits are enabled only if this bit is set.
ONLCR | Append a CR(13) after every transmitted NL(10).
OCRNL | Replace every transmitted NL(10) by CR(13).

(The more obscure flags are not shown.)

lflag
ISIG | Enable signal handling. Receiving a Ctrl-C character (3) will raise the interrupt signal, Ctrl-\ (28) will raise the quit signal.

(The more obscure flags are not shown.)

## RETURN VALUE

On success, a table containing the setup of the device. On failure or end-of-file, returns nil. In case of an error, the error can be retrieved using rawio:lastError().

## ERRORS

This function works only on TTY devices.

## NOTES

Not all hardware implementations support different receive and transmit speeds.

## EXAMPLE

Configure serial port in raw mode at 9600bps, 1 start bit, 8 data bits, 1 stop bit.
> > > > > > >
#include <lua/termbits.h> tty = open("/dev/ttyS1"); tty:setupComm { speed = 9600, iflag = 0, oflag = 0, lflag = 0, cflag = CS8 | CREAD }

## SEE ALSO

rawio:break, rawio:cts, rawio:dcd, rawio:device, rawio:drain, rawio:dsr, rawio:dtr, rawio:fd, rawio:flush, rawio:name, rawio:rng, rawio:rts, rawio:rxcnt, rawio:setDtr, rawio:setRts, rawio:start, rawio:stop, rawio:txcnt