- add iterator interface

- readme extended, partialy converted to reStructuredText


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

1 files changed, 143 insertions, 112 deletions

diff --git a/README.txt b/README.txt
index 522c1d5..97e0b12 100644
--- a/README.txt
+++ b/README.txt
@@ -1,5 +1,5 @@
 pySerial
---------
+========
 This module capsulates the access for the serial port. It provides backends
 for standard Python running on Windows, Linux, BSD (possibly any POSIX
 compilant system) and Jython. The module named "serial" automaticaly selects
@@ -8,8 +8,8 @@ the appropriate backend.
 It is released under a free software license, see LICENSE.txt for more
 details.
 
-Project Homepage: pyserial.sourceforge.net
-(C) 2001-2004 Chris Liechti <cliechti@gmx.net>
+Project Homepage: http://pyserial.sourceforge.net
+(C) 2001-2005 Chris Liechti <cliechti@gmx.net>
 
 
 Features
@@ -52,6 +52,7 @@ to get the source archive anyway, because it contains examples and the readme.
 Do also have a look at the example files in the examples directory in the
 source distribution or online in CVS repository.
 
+
 Serial to USB adapters
 ----------------------
 Such adapters are reported to work under Mac OSX and Windows. They are
@@ -75,39 +76,43 @@ adapter.
 
 Short introduction
 ------------------
-Open port 0 at "9600,8,N,1", no timeout
->>> import serial
->>> ser = serial.Serial(0)  #open first serial port
->>> print ser.portstr       #check which port was realy used
->>> ser.write("hello")      #write a string
->>> ser.close()             #close port
-
-Open named port at "19200,8,N,1", 1s timeout
->>> ser = serial.Serial('/dev/ttyS1', 19200, timeout=1)
->>> x = ser.read()          #read one byte
->>> s = ser.read(10)        #read up to ten bytes (timeout)
->>> line = ser.readline()   #read a '\n' terminated line
->>> ser.close()
-
-Open second port at "38400,8,E,1", non blocking HW handshaking
->>> ser = serial.Serial(1, 38400, timeout=0,
-...                     parity=serial.PARITY_EVEN, rtscts=1)
->>> s = ser.read(100)       #read up to one hunded bytes
-...                         #or as much is in the buffer
-
-Get a Serial instance and configure/open it later
->>> ser = serial.Serial()
->>> ser.baudrate = 19200
->>> ser.port = 0
->>> ser
-Serial<id=0xa81c10, open=False>(port='COM1', baudrate=19200, bytesize=8,
-parity='N', stopbits=1, timeout=None, xonxoff=0, rtscts=0)
->>> ser.open()
->>> ser.isOpen()
-True
->>> ser.close()
->>> ser.isOpen()
-False
+Open port 0 at "9600,8,N,1", no timeout::
+
+    >>> import serial
+    >>> ser = serial.Serial(0)  #open first serial port
+    >>> print ser.portstr       #check which port was realy used
+    >>> ser.write("hello")      #write a string
+    >>> ser.close()             #close port
+
+Open named port at "19200,8,N,1", 1s timeout::
+
+    >>> ser = serial.Serial('/dev/ttyS1', 19200, timeout=1)
+    >>> x = ser.read()          #read one byte
+    >>> s = ser.read(10)        #read up to ten bytes (timeout)
+    >>> line = ser.readline()   #read a '\n' terminated line
+    >>> ser.close()
+
+Open second port at "38400,8,E,1", non blocking HW handshaking::
+
+    >>> ser = serial.Serial(1, 38400, timeout=0,
+    ...                     parity=serial.PARITY_EVEN, rtscts=1)
+    >>> s = ser.read(100)       #read up to one hunded bytes
+    ...                         #or as much is in the buffer
+
+Get a Serial instance and configure/open it later::
+
+    >>> ser = serial.Serial()
+    >>> ser.baudrate = 19200
+    >>> ser.port = 0
+    >>> ser
+    Serial<id=0xa81c10, open=False>(port='COM1', baudrate=19200, bytesize=8,
+    parity='N', stopbits=1, timeout=None, xonxoff=0, rtscts=0)
+    >>> ser.open()
+    >>> ser.isOpen()
+    True
+    >>> ser.close()
+    >>> ser.isOpen()
+    False
 
 Be carefully when using "readline". Do specify a timeout when
 opening the serial port otherwise it could block forever if
@@ -117,102 +122,127 @@ and interprets that as EOF (end of file). It raises an exception
 if the port is not opened correctly.
 
 
-Parameters for the Serial class
--------------------------------
-ser = serial.Serial(
-    port=None,              #number of device, numbering starts at
-                            #zero. if everything fails, the user
-                            #can specify a device string, note
-                            #that this isn't portable anymore
-                            #if no port is specified an unconfigured
-                            #an closed serial port object is created
-    baudrate=9600,          #baudrate
-    bytesize=EIGHTBITS,     #number of databits
-    parity=PARITY_NONE,     #enable parity checking
-    stopbits=STOPBITS_ONE,  #number of stopbits
-    timeout=None,           #set a timeout value, None to wait forever
-    xonxoff=0,              #enable software flow control
-    rtscts=0,               #enable RTS/CTS flow control
-    writeTimeout=None,      #set a timeout for writes
-)
+Parameters for the Serial class::
+
+    ser = serial.Serial(
+        port=None,              #number of device, numbering starts at
+                                #zero. if everything fails, the user
+                                #can specify a device string, note
+                                #that this isn't portable anymore
+                                #if no port is specified an unconfigured
+                                #an closed serial port object is created
+        baudrate=9600,          #baudrate
+        bytesize=EIGHTBITS,     #number of databits
+        parity=PARITY_NONE,     #enable parity checking
+        stopbits=STOPBITS_ONE,  #number of stopbits
+        timeout=None,           #set a timeout value, None to wait forever
+        xonxoff=0,              #enable software flow control
+        rtscts=0,               #enable RTS/CTS flow control
+        writeTimeout=None,      #set a timeout for writes
+    )
 
 The port is immediately opened on object creation, if a port is given.
 It is not opened if port is None.
 
