~ubuntu-branches/ubuntu/trusty/pyserial/trusty : revision 5

1

pySerial

2

--------

3

This module capsulates the access for the serial port. It provides backends

4

for standard Python running on Windows, Linux, BSD (possibly any POSIX

5

compilant system) and Jython. The module named "serial" automaticaly selects

6

the appropriate backend.

7

8

It is released under a free software license, see LICENSE.txt for more

9

details.

10

11

Project Homepage: pyserial.sourceforge.net

12

13

14

15

Features

16

--------

17

- same class based interface on all supported platforms

18

- access to the port settings trough Python 2.2 properties

19

- port numbering starts at zero, no need to know the platform dependant port

20

name in the user program

21

- port name can be specified if access through numbering is inappropriate

22

- support for different bytesizes, stopbits, parity and flow control

23

with RTS/CTS and/or Xon/Xoff

24

- working with or without receive timeout, blocking or non-blocking

25

- file like API with "read" and "write" ("readline" etc. also supported)

26

- The files in this package are 100% pure Python.

27

They depend on non standard but common packages on Windows (win32all) and

28

Jython (JavaComm). POSIX (Linux, BSD) uses only modules from the standard

29

Python distribution)

30

- The port is set up for binary transmission. No NULL byte stripping, CR-LF

31

translation etc. (which are many times enabled for POSIX.) This makes this

32

module universally useful.

33

34

35

Requirements

36

------------

37

- Python 2.2 or newer

38

- win32all extensions on Windows

39

- "Java Communications" (JavaComm) extension for Java/Jython

40

41

42

Installation

43

------------

44

Extract files from the archive, open a shell/console in that directory and

45

let Distutils do the rest: "python setup.py install"

46

47

The files get installed in the "Lib/site-packages" directory.

48

49

There is also a Windows installer, but for developers it may be interesting

50

to get the source archive anyway, because it contains examples and the readme.

51

52

Do also have a look at the example files in the examples directory in the

53

source distribution or online in CVS repository.

54

55

Serial to USB adapters

56

----------------------

57

Such adapters are reported to work under Mac OSX and Windows. They are

58

mapped to a normal COM port under Windows, but on Mac OSX and other platforms

59

they have special device names.

60

61

Mac OSX: "/dev/[cu|tty].USA<adaptername><USB-part>P<serial-port>.1"

62

e.g. "/dev/cu.USA19QW11P1.1"

63

64

Linux: "/dev/usb/ttyUSB[n]" or "/dev/ttyUSB[n]"

65

first for for RedHat, second form for Debian.

66

e.g. "/dev/usb/ttyUSB0"

67

68

Either use these names for the serial ports or create a link to the common device

69

names like "ln -s /dev/cu.USA19QW11P1.1 /dev/cuaa0" or "ln -s /dev/usb/ttyUSB0

70

/dev/ttyS4" etc.

71

72

But be aware that the (USB) device file disappears as soon as you unplug the USB

73

adapter.

74

75

76

Short introduction

77

------------------

78

Open port 0 at "9600,8,N,1", no timeout

79

>>> import serial

80

>>> ser = serial.Serial(0) #open first serial port

81

>>> print ser.portstr #check which port was realy used

82

>>> ser.write("hello") #write a string

83

>>> ser.close() #close port

84

85

Open named port at "19200,8,N,1", 1s timeout

86

>>> ser = serial.Serial('/dev/ttyS1', 19200, timeout=1)

87

>>> x = ser.read() #read one byte

88

>>> s = ser.read(10) #read up to ten bytes (timeout)

89

>>> line = ser.readline() #read a '\n' terminated line

90

>>> ser.close()

91

92

Open second port at "38400,8,E,1", non blocking HW handshaking

93

>>> ser = serial.Serial(1, 38400, timeout=0,

94

... parity=serial.PARITY_EVEN, rtscts=1)

95

>>> s = ser.read(100) #read up to one hunded bytes

96

... #or as much is in the buffer

97

98

Get a Serial instance and configure/open it later

99

>>> ser = serial.Serial()

100

>>> ser.baudrate = 19200

101

>>> ser.port = 0

102

>>> ser

103

Serial<id=0xa81c10, open=False>(port='COM1', baudrate=19200, bytesize=8,

104

parity='N', stopbits=1, timeout=None, xonxoff=0, rtscts=0)

105

>>> ser.open()

106

>>> ser.isOpen()

107

True

108

>>> ser.close()

109

>>> ser.isOpen()

110

False

111

112

Be carefully when using "readline". Do specify a timeout when

113

opening the serial port otherwise it could block forever if

114

no newline character is received. Also note that "readlines" only

