1====================
2 Short introduction
3====================
4
5Opening serial ports
6====================
7
8Open port at "9600,8,N,1", no timeout::
9
10    >>> import serial
11    >>> ser = serial.Serial('/dev/ttyUSB0')  # open serial port
12    >>> print(ser.name)         # check which port was really used
13    >>> ser.write(b'hello')     # write a string
14    >>> ser.close()             # close port
15
16Open named port at "19200,8,N,1", 1s timeout::
17
18    >>> with serial.Serial('/dev/ttyS1', 19200, timeout=1) as ser:
19    ...     x = ser.read()          # read one byte
20    ...     s = ser.read(10)        # read up to ten bytes (timeout)
21    ...     line = ser.readline()   # read a '\n' terminated line
22
23Open port at "38400,8,E,1", non blocking HW handshaking::
24
25    >>> ser = serial.Serial('COM3', 38400, timeout=0,
26    ...                     parity=serial.PARITY_EVEN, rtscts=1)
27    >>> s = ser.read(100)       # read up to one hundred bytes
28    ...                         # or as much is in the buffer
29
30Configuring ports later
31=======================
32
33Get a Serial instance and configure/open it later::
34
35    >>> ser = serial.Serial()
36    >>> ser.baudrate = 19200
37    >>> ser.port = 'COM1'
38    >>> ser
39    Serial<id=0xa81c10, open=False>(port='COM1', baudrate=19200, bytesize=8, parity='N', stopbits=1, timeout=None, xonxoff=0, rtscts=0)
40    >>> ser.open()
41    >>> ser.is_open
42    True
43    >>> ser.close()
44    >>> ser.is_open
45    False
46
47Also supported with :ref:`context manager <context-manager>`::
48
49    with serial.Serial() as ser:
50        ser.baudrate = 19200
51        ser.port = 'COM1'
52        ser.open()
53        ser.write(b'hello')
54
55
56Readline
57========
58Be careful when using :meth:`readline`. Do specify a timeout when opening the
59serial port otherwise it could block forever if no newline character is
60received. Also note that :meth:`readlines` only works with a timeout.
61:meth:`readlines` depends on having a timeout and interprets that as EOF (end
62of file). It raises an exception if the port is not opened correctly.
63
64Do also have a look at the example files in the examples directory in the
65source distribution or online.
66
67.. note::
68
69    The ``eol`` parameter for :meth:`readline` is no longer supported when
70    pySerial is run with newer Python versions (V2.6+) where the module
71    :mod:`io` is available.
72
73EOL
74---
75To specify the EOL character for :meth:`readline` or to use universal newline
76mode, it is advised to use io.TextIOWrapper_::
77
78        import serial
79        import io
80        ser = serial.serial_for_url('loop://', timeout=1)
81        sio = io.TextIOWrapper(io.BufferedRWPair(ser, ser))
82
83        sio.write(unicode("hello\n"))
84        sio.flush() # it is buffering. required to get the data out *now*
85        hello = sio.readline()
86        print(hello == unicode("hello\n"))
87
88
89.. _io.TextIOWrapper: http://docs.python.org/library/io.html#io.TextIOWrapper
90
91
92Testing ports
93=============
94Listing ports
95-------------
96``python -m serial.tools.list_ports`` will print a list of available ports. It
97is also possible to add a regexp as first argument and the list will only
98include entries that matched.
99
100.. note::
101
102    The enumeration may not work on all operating systems. It may be
103    incomplete, list unavailable ports or may lack detailed descriptions of the
104    ports.
105
106.. versionadded: 2.6
107
108Accessing ports
109---------------
110pySerial includes a small console based terminal program called
111:ref:`miniterm`.  It can be started with ``python -m serial.tools.miniterm <port_name>``
112(use option ``-h`` to get a listing of all options).
113