• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. _examples:
2
3==========
4 Examples
5==========
6
7
8Miniterm
9========
10Miniterm is now available as module instead of example.
11see :ref:`miniterm` for details.
12
13miniterm.py_
14    The miniterm program.
15
16setup-miniterm-py2exe.py_
17    This is a py2exe setup script for Windows. It can be used to create a
18    standalone ``miniterm.exe``.
19
20.. _miniterm.py: https://github.com/pyserial/pyserial/blob/master/serial/tools/miniterm.py
21.. _setup-miniterm-py2exe.py: https://github.com/pyserial/pyserial/blob/master/examples/setup-miniterm-py2exe.py
22
23
24TCP/IP - serial bridge
25======================
26This program opens a TCP/IP port. When a connection is made to that port (e.g.
27with telnet) it forwards all data to the serial port and vice versa.
28
29This example only exports a raw socket connection. The next example
30below gives the client much more control over the remote serial port.
31
32- The serial port settings are set on the command line when starting the
33  program.
34- There is no possibility to change settings from remote.
35- All data is passed through as-is.
36
37::
38
39    usage: tcp_serial_redirect.py [-h] [-q] [--parity {N,E,O,S,M}] [--rtscts]
40                                  [--xonxoff] [--rts RTS] [--dtr DTR]
41                                  [-P LOCALPORT]
42                                  SERIALPORT [BAUDRATE]
43
44    Simple Serial to Network (TCP/IP) redirector.
45
46    positional arguments:
47      SERIALPORT            serial port name
48      BAUDRATE              set baud rate, default: 9600
49
50    optional arguments:
51      -h, --help            show this help message and exit
52      -q, --quiet           suppress non error messages
53
54    serial port:
55      --parity {N,E,O,S,M}  set parity, one of {N E O S M}, default: N
56      --rtscts              enable RTS/CTS flow control (default off)
57      --xonxoff             enable software flow control (default off)
58      --rts RTS             set initial RTS line state (possible values: 0, 1)
59      --dtr DTR             set initial DTR line state (possible values: 0, 1)
60
61    network settings:
62      -P LOCALPORT, --localport LOCALPORT
63                            local TCP port
64
65    NOTE: no security measures are implemented. Anyone can remotely connect to
66    this service over the network. Only one connection at once is supported. When
67    the connection is terminated it waits for the next connect.
68
69
70tcp_serial_redirect.py_
71    Main program.
72
73.. _tcp_serial_redirect.py: https://github.com/pyserial/pyserial/blob/master/examples/tcp_serial_redirect.py
74
75
76Single-port TCP/IP - serial bridge (RFC 2217)
77=============================================
78Simple cross platform :rfc:`2217` serial port server. It uses threads and is
79portable (runs on POSIX, Windows, etc).
80
81- The port settings and control lines (RTS/DTR) can be changed at any time
82  using :rfc:`2217` requests. The status lines (DSR/CTS/RI/CD) are polled every
83  second and notifications are sent to the client.
84- Telnet character IAC (0xff) needs to be doubled in data stream. IAC followed
85  by another value is interpreted as Telnet command sequence.
86- Telnet negotiation commands are sent when connecting to the server.
87- RTS/DTR are activated on client connect and deactivated on disconnect.
88- Default port settings are set again when client disconnects.
89
90::
91
92    usage: rfc2217_server.py [-h] [-p TCPPORT] [-v] SERIALPORT
93
94    RFC 2217 Serial to Network (TCP/IP) redirector.
95
96    positional arguments:
97      SERIALPORT
98
99    optional arguments:
100      -h, --help            show this help message and exit
101      -p TCPPORT, --localport TCPPORT
102                            local TCP port, default: 2217
103      -v, --verbose         print more diagnostic messages (option can be given
104                            multiple times)
105
106    NOTE: no security measures are implemented. Anyone can remotely connect to
107    this service over the network. Only one connection at once is supported. When
108    the connection is terminated it waits for the next connect.
109
110.. versionadded:: 2.5
111
112rfc2217_server.py_
113    Main program.
114
115setup-rfc2217_server-py2exe.py_
116    This is a py2exe setup script for Windows. It can be used to create a
117    standalone ``rfc2217_server.exe``.
118
119.. _rfc2217_server.py: https://github.com/pyserial/pyserial/blob/master/examples/rfc2217_server.py
120.. _setup-rfc2217_server-py2exe.py: https://github.com/pyserial/pyserial/blob/master/examples/setup-rfc2217_server-py2exe.py
121
122
123Multi-port TCP/IP - serial bridge (RFC 2217)
124============================================
125This example implements a TCP/IP to serial port service that works with
126multiple ports at once. It uses select, no threads, for the serial ports and
127the network sockets and therefore runs on POSIX systems only.
128
129- Full control over the serial port with :rfc:`2217`.
130- Check existence of ``/tty/USB0...8``. This is done every 5 seconds using
131  ``os.path.exists``.
132- Send zeroconf announcements when port appears or disappears (uses
133  python-avahi and dbus). Service name: ``_serial_port._tcp``.
134- Each serial port becomes available as one TCP/IP server. e.g.
135  ``/dev/ttyUSB0`` is reachable at ``<host>:7000``.
136- Single process for all ports and sockets (not per port).
137- The script can be started as daemon.
138- Logging to stdout or when run as daemon to syslog.
139- Default port settings are set again when client disconnects.
140- modem status lines (CTS/DSR/RI/CD) are not polled periodically and the server
141  therefore does not send NOTIFY_MODEMSTATE on its own. However it responds to
142  request from the client (i.e. use the ``poll_modem`` option in the URL when
143  using a pySerial client.)
144
145::
146
147    usage: port_publisher.py [options]
148
149    Announce the existence of devices using zeroconf and provide
150    a TCP/IP <-> serial port gateway (implements RFC 2217).
151
152    If running as daemon, write to syslog. Otherwise write to stdout.
153
154    optional arguments:
155      -h, --help            show this help message and exit
156
157    serial port settings:
158      --ports-regex REGEX   specify a regex to search against the serial devices
159                            and their descriptions (default: /dev/ttyUSB[0-9]+)
160
161    network settings:
162      --tcp-port PORT       specify lowest TCP port number (default: 7000)
163
164    daemon:
165      -d, --daemon          start as daemon
166      --pidfile FILE        specify a name for the PID file
167
168    diagnostics:
169      -o FILE, --logfile FILE
170                            write messages file instead of stdout
171      -q, --quiet           suppress most diagnostic messages
172      -v, --verbose         increase diagnostic messages
173
174    NOTE: no security measures are implemented. Anyone can remotely connect to
175    this service over the network. Only one connection at once, per port, is
176    supported. When the connection is terminated, it waits for the next connect.
177
178Requirements:
179
180- Python (>= 2.4)
181- python-avahi
182- python-dbus
183- python-serial (>= 2.5)
184
185Installation as daemon:
186
187- Copy the script ``port_publisher.py`` to ``/usr/local/bin``.
188- Copy the script ``port_publisher.sh`` to ``/etc/init.d``.
189- Add links to the runlevels using ``update-rc.d port_publisher.sh defaults 99``
190- That's it :-) the service will be started on next reboot. Alternatively run
191  ``invoke-rc.d port_publisher.sh start`` as root.
192
193.. versionadded:: 2.5 new example
194
195port_publisher.py_
196    Multi-port TCP/IP-serial converter (RFC 2217) for POSIX environments.
197
198port_publisher.sh_
199    Example init.d script.
200
201.. _port_publisher.py: https://github.com/pyserial/pyserial/blob/master/examples/port_publisher.py
202.. _port_publisher.sh: https://github.com/pyserial/pyserial/blob/master/examples/port_publisher.sh
203
204
205wxPython examples
206=================
207A simple terminal application for wxPython and a flexible serial port
208configuration dialog are shown here.
209
210wxTerminal.py_
211    A simple terminal application. Note that the length of the buffer is
212    limited by wx and it may suddenly stop displaying new input.
213
214wxTerminal.wxg_
215    A wxGlade design file for the terminal application.
216
217wxSerialConfigDialog.py_
218    A flexible serial port configuration dialog.
219
220wxSerialConfigDialog.wxg_
221    The wxGlade design file for the configuration dialog.
222
223setup-wxTerminal-py2exe.py_
224    A py2exe setup script to package the terminal application.
225
226.. _wxTerminal.py: https://github.com/pyserial/pyserial/blob/master/examples/wxTerminal.py
227.. _wxTerminal.wxg: https://github.com/pyserial/pyserial/blob/master/examples/wxTerminal.wxg
228.. _wxSerialConfigDialog.py: https://github.com/pyserial/pyserial/blob/master/examples/wxSerialConfigDialog.py
229.. _wxSerialConfigDialog.wxg: https://github.com/pyserial/pyserial/blob/master/examples/wxSerialConfigDialog.wxg
230.. _setup-wxTerminal-py2exe.py: https://github.com/pyserial/pyserial/blob/master/examples/setup-wxTerminal-py2exe.py
231
232
233
234Unit tests
235==========
236The project uses a number of unit test to verify the functionality. They all
237need a loop back connector. The scripts itself contain more information. All
238test scripts are contained in the directory ``test``.
239
240The unit tests are performed on port ``loop://`` unless a different device
241name or URL is given on the command line (``sys.argv[1]``). e.g. to run the
242test on an attached USB-serial converter ``hwgrep://USB`` could be used or
243the actual name such as ``/dev/ttyUSB0`` or ``COM1`` (depending on platform).
244
245run_all_tests.py_
246    Collect all tests from all ``test*`` files and run them. By default, the
247    ``loop://`` device is used.
248
249test.py_
250    Basic tests (binary capabilities, timeout, control lines).
251
252test_advanced.py_
253    Test more advanced features (properties).
254
255test_high_load.py_
256    Tests involving sending a lot of data.
257
258test_readline.py_
259    Tests involving ``readline``.
260
261test_iolib.py_
262    Tests involving the :mod:`io` library. Only available for Python 2.6 and
263    newer.
264
265test_url.py_
266    Tests involving the :ref:`URL <URLs>` feature.
267
268.. _run_all_tests.py:  https://github.com/pyserial/pyserial/blob/master/test/run_all_tests.py
269.. _test.py:           https://github.com/pyserial/pyserial/blob/master/test/test.py
270.. _test_advanced.py:  https://github.com/pyserial/pyserial/blob/master/test/test_advanced.py
271.. _test_high_load.py: https://github.com/pyserial/pyserial/blob/master/test/test_high_load.py
272.. _test_readline.py:  https://github.com/pyserial/pyserial/blob/master/test/test_readline.py
273.. _test_iolib.py:     https://github.com/pyserial/pyserial/blob/master/test/test_iolib.py
274.. _test_url.py:       https://github.com/pyserial/pyserial/blob/master/test/test_url.py
275