115

works with a timeout. "readlines" depends on having a timeout

116

and interprets that as EOF (end of file). It raises an exception

117

if the port is not opened correctly.

118

119

120

Parameters for the Serial class

121

-------------------------------

122

ser = serial.Serial(

123

port=None, #number of device, numbering starts at

124

#zero. if everything fails, the user

125

#can specify a device string, note

126

#that this isn't portable anymore

127

#if no port is specified an unconfigured

128

#an closed serial port object is created

129

baudrate=9600, #baudrate

130

bytesize=EIGHTBITS, #number of databits

131

parity=PARITY_NONE, #enable parity checking

132

stopbits=STOPBITS_ONE, #number of stopbits

133

timeout=None, #set a timeout value, None to wait forever

134

xonxoff=0, #enable software flow control

135

rtscts=0, #enable RTS/CTS flow control

136

writeTimeout=None, #set a timeout for writes

137

)

138

139

The port is immediately opened on object creation, if a port is given.

140

It is not opened if port is None.

141

142

Options for read timeout:

143

timeout=None #wait forever

144

timeout=0 #non-blocking mode (return immediately on read)

145

timeout=x #set timeout to x seconds (float allowed)

146

147

Options for write timeout:

148

writeTimeout=x #will rise a SerialTimeoutException if the data

149

#cannot be sent in x seconds

150

151

Methods of Serial instances

152

---------------------------

153

open() #open port

154

close() #close port immediately

155

setBaudrate(baudrate) #change baudarte on an open port

156

inWaiting() #return the number of chars in the receive buffer

157

read(size=1) #read "size" characters

158

write(s) #write the string s to the port

159

flushInput() #flush input buffer, discarding all it's contents

160

flushOutput() #flush output buffer, abort output

161

sendBreak() #send break condition

162

setRTS(level=1) #set RTS line to specified logic level

163

setDTR(level=1) #set DTR line to specified logic level

164

getCTS() #return the state of the CTS line

165

getDSR() #return the state of the DSR line

166

getRI() #return the state of the RI line

167

getCD() #return the state of the CD line

168

169

Attributes of Serial instances

170

------------------------------

171

Read Only:

172

portstr #device name

173

BAUDRATES #list of valid baudrates

174

BYTESIZES #list of valid byte sizes

175

PARITIES #list of valid parities

176

STOPBITS #list of valid stop bit widths

177

178

New values can be assigned to the following attribues, the port

179

will be reconfigured, even if it's opened at that time (port will be

180

closed and reopened to apply the changes):

181

port #port name/number as set by the user

182

baudrate #current baudrate setting

183

bytesize #bytesize in bits

184

parity #parity setting

185

stopbits #stop bit with (1,2)

186

timeout #read timeout setting

187

xonxoff #if Xon/Xoff flow control is enabled

188

rtscts #if hardware flow control is enabled

189

writeTimeout #write timeout setting

190

191

These attribues also have corresponding getX and setXX methods.

192

193

Exceptions

194

----------

195

serial.SerialException

196

197

Constants

198

---------

199

parity:

200

serial.PARITY_NONE

201

serial.PARITY_EVEN

202

serial.PARITY_ODD

203

stopbits:

204

serial.STOPBITS_ONE

205

serial.STOPBITS_TWO

206

bytesize:

207

serial.FIVEBITS

208

serial.SIXBITS

209

serial.SEVENBITS

210

serial.EIGHTBITS

211

212

Xon/Xoff characters:

213

serial.XON

214

serial.XOFF

215

216

Tips & Tricks

217

-------------

218

- Some protocols need CR LF ("\r\n") as line terminator, not just LF ("\n").

219

Telephone modems with the AT command set are an example of this behaviour.

220

221

- Scanning for available serial ports is possible with more or less success on

222

some platforms. Look at the tools from Roger Binns:

223

http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/bitpim/comscan/

224

225

- When packaging a project with py2exe, it will likely print a warning about

226

missing modules 'javax.comm'. This warning is uncritical as the module is

227

used in the Jython implementation that is not used but packaged.

228

229

It can be avoided with:

230

setup(...

231

options = {'py2exe': {'excludes': ['javax.comm']}})

232

233

See also setup_demo.py in the examples.

234

235

236

References

237

----------

238

- Python: http://www.python.org

239

- Jython: http://www.jython.org

240

- win32all: http://starship.python.net/crew/mhammond/

241

and http://www.activestate.com/Products/ActivePython/win32all.html

242

- Java@IBM http://www-106.ibm.com/developerworks/java/jdk/

243

(JavaComm links are on the download page for the respective platform jdk)

