Transition to the 2.0 series:

- New implementation only supports Python 2.2+, backwards compatibility
  should be maintained almost everywhere.
  The OS handles (like the hComPort or fd attribute) were prefixed with an
  underscore. The different names stay, as anyone that uses one of these
  has to write platform specific code anyway.
- Common base class serialutil.SerialBase for all implementations.
- PARITY_NONE, PARITY_EVEN, PARITY_ODD constants changed and all these
  constants moved to serialutil.py (still available as serial.PARITY_NONE
  etc. and they should be used that way)
- Added serial.PARITY_NAMES (implemented in serialutil.PARITY_NAMES).
  This dictionary can be used to convert parity constants to meaningful
  strings.
- Each Serial class and instance has a list of supported values:
    BAUDRATES, BYTESIZES, PARITIES, STOPBITS
  (i.e. serial.Serial.BAUDRATES or s = serial.Serial; s.BAUDRATES)
  these values can be used to fill in value sin GUI dialogs etc.
- Creating a Serial() object without port spec returns an unconfigured,
  closed port. Useful if a GUI dialog should take a port and configure
  it.
- New methods for serial.Serial instances: open(), isOpen()
- A port can be opened and closed as many times as desired.
- Instances of serial.Serial have baudrate, bytesize, timeout etc.
  attributes implemented as properties, all can be set while the port is
  opened. It will then be reconfigured.
- Improved __doc__'s.
- New test_advanced.py for the property setting/getting testing.
- Small bugfix on posix with get* methods (return value should be true a
  boolean).
- added a __repr__ that returns a meaningful string will all the serial
  setting, easy for debugging.
- The serialposix module does not throw an exception on unsupported
  platforms, the message is still printed. The idea that it may still
  work even if the platform itself s not known, it simply tries to do
  the posix stuff anyway (It's likely that opening ports by number
  fails, but by name it should work).


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

1 files changed, 48 insertions, 11 deletions

diff --git a/README.txt b/README.txt
index 88aef37..8a582f8 100644
--- a/README.txt
+++ b/README.txt
@@ -33,7 +33,7 @@ Features
 
 Requirements
 ------------
-- Python 2.0 or newer (1.5.2 untested)
+- Python 2.2 or newer
 - win32all extensions on Windows
 - "Java Communications" (JavaComm) extension for Java/Jython
 
@@ -43,8 +43,7 @@ Installation
 Extract files from the archive, open a shell/console in that directory and
 let Distutils do the rest: "python setup.py install"
 
-The files get installed in the "Lib/site-packages" directory in newer
-Python versions.
+The files get installed in the "Lib/site-packages" directory.
 
 Serial to USB adapters
 ----------------------
@@ -80,7 +79,7 @@ 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
+>>> line = ser.readline()   #read a '\n' terminated line
 >>> ser.close()
 
 Open second port at "38400,8,E,1", non blocking HW handshaking
@@ -89,6 +88,20 @@ Open second port at "38400,8,E,1", non blocking HW handshaking
 >>> 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
 no newline character is received. Also note that "readlines" only
@@ -100,10 +113,12 @@ if the port is not opened correctly.
 Parameters for the Serial class
 -------------------------------
 ser = serial.Serial(
-    port,                   #number of device, numbering starts at
+    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
@@ -119,15 +134,16 @@ timeout=None            #wait forever
 timeout=0               #non-blocking mode (return immediately on read)
 timeout=x               #set timeout to x seconds (float allowed)
 
-Serial object Methods
----------------------
+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 to the port
-flushInput()            #flush input buffer
-flushOutput()           #flush output buffer
+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
@@ -136,6 +152,27 @@ 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
+
+New values can be assigned to the following attribues, the port
+will be reconfigured, even if it's opened at that time:
+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                 #timeout setting
+xonxoff                 #if XonXoff flow control is enabled
+rtscts                  #if hardware flow control is enabled
+
+
 Constants
 ---------
 parity:
@@ -154,7 +191,7 @@ bytesize:
 Tips & Tricks
 -------------
 - Some protocols need CR LF ("\r\n") as line terminator, not just LF ("\n").
-  Modems are an example of this behaviour.
+  Telephone modems with the AT command set are an example of this behaviour.
 
 - Scanning for available serial ports is possible with more or less sucess on
   some platforms. Look at the tools from Roger Binns: