1==========
2 pySerial
3==========
4
5Overview
6========
7
8This module encapsulates the access for the serial port. It provides backends
9for Python_ running on Windows, OSX, Linux, BSD (possibly any POSIX compliant
10system) and IronPython. The module named "serial" automatically selects the
11appropriate backend.
12
13It is released under a free software license, see LICENSE_ for more
14details.
15
16Copyright (C) 2001-2020 Chris Liechti <cliechti(at)gmx.net>
17
18Other pages (online)
19
20- `project page on GitHub`_
21- `Download Page`_ with releases (PyPi)
22- This page, when viewed online is at https://pyserial.readthedocs.io/en/latest/ or
23  http://pythonhosted.org/pyserial/ .
24
25.. _Python: http://python.org/
26.. _LICENSE: appendix.html#license
27.. _`project page on GitHub`: https://github.com/pyserial/pyserial/
28.. _`Download Page`: http://pypi.python.org/pypi/pyserial
29
30
31Features
32========
33- Same class based interface on all supported platforms.
34- Access to the port settings through Python properties.
35- Support for different byte sizes, stop bits, parity and flow control with
36  RTS/CTS and/or Xon/Xoff.
37- Working with or without receive timeout.
38- File like API with "read" and "write" ("readline" etc. also supported).
39- The files in this package are 100% pure Python.
40- The port is set up for binary transmission. No NULL byte stripping, CR-LF
41  translation etc. (which are many times enabled for POSIX.) This makes this
42  module universally useful.
43- Compatible with :mod:`io` library
44- RFC 2217 client (experimental), server provided in the examples.
45
46
47Requirements
48============
49- Python 2.7 or Python 3.4 and newer
50
51- If running on Windows: Windows 7 or newer
52
53- If running on Jython: "Java Communications" (JavaComm) or compatible
54  extension for Java
55
56For older installations (older Python versions or older operating systems), see
57`older versions`_ below.
58
59
60Installation
61============
62
63This installs a package that can be used from Python (``import serial``).
64
65To install for all users on the system, administrator rights (root)
66may be required.
67
68From PyPI
69---------
70pySerial can be installed from PyPI::
71
72    python -m pip install pyserial
73
74Using the `python`/`python3` executable of the desired version (2.7/3.x).
75
76Developers also may be interested to get the source archive, because it
77contains examples, tests and the this documentation.
78
79From Conda
80----------
81pySerial can be installed from Conda::
82
83    conda install pyserial
84
85    or
86
87    conda install -c conda-forge pyserial
88
89Currently the default conda channel will provide version 3.4 whereas the
90conda-forge channel provides the current 3.x version.
91
92Conda: https://www.continuum.io/downloads
93
94From source (zip/tar.gz or checkout)
95------------------------------------
96Download the archive from http://pypi.python.org/pypi/pyserial or
97https://github.com/pyserial/pyserial/releases.
98Unpack the archive, enter the ``pyserial-x.y`` directory and run::
99
100    python setup.py install
101
102Using the `python`/`python3` executable of the desired version (2.7/3.x).
103
104Packages
105--------
106There are also packaged versions for some Linux distributions:
107
108- Debian/Ubuntu: "python-serial", "python3-serial"
109- Fedora / RHEL / CentOS / EPEL: "pyserial"
110- Arch Linux: "python-pyserial"
111- Gentoo: "dev-python/pyserial"
112
113Note that some distributions may package an older version of pySerial.
114These packages are created and maintained by developers working on
115these distributions.
116
117.. _PyPi: http://pypi.python.org/pypi/pyserial
118
119
120References
121==========
122* Python: http://www.python.org/
123* Jython: http://www.jython.org/
124* IronPython: http://www.codeplex.com/IronPython
125
126
127Older Versions
128==============
129Older versions are still available on the current download_ page or the `old
130download`_ page. The last version of pySerial's 2.x series was `2.7`_,
131compatible with Python 2.3 and newer and partially with early Python 3.x
132versions.
133
134pySerial `1.21`_ is compatible with Python 2.0 on Windows, Linux and several
135un*x like systems, MacOSX and Jython.
136
137On Windows, releases older than 2.5 will depend on pywin32_ (previously known as
138win32all). WinXP is supported up to 3.0.1.
139
140
141.. _`old download`: https://sourceforge.net/projects/pyserial/files/pyserial/
142.. _download: https://pypi.python.org/simple/pyserial/
143.. _pywin32: http://pypi.python.org/pypi/pywin32
144.. _`2.7`: https://pypi.python.org/pypi/pyserial/2.7
145.. _`1.21`: https://sourceforge.net/projects/pyserial/files/pyserial/1.21/pyserial-1.21.zip/download
146