From bfae228264985d762796a9fc13f09a1bcf45fe52 Mon Sep 17 00:00:00 2001 From: cliechti Date: Thu, 30 Jul 2009 21:15:57 +0000 Subject: - move documentation so that distutils sees it - update CHANGES.txt - install miniterm.py as script - version 2.5-rc1 git-svn-id: http://svn.code.sf.net/p/pyserial/code/trunk/pyserial@263 f19166aa-fa4f-0410-85c2-fa1106f25c8a --- documentation/Makefile | 88 +++++++ documentation/appendix.rst | 68 ++++++ documentation/conf.py | 194 +++++++++++++++ documentation/examples.rst | 282 ++++++++++++++++++++++ documentation/index.rst | 29 +++ documentation/pyparallel.rst | 165 +++++++++++++ documentation/pyserial.png | Bin 0 -> 7050 bytes documentation/pyserial.rst | 110 +++++++++ documentation/pyserial_api.rst | 531 +++++++++++++++++++++++++++++++++++++++++ documentation/shortintro.rst | 57 +++++ 10 files changed, 1524 insertions(+) create mode 100644 documentation/Makefile create mode 100644 documentation/appendix.rst create mode 100644 documentation/conf.py create mode 100644 documentation/examples.rst create mode 100644 documentation/index.rst create mode 100644 documentation/pyparallel.rst create mode 100644 documentation/pyserial.png create mode 100644 documentation/pyserial.rst create mode 100644 documentation/pyserial_api.rst create mode 100644 documentation/shortintro.rst (limited to 'documentation') diff --git a/documentation/Makefile b/documentation/Makefile new file mode 100644 index 0000000..8384360 --- /dev/null +++ b/documentation/Makefile @@ -0,0 +1,88 @@ +# 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 ' where 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/documentation/appendix.rst b/documentation/appendix.rst new file mode 100644 index 0000000..001c6e5 --- /dev/null +++ b/documentation/appendix.rst @@ -0,0 +1,68 @@ +========== + Appendix +========== + +Related software +================ + +com0com - http://com0com.sourceforge.net/ + Provides virtual serial ports for Windows. + + +License +======= + +Copyright (C) 2001-2009 Chris Liechti ; +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/documentation/conf.py b/documentation/conf.py new file mode 100644 index 0000000..7420982 --- /dev/null +++ b/documentation/conf.py @@ -0,0 +1,194 @@ +# -*- 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 +# " v 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 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/documentation/examples.rst b/documentation/examples.rst new file mode 100644 index 0000000..283f2d6 --- /dev/null +++ b/documentation/examples.rst @@ -0,0 +1,282 @@ +========== + 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/documentation/index.rst b/documentation/index.rst new file mode 100644 index 0000000..96a78b5 --- /dev/null +++ b/documentation/index.rst @@ -0,0 +1,29 @@ +.. 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/documentation/pyparallel.rst b/documentation/pyparallel.rst new file mode 100644 index 0000000..00c0b95 --- /dev/null +++ b/documentation/pyparallel.rst @@ -0,0 +1,165 @@ +============ + 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 + +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/documentation/pyserial.png b/documentation/pyserial.png new file mode 100644 index 0000000..7fd45f4 Binary files /dev/null and b/documentation/pyserial.png differ diff --git a/documentation/pyserial.rst b/documentation/pyserial.rst new file mode 100644 index 0000000..2db8c21 --- /dev/null +++ b/documentation/pyserial.rst @@ -0,0 +1,110 @@ +========== + 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 + +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/documentation/pyserial_api.rst b/documentation/pyserial_api.rst new file mode 100644 index 0000000..9833254 --- /dev/null +++ b/documentation/pyserial_api.rst @@ -0,0 +1,531 @@ +============== + 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/documentation/shortintro.rst b/documentation/shortintro.rst new file mode 100644 index 0000000..048f94d --- /dev/null +++ b/documentation/shortintro.rst @@ -0,0 +1,57 @@ +==================== + 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(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. -- cgit v1.2.1