Module serial
The serial library enables communication over the serial port.
It provides the usual open, read, write, and close file handling
methods, as well as serial port configuration features.
Type serial
| serial.open(port, config) |
Creates and returns a new serial device instance: #serialdev. |
Type config
| config.baudRate |
to set the baudrate of the serial port
accepted values are: |
| config.flowControl |
to configure flow control on the serial port
accepted values are: |
| config.numDataBits |
to set the number of data bits in each character
accepted values are: |
| config.numStopBits |
to configure the serial port stop bit
accepted values are: |
| config.parity |
to set serial port parity
accepted values are (as a string): |
Type serialdev
| serialdev:close() |
Closes the serial library instance. |
| serialdev:configure(config) |
Configures the serial port. |
| serialdev:flush() |
Flushes pending data. |
| serialdev:read(pattern) |
Reads data from the serial port. |
| serialdev:settimeout(value, mode) |
Changes the timeout values for the object. |
| serialdev:write(buffer) |
Writes buffer to the serial port. |
Type serial
Field(s)
- serial.open(port, config)
-
Creates and returns a new serial device instance: #serialdev.
Parameters
-
port: the serial port to open. It can be given as a port number, or as a POSIX device file path such as"/dev/ttyS0"on POSIX operating systems. -
config: an optional #config table. Default values are{ parity = "none", flowControl = "none", numDataBits = 8, numStopBits = 1, baudRate = 115200 }
Return values
-
#serialdev: a new instance of #serialdev as a table when successful
-
nilfollowed by an error message otherwise
-
Type config
Serial port configuration table.
Can be given to serialdev.configure and serial.open functions:
Field(s)
- config.baudRate
-
to set the baudrate of the serial port accepted values are:
50,75,110,134,150,200,300,600,1200,1800,2400,4800,9600,19200,38400,57600,115200,230400,460800,500000,576000,921600,1000000,1152000,1500000,2000000,2500000,3000000,3500000,4000000(as an integer), however actual support may vary depending on hardware and system capabilities.
- config.flowControl
-
to configure flow control on the serial port accepted values are:
"none","rtscts"or"xon/xoff"(as a string).
- config.numDataBits
-
to set the number of data bits in each character accepted values are:
5, 6, 7and8(as an integer).
- config.numStopBits
-
to configure the serial port stop bit accepted values are:
1to disable it,2to enable it (as an integer).
- config.parity
-
to set serial port parity accepted values are (as a string):
"none","odd","even"
Type serialdev
Serial class.
Field(s)
- serialdev:close()
-
Closes the serial library instance.
Once close has been successfully called, the serialdev instance becomes unusable. A new one may be created if needed.
Return values
-
"ok"on success. -
nilfollowed by an error message otherwise.
-
- serialdev:configure(config)
-
Configures the serial port.
Parameter
Return values
-
"ok"on success. -
nilfollowed by error string otherwise.
-
- serialdev:flush()
-
Flushes pending data.
Return values
-
"ok"on success. -
nilfollowed by an error message otherwise.
-
- serialdev:read(pattern)
-
Reads data from the serial port.
Reads data on the serial port, according to the given formats, which specify what to read. For each format, the function returns a string (or a number) with the characters read, or nil if it cannot read data with the specified format. When called without formats, it uses a default format that reads the entire next line.
The available formats are:
"*l": reads the next line (skipping the end of line), returningnilon end of file. This is the default format."*a": reads the whole file, starting at the current position. On end of file, it returns the empty string.number: reads a string with up to this number of characters, returningnilon end of file. If number is zero, it reads nothing and returns an empty string, or `nil` on end of file.
Parameter
-
pattern: string or number conforming accepted patterns.
Return values
-
the read data, as a string, on success.
-
nilfollowed by error string and the partial read data as a third value when an error occurred.
Usage:
full_buffer, err, partial_buffer = sdevice:read(250)
- serialdev:settimeout(value, mode)
-
Changes the timeout values for the object.
By default, all I/O operations are blocking. That is, any call to the methods serialdev.read and serialdev.write will block indefinitely, until the operation completes. The settimeout method defines a limit on the amount of time the I/O methods can block. When a timeout is set and the specified amount of time has elapsed, the affected methods give up and fail with an error code.
The amount of time to wait is specified as the
valueparameter, in seconds.There are two timeout modes and both can be used together for fine tuning:
"b": block timeout. Specifies the upper limit on the amount of time Serial instance can be blocked by the operating system while waiting for completion of any single I/O operation. This is the default mode;"t": total timeout. Specifies the upper limit on the amount of time Serial instance can block a Lua script before returning from a call.
The
niltimeout value allows operations to block indefinitely. Negative timeout values have the same effect.Parameters
-
value: integer to define timeout in seconds,nilor negative timeout is equivalent to no timeout. -
mode: optional string to define the timeout mode to set, accepted value are"b"(block) or"t"(total), default is"b".
Return value
1on success.
- serialdev:write(buffer)
-
Writes buffer to the serial port.
Parameter
-
buffer: string containing data to send over the serial port.
Return values
-
the number of bytes written on success.
-
nilfollowed by an error message and the number of partial data bytes written as a third value when an error occurred.
Usage:
written_bytes_success, err, written_bytes_partial = sdevice:write(buffer) -