275 lines
10 KiB
ReStructuredText
275 lines
10 KiB
ReStructuredText
.. _examples:
|
|
|
|
==========
|
|
Examples
|
|
==========
|
|
|
|
|
|
Miniterm
|
|
========
|
|
Miniterm is now available as module instead of example.
|
|
see :ref:`miniterm` for details.
|
|
|
|
miniterm.py_
|
|
The miniterm program.
|
|
|
|
setup-miniterm-py2exe.py_
|
|
This is a py2exe setup script for Windows. It can be used to create a
|
|
standalone ``miniterm.exe``.
|
|
|
|
.. _miniterm.py: https://github.com/pyserial/pyserial/blob/master/serial/tools/miniterm.py
|
|
.. _setup-miniterm-py2exe.py: https://github.com/pyserial/pyserial/blob/master/examples/setup-miniterm-py2exe.py
|
|
|
|
|
|
TCP/IP - serial bridge
|
|
======================
|
|
This program opens a TCP/IP port. When a connection is made to that port (e.g.
|
|
with telnet) it forwards all data to the serial port and vice versa.
|
|
|
|
This example only exports a raw socket connection. The next example
|
|
below gives the client much more control over the remote serial port.
|
|
|
|
- The serial port settings are set on the command line when starting the
|
|
program.
|
|
- There is no possibility to change settings from remote.
|
|
- All data is passed through as-is.
|
|
|
|
::
|
|
|
|
usage: tcp_serial_redirect.py [-h] [-q] [--parity {N,E,O,S,M}] [--rtscts]
|
|
[--xonxoff] [--rts RTS] [--dtr DTR]
|
|
[-P LOCALPORT]
|
|
SERIALPORT [BAUDRATE]
|
|
|
|
Simple Serial to Network (TCP/IP) redirector.
|
|
|
|
positional arguments:
|
|
SERIALPORT serial port name
|
|
BAUDRATE set baud rate, default: 9600
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
-q, --quiet suppress non error messages
|
|
|
|
serial port:
|
|
--parity {N,E,O,S,M} set parity, one of {N E O S M}, default: N
|
|
--rtscts enable RTS/CTS flow control (default off)
|
|
--xonxoff enable software flow control (default off)
|
|
--rts RTS set initial RTS line state (possible values: 0, 1)
|
|
--dtr DTR set initial DTR line state (possible values: 0, 1)
|
|
|
|
network settings:
|
|
-P LOCALPORT, --localport LOCALPORT
|
|
local TCP port
|
|
|
|
NOTE: no security measures are implemented. Anyone can remotely connect to
|
|
this service over the network. Only one connection at once is supported. When
|
|
the connection is terminated it waits for the next connect.
|
|
|
|
|
|
tcp_serial_redirect.py_
|
|
Main program.
|
|
|
|
.. _tcp_serial_redirect.py: https://github.com/pyserial/pyserial/blob/master/examples/tcp_serial_redirect.py
|
|
|
|
|
|
Single-port TCP/IP - serial bridge (RFC 2217)
|
|
=============================================
|
|
Simple cross platform :rfc:`2217` serial port server. It uses threads and is
|
|
portable (runs on POSIX, Windows, etc).
|
|
|
|
- The port settings and control lines (RTS/DTR) can be changed at any time
|
|
using :rfc:`2217` requests. The status lines (DSR/CTS/RI/CD) are polled every
|
|
second and notifications are sent to the client.
|
|
- Telnet character IAC (0xff) needs to be doubled in data stream. IAC followed
|
|
by another value is interpreted as Telnet command sequence.
|
|
- Telnet negotiation commands are sent when connecting to the server.
|
|
- RTS/DTR are activated on client connect and deactivated on disconnect.
|
|
- Default port settings are set again when client disconnects.
|
|
|
|
::
|
|
|
|
usage: rfc2217_server.py [-h] [-p TCPPORT] [-v] SERIALPORT
|
|
|
|
RFC 2217 Serial to Network (TCP/IP) redirector.
|
|
|
|
positional arguments:
|
|
SERIALPORT
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
-p TCPPORT, --localport TCPPORT
|
|
local TCP port, default: 2217
|
|
-v, --verbose print more diagnostic messages (option can be given
|
|
multiple times)
|
|
|
|
NOTE: no security measures are implemented. Anyone can remotely connect to
|
|
this service over the network. Only one connection at once is supported. When
|
|
the connection is terminated it waits for the next connect.
|
|
|
|
.. versionadded:: 2.5
|
|
|
|
rfc2217_server.py_
|
|
Main program.
|
|
|
|
setup-rfc2217_server-py2exe.py_
|
|
This is a py2exe setup script for Windows. It can be used to create a
|
|
standalone ``rfc2217_server.exe``.
|
|
|
|
.. _rfc2217_server.py: https://github.com/pyserial/pyserial/blob/master/examples/rfc2217_server.py
|
|
.. _setup-rfc2217_server-py2exe.py: https://github.com/pyserial/pyserial/blob/master/examples/setup-rfc2217_server-py2exe.py
|
|
|
|
|
|
Multi-port TCP/IP - serial bridge (RFC 2217)
|
|
============================================
|
|
This example implements a TCP/IP to serial port service that works with
|
|
multiple ports at once. It uses select, no threads, for the serial ports and
|
|
the network sockets and therefore runs on POSIX systems only.
|
|
|
|
- Full control over the serial port with :rfc:`2217`.
|
|
- Check existence of ``/tty/USB0...8``. This is done every 5 seconds using
|
|
``os.path.exists``.
|
|
- Send zeroconf announcements when port appears or disappears (uses
|
|
python-avahi and dbus). Service name: ``_serial_port._tcp``.
|
|
- Each serial port becomes available as one TCP/IP server. e.g.
|
|
``/dev/ttyUSB0`` is reachable at ``<host>:7000``.
|
|
- Single process for all ports and sockets (not per port).
|
|
- The script can be started as daemon.
|
|
- Logging to stdout or when run as daemon to syslog.
|
|
- Default port settings are set again when client disconnects.
|
|
- modem status lines (CTS/DSR/RI/CD) are not polled periodically and the server
|
|
therefore does not send NOTIFY_MODEMSTATE on its own. However it responds to
|
|
request from the client (i.e. use the ``poll_modem`` option in the URL when
|
|
using a pySerial client.)
|
|
|
|
::
|
|
|
|
usage: port_publisher.py [options]
|
|
|
|
Announce the existence of devices using zeroconf and provide
|
|
a TCP/IP <-> serial port gateway (implements RFC 2217).
|
|
|
|
If running as daemon, write to syslog. Otherwise write to stdout.
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
|
|
serial port settings:
|
|
--ports-regex REGEX specify a regex to search against the serial devices
|
|
and their descriptions (default: /dev/ttyUSB[0-9]+)
|
|
|
|
network settings:
|
|
--tcp-port PORT specify lowest TCP port number (default: 7000)
|
|
|
|
daemon:
|
|
-d, --daemon start as daemon
|
|
--pidfile FILE specify a name for the PID file
|
|
|
|
diagnostics:
|
|
-o FILE, --logfile FILE
|
|
write messages file instead of stdout
|
|
-q, --quiet suppress most diagnostic messages
|
|
-v, --verbose increase diagnostic messages
|
|
|
|
NOTE: no security measures are implemented. Anyone can remotely connect to
|
|
this service over the network. Only one connection at once, per port, is
|
|
supported. When the connection is terminated, it waits for the next connect.
|
|
|
|
Requirements:
|
|
|
|
- Python (>= 2.4)
|
|
- python-avahi
|
|
- python-dbus
|
|
- python-serial (>= 2.5)
|
|
|
|
Installation as daemon:
|
|
|
|
- Copy the script ``port_publisher.py`` to ``/usr/local/bin``.
|
|
- Copy the script ``port_publisher.sh`` to ``/etc/init.d``.
|
|
- Add links to the runlevels using ``update-rc.d port_publisher.sh defaults 99``
|
|
- That's it :-) the service will be started on next reboot. Alternatively run
|
|
``invoke-rc.d port_publisher.sh start`` as root.
|
|
|
|
.. versionadded:: 2.5 new example
|
|
|
|
port_publisher.py_
|
|
Multi-port TCP/IP-serial converter (RFC 2217) for POSIX environments.
|
|
|
|
port_publisher.sh_
|
|
Example init.d script.
|
|
|
|
.. _port_publisher.py: https://github.com/pyserial/pyserial/blob/master/examples/port_publisher.py
|
|
.. _port_publisher.sh: https://github.com/pyserial/pyserial/blob/master/examples/port_publisher.sh
|
|
|
|
|
|
wxPython examples
|
|
=================
|
|
A simple terminal application for wxPython and a flexible serial port
|
|
configuration dialog are shown here.
|
|
|
|
wxTerminal.py_
|
|
A simple terminal application. Note that the length of the buffer is
|
|
limited by wx and it may suddenly stop displaying new input.
|
|
|
|
wxTerminal.wxg_
|
|
A wxGlade design file for the terminal application.
|
|
|
|
wxSerialConfigDialog.py_
|
|
A flexible serial port configuration dialog.
|
|
|
|
wxSerialConfigDialog.wxg_
|
|
The wxGlade design file for the configuration dialog.
|
|
|
|
setup-wxTerminal-py2exe.py_
|
|
A py2exe setup script to package the terminal application.
|
|
|
|
.. _wxTerminal.py: https://github.com/pyserial/pyserial/blob/master/examples/wxTerminal.py
|
|
.. _wxTerminal.wxg: https://github.com/pyserial/pyserial/blob/master/examples/wxTerminal.wxg
|
|
.. _wxSerialConfigDialog.py: https://github.com/pyserial/pyserial/blob/master/examples/wxSerialConfigDialog.py
|
|
.. _wxSerialConfigDialog.wxg: https://github.com/pyserial/pyserial/blob/master/examples/wxSerialConfigDialog.wxg
|
|
.. _setup-wxTerminal-py2exe.py: https://github.com/pyserial/pyserial/blob/master/examples/setup-wxTerminal-py2exe.py
|
|
|
|
|
|
|
|
Unit tests
|
|
==========
|
|
The project uses a number of unit test to verify the functionality. They all
|
|
need a loop back connector. The scripts itself contain more information. All
|
|
test scripts are contained in the directory ``test``.
|
|
|
|
The unit tests are performed on port ``loop://`` unless a different device
|
|
name or URL is given on the command line (``sys.argv[1]``). e.g. to run the
|
|
test on an attached USB-serial converter ``hwgrep://USB`` could be used or
|
|
the actual name such as ``/dev/ttyUSB0`` or ``COM1`` (depending on platform).
|
|
|
|
run_all_tests.py_
|
|
Collect all tests from all ``test*`` files and run them. By default, the
|
|
``loop://`` device is used.
|
|
|
|
test.py_
|
|
Basic tests (binary capabilities, timeout, control lines).
|
|
|
|
test_advanced.py_
|
|
Test more advanced features (properties).
|
|
|
|
test_high_load.py_
|
|
Tests involving sending a lot of data.
|
|
|
|
test_readline.py_
|
|
Tests involving ``readline``.
|
|
|
|
test_iolib.py_
|
|
Tests involving the :mod:`io` library. Only available for Python 2.6 and
|
|
newer.
|
|
|
|
test_url.py_
|
|
Tests involving the :ref:`URL <URLs>` feature.
|
|
|
|
.. _run_all_tests.py: https://github.com/pyserial/pyserial/blob/master/test/run_all_tests.py
|
|
.. _test.py: https://github.com/pyserial/pyserial/blob/master/test/test.py
|
|
.. _test_advanced.py: https://github.com/pyserial/pyserial/blob/master/test/test_advanced.py
|
|
.. _test_high_load.py: https://github.com/pyserial/pyserial/blob/master/test/test_high_load.py
|
|
.. _test_readline.py: https://github.com/pyserial/pyserial/blob/master/test/test_readline.py
|
|
.. _test_iolib.py: https://github.com/pyserial/pyserial/blob/master/test/test_iolib.py
|
|
.. _test_url.py: https://github.com/pyserial/pyserial/blob/master/test/test_url.py
|