← Back to branch summary

~swe3tdave-deactivatedaccount/ubuntu/trusty/pyserial/fix-for-pronterface

« back to all changes in this revision

Viewing changes to documentation/examples.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2011-01-25 07:59:17 UTC
  • mfrom: (3.1.5 experimental)
  • Revision ID: james.westby@ubuntu.com-20110125075917-m132a8pxfff5a7sf
Tags: 2.5-1
http://bugs.debian.org/520618
http://bugs.debian.org/585328
* New upstream version. Closes: #520618.
* Build a python3-serial package.
* Don't use string exception in miniterm.py. Closes: #585328.

Show diffs side-by-side

added added

removed removed

Lines of Context:
documentation/examples.rst
 
1
.. _examples:
 
2
 
 
3
==========
 
4
 Examples
 
5
==========
 
6
 
 
7
.. _miniterm:
 
8
 
 
9
Miniterm
 
10
========
 
11
This is a console application that provides a small terminal application.
 
12
miniterm itself does not implement any terminal features such as VT102
 
13
compatibility. However it inherits these features from the terminal it is run.
 
14
For example on GNU/Linux running from an xterm it will support the escape
 
15
sequences of the xterm. On Windows the typical console window is dumb and does
 
16
not support any escapes. When ANSI.sys is loaded it supports some escapes.
 
17
 
 
18
miniterm::
 
19
 
 
20
    --- Miniterm on /dev/ttyS0: 9600,8,N,1 ---
 
21
    --- Quit: Ctrl+]  |  Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
 
22
 
 
23
Command line options can be given so that binary data including escapes for
 
24
terminals are escaped or output as hex.
 
25
 
 
26
miniterm supports :rfc:`2217` remote serial ports and raw sockets using URLs
 
27
such as ``rfc2217:://<host>:<port>`` respectively ``socket://<host>:<port>`` as
 
28
*port* argument when invoking.
 
29
 
 
30
Command line options ``miniterm.py -h``::
 
31
 
 
32
    Usage: miniterm.py [options] [port [baudrate]]
 
33
 
 
34
    Miniterm - A simple terminal program for the serial port.
 
35
 
 
36
    Options:
 
37
      -h, --help            show this help message and exit
 
38
      -p PORT, --port=PORT  port, a number (default 0) or a device name
 
39
                            (deprecated option)
 
40
      -b BAUDRATE, --baud=BAUDRATE
 
41
                            set baud rate, default 9600
 
42
      --parity=PARITY       set parity, one of [N, E, O, S, M], default=N
 
43
      -e, --echo            enable local echo (default off)
 
44
      --rtscts              enable RTS/CTS flow control (default off)
 
45
      --xonxoff             enable software flow control (default off)
 
46
      --cr                  do not send CR+LF, send CR only
 
47
      --lf                  do not send CR+LF, send LF only
 
48
      -D, --debug           debug received data (escape non-printable chars)
 
49
                            --debug can be given multiple times: 0: just print
 
50
                            what is received 1: escape non-printable characters,
 
51
                            do newlines as unusual 2: escape non-printable
 
52
                            characters, newlines too 3: hex dump everything
 
53
      --rts=RTS_STATE       set initial RTS line state (possible values: 0, 1)
 
54
      --dtr=DTR_STATE       set initial DTR line state (possible values: 0, 1)
 
55
      -q, --quiet           suppress non error messages
 
56
      --exit-char=EXIT_CHAR
 
57
                            ASCII code of special character that is used to exit
 
58
                            the application
 
59
      --menu-char=MENU_CHAR
 
60
                            ASCII code of special character that is used to
 
61
                            control miniterm (menu)
 
62
 
 
63
 
 
64
miniterm supports some control functions. Typing :kbd:`Control+t Control+h` when it is
 
65
running shows the help text::
 
66
 
 
67
    --- pySerial - miniterm - help
 
68
    ---
 
69
    --- Ctrl+]   Exit program
 
70
    --- Ctrl+T   Menu escape key, followed by:
 
71
    --- Menu keys:
 
72
    ---       Ctrl+T   Send the menu character itself to remote
 
73
    ---       Ctrl+]   Send the exit character to remote
 
