update docs with information about RFC2217 implementation

git-svn-id: http://svn.code.sf.net/p/pyserial/code/trunk/pyserial@271 f19166aa-fa4f-0410-85c2-fa1106f25c8a

2 files changed, 59 insertions, 11 deletions

diff --git a/documentation/pyserial.rst b/documentation/pyserial.rst
index 24296c4..4e936d1 100644
--- a/documentation/pyserial.rst
+++ b/documentation/pyserial.rst
@@ -29,24 +29,25 @@ Other pages (online)
 
 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
+- 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
+- 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+)
+- Compatible with :mod:`io` library (Python 2.6+)
+- RFC2217 client (experimental)
 
 
 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
+- 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
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index 9833254..c78bd2f 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -461,6 +461,53 @@ Classes
         Returns self.
 
 
+.. class:: rfc2217.Serial
+
+    This implements a :rfc:`2217` compatible client. Port names are URLs in the
+    form: ``rfc2217://<host>:<port>``
+
+    .. warning:: This implementation is currently in an experimental state. Use
+        at your own risk.
+
+    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)
+    - The telnet option negotiation may be done incorrectly.
+
+
+.. seealso::
+
+   :rfc:`2217` - Telnet Com Port Control Option
+
+
 
 Exceptions
 ==========