diff options
Diffstat (limited to 'pyserial/README.txt')
-rw-r--r-- | pyserial/README.txt | 277 |
1 files changed, 0 insertions, 277 deletions
diff --git a/pyserial/README.txt b/pyserial/README.txt deleted file mode 100644 index 60793a4..0000000 --- a/pyserial/README.txt +++ /dev/null @@ -1,277 +0,0 @@ -======== -pySerial -======== -This module encapsulates the access for the serial port. It provides backends -for standard Python running on Windows, Linux, BSD (possibly any POSIX -compliant system), Jython and IronPython. The module named "serial" -automatically selects the appropriate backend. - -It is released under a free software license, see LICENSE.txt for more -details. - -Project Homepage: http://pyserial.sourceforge.net -(C) 2001-2008 Chris Liechti <cliechti@gmx.net> - - -Features --------- -- same class based interface on all supported platforms -- access to the port settings trough Python 2.2 properties -- port numbering starts at zero, no need to know the platform dependant port - name in the user program -- port name can be specified if access through numbering is inappropriate -- support for different byte sizes, stopbits, parity and flow control - with RTS/CTS and/or Xon/Xoff -- working with or without receive timeout, blocking or non-blocking -- 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 (win32all) and - Jython (JavaComm). POSIX (Linux, 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. - - -Requirements ------------- -- Python 2.2 or newer -- win32all extensions on Windows -- "Java Communications" (JavaComm) extension for Java/Jython - - -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. - -There is also a Windows installer, but for developers it may be interesting -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 -mapped to a normal COM port under Windows, but on Mac OSX and other platforms -they have special device names. - -Mac OSX: "/dev/[cu|tty].USA<adaptername><USB-part>P<serial-port>.1" - e.g. "/dev/cu.USA19QW11P1.1" - -Linux: "/dev/usb/ttyUSB[n]" or "/dev/ttyUSB[n]" - first for for RedHat, second form for Debian. - e.g. "/dev/usb/ttyUSB0" - -Either use these names for the serial ports or create a link to the common device -names like "ln -s /dev/cu.USA19QW11P1.1 /dev/cuaa0" or "ln -s /dev/usb/ttyUSB0 -/dev/ttyS4" etc. - -But be aware that the (USB) device file disappears as soon as you unplug the USB -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 hundred 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 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. - - -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 baud rate 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 baud rates - 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 attributes, 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 baud rate setting - bytesize # byte size 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:: - - serial.PARITY_NONE - serial.PARITY_EVEN - serial.PARITY_ODD - -stopbits:: - - serial.STOPBITS_ONE - serial.STOPBITS_TWO - -bytesize:: - - serial.FIVEBITS - serial.SIXBITS - serial.SEVENBITS - serial.EIGHTBITS - -Xon/Xoff characters:: - - serial.XON - serial.XOFF - -Iterator interface -~~~~~~~~~~~~~~~~~~ -It is possible to iterate over lines coming 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"). - Telephone modems with the AT command set are an example of this behaviour. - -- Scanning for available serial ports is possible with more or less success on - some platforms. Look at the tools from Roger Binns: - http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/bitpim/comscan/ - -- When packaging a project with py2exe, it will likely print a warning about - 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(... - options = {'py2exe': {'excludes': ['javax.comm']}}) - - See also setup_demo.py in the examples. - - -References ----------- -- Python: http://www.python.org -- Jython: http://www.jython.org -- win32all: http://starship.python.net/crew/mhammond/ - and http://www.activestate.com/Products/ActivePython/win32all.html -- 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 - |