244

- Java@SUN http://java.sun.com/products/

1

========

2

pySerial

3

========

4

This module capsulates the access for the serial port. It provides backends

5

for standard Python running on Windows, Linux, BSD (possibly any POSIX

6

compilant system) and Jython. The module named "serial" automaticaly selects

7

the appropriate backend.

8

9

It is released under a free software license, see LICENSE.txt for more

10

details.

11

12

Project Homepage: http://pyserial.sourceforge.net

13

14

15

16

Features

17

--------

18

- same class based interface on all supported platforms

19

- access to the port settings trough Python 2.2 properties

20

- port numbering starts at zero, no need to know the platform dependant port

21

name in the user program

22

- port name can be specified if access through numbering is inappropriate

23

- support for different bytesizes, stopbits, parity and flow control

24

with RTS/CTS and/or Xon/Xoff

25

- working with or without receive timeout, blocking or non-blocking

26

- file like API with "read" and "write" ("readline" etc. also supported)

27

- The files in this package are 100% pure Python.

28

They depend on non standard but common packages on Windows (win32all) and

29

Jython (JavaComm). POSIX (Linux, BSD) uses only modules from the standard

30

Python distribution)

31

- The port is set up for binary transmission. No NULL byte stripping, CR-LF

32

translation etc. (which are many times enabled for POSIX.) This makes this

33

module universally useful.

34

35

36

Requirements

37

------------

38

- Python 2.2 or newer

39

- win32all extensions on Windows

40

- "Java Communications" (JavaComm) extension for Java/Jython

41

42

43

Installation

44

------------

45

Extract files from the archive, open a shell/console in that directory and

46

let Distutils do the rest: "python setup.py install"

47

48

The files get installed in the "Lib/site-packages" directory.

49

50

There is also a Windows installer, but for developers it may be interesting

51

to get the source archive anyway, because it contains examples and the readme.

52

53

Do also have a look at the example files in the examples directory in the

54

source distribution or online in CVS repository.

55

56

57

Serial to USB adapters

58

----------------------

59

Such adapters are reported to work under Mac OSX and Windows. They are

60

mapped to a normal COM port under Windows, but on Mac OSX and other platforms

61

they have special device names.

62

63

Mac OSX: "/dev/[cu|tty].USA<adaptername><USB-part>P<serial-port>.1"

64

e.g. "/dev/cu.USA19QW11P1.1"

65

66

Linux: "/dev/usb/ttyUSB[n]" or "/dev/ttyUSB[n]"

67

first for for RedHat, second form for Debian.

68

e.g. "/dev/usb/ttyUSB0"

69

70

Either use these names for the serial ports or create a link to the common device

71

names like "ln -s /dev/cu.USA19QW11P1.1 /dev/cuaa0" or "ln -s /dev/usb/ttyUSB0

72

/dev/ttyS4" etc.

73

74

But be aware that the (USB) device file disappears as soon as you unplug the USB

75

adapter.

76

77

78

Short introduction

79

------------------

80

Open port 0 at "9600,8,N,1", no timeout::

81

82

>>> import serial

83

>>> ser = serial.Serial(0) #open first serial port

84

>>> print ser.portstr #check which port was realy used

85

>>> ser.write("hello") #write a string

86

>>> ser.close() #close port

87

88

Open named port at "19200,8,N,1", 1s timeout::

89

90

>>> ser = serial.Serial('/dev/ttyS1', 19200, timeout=1)

91

>>> x = ser.read() #read one byte

92

>>> s = ser.read(10) #read up to ten bytes (timeout)

93

>>> line = ser.readline() #read a '\n' terminated line

94

>>> ser.close()

95

96

Open second port at "38400,8,E,1", non blocking HW handshaking::

97

98

>>> ser = serial.Serial(1, 38400, timeout=0,

99

... parity=serial.PARITY_EVEN, rtscts=1)

100

>>> s = ser.read(100) #read up to one hunded bytes

101

... #or as much is in the buffer

102

103

Get a Serial instance and configure/open it later::

104

105

>>> ser = serial.Serial()

106

>>> ser.baudrate = 19200

107

>>> ser.port = 0

108

>>> ser

109

Serial<id=0xa81c10, open=False>(port='COM1', baudrate=19200, bytesize=8,

110

parity='N', stopbits=1, timeout=None, xonxoff=0, rtscts=0)

111

>>> ser.open()

112

>>> ser.isOpen()

113

True

114

>>> ser.close()

115

>>> ser.isOpen()

116

False

117

118

Be carefully when using "readline". Do specify a timeout when

119

opening the serial port otherwise it could block forever if

120

