diff options
Diffstat (limited to 'pyserial/documentation')
| -rw-r--r-- | pyserial/documentation/Makefile | 88 | ||||
| -rw-r--r-- | pyserial/documentation/appendix.rst | 68 | ||||
| -rw-r--r-- | pyserial/documentation/conf.py | 194 | ||||
| -rw-r--r-- | pyserial/documentation/examples.rst | 282 | ||||
| -rw-r--r-- | pyserial/documentation/index.rst | 29 | ||||
| -rw-r--r-- | pyserial/documentation/pyparallel.rst | 165 | ||||
| -rw-r--r-- | pyserial/documentation/pyserial.png | bin | 7050 -> 0 bytes | |||
| -rw-r--r-- | pyserial/documentation/pyserial.rst | 110 | ||||
| -rw-r--r-- | pyserial/documentation/pyserial_api.rst | 531 | ||||
| -rw-r--r-- | pyserial/documentation/shortintro.rst | 57 |
10 files changed, 0 insertions, 1524 deletions
diff --git a/pyserial/documentation/Makefile b/pyserial/documentation/Makefile deleted file mode 100644 index 8384360..0000000 --- a/pyserial/documentation/Makefile +++ /dev/null @@ -1,88 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf _build/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html - @echo - @echo "Build finished. The HTML pages are in _build/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml - @echo - @echo "Build finished. The HTML pages are in _build/dirhtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in _build/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in _build/qthelp, like this:" - @echo "# qcollectiongenerator _build/qthelp/pySerial.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile _build/qthelp/pySerial.qhc" - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex - @echo - @echo "Build finished; the LaTeX files are in _build/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes - @echo - @echo "The overview file is in _build/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in _build/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in _build/doctest/output.txt." diff --git a/pyserial/documentation/appendix.rst b/pyserial/documentation/appendix.rst deleted file mode 100644 index 001c6e5..0000000 --- a/pyserial/documentation/appendix.rst +++ /dev/null @@ -1,68 +0,0 @@ -========== - Appendix -========== - -Related software -================ - -com0com - http://com0com.sourceforge.net/ - Provides virtual serial ports for Windows. - - -License -======= - -Copyright (C) 2001-2009 Chris Liechti <cliechti(at)gmx.net>; -All Rights Reserved. - -This is the Python license. In short, you can use this product in commercial -and non-commercial applications, modify it, redistribute it. A notification to -the author when you use and/or modify it is welcome. - - -**TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING THIS SOFTWARE** - -*LICENSE AGREEMENT* - -1. This LICENSE AGREEMENT is between the copyright holder of this product, and - the Individual or Organization ("Licensee") accessing and otherwise using - this product in source or binary form and its associated documentation. - -2. Subject to the terms and conditions of this License Agreement, the copyright - holder hereby grants Licensee a nonexclusive, royalty-free, world-wide - license to reproduce, analyze, test, perform and/or display publicly, - prepare derivative works, distribute, and otherwise use this product alone - or in any derivative version, provided, however, that copyright holders - License Agreement and copyright holders notice of copyright are retained in - this product alone or in any derivative version prepared by Licensee. - -3. In the event Licensee prepares a derivative work that is based on or - incorporates this product or any part thereof, and wants to make the - derivative work available to others as provided herein, then Licensee hereby - agrees to include in any such work a brief summary of the changes made to - this product. - -4. The copyright holder is making this product available to Licensee on an "AS - IS" basis. THE COPYRIGHT HOLDER MAKES NO REPRESENTATIONS OR WARRANTIES, - EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, THE COPYRIGHT - HOLDER MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF - MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF - THIS PRODUCT WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. - -5. THE COPYRIGHT HOLDER SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF - THIS PRODUCT FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS - AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING THIS PRODUCT, OR - ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -6. This License Agreement will automatically terminate upon a material breach - of its terms and conditions. - -7. Nothing in this License Agreement shall be deemed to create any relationship - of agency, partnership, or joint venture between the copyright holder and - Licensee. This License Agreement does not grant permission to use trademarks - or trade names from the copyright holder in a trademark sense to endorse or - promote products or services of Licensee, or any third party. - -8. By copying, installing or otherwise using this product, Licensee agrees to - be bound by the terms and conditions of this License Agreement. - diff --git a/pyserial/documentation/conf.py b/pyserial/documentation/conf.py deleted file mode 100644 index 7420982..0000000 --- a/pyserial/documentation/conf.py +++ /dev/null @@ -1,194 +0,0 @@ -# -*- coding: utf-8 -*- -# -# pySerial documentation build configuration file, created by -# sphinx-quickstart on Tue Jul 21 00:27:45 2009. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.append(os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'pySerial' -copyright = u'2009, Chris Liechti' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '2.5' -# The full version, including alpha/beta/rc tags. -release = '2.5 preview' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of documents that shouldn't be included in the build. -#unused_docs = [] - -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = 'pyserial.png' - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_use_modindex = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'pySerialdoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'pySerial.tex', u'pySerial Documentation', - u'Chris Liechti', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -latex_logo = 'pyserial.png' - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_use_modindex = True diff --git a/pyserial/documentation/examples.rst b/pyserial/documentation/examples.rst deleted file mode 100644 index 283f2d6..0000000 --- a/pyserial/documentation/examples.rst +++ /dev/null @@ -1,282 +0,0 @@ -========== - Examples -========== - -Miniterm -======== -This is a console application that provides a small terminal application. -miniterm itself does not implement any terminal features such as VT102 -compatibility. However it inherits these features from the terminal it is run. -For example on GNU/Linux running from an xterm it will support the escape -sequences of the xterm. On Windows the typical console window is dumb and does -not support any escapes. When ANSI.sys is loaded it supports some escapes. - -miniterm:: - - --- Miniterm on /dev/ttyS0: 9600,8,N,1 --- - --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- - -Command line options can be given so that binary data including escapes for -terminals are escaped or output as hex. - -Command line options ``miniterm.py -h``:: - - Usage: miniterm.py [options] [port [baudrate]] - - Miniterm - A simple terminal program for the serial port. - - Options: - -h, --help show this help message and exit - -p PORT, --port=PORT port, a number (default 0) or a device name - (deprecated option) - -b BAUDRATE, --baud=BAUDRATE - set baud rate, default 9600 - --parity=PARITY set parity, one of [N, E, O, S, M], default=N - -e, --echo enable local echo (default off) - --rtscts enable RTS/CTS flow control (default off) - --xonxoff enable software flow control (default off) - --cr do not send CR+LF, send CR only - --lf do not send CR+LF, send LF only - -D, --debug debug received data (escape non-printable chars) - --debug can be given multiple times: 0: just print - what is received 1: escape non-printable characters, - do newlines as unusual 2: escape non-printable - characters, newlines too 3: hex dump everything - --rts=RTS_STATE set initial RTS line state (possible values: 0, 1) - --dtr=DTR_STATE set initial DTR line state (possible values: 0, 1) - -q, --quiet suppress non error messages - --exit-char=EXIT_CHAR - ASCII code of special character that is used to exit - the application - --menu-char=MENU_CHAR - ASCII code of special character that is used to - control miniterm (menu) - - -miniterm supports some control functions. Typing :kbd:`Control+t Control+h` when it is -running shows the help text:: - - --- pySerial - miniterm - help - --- - --- Ctrl+] Exit program - --- Ctrl+T Menu escape key, followed by: - --- Menu keys: - --- Ctrl+T Send the menu character itself to remote - --- Ctrl+] Send the exit character to remote - --- Ctrl+I Show info - --- Ctrl+U Upload file (prompt will be shown) - --- Toggles: - --- Ctrl+R RTS Ctrl+E local echo - --- Ctrl+D DTR Ctrl+B BREAK - --- Ctrl+L line feed Ctrl+A Cycle repr mode - --- - --- Port settings (Ctrl+T followed by the following): - --- 7 8 set data bits - --- n e o s m change parity (None, Even, Odd, Space, Mark) - --- 1 2 3 set stop bits (1, 2, 1.5) - --- b change baud rate - --- x X disable/enable software flow control - --- r R disable/enable hardware flow control - - -miniterm.py_ - The miniterm program. - -setup-miniterm-py2exe.py_ - This is a py2exe setup script for Windows. It can be used to create a - standalone ``miniterm.exe``. - -.. _miniterm.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/miniterm.py -.. _setup-miniterm-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup-miniterm-py2exe.py - - -TCP/IP - serial bridge -====================== -This program opens a TCP/IP port. When a connection is made to that port (e.g. -with telnet) it forwards all data to the serial port and vice versa. - -The serial port settings are set on the command line when starting the program. -There is no possibility to change settings from remote. -:: - - Usage: tcp_serial_redirect.py [options] [port [baudrate]] - - Simple Serial to Network (TCP/IP) redirector. - - Options: - -h, --help show this help message and exit - -q, --quiet suppress non error messages - --spy peek at the communication and print all data to the - console - - Serial Port: - Serial port settings - - -p PORT, --port=PORT - port, a number (default 0) or a device name - -b BAUDRATE, --baud=BAUDRATE - set baud rate, default: 9600 - --parity=PARITY set parity, one of [N, E, O], default=N - --rtscts enable RTS/CTS flow control (default off) - --xonxoff enable software flow control (default off) - --rts=RTS_STATE set initial RTS line state (possible values: 0, 1) - --dtr=DTR_STATE set initial DTR line state (possible values: 0, 1) - - Network settings: - Network configuration. - - -P LOCAL_PORT, --localport=LOCAL_PORT - local TCP port - - Newline Settings: - Convert newlines between network and serial port. Conversion is - normally disabled and can be enabled by --convert. - - -c, --convert enable newline conversion (default off) - --net-nl=NET_NEWLINE - type of newlines that are expected on the network - (default: LF) - --ser-nl=SER_NEWLINE - type of newlines that are expected on the serial port - (default: CR+LF) - - NOTE: no security measures are implemented. Anyone can remotely connect to - this service over the network. Only one connection at once is supported. When - the connection is terminated it waits for the next connect. - - -tcp_serial_redirect.py_ - Main program. - -.. _tcp_serial_redirect.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/tcp_serial_redirect.py - - -Multi-port TCP/IP - serial bridge -================================= -This example implements a TCP/IP to serial port service that works with -multiple ports at once. It uses select, no threads, and runs on POSIX systems -only. - -- Check existence of ``/tty/USB0...9``. -- Ports are periodically checked using ``os.path.exists``. -- Send Zeroconfig announcements when port appears or disappears (uses - python-avahi and dbus). -- Single process for all ports (not per port). -- All published services are kept in a dictionary that maps device->publisher - object. -- A delay of 5 seconds slows down the poll loop to a reasonable period. -- The script implements a daemon that logs to the syslog, unless specified - otherwise on the command line. - - -Requirements ------------- -- python (>2.4) -- python-avahi -- python-dbus -- python-serial - - -Installation ------------- -- Copy the script ``port_publisher.py`` to ``/usr/local/bin``. -- Copy the script ``port_publisher.sh`` to ``/etc/init.d``. -- Add links to the runlevels using ``update-rc.d port_publisher.sh defaults 99`` -- Thats it :-) the service will be started on next reboot. Alternatively run - ``invoke-rc.d port_publisher.sh start`` as root. - - -port_publisher.py_ - Multi-port TCP/IP-serial converter for POSIX environments. - -port_publisher.sh_ - Example init.d script. - -.. _port_publisher.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/port_publisher.py -.. _port_publisher.sh: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/port_publisher.sh - - -wxPython examples -================= -A simple terminal application for wxPython and a flexible serial port -configuration dialog are shown here. - -wxTerminal.py_ - A simple terminal application. Note that the length of the buffer is - limited by wx and it may suddenly stop displaying new input. - -wxTerminal.wxg_ -test_high_load.py_ - Tests involving sending a lot of data. - A wxGlade design file for the terminal application. - -wxSerialConfigDialog.py_ - A flexible serial port configuration dialog. - -wxSerialConfigDialog.wxg_ - The wxGlade design file for the configuration dialog. - -setup_demo.py_ - A py2exe setup script to package the terminal application. - -.. _wxTerminal.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxTerminal.py -.. _wxTerminal.wxg: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxTerminal.wxg -.. _wxSerialConfigDialog.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxSerialConfigDialog.py -.. _wxSerialConfigDialog.wxg: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxSerialConfigDialog.wxg -.. _setup_demo.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup_demo.py - - -Wrapper class -============= -This example provides a subclass based on ``Serial`` that has an alternative -implementation of ``readline()`` - -enhancedserial.py_ - A class with alternative ``readline()`` implementation. - -.. _enhancedserial.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/enhancedserial.py - - -Finding serial ports -==================== -scan.py_ - A simple loop that probes serial ports by number. - -scanlinux.py_ - A Linux only version looking at the entries in ``/dev``. It works best with - on systems with devfs or udev that only create those entries that represent - devices. On older installations a lot of pre-created device files are found - and an additional open check should be added to ensure that the device is - real. - -scanwin32.py_ - A Windows only version that returns a list of serial ports with information - from the registry. - -.. _scan.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scan.py -.. _scanlinux.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanlinux.py -.. _scanwin32.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanwin32.py - - -Unit tests -========== -The project uses a number of unit test to verify the functionality. They all -need a loop back connector. The scripts itself contain more information. - -test.py_ - Basic tests. - -test_advanced.py_ - Test more advanced features. - -test_high_load.py_ - Tests involving sending a lot of data. - -test_iolib.py_ - Tests involving the :mod:`io` library. Only available for Python 2.6 and - newer. - -.. _test.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test.py -.. _test_advanced.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test_advanced.py -.. _test_high_load.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test_high_load.py -.. _test_iolib.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test_iolib.py diff --git a/pyserial/documentation/index.rst b/pyserial/documentation/index.rst deleted file mode 100644 index 96a78b5..0000000 --- a/pyserial/documentation/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. pySerial documentation master file - -Welcome to pySerial's documentation -=================================== - -This module encapsulates the access for the serial port. It provides backends -for Python running on Windows, Linux, BSD (possibly any POSIX compliant -system), Jython and IronPython (.NET and Mono). The module named "serial" -automatically selects the appropriate backend. - -Contents: - -.. toctree:: - :maxdepth: 2 - - pyserial - shortintro - examples - pyserial_api - pyparallel - appendix - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/pyserial/documentation/pyparallel.rst b/pyserial/documentation/pyparallel.rst deleted file mode 100644 index 00c0b95..0000000 --- a/pyserial/documentation/pyparallel.rst +++ /dev/null @@ -1,165 +0,0 @@ -============ - pyParallel -============ - -.. note:: This module is in development (since years ;-) - -Overview -======== -This module encapsulates the access for the parallel port. It provides backends -for Python running on Windows and Linux. Other platforms are possible too but -not yet integrated. - -This module is still under development. But it may be useful for developers. - -Copyright (C) 2001-2003 Chris Liechti <cliechti(at)gmx.net> - -Here is the `project page on SourceForge`_ and here is the `SVN repository`_. - -.. _`project page on SourceForge`: http://sourceforge.net/projects/pyserial/ -.. _`SVN repository`: http://sourceforge.net/svn/?group_id=46487 - - -Features --------- -* same class based interface on all supported platforms -* port numbering starts at zero, no need to know the port name in the user program -* port string (device name) can be specified if access through numbering is inappropriate - - -Requirements ------------- -* Python 2.2 or newer -* "Java Communications" (JavaComm) extension for Java/Jython - - -Installation ------------- -Extract files from the archive, open a shell/console in that directory and let -Distutils do the rest: ``python setup.py install`` - -The files get installed in the "Lib/site-packages" directory in newer Python versions. - -The windows version needs a compiled extension and the giveio.sys driver for -Windows NT/2k/XP. The extension module can be compiled with Distutils with -either MSVC or GCC/mingw32. - -It is released under a free software license, see LICENSE.txt for more details. - - -Short introduction -================== -:: - - >>> import parallel - >>> p = parallel.Parallel() # open LPT1 - >>> p.setData(0x55) - - -Examples --------- -Please look in the SVN Repository. There is an example directory where you can -find a simple terminal and more. -http://pyserial.svn.sourceforge.net/viewvc/pyserial/trunk/pyparallel/examples/ - - -API -=== - -.. module:: parallel - -.. class:: Parallel - - .. method:: __init__(port) - - Open given parallel port. - - .. method:: setData(value) - - Apply the given byte to the data pins of the parallel port. - - .. method:: setDataStrobe(level) - - Set the "data strobe" line to the given state. - - .. method:: setAutoFeed(level) - - Set "auto feed" line to given state. - - .. method:: setInitOut(level) - - Set "initialize" line to given state. - - .. method: setSelect(level) - - Set "select" line to given state. - - .. method:getInError() - - Set "Error" line to given state. - - .. method:: getInSelected() - - Read level of "select" line. - - .. method:: getInPaperOut() - - Read level of "paper out" line. - - .. method:: getInAcknowledge() - - Read level of "Acknowledge" line. - - .. method: getInBusy() - - Read level of "busy" line. - - -.. module:: parallel.parallelutil - -.. class:: BitaccessMeta - - This mix-in class adds a few properties that allow easier bit access to the - data lines. (D0 .. D7) e.g. p.D0 refers to the first bit of the data - lines. - -.. class:: VirtualParallelPort - - This class provides a virtual parallel port implementation, useful - for tests and simulations without real hardware. - - -Notes -===== - -Linux ------ -1. The :manpage:`lp(4)` module must be unloaded, ``rmmod lp``. ``lp`` claims - exclusive access to the port and other programs won't be able to use it. - -2. The :manpage:`ppdev(4)` module needs to be loaded, ``modprobe ppdev``. When - ``udev`` is in use, (default with 2.6 kernels) this will create a - ``/dev/parport0``. - -3. The user needs to have write permissions to ``/dev/parport0``. Many - distributions have an ``lp`` group that owns the device; the simplest is to - add the user account to this group. Simply changing permissions on the - device is not the best strategy as they will be reverted to their defaults - next time the driver is loaded. - - -Windows -------- -The giveio driver must be installed as the module needs direct access to the -hardware. This also means that USB parallel port adapters won't be supported. - - -Misc -==== -References ----------- -* Python: http://www.python.org/ -* Jython: http://www.jython.org/ -* Java@IBM: http://www-106.ibm.com/developerworks/java/jdk/ (JavaComm links are - on the download page for the respective platform JDK) -* Java@SUN: http://java.sun.com/products/ diff --git a/pyserial/documentation/pyserial.png b/pyserial/documentation/pyserial.png Binary files differdeleted file mode 100644 index 7fd45f4..0000000 --- a/pyserial/documentation/pyserial.png +++ /dev/null diff --git a/pyserial/documentation/pyserial.rst b/pyserial/documentation/pyserial.rst deleted file mode 100644 index 2db8c21..0000000 --- a/pyserial/documentation/pyserial.rst +++ /dev/null @@ -1,110 +0,0 @@ -========== - pySerial -========== - -Overview -======== -This module encapsulates the access for the serial port. It provides backends -for Python running on Windows, Linux, BSD (possibly any POSIX compliant -system), Jython and IronPython (.NET and Mono). The module named "serial" -automatically selects the appropriate backend. - -It is released under a free software license, see LICENSE_ for more -details. - -Copyright (C) 2001-2009 Chris Liechti <cliechti(at)gmx.net> - -The `project page on SourceForge`_ and here is the `SVN repository`_ and the -`Download Page`_. - -The homepage is at http://pyserial.sf.net. - -.. _LICENSE: appendix.html#license -.. _`project page on SourceForge`: http://sourceforge.net/projects/pyserial/ -.. _`SVN repository`: http://sourceforge.net/svn/?group_id=46487 -.. _`Download Page`: http://sourceforge.net/project/showfiles.php?group_id=46487 - - -Features -======== -* Same class based interface on all supported platforms. -* Access to the port settings through Python properties. -* Support for different byte sizes, stop bits, parity and flow control with - RTS/CTS and/or Xon/Xoff. -* Working with or without receive timeout. -* File like API with "read" and "write" ("readline" etc. also supported). -* The files in this package are 100% pure Python. -* The port is set up for binary transmission. No NULL byte stripping, CR-LF - translation etc. (which are many times enabled for POSIX.) This makes this - module universally useful. -* Compatible with :mod:`io` library (Python 2.6+) - - -Requirements -============ -* Python 2.3 or newer, including Python 3.x -* ctypes extensions on Windows (is in standard library since Python 2.5+) -* "Java Communications" (JavaComm) or compatible extension for Java/Jython - - -Installation -============ - -pyserial --------- -This installs a package that can be used from Python (``import serial``). - -To install the module for all users on the system, administrator rights (root) -is required.. - -From source (tar.gz or checkout) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -http://pypi.python.org/pypi/pyserial -Unpack the archive, enter the ``pyserial-x.y`` directory and run:: - - python setup.py install - -Setuptools/PyPI -~~~~~~~~~~~~~~~ -Alternatively it can be installed from PyPI, either manually downloading the -files and installing as described above or using:: - - easy_install -U pyserial - -Packages -~~~~~~~~ -There are also packaged versions for some Linux distributions and Windows: - -Debian/Ubuntu - A package is available under the name "python-serial". - -Windows - There is also a Windows installer for end users. It is located in the - PyPi_. Developers may be interested to get the source archive, because it - contains examples and the readme. - -.. _PyPi: http://pypi.python.org/pypi/pyserial - - -References -========== -* Python: http://www.python.org/ -* Jython: http://www.jython.org/ -* Java@IBM: http://www-106.ibm.com/developerworks/java/jdk/ (JavaComm links are - on the download page for the respective platform JDK) -* Java@SUN: http://java.sun.com/products/ -* IronPython: http://www.codeplex.com/IronPython -* setuptools: http://peak.telecommunity.com/DevCenter/setuptools - - -Older Versions -============== -Older versions are still available on the `Download Page`_. pySerial 1.21 is -compatible with Python 2.0 on Windows, Linux and several un*x like systems, -MacOSX and Jython. - -On windows releases older than 2.5 will depend on pywin32_ (previously known as -win32all) - -.. _`Download Page`: http://sourceforge.net/project/showfiles.php?group_id=46487 -.. _pywin32: http://pypi.python.org/pypi/pywin32 diff --git a/pyserial/documentation/pyserial_api.rst b/pyserial/documentation/pyserial_api.rst deleted file mode 100644 index 9833254..0000000 --- a/pyserial/documentation/pyserial_api.rst +++ /dev/null @@ -1,531 +0,0 @@ -============== - pySerial API -============== - -.. module:: serial - -Classes -======= - -.. class:: Serial - - .. method:: __init__(port=None, baudrate=9600, bytesize=EIGHTBITS, parity=PARITY_NONE, stopbits=STOPBITS_ONE, timeout=None, xonxoff=0, rtscts=0, interCharTimeout=None) - - :param port: - Device name or port number number or :const:`None`. - - :param baudrate: - Baud rate such as 9600 or 115200 etc. - - :param bytesize: - Number of data bits. Possible values: - :const:`FIVEBITS`, :const:`SIXBITS`, :const:`SEVENBITS`, - :const:`EIGHTBITS` - - :param parity: - Enable parity checking. Possible values: - :const:`PARITY_NONE` :const:`PARITY_EVEN` :const:`PARITY_ODD` - :const:`PARITY_MARK` :const:`PARITY_SPACE` - - :param stopbits: - Number of stop bits. Possible values: - :const:`STOPBITS_ONE` :const:`STOPBITS_ONE_POINT_FIVE` - :const:`STOPBITS_TWO` - - :param timeout: - Set a read timeout value. - - :param xonxoff: - Enable software flow control. - - :param rtscts: - Enable hardware (RTS/CTS) flow control. - - :param interCharTimeout: - Inter-character timeout, :const:`None` to disable (default). - - :exception ValueError: - Will be raised when parameter are out of range, e.g. baud rate, data bits. - - :exception SerialException: - In case the device can not be found or can not be configured. - - - The port is immediately opened on object creation, when a *port* is - given. It is not opened when *port* is :const:`None` and a successive call - to :meth:`open` will be needed. - - Possible values for the parameter *port*: - - - Number: number of device, numbering starts at zero. - - Device name: depending on operating system. e.g. ``/dev/ttyUSB0`` - on GNU/Linux or ``COM3`` on Windows. - - Possible values for the parameter *timeout*: - - - ``timeout = None``: wait forever - - ``timeout = 0``: non-blocking mode (return immediately on read) - - ``timeout = x``: set timeout to ``x`` seconds (float allowed) - - - .. method:: open() - - Open port. - - .. method:: close() - - Close port immediately. - - - The following methods may raise :exc:`ValueError` when applied to a closed - port. - - .. method:: read(size=1) - - :param size: Number of bytes to read. - :return: Bytes read from the port. - - Read *size* bytes from the serial port. If a timeout is set it may - return less characters as requested. With no timeout it will block - until the requested number of bytes is read. - - .. versionchanged:: 2.5 - Returns an instance of :class:`bytes` when available (Python 2.6 - and newer) and :class:`str` otherwiese. - - .. method:: write(data) - - :param data: Data to send. - :return: Number of bytes written. - :exception SerialTimeoutException: - In case a write timeout is configured for the port and the time is - exceeded. - - Write the string *data* to the port. - - .. versionchanged:: 2.5 - Accepts instances of :class:`bytes` and :class:`bytearray` when - available (Python 2.6 and newer) and :class:`str` otherwiese. - - .. method:: inWaiting() - - Return the number of chars in the receive buffer. - - .. method:: flush() - - Flush of file like objects. In this case, wait until all data is - written. - - .. method:: flushInput() - - Flush input buffer, discarding all it's contents. - - .. method:: flushOutput() - - Clear output buffer, aborting the current output and - discarding all that is in the buffer. - - .. method:: sendBreak(duration=0.25) - - :param duration: Time (float) to activate the BREAK condition. - - Send break condition. Timed, returns to idle state after given - duration. - - .. method:: setBreak(level=True) - - :param level: when true activate BREAK condition, else disable. - - Set break: Controls TXD. When active, no transmitting is possible. - - .. method:: setRTS(level=True) - - :param level: Set control line to logic level. - - Set RTS line to specified logic level. - - .. method:: setDTR(level=True) - - :param level: Set control line to logic level. - - Set DTR line to specified logic level. - - .. method:: getCTS() - - :return: Current state (boolean) - - Return the state of the CTS line. - - .. method:: getDSR() - - :return: Current state (boolean) - - Return the state of the DSR line. - - .. method:: getRI() - - :return: Current state (boolean) - - Return the state of the RI line. - - .. method:: getCD() - - :return: Current state (boolean) - - Return the state of the CD line - - Read-only attributes: - - .. attribute:: name - - Device name. This is always the device name even if the - port was opened by a number. (Read Only). - - .. versionadded:: 2.5 - - .. attribute:: portstr - - :deprecated: use :attr:`name` instead - - .. attribute:: BAUDRATES - - A list of valid baud rates. The list may be incomplete such that higher - baud rates may be supported by the device and that values in between the - standard baud rates are supported. (Read Only). - - .. attribute:: BYTESIZES - - A list of valid byte sizes for the device (Read Only). - - .. attribute:: PARITIES - - A list of valid parities for the device (Read Only). - - .. attribute:: STOPBITS - - A list of valid stop bit widths for the device (Read Only). - - - New values can be assigned to the following attributes, the port will be - reconfigured, even if it's opened at that time: - - .. attribute:: port - - Port name/number as set by the user. - - .. attribute:: baudrate - - Current baud rate setting. - - .. attribute:: bytesize - - Byte size in bits. - - .. attribute:: parity - - Parity setting. - - .. attribute:: stopbits - - Stop bit with. - - .. attribute:: timeout - - Timeout setting (seconds, float). - - .. attribute:: xonxoff - - If Xon/Xoff flow control is enabled. - - .. attribute:: rtscts - - If hardware flow control is enabled. - - Platform specific methods. - - .. warning:: Programs using the following methods are not portable to other platforms! - - .. method:: nonblocking() - - :platform: Unix - - Configure the device for nonblocking operations. This can be useful if - the port is used with ``select``. - - .. method:: fileno() - - :platform: Unix - :return: File descriptor. - - Return file descriptor number for the port that is opened by this object. - - .. method:: setXON(level=True) - - :platform: Windows - :param level: Set flow control state. - - Set software flow control state. - - -.. class:: SerialBase - - The following attributes are implemented as properties. They work with open - and closed ports. - - .. attribute:: port - - Read or write port. When the port is already open, it will be closed - and reopened with the new setting. - - .. attribute:: baudrate - - Read or write current baud rate setting. - - .. attribute:: bytesize - - Read or write current data byte size setting. - - .. attribute:: parity - - Read or write current parity setting. - - .. attribute:: stopbits - - Read or write current stop bit width setting. - - .. attribute:: timeout - - Read or write current read timeout setting. - - .. attribute:: writeTimeout - - Read or write current write timeout setting. - - .. attribute:: xonxoff - - Read or write current software flow control rate setting. - - .. attribute:: rtscts - - Read or write current hardware flow control setting. - - .. attribute:: dsrdtr - - Read or write current hardware flow control setting. - - .. attribute:: interCharTimeout - - Read or write current inter character timeout setting. - - The following constants are also provided: - - .. attribute:: BAUDRATES - - A tuple of standard baud rate values. The actual device may support more - or less... - - .. attribute:: BYTESIZES - - A tuple of supported byte size values. - - .. attribute:: PARITIES - - A tuple of supported parity settings. - - .. attribute:: STOPBITS - - A tuple of supported stop bit settings. - - .. method:: readline(size=None, eol='\\n') - - :param size: Max number of bytes to read, ``None`` -> no limit. - :param eol: The end of line character. - - Read a line which is terminated with end-of-line (*eol*) character - (``\\n`` by default) or until timeout. - - .. method:: readlines(sizehint=None, eol='\\n') - - :param size: Ignored parameter. - :param eol: The end of line character. - - Read a list of lines, until timeout. *sizehint* is ignored and only - present for API compatibility with built-in File objects. - - .. method:: xreadlines(sizehint=None) - - Just calls :meth:`readlines` - here for compatibility. - - For compatibility with the :mod:`io` library are the following methods. - - .. method:: readable() - - :return: True - .. versionadded:: 2.5 - - .. method:: writable() - - :return: True - .. versionadded:: 2.5 - - .. method:: seekable() - - :return: False - .. versionadded:: 2.5 - - .. method:: readinto(b) - - :param b: bytearray or array instace - :return: Number of byte read - - Read up to len(b) bytes into bytearray b and return the number of bytes read. - - .. versionadded:: 2.5 - - -.. note:: - - For systems that provide the :mod:`io` library (Python 2.6 and newer), the - class :class:`Serial` will derrive from :class:`io.RawIOBase`. For all - others from :class:`FileLike`. - -.. class:: FileLike - - An abstract file like class. It is used as base class for :class:`Serial`. - - This class implements :meth:`readline` and :meth:`readlines` based on read - and :meth:`writelines` based on write. This class is used to provide the - above functions for to Serial port objects. - - Note that when the serial port was opened with no timeout that - :meth:`readline` blocks until it sees a newline (or the specified size is - reached) and that :meth:`readlines` would never return and therefore - refuses to work (it raises an exception in this case)! - - .. method:: writelines(sequence) - - Write a list of strings to the port. - - - The following three methods are overridden in :class:`Serial`. - - .. method:: flush() - - Flush of file like objects. It's a no-op in this class, may be overridden. - - .. method:: read() - - Raises NotImplementedError, needs to be overridden by subclass. - - .. method:: write(data) - - Raises NotImplementedError, needs to be overridden by subclass. - - The following functions are implemented for compatibility with other - file-like objects, however serial ports are not seekable. - - - .. method:: seek(pos, whence=0) - - :exception IOError: always, as method is not supported on serial port - - .. versionadded:: 2.5 - - .. method:: tell() - - :exception IOError: always, as method is not supported on serial port - - .. versionadded:: 2.5 - - .. method:: truncate(self, n=None) - - :exception IOError: always, as method is not supported on serial port - - .. versionadded:: 2.5 - - .. method:: isatty() - - :exception IOError: always, as method is not supported on serial port - - .. versionadded:: 2.5 - - To be able to use the file like object as iterator for e.g. - ``for line in Serial(0): ...`` usage: - - .. method:: next() - - Return the next line by calling :meth:`readline`. - - .. method:: __iter__() - - Returns self. - - - -Exceptions -========== - -.. exception:: SerialException - - Base class for serial port exceptions. - - .. versionchanged:: 2.5 - Now derrives from :exc:`IOError` instead of :exc:`Exception` - -.. exception:: SerialTimeoutException - - Exception that is raised on write timeouts. - - -Constants -========= - -Parity ------- -.. data:: PARITY_NONE -.. data:: PARITY_EVEN -.. data:: PARITY_ODD -.. data:: PARITY_MARK -.. data:: PARITY_SPACE - -Stop bits ---------- -.. data:: STOPBITS_ONE -.. data:: STOPBITS_ONE_POINT_FIVE -.. data:: STOPBITS_TWO - -Byte size ---------- -.. data:: FIVEBITS -.. data:: SIXBITS -.. data:: SEVENBITS -.. data:: EIGHTBITS - -Others -------- -Default control characters (instnces of :class:`bytes` for Python 3.0+) for -software flow control: - -.. data:: XON -.. data:: XOFF - -Module version: - -.. data:: VERSION - - A string indicating the pySerial version, such as ``2.5``. - -Functions: - -.. function:: device(number) - - :param number: Port number. - :return: String containing device name. - :deprecated: Use device names directly. - - Convert a port number to a platform dependent device name. Unfortunately - this does not work well for all platforms; e.g. some may miss USB-Serial - converters and enumerate only internal serial ports. - - The conversion may be made off-line, that is, there is no guarantee that - the returned device name really exists on the system. diff --git a/pyserial/documentation/shortintro.rst b/pyserial/documentation/shortintro.rst deleted file mode 100644 index 048f94d..0000000 --- a/pyserial/documentation/shortintro.rst +++ /dev/null @@ -1,57 +0,0 @@ -==================== - Short introduction -==================== - -Opening serial ports -==================== - -Open port 0 at "9600,8,N,1", no timeout:: - - >>> import serial - >>> ser = serial.Serial(0) # open first serial port - >>> print ser.portstr # check which port was really used - >>> ser.write("hello") # write a string - >>> ser.close() # close port - -Open named port at "19200,8,N,1", 1s timeout:: - - >>> ser = serial.Serial('/dev/ttyS1', 19200, timeout=1) - >>> x = ser.read() # read one byte - >>> s = ser.read(10) # read up to ten bytes (timeout) - >>> line = ser.readline() # read a '\n' terminated line - >>> ser.close() - -Open second port at "38400,8,E,1", non blocking HW handshaking:: - - >>> ser = serial.Serial(1, 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 = 0 - >>> 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.isOpen() - True - >>> ser.close() - >>> ser.isOpen() - False - -Readline -======== -Be carefully when using "readline". Do specify a timeout when opening the -serial port otherwise it could block forever if no newline character is -received. Also note that "readlines" only works with a timeout. "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. |
