Serial

Code Example

from periphery import Serial

# Open /dev/ttyUSB0 with baudrate 115200, and defaults of 8N1, no flow control
serial = Serial("/dev/ttyUSB0", 115200)

serial.write(b"Hello World!")

# Read up to 128 bytes with 500ms timeout
buf = serial.read(128, 0.5)
print("read {:d} bytes: _{:s}_".format(len(buf), buf))

serial.close()

API

class periphery.Serial(devpath, baudrate, databits=8, parity='none', stopbits=1, xonxoff=False, rtscts=False)[source]

Bases: object

Instantiate a Serial object and open the tty device at the specified path with the specified baudrate, and the defaults of 8 data bits, no parity, 1 stop bit, no software flow control (xonxoff), and no hardware flow control (rtscts).

Parameters:
  • devpath (str) – tty device path.

  • baudrate (int) – baudrate.

  • databits (int) – data bits, can be 5, 6, 7, 8.

  • parity (str) – parity, can be “none”, “even”, “odd”.

  • stopbits (int) – stop bits, can be 1 or 2.

  • xonxoff (bool) – software flow control.

  • rtscts (bool) – hardware flow control.

Returns:

Serial object.

Return type:

Serial

Raises:
  • SerialError – if an I/O or OS error occurs.

  • TypeError – if devpath, baudrate, databits, parity, stopbits, xonxoff, or rtscts types are invalid.

  • ValueError – if baudrate, databits, parity, or stopbits values are invalid.

read(length, timeout=None)[source]

Read up to length number of bytes from the serial port with an optional timeout.

timeout can be positive for a blocking read with a timeout in seconds, zero for a non-blocking read, or negative or None for a blocking read that will block until length number of bytes are read. Default is a blocking read.

For a non-blocking or timeout-bound read, read() may return less than the requested number of bytes.

For a blocking read with the VMIN setting configured, read() will block until at least VMIN bytes are read. For a blocking read with both VMIN and VTIME settings configured, read() will block until at least VMIN bytes are read or the VTIME interbyte timeout expires after the last byte read. In either case, read() may return less than the requested number of bytes.

Parameters:
  • length (int) – length in bytes.

  • timeout (int, float, None) – timeout duration in seconds.

Returns:

data read.

Return type:

bytes

Raises:

SerialError – if an I/O or OS error occurs.

write(data)[source]

Write data to the serial port and return the number of bytes written.

Parameters:

data (bytes, bytearray, list) – a byte array or list of 8-bit integers to write.

Returns:

number of bytes written.

Return type:

int

Raises:
  • SerialError – if an I/O or OS error occurs.

  • TypeError – if data type is invalid.

  • ValueError – if data is not valid bytes.

poll(timeout=None)[source]

Poll for data available for reading from the serial port with an optional timeout.

timeout can be positive for a timeout in seconds, zero for a non-blocking poll, or negative or None for a blocking poll. Default is a blocking poll.

Parameters:

timeout (int, float, None) – timeout duration in seconds.

Returns:

True if data is available for reading from the serial port, False if not.

Return type:

bool

flush()[source]

Flush the write buffer of the serial port, blocking until all bytes are written.

Raises:

SerialError – if an I/O or OS error occurs.

input_waiting()[source]

Query the number of bytes waiting to be read from the serial port.

Returns:

number of bytes waiting to be read.

Return type:

int

Raises:

SerialError – if an I/O or OS error occurs.

output_waiting()[source]

Query the number of bytes waiting to be written to the serial port.

Returns:

number of bytes waiting to be written.

Return type:

int

Raises:

SerialError – if an I/O or OS error occurs.

close()[source]

Close the tty device.

Raises:

SerialError – if an I/O or OS error occurs.

property fd

Get the file descriptor of the underlying tty device.

Type:

int

property devpath

Get the device path of the underlying tty device.

Type:

str

property baudrate

Get or set the baudrate.

Raises:
  • SerialError – if an I/O or OS error occurs.

  • TypeError – if baudrate type is not int.

  • ValueError – if baudrate value is not supported.

Type:

int

property databits

Get or set the data bits. Can be 5, 6, 7, 8.

Raises:
  • SerialError – if an I/O or OS error occurs.

  • TypeError – if databits type is not int.

  • ValueError – if databits value is invalid.

Type:

int

property parity

Get or set the parity. Can be “none”, “even”, “odd”.

Raises:
  • SerialError – if an I/O or OS error occurs.

  • TypeError – if parity type is not str.

  • ValueError – if parity value is invalid.

Type:

str

property stopbits

Get or set the stop bits. Can be 1 or 2.

Raises:
  • SerialError – if an I/O or OS error occurs.

  • TypeError – if stopbits type is not int.

  • ValueError – if stopbits value is invalid.

Type:

int

property xonxoff

Get or set software flow control.

Raises:
  • SerialError – if an I/O or OS error occurs.

  • TypeError – if xonxoff type is not bool.

Type:

bool

property rtscts

Get or set hardware flow control.

Raises:
  • SerialError – if an I/O or OS error occurs.

  • TypeError – if rtscts type is not bool.

Type:

bool

property vmin

Get or set the VMIN termios setting for minimum number of bytes returned from a blocking read. Can be between 0 and 255.

When configured in conjunction with VTIME, VTIME acts as an interbyte timeout that restarts on every byte received, and a blocking read will block until at least VMIN bytes are read or the VTIME timeout expires after the last byte read. See the termios man page for more information.

Raises:
  • SerialError – if an I/O or OS error occurs.

  • TypeError – if vmin type is not int.

  • ValueError – if vmin value is invalid.

Type:

int

property vtime

Get or set the VTIME termios setting for timeout in seconds of a blocking read. Can be between 0 to 25.5 seconds, with a resolution of 0.1 seconds.

When configured in conjunction with VMIN, VTIME acts as an interbyte timeout that restarts on every byte received, and a blocking read will block until at least VMIN bytes are read or the VTIME timeout expires after the last byte read. See the termios man page for more information.

Raises:
  • SerialError – if an I/O or OS error occurs.

  • TypeError – if vtime type is not float or int.

  • ValueError – if vtime value is invalid.

Type:

float

class periphery.SerialError[source]

Bases: OSError

Base class for Serial errors.