diff options
Diffstat (limited to 'documentation/examples.rst')
| -rw-r--r-- | documentation/examples.rst | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/documentation/examples.rst b/documentation/examples.rst new file mode 100644 index 0000000..197c015 --- /dev/null +++ b/documentation/examples.rst @@ -0,0 +1,274 @@ +.. _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 |