- more documentation updates
- added logo
diff --git a/documentation/appendix.rst b/documentation/appendix.rst
index a8c83e3..3a4a766 100644
--- a/documentation/appendix.rst
+++ b/documentation/appendix.rst
@@ -5,19 +5,17 @@
License
=======
-Copyright (c) 2001-2008 Chris Liechti <cliechti@gmx.net>;
+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.
+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
--------------------------------------------------------------------
+**TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING THIS SOFTWARE**
-LICENSE AGREEMENT
-~~~~~~~~~~~~~~~~~
+*LICENSE AGREEMENT*
1. This LICENSE AGREEMENT is between the copyright holder of this
product, and the Individual or Organization ("Licensee") accessing and
diff --git a/documentation/conf.py b/documentation/conf.py
index 4ff412c..8f5943a 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -110,7 +110,7 @@
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
-#html_logo = None
+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
@@ -178,7 +178,7 @@
# The name of an image file (relative to this directory) to place at the top of
# the title page.
-#latex_logo = None
+latex_logo = 'pyserial.png'
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
diff --git a/documentation/examples.rst b/documentation/examples.rst
index a50b655..33450ea 100644
--- a/documentation/examples.rst
+++ b/documentation/examples.rst
@@ -11,11 +11,73 @@
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 some control functions. Typing ``CTRL+T CTRL+H`` when it is
-running shows the help text.
+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
+
miniterm.py_
The miniterm program.
@@ -35,6 +97,53 @@
The serial port settings are set on the command line when starting the program.
There is no possibility to change settings from remote.
+::
+
+ 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
+
+ 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.
diff --git a/documentation/index.rst b/documentation/index.rst
index 8019123..96a78b5 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -1,10 +1,12 @@
-.. pySerial documentation master file, created by
- sphinx-quickstart on Tue Jul 21 00:27:45 2009.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
+.. pySerial documentation master file
-Welcome to pySerial's documentation!
-====================================
+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.
Contents:
diff --git a/documentation/pyparallel.rst b/documentation/pyparallel.rst
index 36611a9..b7bab7d 100644
--- a/documentation/pyparallel.rst
+++ b/documentation/pyparallel.rst
@@ -12,7 +12,7 @@
This module is still under development. But it may be useful for developers.
- (C) 2001-2003 Chris Liechti <cliechti@gmx.net>
+Copyright (C) 2001-2003 Chris Liechti <cliechti(at)gmx.net>
Here is the `project page on SourceForge`_ and here is the `SVN repository`_.
@@ -26,11 +26,13 @@
* 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
@@ -39,7 +41,7 @@
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
+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.
@@ -53,12 +55,14 @@
>>> 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
===
@@ -110,6 +114,7 @@
Read level of "busy" line.
+
.. module:: parallel.parallelutil
.. class:: BitaccessMeta
@@ -128,7 +133,8 @@
====
References
----------
-* Python: http://www.python.org/|http://www.python.org
-* Jython: http://www.jython.org/|http://www.jython.org
-* Java@IBM http://www-106.ibm.com/developerworks/java/jdk/ (JavaComm links are on the download page for the respective platform jdk)
-* Java@SUN http://java.sun.com/products/
+* 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
new file mode 100644
index 0000000..7fd45f4
--- /dev/null
+++ b/documentation/pyserial.png
Binary files differ
diff --git a/documentation/pyserial.rst b/documentation/pyserial.rst
index fcc3fd0..c7c7b3d 100644
--- a/documentation/pyserial.rst
+++ b/documentation/pyserial.rst
@@ -9,16 +9,17 @@
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.txt_ for more
+It is released under a free software license, see LICENSE_ for more
details.
- (C) 2001-2009 Chris Liechti <cliechti@gmx.net>
+Copyright (C) 2001-2009 Chris Liechti <cliechti(at)gmx.net>
-The `project page on SourceForge`_ and here is the `SVN repository`_ and the `Download Page`_.
+The `project page on SourceForge`_ and here is the `SVN repository`_ and the
+`Download Page`_.
The homepage is at http://pyserial.sf.net.
-.. _LICENSE.txt: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/LICENSE.txt
+.. _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
@@ -26,19 +27,19 @@
Features
========
-* same class based interface on all supported platforms
-* access to the port settings through Python 2.2+ properties
-* 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
-* support for different bytesizes, stopbits, 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)
+* Same class based interface on all supported platforms.
+* Access to the port settings through Python 2.2+ properties.
+* 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.
+* Support for different bytesizes, stopbits, 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. They depend on non standard
but common packages on Windows (pywin32) and Jython (JavaComm). POSIX (Linux,
- BSD) uses only modules from the standard Python distribution)
+ BSD) uses only modules from the standard Python distribution).
* 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.
@@ -50,14 +51,15 @@
* pywin32 extensions on Windows
* "Java Communications" (JavaComm) or compatible extension for Java/Jython
+
Installation
============
pyserial
--------
-This installs a package that can be used from python (``import serial``).
+This installs a package that can be used from Python (``import serial``).
-The Python pywin32 library needs to be installed on windows.
+The Python pywin32 library needs to be installed on Windows.
To install the module for all users on the system, administrator rights (root)
is required..
@@ -71,7 +73,7 @@
Setuptools/PyPI
~~~~~~~~~~~~~~~
-Alternatively it can be installed from PyPy, either manually downloading the
+Alternatively it can be installed from PyPI, either manually downloading the
files and installing as described above or using::
easy_install -U pyserial
@@ -81,7 +83,7 @@
There are also packaged versions for some Linux distributions and Windows:
Debian/Ubuntu
- A package is availabe under the name "python-serial"
+ A package is available under the name "python-serial".
Windows
There is also a Windows installer for end users. It is located in the
@@ -96,9 +98,9 @@
* Python: http://www.python.org/
* pywin32: http://sourceforge.net/projects/pywin32/ (previously known as win32all)
* 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/
+* 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 fa67b89..82024f1 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -12,13 +12,8 @@
.. method:: __init__(port=None, baudrate=9600, bytesize=EIGHTBITS, parity=PARITY_NONE, stopbits=STOPBITS_ONE, timeout=None, xonxoff=0, rtscts=0, interCharTimeout=None)
:param port:
-
Device name or port number number or None.
- Number: number of device, numbering starts at zero
- Device name: depending on operating system. e.g. ``/dev/ttyUSB0``
- on GNU/Linux or ``COM3`` on Windows.
-
:param baudrate:
Baud rate such as 9600 or 115200 etc.
@@ -43,14 +38,18 @@
: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.
+ The port is immediately opened on object creation, when a ``port`` is
+ given. It is not opened when port is None.
- Possible values for the parameter ``timeout``::
+ - 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.
- timeout = None # wait forever
- timeout = 0 # non-blocking mode (return immediately on read)
- timeout = x # set timeout to x seconds (float allowed)
+ 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)
.. method:: open()
@@ -79,7 +78,7 @@
Write the string `s` to the port.
- .. method:: flush(self):
+ .. method:: flush():
Flush of file like objects. In this case, wait until all data is
written.
@@ -130,8 +129,8 @@
.. attribute:: portstr
- Device name (Read Only). This is always the device name even if the
- port was opened by a number.
+ Device name. This is always the device name even if the
+ port was opened by a number. (Read Only).
.. attribute:: BAUDRATES
@@ -176,7 +175,7 @@
.. attribute:: timeout
- Timeout setting (seconds).
+ Timeout setting (seconds, float).
.. attribute:: xonxoff
@@ -226,7 +225,7 @@
Constants
=========
-parity
+Parity
------
.. data:: PARITY_NONE
.. data:: PARITY_EVEN
@@ -234,13 +233,13 @@
.. data:: PARITY_MARK
.. data:: PARITY_SPACE
-stopbits
+Stopbits
--------
.. data:: STOPBITS_ONE
.. data:: STOPBITS_ONE_POINT_FIVE
.. data:: STOPBITS_TWO
-bytesize
+Bytesize
--------
.. data:: FIVEBITS
.. data:: SIXBITS