74
    ---       Ctrl+I   Show info
 
75
    ---       Ctrl+U   Upload file (prompt will be shown)
 
76
    --- Toggles:
 
77
    ---       Ctrl+R  RTS          Ctrl+E  local echo
 
78
    ---       Ctrl+D  DTR          Ctrl+B  BREAK
 
79
    ---       Ctrl+L  line feed    Ctrl+A  Cycle repr mode
 
80
    ---
 
81
    --- Port settings (Ctrl+T followed by the following):
 
82
    --- 7 8           set data bits
 
83
    --- n e o s m     change parity (None, Even, Odd, Space, Mark)
 
84
    --- 1 2 3         set stop bits (1, 2, 1.5)
 
85
    --- b             change baud rate
 
86
    --- x X           disable/enable software flow control
 
87
    --- r R           disable/enable hardware flow control
 
88
 
 
89
.. versionchanged:: 2.5
 
90
    Added :kbd:`Control+t` menu and added support for opening URLs.
 
91
 
 
92
miniterm.py_
 
93
    The miniterm program.
 
94
 
 
95
setup-miniterm-py2exe.py_
 
96
    This is a py2exe setup script for Windows. It can be used to create a
 
97
    standalone ``miniterm.exe``.
 
98
 
 
99
.. _miniterm.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/miniterm.py
 
100
.. _setup-miniterm-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup-miniterm-py2exe.py
 
101
 
 
102
 
 
103
TCP/IP - serial bridge
 
104
======================
 
105
This program opens a TCP/IP port. When a connection is made to that port (e.g.
 
106
with telnet) it forwards all data to the serial port and vice versa.
 
107
 
 
108
This example only exports a raw socket connection. The next example
 
109
below gives the client much more control over the remote serial port.
 
110
 
 
111
- The serial port settings are set on the command line when starting the
 
112
  program.
 
113
- There is no possibility to change settings from remote.
 
114
- All data is passed through as-is.
 
115
 
 
116
::
 
117
 
 
118
    Usage: tcp_serial_redirect.py [options] [port [baudrate]]
 
119
 
 
120
    Simple Serial to Network (TCP/IP) redirector.
 
121
 
 
122
    Options:
 
123
      -h, --help            show this help message and exit
 
124
      -q, --quiet           suppress non error messages
 
125
      --spy                 peek at the communication and print all data to the
 
126
                            console
 
127
 
 
128
      Serial Port:
 
129
        Serial port settings
 
130
 
 
131
        -p PORT, --port=PORT
 
132
                            port, a number (default 0) or a device name
 
133
        -b BAUDRATE, --baud=BAUDRATE
 
134
                            set baud rate, default: 9600
 
135
        --parity=PARITY     set parity, one of [N, E, O], default=N
 
136
        --rtscts            enable RTS/CTS flow control (default off)
 
137
        --xonxoff           enable software flow control (default off)
 
138
        --rts=RTS_STATE     set initial RTS line state (possible values: 0, 1)
 
139
        --dtr=DTR_STATE     set initial DTR line state (possible values: 0, 1)
 
140
 
 
141
      Network settings:
 
142
        Network configuration.
 
143
 
 
144
        -P LOCAL_PORT, --localport=LOCAL_PORT
 
145
                            local TCP port
 
146
        --rfc2217           allow control commands with Telnet extension RFC-2217
 
147
 
 
148
      Newline Settings:
 
149
        Convert newlines between network and serial port. Conversion is
 
150
        normally disabled and can be enabled by --convert.
 
151
 
 
152
        -c, --convert       enable newline conversion (default off)
 
153
        --net-nl=NET_NEWLINE
 
154
                            type of newlines that are expected on the network
 
155
                            (default: LF)
 
156
        --ser-nl=SER_NEWLINE
 
157
                            type of newlines that are expected on the serial port
 
158
                            (default: CR+LF)
 
159
 
 
160
    NOTE: no security measures are implemented. Anyone can remotely connect to
 
161
    this service over the network.  Only one connection at once is supported. When
 
162
    the connection is terminated it waits for the next connect.
 
163
 
 
164
 
 
165
tcp_serial_redirect.py_
 
166
    Main program.
 
