If you're looking for pyParallel, click here.

pySerial

Overview

This module encapsulates the access for the serial port. It provides backends for Python running on Windows, Linux, BSD (possibly any POSIX compilant system) and Jython. 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-2003 Chris Liechti cliechti@gmx.net

The project page on SourceForge and here is the CVS repository and the Download Page.
The homepage is on http://pyserial.sf.net

Features

Requirements

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.

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

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.

Do also have a look at the example files in the examples directory in the source distribution or online in CVS repository .

Examples

Please look in the CVS Repository. There is an example directory where you can find a simple terminal and more.
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/pyserial/pyserial/examples/

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 for waiting forever
    xonxoff=0,              #enable software flow control
    rtscts=0,               #enable RTS/CTS flow control
)

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)

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

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 Xon/Xoff flow control is enabled
rtscts                  #if hardware flow control is enabled

Exceptions

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

References

Older Versions

Older versions are still available on the Download Page. pySerial 1.21 is compatible with Python 2.0 on Windows, Linux and several un*x like systems, MacOSX and Jython.



This page is hosted on:
SourceForge Logo