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_" % (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 timeout in seconds, 0 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 data whose length is less than or equal to the requested length.

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.

timeout can be positive for a timeout in seconds, 0 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.
fd

Get the file descriptor of the underlying tty device.

Type:int
devpath

Get the device path of the underlying tty device.

Type:str
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
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
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
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
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
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
class periphery.SerialError[source]

Bases: exceptions.IOError

Base class for Serial errors.