diff options
author | Chris Liechti <cliechti@gmx.net> | 2015-08-04 03:32:02 +0200 |
---|---|---|
committer | Chris Liechti <cliechti@gmx.net> | 2015-08-04 03:32:02 +0200 |
commit | 90570b9a7d663e52bdf70b6a6b877bfd3246521e (patch) | |
tree | a8f6ff00819025b355caf9228bf34f18bb7e7139 /documentation | |
parent | 70b892395deeaf3dc4967bd808101e61e4e1a53f (diff) | |
download | pyserial-git-90570b9a7d663e52bdf70b6a6b877bfd3246521e.tar.gz |
doc update: links, remove pyparallel page, rename README.txt to end in .rst
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/appendix.rst | 80 | ||||
-rw-r--r-- | documentation/conf.py | 6 | ||||
-rw-r--r-- | documentation/examples.rst | 48 | ||||
-rw-r--r-- | documentation/index.rst | 9 | ||||
-rw-r--r-- | documentation/pyparallel.rst | 165 | ||||
-rw-r--r-- | documentation/pyserial.rst | 17 | ||||
-rw-r--r-- | documentation/shortintro.rst | 8 |
7 files changed, 64 insertions, 269 deletions
diff --git a/documentation/appendix.rst b/documentation/appendix.rst index eaba1e8..99e16d7 100644 --- a/documentation/appendix.rst +++ b/documentation/appendix.rst @@ -81,58 +81,34 @@ com0com - http://com0com.sourceforge.net/ License ======= - -Copyright (C) 2001-2013 Chris Liechti <cliechti(at)gmx.net>; +Copyright (c) 2001-2015 Chris Liechti <cliechti@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. +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + * Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/documentation/conf.py b/documentation/conf.py index 66650d9..d1c6717 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -38,16 +38,16 @@ master_doc = 'index' # General information about the project. project = u'pySerial' -copyright = u'2001-2013, Chris Liechti' +copyright = u'2001-2015, 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.7' +version = '3.0' # The full version, including alpha/beta/rc tags. -release = '2.7' +release = '3.x' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/documentation/examples.rst b/documentation/examples.rst index 181aa2c..bf6f22d 100644 --- a/documentation/examples.rst +++ b/documentation/examples.rst @@ -108,8 +108,8 @@ 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://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/serial/tools/miniterm.py -.. _setup-miniterm-py2exe.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/setup-miniterm-py2exe.py +.. _miniterm.py: https://github.com/pyserial/pyserial/blob/master/serial/tools/miniterm.py +.. _setup-miniterm-py2exe.py: https://github.com/pyserial/pyserial/blob/master/examples/setup-miniterm-py2exe.py TCP/IP - serial bridge @@ -177,7 +177,7 @@ below gives the client much more control over the remote serial port. tcp_serial_redirect.py_ Main program. -.. _tcp_serial_redirect.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/tcp_serial_redirect.py +.. _tcp_serial_redirect.py: https://github.com/pyserial/pyserial/blob/master/examples/tcp_serial_redirect.py Single-port TCP/IP - serial bridge (RFC 2217) @@ -218,8 +218,8 @@ 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://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/rfc2217_server.py -.. _setup-rfc2217_server-py2exe.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/setup-rfc2217_server-py2exe.py +.. _rfc2217_server.py: https://github.com/pyserial/pyserial/blob/master/examples/rfc2217_server.py +.. _setup-rfc2217_server-py2exe.py: https://github.com/pyserial/pyserial/blob/master/examples/setup-rfc2217_server-py2exe.py Multi-port TCP/IP - serial bridge (RFC 2217) @@ -267,8 +267,8 @@ port_publisher.py_ port_publisher.sh_ Example init.d script. -.. _port_publisher.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/port_publisher.py -.. _port_publisher.sh: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/port_publisher.sh +.. _port_publisher.py: https://github.com/pyserial/pyserial/blob/master/examples/port_publisher.py +.. _port_publisher.sh: https://github.com/pyserial/pyserial/blob/master/examples/http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/port_publisher.sh wxPython examples @@ -292,23 +292,13 @@ wxSerialConfigDialog.wxg_ setup-wxTerminal-py2exe.py_ A py2exe setup script to package the terminal application. -.. _wxTerminal.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/wxTerminal.py -.. _wxTerminal.wxg: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/wxTerminal.wxg -.. _wxSerialConfigDialog.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/wxSerialConfigDialog.py -.. _wxSerialConfigDialog.wxg: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/wxSerialConfigDialog.wxg -.. _setup-wxTerminal-py2exe.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/setup-wxTerminal-py2exe.py +.. _wxTerminal.py: https://github.com/pyserial/pyserial/blob/master/examples/wxTerminal.py +.. _wxTerminal.wxg: https://github.com/pyserial/pyserial/blob/master/examples/wxTerminal.wxg +.. _wxSerialConfigDialog.py: https://github.com/pyserial/pyserial/blob/master/examples/wxSerialConfigDialog.py +.. _wxSerialConfigDialog.wxg: https://github.com/pyserial/pyserial/blob/master/examples/wxSerialConfigDialog.wxg +.. _setup-wxTerminal-py2exe.py: https://github.com/pyserial/pyserial/blob/master/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://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/examples/enhancedserial.py - Unit tests ========== @@ -342,10 +332,10 @@ test_iolib.py_ test_url.py_ Tests involving the :ref:`URL <URLs>` feature. -.. _run_all_tests.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/test/run_all_tests.py -.. _test.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/test/test.py -.. _test_advanced.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/test/test_advanced.py -.. _test_high_load.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/test/test_high_load.py -.. _test_readline.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/test/test_readline.py -.. _test_iolib.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/test/test_iolib.py -.. _test_url.py: http://sourceforge.net/p/pyserial/code/HEAD/tree/trunk/pyserial/test/test_url.py +.. _run_all_tests.py: https://github.com/pyserial/pyserial/blob/master/test/run_all_tests.py +.. _test.py: https://github.com/pyserial/pyserial/blob/master/test/test.py +.. _test_advanced.py: https://github.com/pyserial/pyserial/blob/master/test/test_advanced.py +.. _test_high_load.py: https://github.com/pyserial/pyserial/blob/master/test/test_high_load.py +.. _test_readline.py: https://github.com/pyserial/pyserial/blob/master/test/test_readline.py +.. _test_iolib.py: https://github.com/pyserial/pyserial/blob/master/test/test_iolib.py +.. _test_url.py: https://github.com/pyserial/pyserial/blob/master/test/test_url.py diff --git a/documentation/index.rst b/documentation/index.rst index 9226aee..9a258fe 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -10,13 +10,11 @@ automatically selects the appropriate backend. Other pages (online) -- `project page on SourceForge`_ -- `SVN repository`_ +- `project page on GitHub`_ - `Download Page`_ with releases -- This page, when viewed online, is at http://pyserial.sf.net. +- This page, when viewed online, is at http://pythonhosted.org/pyserial/ . -.. _`project page on SourceForge`: http://sourceforge.net/projects/pyserial/ -.. _`SVN repository`: http://svn.code.sf.net/p/pyserial/code/trunk +.. _`project page on GitHub`: https://github.com/pyserial/ .. _`Download Page`: http://pypi.python.org/pypi/pyserial @@ -29,7 +27,6 @@ Contents: shortintro examples pyserial_api - pyparallel appendix Indices and tables diff --git a/documentation/pyparallel.rst b/documentation/pyparallel.rst deleted file mode 100644 index 00c0b95..0000000 --- a/documentation/pyparallel.rst +++ /dev/null @@ -1,165 +0,0 @@ -============ - pyParallel -============ - -.. note:: This module is in development (since years ;-) - -Overview -======== -This module encapsulates the access for the parallel port. It provides backends -for Python running on Windows and Linux. Other platforms are possible too but -not yet integrated. - -This module is still under development. But it may be useful for developers. - -Copyright (C) 2001-2003 Chris Liechti <cliechti(at)gmx.net> - -Here is the `project page on SourceForge`_ and here is the `SVN repository`_. - -.. _`project page on SourceForge`: http://sourceforge.net/projects/pyserial/ -.. _`SVN repository`: http://sourceforge.net/svn/?group_id=46487 - - -Features --------- -* same class based interface on all supported platforms -* port numbering starts at zero, no need to know the port name in the user program -* port string (device name) can be specified if access through numbering is inappropriate - - -Requirements ------------- -* Python 2.2 or newer -* "Java Communications" (JavaComm) extension for Java/Jython - - -Installation ------------- -Extract files from the archive, open a shell/console in that directory and let -Distutils do the rest: ``python setup.py install`` - -The files get installed in the "Lib/site-packages" directory in newer Python versions. - -The windows version needs a compiled extension and the giveio.sys driver for -Windows NT/2k/XP. The extension module can be compiled with Distutils with -either MSVC or GCC/mingw32. - -It is released under a free software license, see LICENSE.txt for more details. - - -Short introduction -================== -:: - - >>> import parallel - >>> p = parallel.Parallel() # open LPT1 - >>> p.setData(0x55) - - -Examples --------- -Please look in the SVN Repository. There is an example directory where you can -find a simple terminal and more. -http://pyserial.svn.sourceforge.net/viewvc/pyserial/trunk/pyparallel/examples/ - - -API -=== - -.. module:: parallel - -.. class:: Parallel - - .. method:: __init__(port) - - Open given parallel port. - - .. method:: setData(value) - - Apply the given byte to the data pins of the parallel port. - - .. method:: setDataStrobe(level) - - Set the "data strobe" line to the given state. - - .. method:: setAutoFeed(level) - - Set "auto feed" line to given state. - - .. method:: setInitOut(level) - - Set "initialize" line to given state. - - .. method: setSelect(level) - - Set "select" line to given state. - - .. method:getInError() - - Set "Error" line to given state. - - .. method:: getInSelected() - - Read level of "select" line. - - .. method:: getInPaperOut() - - Read level of "paper out" line. - - .. method:: getInAcknowledge() - - Read level of "Acknowledge" line. - - .. method: getInBusy() - - Read level of "busy" line. - - -.. module:: parallel.parallelutil - -.. class:: BitaccessMeta - - This mix-in class adds a few properties that allow easier bit access to the - data lines. (D0 .. D7) e.g. p.D0 refers to the first bit of the data - lines. - -.. class:: VirtualParallelPort - - This class provides a virtual parallel port implementation, useful - for tests and simulations without real hardware. - - -Notes -===== - -Linux ------ -1. The :manpage:`lp(4)` module must be unloaded, ``rmmod lp``. ``lp`` claims - exclusive access to the port and other programs won't be able to use it. - -2. The :manpage:`ppdev(4)` module needs to be loaded, ``modprobe ppdev``. When - ``udev`` is in use, (default with 2.6 kernels) this will create a - ``/dev/parport0``. - -3. The user needs to have write permissions to ``/dev/parport0``. Many - distributions have an ``lp`` group that owns the device; the simplest is to - add the user account to this group. Simply changing permissions on the - device is not the best strategy as they will be reverted to their defaults - next time the driver is loaded. - - -Windows -------- -The giveio driver must be installed as the module needs direct access to the -hardware. This also means that USB parallel port adapters won't be supported. - - -Misc -==== -References ----------- -* Python: http://www.python.org/ -* Jython: http://www.jython.org/ -* Java@IBM: http://www-106.ibm.com/developerworks/java/jdk/ (JavaComm links are - on the download page for the respective platform JDK) -* Java@SUN: http://java.sun.com/products/ diff --git a/documentation/pyserial.rst b/documentation/pyserial.rst index bedef79..7e925d1 100644 --- a/documentation/pyserial.rst +++ b/documentation/pyserial.rst @@ -12,18 +12,16 @@ automatically selects the appropriate backend. It is released under a free software license, see LICENSE_ for more details. -Copyright (C) 2001-2013 Chris Liechti <cliechti(at)gmx.net> +Copyright (C) 2001-2015 Chris Liechti <cliechti(at)gmx.net> Other pages (online) -- `project page on SourceForge`_ -- `SVN repository`_ +- `project page on GitHub`_ - `Download Page`_ with releases (PyPi) -- This page, when viewed online is at http://pyserial.sf.net. +- This page, when viewed online is at http://pythonhosted.org/pyserial/ . .. _LICENSE: appendix.html#license -.. _`project page on SourceForge`: http://sourceforge.net/projects/pyserial/ -.. _`SVN repository`: http://svn.code.sf.net/p/pyserial/code/trunk +.. _`project page on GitHub`: https://github.com/pyserial/pyserial/ .. _`Download Page`: http://pypi.python.org/pypi/pyserial @@ -39,14 +37,13 @@ Features - 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+) +- Compatible with :mod:`io` library - RFC 2217 client (experimental), server provided in the examples. Requirements ============ -- Python 2.3 or newer, including Python 3.x -- ctypes extension on Windows (is in standard library since Python 2.5+) +- Python 2.7 or newer, including Python 3.4 and newer - "Java Communications" (JavaComm) or compatible extension for Java/Jython @@ -118,5 +115,5 @@ MacOSX and Jython. On windows releases older than 2.5 will depend on pywin32_ (previously known as win32all) -.. _download: http://sourceforge.net/projects/pyserial/files/pyserial/ +.. _download: https://pypi.python.org/pypi/pyserial .. _pywin32: http://pypi.python.org/pypi/pywin32 diff --git a/documentation/shortintro.rst b/documentation/shortintro.rst index 2d9dd1b..6b0d81f 100644 --- a/documentation/shortintro.rst +++ b/documentation/shortintro.rst @@ -9,8 +9,8 @@ Open port 0 at "9600,8,N,1", no timeout:: >>> import serial >>> ser = serial.Serial(0) # open first serial port - >>> print ser.name # check which port was really used - >>> ser.write("hello") # write a string + >>> print(ser.name) # check which port was really used + >>> ser.write(b"hello") # write a string >>> ser.close() # close port Open named port at "19200,8,N,1", 1s timeout:: @@ -75,7 +75,7 @@ mode, it is advised to use io.TextIOWrapper_:: sio.write(unicode("hello\n")) sio.flush() # it is buffering. required to get the data out *now* hello = sio.readline() - print hello == unicode("hello\n") + print(hello == unicode("hello\n")) .. _io.TextIOWrapper: http://docs.python.org/library/io.html#io.TextIOWrapper @@ -100,5 +100,5 @@ include entries that matched. Accessing ports --------------- pySerial includes a small console based terminal program called -:ref:`miniterm`. It ca be started with ``python -m serial.tools.miniterm <port name>`` +:ref:`miniterm`. It ca be started with ``python -m serial.tools.miniterm <port_name>`` (use option ``-h`` to get a listing of all options). |