no newline character is received. Also note that "readlines" only

121

works with a timeout. "readlines" depends on having a timeout

122

and interprets that as EOF (end of file). It raises an exception

123

if the port is not opened correctly.

124

125

126

Parameters for the Serial class::

127

128

ser = serial.Serial(

129

port=None, #number of device, numbering starts at

130

#zero. if everything fails, the user

131

#can specify a device string, note

132

#that this isn't portable anymore

133

#if no port is specified an unconfigured

134

#an closed serial port object is created

135

baudrate=9600, #baudrate

136

bytesize=EIGHTBITS, #number of databits

137

parity=PARITY_NONE, #enable parity checking

138

stopbits=STOPBITS_ONE, #number of stopbits

139

timeout=None, #set a timeout value, None to wait forever

140

xonxoff=0, #enable software flow control

141

rtscts=0, #enable RTS/CTS flow control

142

writeTimeout=None, #set a timeout for writes

143

)

144

145

The port is immediately opened on object creation, if a port is given.

146

It is not opened if port is None.

147

148

Options for read timeout::

149

150

timeout=None #wait forever

151

timeout=0 #non-blocking mode (return immediately on read)

152

timeout=x #set timeout to x seconds (float allowed)

153

154

Options for write timeout::

155

156

writeTimeout=x #will rise a SerialTimeoutException if the data

157

#cannot be sent in x seconds

158

159

160

Methods of Serial instances::

161

162

open() #open port

163

close() #close port immediately

164

setBaudrate(baudrate) #change baudarte on an open port

165

inWaiting() #return the number of chars in the receive buffer

166

read(size=1) #read "size" characters

167

write(s) #write the string s to the port

168

flushInput() #flush input buffer, discarding all it's contents

169

flushOutput() #flush output buffer, abort output

170

sendBreak() #send break condition

171

setRTS(level=1) #set RTS line to specified logic level

172

setDTR(level=1) #set DTR line to specified logic level

173

getCTS() #return the state of the CTS line

174

getDSR() #return the state of the DSR line

175

getRI() #return the state of the RI line

176

getCD() #return the state of the CD line

177

178

179

Read only Attributes of Serial instances::

180

181

portstr #device name

182

BAUDRATES #list of valid baudrates

183

BYTESIZES #list of valid byte sizes

184

PARITIES #list of valid parities

185

STOPBITS #list of valid stop bit widths

186

187

New values can be assigned to the following attribues, the port

188

will be reconfigured, even if it's opened at that time (port will be

189

closed and reopened to apply the changes)::

190

191

port #port name/number as set by the user

192

baudrate #current baudrate setting

193

bytesize #bytesize in bits

194

parity #parity setting

195

stopbits #stop bit with (1,2)

196

timeout #read timeout setting

197

xonxoff #if Xon/Xoff flow control is enabled

198

rtscts #if hardware flow control is enabled

199

writeTimeout #write timeout setting

200

201

These attributes also have corresponding getX and setXX methods.

202

203

204

Exceptions that can be raised::

205

206

serial.SerialException

207

208

209

Constants

210

211

parity::

212

213

serial.PARITY_NONE

214

serial.PARITY_EVEN

215

serial.PARITY_ODD

216

217

stopbits::

218

219

serial.STOPBITS_ONE

220

serial.STOPBITS_TWO

221

222

bytesize::

223

224

serial.FIVEBITS

225

serial.SIXBITS

226

serial.SEVENBITS

227

serial.EIGHTBITS

228

229

Xon/Xoff characters::

230

231

serial.XON

232

serial.XOFF

233

234

Iterator interface

235

~~~~~~~~~~~~~~~~~~

236

It is possible to iterate over lines comming from a serial port::

237

238

>>> ser = serial.Serial(0, timeout=10)

239

>>> for line in ser:

240

... print line

241

242

The use is somewhat restricted tough, as many protocols on the

243

wire require that commands are sent and answers are read and this

244

one only reads lines.

245

246

247

Tips & Tricks

248

-------------

249

- Some protocols need CR LF ("\r\n") as line terminator, not just LF ("\n").

250

Telephone modems with the AT command set are an example of this behaviour.

251

252

- Scanning for available serial ports is possible with more or less success on

253

some platforms. Look at the tools from Roger Binns:

254

http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/bitpim/comscan/

255

256

- When packaging a project with py2exe, it will likely print a warning about

257

missing modules 'javax.comm'. This warning is uncritical as the module is

258

used in the Jython implementation that is not used but packaged.

259

260

It can be avoided with::

261

262

setup(...

263

options = {'py2exe': {'excludes': ['javax.comm']}})

264

265