167
 
 
168
.. _tcp_serial_redirect.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/tcp_serial_redirect.py
 
169
 
 
170
Single-port TCP/IP - serial bridge (RFC 2217)
 
171
=============================================
 
172
Simple cross platform :rfc:`2217` serial port server. It uses threads and is
 
173
portable (runs on POSIX, Windows, etc).
 
174
 
 
175
- The port settings and control lines (RTS/DTR) can be changed at any time
 
176
  using :rfc:`2217` requests. The status lines (DSR/CTS/RI/CD) are polled every
 
177
  second and notifications are sent to the client.
 
178
- Telnet character IAC (0xff) needs to be doubled in data stream. IAC followed
 
179
  by an other value is interpreted as Telnet command sequence.
 
180
- Telnet negotiation commands are sent when connecting to the server.
 
181
- RTS/DTR are activated on client connect and deactivated on disconnect.
 
182
- Default port settings are set again when client disconnects.
 
183
 
 
184
::
 
185
 
 
186
    Usage: rfc2217_server.py [options] port
 
187
 
 
188
    RFC 2217 Serial to Network (TCP/IP) redirector.
 
189
 
 
190
    Options:
 
191
      -h, --help            show this help message and exit
 
192
      -p LOCAL_PORT, --localport=LOCAL_PORT
 
193
                            local TCP port
 
194
 
 
195
    NOTE: no security measures are implemented. Anyone can remotely connect to
 
196
    this service over the network.  Only one connection at once is supported. When
 
197
    the connection is terminated it waits for the next connect.
 
198
 
 
199
.. versionadded:: 2.5
 
200
 
 
201
rfc2217_server.py_
 
202
    Main program.
 
203
 
 
204
setup-rfc2217_server-py2exe.py_
 
205
    This is a py2exe setup script for Windows. It can be used to create a
 
206
    standalone ``rfc2217_server.exe``.
 
207
 
 
208
.. _rfc2217_server.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/rfc2217_server.py
 
209
.. _setup-rfc2217_server-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup-rfc2217_server-py2exe.py
 
210
 
 
211
 
 
212
Multi-port TCP/IP - serial bridge (RFC 2217)
 
213
============================================
 
214
This example implements a TCP/IP to serial port service that works with
 
215
multiple ports at once. It uses select, no threads, for the serial ports and
 
216
the network sockets and therefore runs on POSIX systems only.
 
217
 
 
218
- Full control over the serial port with :rfc:`2217`.
 
219
- Check existence of ``/tty/USB0...8``. This is done every 5 seconds using
 
220
  ``os.path.exists``.
 
221
- Send zeroconf announcements when port appears or disappears (uses
 
222
  python-avahi and dbus). Service name: ``_serial_port._tcp``.
 
223
- Each serial port becomes available as one TCP/IP server. e.g.
 
224
  ``/dev/ttyUSB0`` is reachable at ``<host>:7000``.
 
225
- Single process for all ports and sockets (not per port).
 
226
- The script can be started as daemon.
 
227
- Logging to stdout or when run as daemon to syslog.
 
228
- Default port settings are set again when client disconnects.
 
229
- modem status lines (CTS/DSR/RI/CD) are not polled periodically and the server
 
230
  therefore does not send NOTIFY_MODEMSTATE on its own. However it responds to
 
231
  request from the client (i.e. use the ``poll_modem`` option in the URL when
 
232
  using a pySerial client.)
 
233
 
 
234
Requirements:
 
235
 
 
236
- Python (>= 2.4)
 
237
- python-avahi
 
238
- python-dbus
 
239
- python-serial (>= 2.5)
 
240
 
 
241
Installation as daemon:
 
242
 
 
243
- Copy the script ``port_publisher.py`` to ``/usr/local/bin``.
 
244
- Copy the script ``port_publisher.sh`` to ``/etc/init.d``.
 
245
- Add links to the runlevels using ``update-rc.d port_publisher.sh defaults 99``
 
246
- Thats it :-) the service will be started on next reboot. Alternatively run
 
247
  ``invoke-rc.d port_publisher.sh start`` as root.
 
248
 
 
249
.. versionadded:: 2.5 new example
 
