diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/Makefile | 88 | ||||
| -rw-r--r-- | documentation/appendix.rst | 100 | ||||
| -rw-r--r-- | documentation/conf.py | 194 | ||||
| -rw-r--r-- | documentation/examples.rst | 351 | ||||
| -rw-r--r-- | documentation/index.rst | 41 | ||||
| -rw-r--r-- | documentation/pyparallel.rst | 165 | ||||
| -rw-r--r-- | documentation/pyserial.png | bin | 0 -> 7050 bytes | |||
| -rw-r--r-- | documentation/pyserial.rst | 113 | ||||
| -rw-r--r-- | documentation/pyserial_api.rst | 800 | ||||
| -rw-r--r-- | documentation/shortintro.rst | 57 |
10 files changed, 1909 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/appendix.rst b/documentation/appendix.rst new file mode 100644 index 0000000..8492717 --- /dev/null +++ b/documentation/appendix.rst @@ -0,0 +1,100 @@ +========== + Appendix +========== + +How To +====== + +Enable :rfc:`2217` in programs using pySerial. + Patch the code where the :class:`serial.Serial` is instantiated. Replace + it with:: + + try: + s = serial.serial_for_url(...) + except AttributeError: + s = serial.Serial(...) + + Assuming the application already stores port names as strings that's all + that is required. The user just needs a way to change the port setting of + your application to an ``rfc2217://`` :ref:`URL <URLs>` (e.g. by editing a + configuration file, GUI dialog etc.). + + Please note that this enables all :ref:`URL <URLs>` types supported by + pySerial and that those involving the network are unencrypted and not + protected against eavesdropping. + +Test your setup. + Is the device not working as expected? Maybe it's time to check the + connection before proceeding. :ref:`miniterm` from the :ref:`examples` + can be used to open the serial port and do some basic tests. + + To test cables, connecting RX to TX (loop back) and typing some characters + in :ref:`miniterm` is a simple test. When the characters are displayed + on the screen, then at least RX and TX work (they still could be swapped + though). + + +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/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 +# "<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/documentation/examples.rst b/documentation/examples.rst new file mode 100644 index 0000000..0bfdaae --- /dev/null +++ b/documentation/examples.rst @@ -0,0 +1,351 @@ +.. _examples: + +========== + Examples +========== + +.. _miniterm: + +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. + +miniterm supports :rfc:`2217` remote serial ports and raw sockets using URLs +such as ``rfc2217:://<host>:<port>`` respectively ``socket://<host>:<port>`` as +*port* argument when invoking. + +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 + +.. versionchanged:: 2.5 + Added :kbd:`Control+t` menu and added support for opening URLs. + +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. + +This example only exports a raw socket connection. The next example +below gives the client much more control over the remote serial port. + +- The serial port settings are set on the command line when starting the + program. +- There is no possibility to change settings from remote. +- All data is passed through as-is. + +:: + + 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 + --rfc2217 allow control commands with Telnet extension RFC-2217 + + 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 + +Single-port TCP/IP - serial bridge (RFC 2217) +============================================= +Simple cross platform :rfc:`2217` serial port server. It uses threads and is +portable (runs on POSIX, Windows, etc). + +- The port settings and control lines (RTS/DTR) can be changed at any time + using :rfc:`2217` requests. The status lines (DSR/CTS/RI/CD) are polled every + second and notifications are sent to the client. +- Telnet character IAC (0xff) needs to be doubled in data stream. IAC followed + by an other value is interpreted as Telnet command sequence. +- Telnet negotiation commands are sent when connecting to the server. +- RTS/DTR are activated on client connect and deactivated on disconnect. +- Default port settings are set again when client disconnects. + +:: + + Usage: rfc2217_server.py [options] port + + RFC 2217 Serial to Network (TCP/IP) redirector. + + Options: + -h, --help show this help message and exit + -p LOCAL_PORT, --localport=LOCAL_PORT + local TCP port + + 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. + +.. versionadded:: 2.5 + +rfc2217_server.py_ + Main program. + +setup-rfc2217_server-py2exe.py_ + This is a py2exe setup script for Windows. It can be used to create a + standalone ``rfc2217_server.exe``. + +.. _rfc2217_server.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/rfc2217_server.py +.. _setup-rfc2217_server-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup-rfc2217_server-py2exe.py + + +Multi-port TCP/IP - serial bridge (RFC 2217) +============================================ +This example implements a TCP/IP to serial port service that works with +multiple ports at once. It uses select, no threads, for the serial ports and +the network sockets and therefore runs on POSIX systems only. + +- Full control over the serial port with :rfc:`2217`. +- Check existence of ``/tty/USB0...8``. This is done every 5 seconds using + ``os.path.exists``. +- Send zeroconf announcements when port appears or disappears (uses + python-avahi and dbus). Service name: ``_serial_port._tcp``. +- Each serial port becomes available as one TCP/IP server. e.g. + ``/dev/ttyUSB0`` is reachable at ``<host>:7000``. +- Single process for all ports and sockets (not per port). +- The script can be started as daemon. +- Logging to stdout or when run as daemon to syslog. +- Default port settings are set again when client disconnects. +- modem status lines (CTS/DSR/RI/CD) are not polled periodically and the server + therefore does not send NOTIFY_MODEMSTATE on its own. However it responds to + request from the client (i.e. use the ``poll_modem`` option in the URL when + using a pySerial client.) + +Requirements: + +- Python (>= 2.4) +- python-avahi +- python-dbus +- python-serial (>= 2.5) + +Installation as daemon: + +- 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. + +.. versionadded:: 2.5 new example + +port_publisher.py_ + Multi-port TCP/IP-serial converter (RFC 2217) 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_ + 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-wxTerminal-py2exe.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-wxTerminal-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup-wxTerminal-py2exe.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. All +test scripts are contained in the directory ``test``. + +The unit tests are performed on port ``0`` unless a different device name or +``rfc2217://`` URL is given on the command line (argv[1]). + +run_all_tests.py_ + Collect all tests from all ``test*`` files and run them. By default, the + ``loop://`` device is used. + +test.py_ + Basic tests (binary capabilities, timeout, control lines). + +test_advanced.py_ + Test more advanced features (properties). + +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. + +.. _run_all_tests.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/run_all_tests.py +.. _test.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test.py +.. _test_advanced.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_advanced.py +.. _test_high_load.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_high_load.py +.. _test_iolib.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_iolib.py diff --git a/documentation/index.rst b/documentation/index.rst new file mode 100644 index 0000000..77dae93 --- /dev/null +++ b/documentation/index.rst @@ -0,0 +1,41 @@ +.. 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. + +Other pages (online) + +- `project page on SourceForge`_ +- `SVN repository`_ +- `Download Page`_ with releases +- This page, when viewed online is at http://pyserial.sf.net. + +.. _`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 + + +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 <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/documentation/pyserial.png b/documentation/pyserial.png Binary files differnew file mode 100644 index 0000000..7fd45f4 --- /dev/null +++ b/documentation/pyserial.png diff --git a/documentation/pyserial.rst b/documentation/pyserial.rst new file mode 100644 index 0000000..0bc6522 --- /dev/null +++ b/documentation/pyserial.rst @@ -0,0 +1,113 @@ +========== + 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> + +Other pages (online) + +- `project page on SourceForge`_ +- `SVN repository`_ +- `Download Page`_ with releases +- This page, when viewed online 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+) +- RFC 2217 client (experimental), server provided in the examples. + + +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..5f15046 --- /dev/null +++ b/documentation/pyserial_api.rst @@ -0,0 +1,800 @@ +============== + pySerial API +============== + +.. module:: serial + +Classes +======= + +Native ports +------------ + +.. 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) + + Note that enabling both flow control methods (*xonxoff* and *rtscts*) + together may not be supported. It is common to use one of the methods + at once, not both. + + .. 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` otherwise. + + .. 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` otherwise. + + .. 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 instance + :return: Number of byte read + + Read up to len(b) bytes into :class:`bytearray` *b* and return the + number of bytes read. + + .. versionadded:: 2.5 + + .. method:: getSettingsDict() + + :return: a dictionary with current port settings. + + Get a dictionary with port settings. This is useful to backup the + current settings so that a later point in time they can be restored + using :meth:`applySettingsDict`. + + Note that control lines (RTS/DTR) are part of the settings. + + .. versionadded:: 2.5 + + .. method:: applySettingsDict(d) + + :param d: a dictionary with port settings. + + Applies a dictionary that was created by :meth:`getSettingsDict`. Only + changes are applied and when a key is missing it means that the setting + stays unchanged. + + Note that control lines (RTS/DTR) are not changed. + + .. versionadded:: 2.5 + + +.. note:: + + For systems that provide the :mod:`io` library (Python 2.6 and newer), the + class :class:`Serial` will derive 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. + +:rfc:`2217` Network ports +------------------------- + +.. warning:: This implementation is currently in an experimental state. Use + at your own risk. + +.. class:: rfc2217.Serial + + This implements a :rfc:`2217` compatible client. Port names are URLs_ in the + form: ``rfc2217://<host>:<port>[/<option>[/<option>]]`` + + This class API is compatible to :class:`Serial` with a few exceptions: + + - numbers as port name are not allowed, only URLs in the form described + above. + - writeTimeout is not implemented + - The current implementation starts a thread that keeps reading from the + (internal) socket. The thread is managed automatically by the + :class:`rfc2217.Serial` port object on :meth:`open`/:meth:`close`. + However it may be a problem for user applications that like to use select + instead of threads. + + Due to the nature of the network and protocol involved there are a few + extra points to keep in mind: + + - All operations have an additional latency time. + - Setting control lines (RTS/CTS) needs more time. + - Reading the status lines (DSR/DTR etc.) returns a cached value. When that + cache is updated depends entirely on the server. The server itself may + implement a polling at a certain rate and quick changes may be invisible. + - The network layer also has buffers. This means that :meth:`flush`, + :meth:`flushInput` and :meth:`flushOutput` may work with additional delay. + Likewise :meth:`inWaiting` returns the size of the data arrived at the + object internal buffer and excludes any bytes in the network buffers or + any server side buffer. + - Closing and immediately reopening the same port may fail due to time + needed by the server to get ready again. + + Not implemented yet / Possible problems with the implementation: + + - :rfc:`2217` flow control between client and server (objects internal + buffer may eat all your memory when never read). + - No authentication support (servers may not prompt for a password etc.) + - No encryption. + + Due to lack of authentication and encryption it is not suitable to use this + client for connections across the internet and should only be used in + controlled environments. + + .. versionadded:: 2.5 + + +.. class:: rfc2217.PortManager + + This class provides helper functions for implementing :rfc:`2217` + compatible servers. + + Basically, it implements every thing needed for the :rfc:`2217` protocol. + It just does not open sockets and read/write to serial ports (though it + changes other port settings). The user of this class must take care of the + data transmission itself. The reason for that is, that this way, this class + supports all programming models such as threads and select. + + Usage examples can be found in the examples where two TCP/IP - serial + converters are shown, one using threads (the single port server) and an + other using select (the multi port server). + + .. note:: Each new client connection must create a new instance as this + object (and the :rfc:`2217` protocol) has internal state. + + .. method:: __init__(serial_port, connection, debug_output=False) + + :param serial_port: a :class:`Serial` instance that is managed. + :param connection: an object implementing :meth:`write`, used to write + to the network. + :param debug_output: enables debug messages: a :class:`logging.Logger` + instance or None. + + Initializes the Manager and starts negotiating with client in Telnet + and :rfc:`2217` protocol. The negotiation starts immediately so that + the class should be instantiated in the moment the client connects. + + The *serial_port* can be controlled by :rfc:`2217` commands. This + object will modify the port settings (baud rate etc) and control lines + (RTS/DTR) send BREAK etc. when the corresponding commands are found by + the :meth:`filter` method. + + The *connection* object must implement a :meth:`write(data)` function. + This function must ensure that *data* is written at once (no user data + mixed in, i.e. it must be thread-safe). All data must be sent in its + raw form (:meth:`escape` must not be used) as it is used to send Telnet + and :rfc:`2217` control commands. + + For diagnostics of the connection or the implementation, *debug_output* + can be set to an instance of a :class:`logging.Logger` (e.g. + ``logging.getLogger('rfc2217.server')``). The caller should configure + the logger using ``setLevel`` for the desired detail level of the logs. + + .. method:: escape(data) + + :param data: data to be sent over the network. + :return: data, escaped for Telnet/:rfc:`2217` + + A generator that escapes all data to be compatible with :rfc:`2217`. + Implementors of servers should use this function to process all data + sent over the network. + + The function returns a generator which can be used in ``for`` loops. + It can be converted to bytes using ``serial.to_bytes``. + + .. method:: filter(data) + + :param data: data read from the network, including Telnet and + :rfc:`2217` controls. + :return: data, free from Telnet and :rfc:`2217` controls. + + A generator that filters and processes all data related to :rfc:`2217`. + Implementors of servers should use this function to process all data + received from the network. + + The function returns a generator which can be used in ``for`` loops. + It can be converted to bytes using ``serial.to_bytes``. + + .. method:: check_modem_lines(force_notification=False) + + :param force_notification: Set to false. Parameter is for internal use. + + This function needs to be called periodically (e.g. every second) when + the server wants to send NOTIFY_MODEMSTATE messages. This is required + to support the client for reading CTS/DSR/RI/CD status lines. + + The function reads the status line and issues the notifications + automatically. + + .. versionadded:: 2.5 + +.. seealso:: + + :rfc:`2217` - Telnet Com Port Control Option + + +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 (instances 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. + + +.. function:: serial_for_url(url, \*args, \*\*kwargs) + + :param url: Device name, number or :ref:`URL <URLs>` + :param do_not_open: When set to true, the serial port is not opened. + :return: an instance of :class:`Serial` or a compatible object. + + Get a native or a :rfc:`2217` implementation of the Serial class, depending + on port/url. This factory function is useful when an application wants + to support both, local ports and remote ports. + + When *url* matches the form ``rfc2217://<host>:<port>`` an instance of + :class:`rfc2217.Serial` is returned. In all other cases the native (system + dependant) :class:`Serial` instance is returned. + + The port is not opened when a keyword parameter called *do_not_open* is + given and true, by default it is opened. + + .. versionadded:: 2.5 + +.. _URLs: + +URLs +---- +The class :class:`rfc2217.Serial` and the function :func:`serial_for_url` +accept the following types URL: + +- ``rfc2217://<host>:<port>[/<option>[/<option>]]`` +- ``socket://<host>:<port>[/<option>[/<option>]]`` +- ``loop://[<option>[/<option>]]`` + +(Future releases of pySerial might add more types). + +``rfc2217://`` + Used to connect to :rfc:`2217` compatible servers. All serial port + functions are supported. + + Supported options in the URL are: + + - ``ign_set_control`` does not wait for acknowledges to SET_CONTROL. This + option can be used for non compliant servers (i.e. when getting an + ``remote rejected value for option 'control'`` error when connecting). + + - ``poll_modem``: The client issues NOTIFY_MODEMSTATE requests when status + lines are read (CTS/DTR/RI/CD). Without this option it relies on the server + sending the notifications automatically (that's what the RFC suggests and + most servers do). Enable this option when :meth:`getCTS` does not work as + expected, i.e. for servers that do not send notifications. + + - ``timeout=<value>``: Change network timeout (default 3 seconds). This is + useful when the server takes a little more time to send its answers. The + timeout applies to the initial Telnet / :rfc:`2271` negotiation as well + as changing port settings or control line change commands. + + - ``logging=[debug|info|warning|error]``: Prints diagnostic messages (not + useful for end users). It uses the logging module and a logger called + ``pySerial.rfc2217`` so that the application can setup up logging + handlers etc. It will call :meth:`logging.basicConfig` which initializes + for output on ``sys.stderr`` (if no logging was set up already). + +``socket://`` + The purpose of this connection type is that applications using pySerial can + connect to TCP/IP to serial port converters that do not support :rfc:`2217`. + + Uses a TCP/IP socket. All serial port settings, control and status lines + are ignored. Only data is transmitted and received. + + Supported options in the URL are: + + - ``logging=[debug|info|warning|error]``: Prints diagnostic messages (not + useful for end users). It uses the logging module and a logger called + ``pySerial.socket`` so that the application can setup up logging handlers + etc. It will call :meth:`logging.basicConfig` which initializes for + output on ``sys.stderr`` (if no logging was set up already). + +``loop://`` + The least useful type. It simulates a loop back connection. + ``RX<->TX`` ``RTS<->CTS`` ``DTR<->DSR`` + + Supported options in the URL are: + + - ``logging=[debug|info|warning|error]``: Prints diagnostic messages (not + useful for end users). It uses the logging module and a logger called + ``pySerial.loop`` so that the application can setup up logging handlers + etc. It will call :meth:`logging.basicConfig` which initializes for + output on ``sys.stderr`` (if no logging was set up already). + + +Examples: + +- ``rfc2217://localhost:7000`` +- ``rfc2217://localhost:7000/poll_modem`` +- ``rfc2217://localhost:7000/ign_set_control/timeout=5.5`` +- ``socket://localhost:7777`` +- ``loop://logging=debug`` 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<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. |
