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

    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.

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

    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.

  `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`

  Bases: `OSError`

  Base class for Serial errors.