250
 
 
251
port_publisher.py_
 
252
    Multi-port TCP/IP-serial converter (RFC 2217) for POSIX environments.
 
253
 
 
254
port_publisher.sh_
 
255
    Example init.d script.
 
256
 
 
257
.. _port_publisher.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/port_publisher.py
 
258
.. _port_publisher.sh: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/port_publisher.sh
 
259
 
 
260
 
 
261
wxPython examples
 
262
=================
 
263
A simple terminal application for wxPython and a flexible serial port
 
264
configuration dialog are shown here.
 
265
 
 
266
wxTerminal.py_
 
267
    A simple terminal application. Note that the length of the buffer is
 
268
    limited by wx and it may suddenly stop displaying new input.
 
269
 
 
270
wxTerminal.wxg_
 
271
    A wxGlade design file for the terminal application.
 
272
 
 
273
wxSerialConfigDialog.py_
 
274
    A flexible serial port configuration dialog.
 
275
 
 
276
wxSerialConfigDialog.wxg_
 
277
    The wxGlade design file for the configuration dialog.
 
278
 
 
279
setup-wxTerminal-py2exe.py_
 
280
    A py2exe setup script to package the terminal application.
 
281
 
 
282
.. _wxTerminal.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxTerminal.py
 
283
.. _wxTerminal.wxg: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxTerminal.wxg
 
284
.. _wxSerialConfigDialog.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxSerialConfigDialog.py
 
285
.. _wxSerialConfigDialog.wxg: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxSerialConfigDialog.wxg
 
286
.. _setup-wxTerminal-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup-wxTerminal-py2exe.py
 
287
 
 
288
 
 
289
Wrapper class
 
290
=============
 
291
This example provides a subclass based on ``Serial`` that has an alternative
 
292
implementation of ``readline()``
 
293
 
 
294
enhancedserial.py_
 
295
    A class with alternative ``readline()`` implementation.
 
296
 
 
297
.. _enhancedserial.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/enhancedserial.py
 
298
 
 
299
 
 
300
Finding serial ports
 
301
====================
 
302
scan.py_
 
303
    A simple loop that probes serial ports by number.
 
304
 
 
305
scanlinux.py_
 
306
    A Linux only version looking at the entries in ``/dev``. It works best with
 
307
    on systems with devfs or udev that only create those entries that represent
 
308
    devices. On older installations a lot of pre-created device files are found
 
309
    and an additional open check should be added to ensure that the device is
 
310
    real.
 
311
 
 
312
scanwin32.py_
 
313
    A Windows only version that returns a list of serial ports with information
 
314
    from the registry.
 
315
 
 
316
.. _scan.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scan.py
 
317
.. _scanlinux.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanlinux.py
 
318
.. _scanwin32.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanwin32.py
 
319
 
 
320
 
 
321
Unit tests
 
322
==========
 
323
The project uses a number of unit test to verify the functionality. They all
 
324
need a loop back connector. The scripts itself contain more information. All
 
325
test scripts are contained in the directory ``test``.
 
326
 
 
327
The unit tests are performed on port ``0`` unless a different device name or
 
328
``rfc2217://`` URL is given on the command line (argv[1]).
 
329
 
 
330
run_all_tests.py_
 
331
    Collect all tests from all ``test*`` files and run them. By default, the
 
332
    ``loop://`` device is used.
 
333
 
 
334
test.py_
 
335
    Basic tests (binary capabilities, timeout, control lines).
 
336
 
 
337
test_advanced.py_
 
338
    Test more advanced features (properties).
 
339
 
 
340
test_high_load.py_
 
341
    Tests involving sending a lot of data.
 
342
 
 
343
test_readline.py_
 
344
    Tests involving readline.
 
345
 
 
346
test_iolib.py_
 
347
    Tests involving the :mod:`io` library. Only available for Python 2.6 and
 
348
    newer.
 
349
 
 
350
.. _run_all_tests.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/run_all_tests.py
 
351
.. _test.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test.py
 
352
.. _test_advanced.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_advanced.py
 
353
.. _test_high_load.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_high_load.py
 
354
.. _test_readline.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_readline.py
 
355
.. _test_iolib.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_iolib.py