# 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)

  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)

    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)

    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)

    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()

    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()

    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()

    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()

    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

  Bases: `OSError`

  Base class for Serial errors.