diff options
author | cliechti <cliechti@f19166aa-fa4f-0410-85c2-fa1106f25c8a> | 2009-07-21 13:32:45 +0000 |
---|---|---|
committer | cliechti <cliechti@f19166aa-fa4f-0410-85c2-fa1106f25c8a> | 2009-07-21 13:32:45 +0000 |
commit | 86e8787c23663ce357c8311e070442be3d1297f2 (patch) | |
tree | 474a4969a25335245d113094d94989c2dbde797c | |
parent | 2297814a5de3ca85869bd19009966db9f12a8840 (diff) | |
download | pyserial-git-86e8787c23663ce357c8311e070442be3d1297f2.tar.gz |
documentation updates
-rw-r--r-- | documentation/appendix.rst | 60 | ||||
-rw-r--r-- | documentation/examples.rst | 113 | ||||
-rw-r--r-- | documentation/index.rst | 1 | ||||
-rw-r--r-- | documentation/pyserial.rst | 7 | ||||
-rw-r--r-- | documentation/pyserial_api.rst | 18 | ||||
-rw-r--r-- | documentation/shortintro.rst | 14 |
6 files changed, 168 insertions, 45 deletions
diff --git a/documentation/appendix.rst b/documentation/appendix.rst index eaea2da..a8c83e3 100644 --- a/documentation/appendix.rst +++ b/documentation/appendix.rst @@ -20,49 +20,47 @@ 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. + 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. + 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. + 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. + 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. + 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. + 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. + 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. + agrees to be bound by the terms and conditions of this License Agreement. diff --git a/documentation/examples.rst b/documentation/examples.rst new file mode 100644 index 0000000..a50b655 --- /dev/null +++ b/documentation/examples.rst @@ -0,0 +1,113 @@ +========== + Examples +========== + +Miniterm +======== +This is a console application that provides a small terminal application. +miniterm itself does not implement any terminal features such as VT102 +compatibility. However it inherits these features from the terminal it is run. +For example on GNU/Linux running from an xterm it will support the escape +sequences of the xterm. On Windows the typical console window is dumb and does +not support any escapes. When ANSI.sys is loaded it supports some escapes. + +Command line options can be given so that binary data including escapes for +terminals are escaped or output as hex. + +miniterm supports some control functions. Typing ``CTRL+T CTRL+H`` when it is +running shows the help text. + +miniterm.py_ + The miniterm program. + +setup-miniterm-py2exe.py_ + This is a py2exe setup script for Windows. It can be used to create a + standalone ``miniterm.exe``. + +.. _miniterm.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/miniterm.py +.. _setup-miniterm-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup-miniterm-py2exe.py + + +TCP/IP - serial bridge +====================== +This program opens a TCP/IP port. When a connection is made to that port (e.g. +with telnet) it forwards all data to the serial port and vice versa. + +The serial port settings are set on the command line when starting the program. +There is no possibility to change settings from remote. + +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 + + +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_demo.py_ + A py2exe setup script to package the terminal application. + +.. _wxTerminal.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxTerminal.py +.. _wxTerminal.wxg: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxTerminal.wxg +.. _wxSerialConfigDialog.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxSerialConfigDialog.py +.. _wxSerialConfigDialog.wxg: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxSerialConfigDialog.wxg +.. _setup_demo.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup_demo.py + + +Wrapper class +============= +This example provides a subclass based on ``Serial`` that has an alternative +implementation of ``readline()`` + +enhancedserial.py_ + A class with alternative ``readline()`` implementation. + +.. _enhancedserial.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/enhancedserial.py + + +Finding serial ports +==================== +scan.py_ + A simple loop that probes serial ports by number. + +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 +.. _scanwin32.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanwin32.py + + +Unit tests +========== +The project uses a number of unit test to verify the functionality. They all +need a loop back connector. The scripts itself contain more information. + +test.py_ + Basic tests. + +test_high_load.py_ + Tests involving sending a lot of data. + +test_advanced.py_ + Test more advanced features. + +.. _test.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test.py +.. _test_high_load.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test_high_load.py +.. _test_advanced.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test_advanced.py diff --git a/documentation/index.rst b/documentation/index.rst index 9c600e2..8019123 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -13,6 +13,7 @@ Contents: pyserial shortintro + examples pyserial_api pyparallel appendix diff --git a/documentation/pyserial.rst b/documentation/pyserial.rst index 258ef51..fcc3fd0 100644 --- a/documentation/pyserial.rst +++ b/documentation/pyserial.rst @@ -93,10 +93,11 @@ Windows References ========== -* Python: http://www.python.org/|http://www.python.org +* Python: http://www.python.org/ * pywin32: http://sourceforge.net/projects/pywin32/ (previously known as win32all) -* 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) +* 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 diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst index 7c5ea1d..fa67b89 100644 --- a/documentation/pyserial_api.rst +++ b/documentation/pyserial_api.rst @@ -35,25 +35,22 @@ Classes 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`:: + 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) + timeout = None # wait forever + timeout = 0 # non-blocking mode (return immediately on read) + timeout = x # set timeout to x seconds (float allowed) .. method:: open() @@ -80,7 +77,7 @@ Classes .. method:: write(s) - Write the string :param:`s` to the port. + Write the string `s` to the port. .. method:: flush(self): @@ -134,7 +131,7 @@ Classes .. attribute:: portstr Device name (Read Only). This is always the device name even if the - port was opened by a numeber. + port was opened by a number. .. attribute:: BAUDRATES @@ -196,18 +193,21 @@ Classes .. 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. diff --git a/documentation/shortintro.rst b/documentation/shortintro.rst index 5e117ca..048f94d 100644 --- a/documentation/shortintro.rst +++ b/documentation/shortintro.rst @@ -2,6 +2,9 @@ Short introduction ==================== +Opening serial ports +==================== + Open port 0 at "9600,8,N,1", no timeout:: >>> import serial @@ -25,6 +28,9 @@ Open second port at "38400,8,E,1", non blocking HW handshaking:: >>> 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() @@ -39,9 +45,13 @@ Get a Serial instance and configure/open it later:: >>> 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. +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. |