documentation updates
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 @@
~~~~~~~~~~~~~~~~~
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 @@
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 @@
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 @@
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 @@
.. 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 @@
.. 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 @@
.. 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 @@
>>> 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 @@
>>> 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.