1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
====================
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 :ref:`context manager <context-manager>`::
with serial.Serial() as ser:
ser.baudrate = 19200
ser.port = 'COM1'
ser.open()
ser.write(b'hello')
.. _shortintro_readline:
Readline
========
:meth:`readline` reads up to one line, including the ``\n`` at the end.
Be careful when using :meth:`readline`. Do specify a timeout when opening the
serial port otherwise it could block forever if no newline character is
received. If the ``\n`` is missing in the return value, it returned on timeout.
:meth:`readlines` tries to read "all" lines which is not well defined for a
serial port that is still open. Therefore :meth:`readlines` depends on having
a timeout on the port and interprets that as EOF (end of file). It raises an
exception if the port is not opened correctly. The returned list of lines do
not include the ``\n``.
Both functions call :meth:`read` to get their data and the serial port timeout
is acting on this function. Therefore the effective timeout, especially for
:meth:`readlines`, can be much larger.
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 can be started with ``python -m serial.tools.miniterm <port_name>``
(use option ``-h`` to get a listing of all options).
|
