diff options
Diffstat (limited to 'documentation/examples.rst')
| -rw-r--r-- | documentation/examples.rst | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/documentation/examples.rst b/documentation/examples.rst new file mode 100644 index 0000000..a22f5e0 --- /dev/null +++ b/documentation/examples.rst @@ -0,0 +1,355 @@ +.. _examples: + +========== + Examples +========== + +.. _miniterm: + +Miniterm +======== +This is a console application that provides a small terminal application. +miniterm itself does not implement any terminal features such as VT102 +compatibility. However it inherits these features from the terminal it is run. +For example on GNU/Linux running from an xterm it will support the escape +sequences of the xterm. On Windows the typical console window is dumb and does +not support any escapes. When ANSI.sys is loaded it supports some escapes. + +miniterm:: + + --- Miniterm on /dev/ttyS0: 9600,8,N,1 --- + --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- + +Command line options can be given so that binary data including escapes for +terminals are escaped or output as hex. + +miniterm supports :rfc:`2217` remote serial ports and raw sockets using URLs +such as ``rfc2217:://<host>:<port>`` respectively ``socket://<host>:<port>`` as +*port* argument when invoking. + +Command line options ``miniterm.py -h``:: + + Usage: miniterm.py [options] [port [baudrate]] + + Miniterm - A simple terminal program for the serial port. + + Options: + -h, --help show this help message and exit + -p PORT, --port=PORT port, a number (default 0) or a device name + (deprecated option) + -b BAUDRATE, --baud=BAUDRATE + set baud rate, default 9600 + --parity=PARITY set parity, one of [N, E, O, S, M], default=N + -e, --echo enable local echo (default off) + --rtscts enable RTS/CTS flow control (default off) + --xonxoff enable software flow control (default off) + --cr do not send CR+LF, send CR only + --lf do not send CR+LF, send LF only + -D, --debug debug received data (escape non-printable chars) + --debug can be given multiple times: 0: just print + what is received 1: escape non-printable characters, + do newlines as unusual 2: escape non-printable + characters, newlines too 3: hex dump everything + --rts=RTS_STATE set initial RTS line state (possible values: 0, 1) + --dtr=DTR_STATE set initial DTR line state (possible values: 0, 1) + -q, --quiet suppress non error messages + --exit-char=EXIT_CHAR + ASCII code of special character that is used to exit + the application + --menu-char=MENU_CHAR + ASCII code of special character that is used to + control miniterm (menu) + + +miniterm supports some control functions. Typing :kbd:`Control+t Control+h` when it is +running shows the help text:: + + --- pySerial - miniterm - help + --- + --- Ctrl+] Exit program + --- Ctrl+T Menu escape key, followed by: + --- Menu keys: + --- Ctrl+T Send the menu character itself to remote + --- Ctrl+] Send the exit character to remote + --- Ctrl+I Show info + --- Ctrl+U Upload file (prompt will be shown) + --- Toggles: + --- Ctrl+R RTS Ctrl+E local echo + --- Ctrl+D DTR Ctrl+B BREAK + --- Ctrl+L line feed Ctrl+A Cycle repr mode + --- + --- Port settings (Ctrl+T followed by the following): + --- 7 8 set data bits + --- n e o s m change parity (None, Even, Odd, Space, Mark) + --- 1 2 3 set stop bits (1, 2, 1.5) + --- b change baud rate + --- x X disable/enable software flow control + --- r R disable/enable hardware flow control + +.. versionchanged:: 2.5 + Added :kbd:`Control+t` menu and added support for opening URLs. + +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: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/miniterm.py +.. _setup-miniterm-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/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 [options] [port [baudrate]] + + Simple Serial to Network (TCP/IP) redirector. + + Options: + -h, --help show this help message and exit + -q, --quiet suppress non error messages + --spy peek at the communication and print all data to the + console + + Serial Port: + Serial port settings + + -p PORT, --port=PORT + port, a number (default 0) or a device name + -b BAUDRATE, --baud=BAUDRATE + set baud rate, default: 9600 + --parity=PARITY set parity, one of [N, E, O], default=N + --rtscts enable RTS/CTS flow control (default off) + --xonxoff enable software flow control (default off) + --rts=RTS_STATE set initial RTS line state (possible values: 0, 1) + --dtr=DTR_STATE set initial DTR line state (possible values: 0, 1) + + Network settings: + Network configuration. + + -P LOCAL_PORT, --localport=LOCAL_PORT + local TCP port + --rfc2217 allow control commands with Telnet extension RFC-2217 + + Newline Settings: + Convert newlines between network and serial port. Conversion is + normally disabled and can be enabled by --convert. + + -c, --convert enable newline conversion (default off) + --net-nl=NET_NEWLINE + type of newlines that are expected on the network + (default: LF) + --ser-nl=SER_NEWLINE + type of newlines that are expected on the serial port + (default: CR+LF) + + 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: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/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 an other 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 [options] port + + RFC 2217 Serial to Network (TCP/IP) redirector. + + Options: + -h, --help show this help message and exit + -p LOCAL_PORT, --localport=LOCAL_PORT + 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. + +.. 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: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/rfc2217_server.py +.. _setup-rfc2217_server-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/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.) + +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`` +- Thats 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: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/port_publisher.py +.. _port_publisher.sh: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/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: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxTerminal.py +.. _wxTerminal.wxg: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxTerminal.wxg +.. _wxSerialConfigDialog.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxSerialConfigDialog.py +.. _wxSerialConfigDialog.wxg: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxSerialConfigDialog.wxg +.. _setup-wxTerminal-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup-wxTerminal-py2exe.py + + +Wrapper class +============= +This example provides a subclass based on ``Serial`` that has an alternative +implementation of ``readline()`` + +enhancedserial.py_ + A class with alternative ``readline()`` implementation. + +.. _enhancedserial.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/enhancedserial.py + + +Finding serial ports +==================== +scan.py_ + A simple loop that probes serial ports by number. + +scanlinux.py_ + A Linux only version looking at the entries in ``/dev``. It works best with + on systems with devfs or udev that only create those entries that represent + devices. On older installations a lot of pre-created device files are found + and an additional open check should be added to ensure that the device is + real. + +scanwin32.py_ + A Windows only version that returns a list of serial ports with information + from the registry. + +.. _scan.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scan.py +.. _scanlinux.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanlinux.py +.. _scanwin32.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanwin32.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 ``0`` unless a different device name or +``rfc2217://`` URL is given on the command line (argv[1]). + +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. + +.. _run_all_tests.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/run_all_tests.py +.. _test.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test.py +.. _test_advanced.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_advanced.py +.. _test_high_load.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_high_load.py +.. _test_readline.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_readline.py +.. _test_iolib.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_iolib.py |