documentation/shortintro.rst

====================
 Short introduction
====================

Opening serial ports
====================

Open port at "9600,8,N,1", no timeout::

    >>> import serial
    >>> ser = serial.Serial('/dev/ttyUSB0')  # open serial port
    >>> print(ser.name)         # check which port was really used
    >>> ser.write(b'hello')     # write a string
    >>> ser.close()             # close port

Open named port at "19200,8,N,1", 1s timeout::

    >>> with serial.Serial('/dev/ttyS1', 19200, timeout=1) as ser:
    ...     x = ser.read()          # read one byte
    ...     s = ser.read(10)        # read up to ten bytes (timeout)
    ...     line = ser.readline()   # read a '\n' terminated line

Open port at "38400,8,E,1", non blocking HW handshaking::

    >>> ser = serial.Serial('COM3', 38400, timeout=0,
    ...                     parity=serial.PARITY_EVEN, rtscts=1)
    >>> s = ser.read(100)       # read up to one hundred bytes
    ...                         # or as much is in the buffer

Configuring ports later
=======================

Get a Serial instance and configure/open it later::

    >>> ser = serial.Serial()
    >>> ser.baudrate = 19200
    >>> ser.port = 'COM1'
    >>> ser
    Serial<id=0xa81c10, open=False>(port='COM1', baudrate=19200, bytesize=8, parity='N', stopbits=1, timeout=None, xonxoff=0, rtscts=0)
    >>> ser.open()
    >>> ser.is_open
    True
    >>> ser.close()
    >>> ser.is_open
    False

Also supported with context manager::

    serial.Serial() as ser:
        ser.baudrate = 19200
        ser.port = 'COM1'
        ser.open()
        ser.write(b'hello')


Readline
========
Be carefully when using :meth:`readline`. Do specify a timeout when opening the
serial port otherwise it could block forever if no newline character is
received. Also note that :meth:`readlines` only works with a timeout.
:meth:`readlines` depends on having a timeout and interprets that as EOF (end
of file). It raises an exception if the port is not opened correctly.

Do also have a look at the example files in the examples directory in the
source distribution or online.

.. note::

    The ``eol`` parameter for :meth:`readline` is no longer supported when
    pySerial is run with newer Python versions (V2.6+) where the module
    :mod:`io` is available.

EOL
---
To specify the EOL character for :meth:`readline` or to use universal newline
mode, it is advised to use io.TextIOWrapper_::

        import serial
        import io
        ser = serial.serial_for_url('loop://', timeout=1)
        sio = io.TextIOWrapper(io.BufferedRWPair(ser, ser))

        sio.write(unicode("hello\n"))
        sio.flush() # it is buffering. required to get the data out *now*
        hello = sio.readline()
        print(hello == unicode("hello\n"))


.. _io.TextIOWrapper: http://docs.python.org/library/io.html#io.TextIOWrapper


Testing ports
=============
Listing ports
-------------
``python -m serial.tools.list_ports`` will print a list of available ports. It
is also possible to add a regexp as first argument and the list will only
include entries that matched.

.. note::

    The enumeration may not work on all operating systems. It may be
    incomplete, list unavailable ports or may lack detailed descriptions of the
    ports.

.. versionadded: 2.6

Accessing ports
---------------
pySerial includes a small console based terminal program called
:ref:`miniterm`.  It ca be started with ``python -m serial.tools.miniterm <port_name>``
(use option ``-h`` to get a listing of all options).