1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
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
the appropriate backend.
It is released under a free software license, see LICENSE.txt for more
details.
Project Homepage: pyserial.sourceforge.net
(C) 2001-2003 Chris Liechti <cliechti@gmx.net>
Features
--------
- same class based interface on all supported platforms
- 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 bytesizes, 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.
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 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.
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
)
The port is immediately opened on object creation.
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 XonXoff flow control is enabled
rtscts #if hardware flow control is enabled
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
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/
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/
|
