diff options
| -rw-r--r-- | documentation/Makefile | 88 | ||||
| -rw-r--r-- | documentation/conf.py | 194 | ||||
| -rw-r--r-- | documentation/index.rst | 28 | ||||
| -rw-r--r-- | documentation/pyparallel.rst | 67 | ||||
| -rw-r--r-- | documentation/pyserial_api.rst | 248 |
5 files changed, 625 insertions, 0 deletions
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 <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/documentation/conf.py b/documentation/conf.py new file mode 100644 index 0000000..4ff412c --- /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.4' +# The full version, including alpha/beta/rc tags. +release = '2.4' + +# 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 = None + +# 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 = None + +# 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/index.rst b/documentation/index.rst new file mode 100644 index 0000000..65a4c04 --- /dev/null +++ b/documentation/index.rst @@ -0,0 +1,28 @@ +.. pySerial documentation master file, created by + sphinx-quickstart on Tue Jul 21 00:27:45 2009. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to pySerial's documentation! +==================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + pyserial + manual + 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..3560bce --- /dev/null +++ b/documentation/pyparallel.rst @@ -0,0 +1,67 @@ +============ + 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. + + (C) 2001-2003 Chris Liechti <cliechti@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/ + +References +---------- +* Python: http://www.python.org/|http://www.python.org +* Jython: http://www.jython.org/|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_api.rst b/documentation/pyserial_api.rst new file mode 100644 index 0000000..7c5ea1d --- /dev/null +++ b/documentation/pyserial_api.rst @@ -0,0 +1,248 @@ +============== + 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 None. + + 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. + + :param baudrate: + Baud rate such as 9600 or 115200 etc. + + :param bytesize: + Number of data bits. Possible values: FIVEBITS, SIXBITS, SEVENBITS, EIGHTBITS + + :param parity: + Enable parity checking. Possible values: PARITY_NONE PARITY_EVEN PARITY_ODD PARITY_MARK PARITY_SPACE + + :param stopbits: + Number of stop bits. Possible values: STOPBITS_ONE STOPBITS_ONE_POINT_FIVE 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, None to disable. + + The port is immediately opened on object creation, when a port is given. It + is not opened when port is None. + + Possible values for :param:`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. + + .. method:: setBaudrate(baudrate) + + Change baud rate on an open port. + + .. method:: inWaiting() + + Return the number of chars in the receive buffer. + + .. method:: read(size=1) + + 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. + + .. method:: write(s) + + Write the string :param:`s` to the port. + + .. method:: flush(self): + + 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) + + Send break condition. Timed, returns to idle state after given + duration. + + .. method:: setBreak(level=True) + + Set break: Controls TXD. When active, no transmitting is possible. + + .. method:: setRTS(level=True) + + Set RTS line to specified logic level. + + .. method:: setDTR(level=True) + + Set DTR line to specified logic level. + + .. method:: getCTS() + + Return the state of the CTS line. + + .. method:: getDSR() + + Return the state of the DSR line. + + .. method:: getRI() + + Return the state of the RI line. + + .. method:: getCD() + + Return the state of the CD line + + Read-only attributes: + + .. attribute:: portstr + + Device name (Read Only). This is always the device name even if the + port was opened by a numeber. + + .. 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). + + .. 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 number. + + + .. method:: setXON(level=True) + + :platform: Windows + Set software flow control state. + + +Exceptions +========== + +.. exception:: SerialException + + Base class for serial port exceptions. + +.. 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 + +stopbits +-------- +.. data:: STOPBITS_ONE +.. data:: STOPBITS_ONE_POINT_FIVE +.. data:: STOPBITS_TWO + +bytesize +-------- +.. data:: FIVEBITS +.. data:: SIXBITS +.. data:: SEVENBITS +.. data:: EIGHTBITS |