-Options for read timeout:
-timeout=None            #wait forever
-timeout=0               #non-blocking mode (return immediately on read)
-timeout=x               #set timeout to x seconds (float allowed)
-
-Options for write timeout:
-writeTimeout=x          #will rise a SerialTimeoutException if the data
-                        #cannot be sent in x seconds
-
-Methods of Serial instances
----------------------------
-open()                  #open port
-close()                 #close port immediately
-setBaudrate(baudrate)   #change baudarte on an open port
-inWaiting()             #return the number of chars in the receive buffer
-read(size=1)            #read "size" characters
-write(s)                #write the string s to the port
-flushInput()            #flush input buffer, discarding all it's contents
-flushOutput()           #flush output buffer, abort output
-sendBreak()             #send break condition
-setRTS(level=1)         #set RTS line to specified logic level
-setDTR(level=1)         #set DTR line to specified logic level
-getCTS()                #return the state of the CTS line
-getDSR()                #return the state of the DSR line
-getRI()                 #return the state of the RI line
-getCD()                 #return the state of the CD line
-
-Attributes of Serial instances
-------------------------------
-Read Only:
-portstr                 #device name
-BAUDRATES               #list of valid baudrates
-BYTESIZES               #list of valid byte sizes
-PARITIES                #list of valid parities
-STOPBITS                #list of valid stop bit widths
+Options for read timeout::
+
+    timeout=None            #wait forever
+    timeout=0               #non-blocking mode (return immediately on read)
+    timeout=x               #set timeout to x seconds (float allowed)
+
+Options for write timeout::
+
+    writeTimeout=x          #will rise a SerialTimeoutException if the data
+                            #cannot be sent in x seconds
+
+
+Methods of Serial instances::
+
+    open()                  #open port
+    close()                 #close port immediately
+    setBaudrate(baudrate)   #change baudarte on an open port
+    inWaiting()             #return the number of chars in the receive buffer
+    read(size=1)            #read "size" characters
+    write(s)                #write the string s to the port
+    flushInput()            #flush input buffer, discarding all it's contents
+    flushOutput()           #flush output buffer, abort output
+    sendBreak()             #send break condition
+    setRTS(level=1)         #set RTS line to specified logic level
+    setDTR(level=1)         #set DTR line to specified logic level
+    getCTS()                #return the state of the CTS line
+    getDSR()                #return the state of the DSR line
+    getRI()                 #return the state of the RI line
+    getCD()                 #return the state of the CD line
+
+
+Read only Attributes of Serial instances::
+
+    portstr                 #device name
+    BAUDRATES               #list of valid baudrates
+    BYTESIZES               #list of valid byte sizes
+    PARITIES                #list of valid parities
+    STOPBITS                #list of valid stop bit widths
 
 New values can be assigned to the following attribues, the port
 will be reconfigured, even if it's opened at that time (port will be 
-closed and reopened to apply the changes):
-port                    #port name/number as set by the user
-baudrate                #current baudrate setting
-bytesize                #bytesize in bits
-parity                  #parity setting
-stopbits                #stop bit with (1,2)
-timeout                 #read timeout setting
-xonxoff                 #if Xon/Xoff flow control is enabled
-rtscts                  #if hardware flow control is enabled
-writeTimeout            #write timeout setting
-
-These attribues also have corresponding getX and setXX methods.
-
-Exceptions
-----------
-serial.SerialException
+closed and reopened to apply the changes)::
+
+    port                    #port name/number as set by the user
+    baudrate                #current baudrate setting
+    bytesize                #bytesize in bits
+    parity                  #parity setting
+    stopbits                #stop bit with (1,2)
+    timeout                 #read timeout setting
+    xonxoff                 #if Xon/Xoff flow control is enabled
+    rtscts                  #if hardware flow control is enabled
+    writeTimeout            #write timeout setting
+
+These attributes also have corresponding getX and setXX methods.
+
+
+Exceptions that can be raised::
+
+    serial.SerialException
+
 
 Constants
----------
-parity:
+
+parity::
+
     serial.PARITY_NONE
     serial.PARITY_EVEN
     serial.PARITY_ODD
-stopbits:
+    
+stopbits::
+
     serial.STOPBITS_ONE
     serial.STOPBITS_TWO
-bytesize:
+    
+bytesize::
+
     serial.FIVEBITS
     serial.SIXBITS
     serial.SEVENBITS
     serial.EIGHTBITS
 
-Xon/Xoff characters:
+Xon/Xoff characters::
+
     serial.XON
     serial.XOFF
 
+Iterator interface
+~~~~~~~~~~~~~~~~~~
+It is possible to iterate over lines comming from a serial port::
+    
+    >>> ser = serial.Serial(0, timeout=10)
+    >>> for line in ser:
+    ...     print line
+
+The use is somewhat restricted tough, as many protocols on the
+wire require that commands are sent and answers are read and this
+one only reads lines.
+
+
 Tips & Tricks
 -------------
 - Some protocols need CR LF ("\r\n") as line terminator, not just LF ("\n").
@@ -226,8 +256,9 @@ Tips & Tricks
   missing modules 'javax.comm'. This warning is uncritical as the module is
   used in the Jython implementation that is not used but packaged.
   
-  It can be avoided with:
-  setup(...
+  It can be avoided with::
+  
+    setup(...
         options = {'py2exe': {'excludes': ['javax.comm']}})
   
   See also setup_demo.py in the examples.