pySerial
Overview
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.
It is released under a free software license, see LICENSE.txt for more details.
(C) 2001-2008 Chris Liechti cliechti@gmx.net
The project page on SourceForge and here is the SVN repository and the Download Page .
The homepage is on http://pyserial.sf.net/
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)
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)
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
pywin32 extensions on Windows
“Java Communications” (JavaComm) or compatible extension for Java/Jython
Installation
from source
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.
easy_install
An EGG is available from the Python Package Index: http://pypi.python.org/pypi/pyserial
easy_install pyserial
windows installer
There is also a Windows installer for end users. It is located in the Download Page
Developers may be interested to get the source archive, because it contains examples and the readme.
Short introduction
Open port 0 at “9600,8,N,1”, no timeout
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
import serial
ser = serial.Serial(0) # open first serial port
print ser.portstr # check which port was really used
ser.write(“hello”) # write a string
ser.close() # close port
Open named port at “19200,8,N,1”, 1s timeout
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
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
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
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
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
ser = serial.Serial()
ser.baudrate = 19200
ser.port = 0
ser
Serial
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, # baud rate
bytesize=EIGHTBITS, # number of databits
parity=PARITY_NONE, # enable parity checking
stopbits=STOPBITS_ONE, # number of stopbits
timeout=None, # set a timeout value, None for waiting forever
xonxoff=0, # enable software flow control
rtscts=0, # enable RTS/CTS flow control
interCharTimeout=None # Inter-character timeout, None to disable
)
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:
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
timeout=None # wait forever
timeout=0 # non-blocking mode (return immediately on read)
timeout=x # set timeout to x seconds (float allowed)
Methods of Serial instances
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
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
Attributes of Serial instances
Read Only:
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
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 attributes, the port will be reconfigured, even if it’s opened at that time:
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
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 # timeout setting
xonxoff # if Xon/Xoff flow control is enabled
rtscts # if hardware flow control is enabled
Exceptions
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
serial.SerialException
Constants
parity:
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
serial.PARITY_NONE
serial.PARITY_EVEN
serial.PARITY_ODD
stopbits:
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
serial.STOPBITS_ONE
al.STOPBITS_TWO
bytesize:
.text .imp { font-weight: bold; color: red; }
[text] view plain copy
serial.FIVEBITS
serial.SIXBITS
serial.SEVENBITS
serial.EIGHTBITS