doc update: reorganize chapters/files
diff --git a/documentation/examples.rst b/documentation/examples.rst
index 5c51ef6..1114a18 100644
--- a/documentation/examples.rst
+++ b/documentation/examples.rst
@@ -4,107 +4,11 @@
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 may inherit 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 :ref:`URLs`
-such as ``rfc2217:://<host>:<port>`` respectively ``socket://<host>:<port>`` as
-*port* argument when invoking.
-
-Command line options ``python -m serial.tools.miniterm -h``::
-
- usage: miniterm.py [-h] [--parity {N,E,O,S,M}] [--rtscts] [--xonxoff]
- [--rts RTS] [--dtr DTR] [-e] [--encoding CODEC] [-f NAME]
- [--eol {CR,LF,CRLF}] [--raw] [--exit-char NUM]
- [--menu-char NUM] [-q] [--develop]
- [port] [baudrate]
-
- Miniterm - A simple terminal program for the serial port.
-
- positional arguments:
- port serial port name
- baudrate set baud rate, default: 9600
-
- optional arguments:
- -h, --help show this help message and exit
-
- port settings:
- --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)
-
- data handling:
- -e, --echo enable local echo (default off)
- --encoding CODEC set the encoding for the serial port (e.g. hexlify,
- Latin1, UTF-8), default: UTF-8
- -f NAME, --filter NAME
- add text transformation
- --eol {CR,LF,CRLF} end of line mode
- --raw Do no apply any encodings/transformations
-
- hotkeys:
- --exit-char NUM Unicode of special character that is used to exit the
- application, default: 29
- --menu-char NUM Unicode code of special character that is used to
- control miniterm (menu), default: 20
-
- diagnostics:
- -q, --quiet suppress non-error messages
- --develop show Python traceback on error
-
-
-Miniterm supports some control functions. Typing :kbd:`Ctrl+T Ctrl+H` when it is
-running shows the help text::
-
- --- pySerial (3.0a) - 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 itself to remote
- --- Ctrl+I Show info
- --- Ctrl+U Upload file (prompt will be shown)
- --- Ctrl+A encoding
- --- Ctrl+F edit filters
- --- Toggles:
- --- Ctrl+R RTS Ctrl+D DTR Ctrl+B BREAK
- --- Ctrl+E echo Ctrl+L EOL
- ---
- --- Port settings (Ctrl+T followed by the following):
- --- p change port
- --- 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:`Ctrl+T` menu and added support for opening URLs.
-.. versionchanged:: 2.6
- File moved from the examples to :mod:`serial.tools.miniterm`.
-.. versionchanged:: 3.0
- Apply encoding on serial port, convert to Unicode for console.
- Added new filters, default to stripping terminal control sequences.
+Miniterm is now available as module instead of example.
+see :ref:`miniterm` for details.
miniterm.py_
The miniterm program.
diff --git a/documentation/index.rst b/documentation/index.rst
index 9a258fe..e1699f5 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -25,8 +25,10 @@
pyserial
shortintro
- examples
pyserial_api
+ tools
+ url_handlers
+ examples
appendix
Indices and tables
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index 85dd53a..005eeda 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -47,10 +47,10 @@
:param bool dsrdtr:
Enable hardware (DSR/DTR) flow control.
- :param float write_timeout
+ :param float write_timeout:
Set a write timeout value.
- :param float inter_byte_timeout
+ :param float inter_byte_timeout:
Inter-character timeout, :const:`None` to disable (default).
:exception ValueError:
@@ -890,17 +890,6 @@
.. function:: device(number)
- :param number: Port number.
- :return: String containing device name.
- :deprecated: Use device names directly.
-
- Convert a port number to a platform dependent device name. Unfortunately
- this does not work well for all platforms; e.g. some may miss USB-Serial
- converters and enumerate only internal serial ports.
-
- The conversion may be made off-line, that is, there is no guarantee that
- the returned device name really exists on the system.
-
.. versionchanged:: 3.0 removed, use ``serial.tools.list_ports`` instead
@@ -913,7 +902,7 @@
Get a native or a :rfc:`2217` implementation of the Serial class, depending
on port/url. This factory function is useful when an application wants
to support both, local ports and remote ports. There is also support
- for other types, see :ref:`URL <URLs>` section below.
+ for other types, see :ref:`URL <URLs>` section.
The port is not opened when a keyword parameter called *do_not_open* is
given and true, by default it is opened.
@@ -967,190 +956,15 @@
.. versionadded:: 3.0
-.. _URLs:
-
-URLs
-----
-The function :func:`serial_for_url` accepts the following types of URLs:
-
-- ``rfc2217://<host>:<port>[?<option>[&<option>...]]``
-- ``socket://<host>:<port>[?logging={debug|info|warning|error}]``
-- ``loop://[?logging={debug|info|warning|error}]``
-- ``hwgrep://<regexp>``
-- ``spy://port[?option[=value][&option[=value]]]``
-
-.. versionchanged:: 3.0 Options are specified with ``?`` and ``&`` instead of ``/``
-
-Device names are also supported, e.g.:
-
-- ``/dev/ttyUSB0`` (Linux)
-- ``COM3`` (Windows)
-
-Future releases of pySerial might add more types. Since pySerial 2.6 it is also
-possible for the user to add protocol handlers using
-:attr:`protocol_handler_packages`.
-
-``rfc2217://``
- Used to connect to :rfc:`2217` compatible servers. All serial port
- functions are supported. Implemented by :class:`rfc2217.Serial`.
-
- Supported options in the URL are:
-
- - ``ign_set_control`` does not wait for acknowledges to SET_CONTROL. This
- option can be used for non compliant servers (i.e. when getting an
- ``remote rejected value for option 'control'`` error when connecting).
-
- - ``poll_modem``: The client issues NOTIFY_MODEMSTATE requests when status
- lines are read (CTS/DTR/RI/CD). Without this option it relies on the server
- sending the notifications automatically (that's what the RFC suggests and
- most servers do). Enable this option when :attr:`cts` does not work as
- expected, i.e. for servers that do not send notifications.
-
- - ``timeout=<value>``: Change network timeout (default 3 seconds). This is
- useful when the server takes a little more time to send its answers. The
- timeout applies to the initial Telnet / :rfc:`2271` negotiation as well
- as changing port settings or control line change commands.
-
- - ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
- useful for end users). It uses the logging module and a logger called
- ``pySerial.rfc2217`` so that the application can setup up logging
- handlers etc. It will call :meth:`logging.basicConfig` which initializes
- for output on ``sys.stderr`` (if no logging was set up already).
-
-``socket://``
- The purpose of this connection type is that applications using pySerial can
- connect to TCP/IP to serial port converters that do not support :rfc:`2217`.
-
- Uses a TCP/IP socket. All serial port settings, control and status lines
- are ignored. Only data is transmitted and received.
-
- Supported options in the URL are:
-
- - ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
- useful for end users). It uses the logging module and a logger called
- ``pySerial.socket`` so that the application can setup up logging handlers
- etc. It will call :meth:`logging.basicConfig` which initializes for
- output on ``sys.stderr`` (if no logging was set up already).
-
-``loop://``
- The least useful type. It simulates a loop back connection
- (``RX<->TX`` ``RTS<->CTS`` ``DTR<->DSR``). It could be used to test
- applications or run the unit tests.
-
- Supported options in the URL are:
-
- - ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
- useful for end users). It uses the logging module and a logger called
- ``pySerial.loop`` so that the application can setup up logging handlers
- etc. It will call :meth:`logging.basicConfig` which initializes for
- output on ``sys.stderr`` (if no logging was set up already).
-
-``hwgrep://``
- This type uses :mod:`serial.tools.list_ports` to obtain a list of ports and
- searches the list for matches by a regexp (see :py:mod:`re`) that follows
- the slashes.
-
- Depending on the capabilities of the list_ports module on the system, it is
- possible to search for the description or hardware ID of a device, e.g. USB
- VID:PID or texts.
-
- Unfortunately, on some systems list_ports only lists a subset of the port
- names with no additional information. Currently, on Windows and Linux and
- OSX it should find additional information.
-
-``spy://``
- Wrapping the native serial port, this protocol makes it possible to
- intercept the data received and transmitted as well as the access to the
- control lines, break and flush commands.
-
- Supported options in the URL are:
-
- - ``file=FILENAME`` output to given file or device instead of stderr
- - ``color`` enable ANSI escape sequences to colorize output
- - ``raw`` output the read and written data directly (default is to create a
- hex dump). In this mode, no control line and other commands are logged.
- - ``all`` also show ``in_waiting`` and empty ``read()`` calls (hidden by
- default because of high traffic).
-
- Example::
-
- import serial
-
- with serial.serial_for_url('spy:///dev/ttyUSB0?file=test.txt', timeout=1) as s:
- s.dtr = False
- s.write('hello world')
- s.read(20)
- s.dtr = True
- s.write(serial.to_bytes(range(256)))
- s.read(400)
- s.send_break()
-
- with open('test.txt') as f:
- print(f.read())
-
- Outputs::
-
- 000000.002 Q-RX reset_input_buffer
- 000000.002 DTR inactive
- 000000.002 TX 0000 68 65 6C 6C 6F 20 77 6F 72 6C 64 hello world
- 000001.015 RX 0000 68 65 6C 6C 6F 20 77 6F 72 6C 64 hello world
- 000001.015 DTR active
- 000001.015 TX 0000 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ................
- 000001.015 TX 0010 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F ................
- 000001.015 TX 0020 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F !"#$%&'()*+,-./
- 000001.015 TX 0030 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 0123456789:;<=>?
- 000001.015 TX 0040 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F @ABCDEFGHIJKLMNO
- 000001.016 TX 0050 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F PQRSTUVWXYZ[\]^_
- 000001.016 TX 0060 60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F `abcdefghijklmno
- 000001.016 TX 0070 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F pqrstuvwxyz{|}~.
- 000001.016 TX 0080 80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F ................
- 000001.016 TX 0090 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F ................
- 000001.016 TX 00A0 A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF ................
- 000001.016 TX 00B0 B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF ................
- 000001.016 TX 00C0 C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF ................
- 000001.016 TX 00D0 D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF ................
- 000001.016 TX 00E0 E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF ................
- 000001.016 TX 00F0 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF ................
- 000002.284 RX 0000 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ................
- 000002.284 RX 0010 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F ................
- 000002.284 RX 0020 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F !"#$%&'()*+,-./
- 000002.284 RX 0030 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 0123456789:;<=>?
- 000002.284 RX 0040 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F @ABCDEFGHIJKLMNO
- 000002.284 RX 0050 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F PQRSTUVWXYZ[\]^_
- 000002.284 RX 0060 60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F `abcdefghijklmno
- 000002.284 RX 0070 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F pqrstuvwxyz{|}~.
- 000002.284 RX 0080 80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F ................
- 000002.284 RX 0090 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F ................
- 000002.284 RX 00A0 A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF ................
- 000002.284 RX 00B0 B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF ................
- 000002.284 RX 00C0 C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF ................
- 000002.284 RX 00D0 D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF ................
- 000002.284 RX 00E0 E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF ................
- 000002.284 RX 00F0 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF ................
- 000002.284 BRK send_break 0.25
-
- .. versionadded:: 3.0
-
-
-
-Examples:
-
-- ``rfc2217://localhost:7000``
-- ``rfc2217://localhost:7000?poll_modem``
-- ``rfc2217://localhost:7000?ign_set_control&timeout=5.5``
-- ``socket://localhost:7777``
-- ``loop://?logging=debug``
-- ``hwgrep://0451:f432`` (USB VID:PID)
-- ``spy://COM54?file=log.txt``
-
-
asyncio
=======
+.. module:: serial.aio
+
.. warning:: This implementation is currently in an experimental state. Use
at your own risk.
-Experimental asyncio support is available for Python 3.4 and newer. The
+Experimental asyncio support is available for Python 3.4 and newer. The module
:mod:`serial.aio` provides a :class:`asyncio.Transport`:
``SerialTransport``.
@@ -1173,7 +987,7 @@
def connection_made(self, transport):
self.transport = transport
print('port opened', transport)
- transport.serial.setRTS(0)
+ transport.serial.rts = False
transport.write(b'hello world\n')
def data_received(self, data):
@@ -1185,93 +999,8 @@
asyncio.get_event_loop().stop()
loop = asyncio.get_event_loop()
- coro = create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
+ coro = serial.aio.create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
loop.run_until_complete(coro)
loop.run_forever()
loop.close()
-
-Tools
-=====
-
-serial.tools.list_ports
------------------------
-.. module:: serial.tools.list_ports
-.. versionadded:: 2.6
-
-This module can be executed to get a list of ports (``python -m
-serial.tools.list_ports``). It also contains the following functions.
-
-
-.. function:: comports()
-
- :return: an iterable.
-
- The function returns an iterable that yields tuples of three strings:
-
- - port name as it can be passed to :class:`serial.Serial` or
- :func:`serial.serial_for_url`
- - description in human readable form
- - sort of hardware ID. E.g. may contain VID:PID of USB-serial adapters.
-
- Items are returned in no particular order. It may make sense to sort the
- items. Also note that the reported strings are different across platforms
- and operating systems, even for the same device.
-
- .. note:: Support is limited to a number of operating systems. On some
- systems description and hardware ID will not be available
- (``None``).
-
- :platform: Posix (/dev files)
- :platform: Linux (/dev files, sysfs and lsusb)
- :platform: OSX (iokit)
- :platform: Windows (setupapi, registry)
-
-
-.. function:: grep(regexp)
-
- :param regexp: regular expression (see stdlib :mod:`re`)
- :return: filtered sequence, see :func:`comports`.
-
- Search for ports using a regular expression. Port name, description and
- hardware ID are searched (case insensitive). The function returns an
- iterable that contains the same tuples that :func:`comport` generates but
- only those that match the regexp.
-
-
-Command line usage
-
-Help for ``python -m serial.tools.list_ports``::
-
- usage: list_ports.py [-h] [-v] [-q] [-n N] [regexp]
-
- Serial port enumeration
-
- positional arguments:
- regexp only show ports that match this regex
-
- optional arguments:
- -h, --help show this help message and exit
- -v, --verbose show more messages
- -q, --quiet suppress all messages
- -n N only output the N-th entry
-
-Examples:
-
-- List all ports with details::
-
- python -m serial.tools.list_ports -v
-
-- List the 2nd port matching a USB VID:PID pattern::
-
- python -m serial.tools.list_ports 1234:5678 -q -n 2
-
-
-serial.tools.miniterm
----------------------
-.. module:: serial.tools.miniterm
-.. versionadded:: 2.6
-
-Miniterm is now available as module instead of example.
-see :ref:`miniterm` for details.
-
diff --git a/documentation/tools.rst b/documentation/tools.rst
new file mode 100644
index 0000000..962c98b
--- /dev/null
+++ b/documentation/tools.rst
@@ -0,0 +1,184 @@
+=======
+ Tools
+=======
+
+.. module:: serial
+
+serial.tools.list_ports
+=======================
+.. module:: serial.tools.list_ports
+
+This module can be executed to get a list of ports (``python -m
+serial.tools.list_ports``). It also contains the following functions.
+
+
+.. function:: comports()
+
+ :return: an iterable.
+
+ The function returns an iterable that yields tuples of three strings:
+
+ - port name as it can be passed to :class:`serial.Serial` or
+ :func:`serial.serial_for_url`
+ - description in human readable form
+ - sort of hardware ID. E.g. may contain VID:PID of USB-serial adapters.
+
+ Items are returned in no particular order. It may make sense to sort the
+ items. Also note that the reported strings are different across platforms
+ and operating systems, even for the same device.
+
+ .. note:: Support is limited to a number of operating systems. On some
+ systems description and hardware ID will not be available
+ (``None``).
+
+ :platform: Posix (/dev files)
+ :platform: Linux (/dev files, sysfs and lsusb)
+ :platform: OSX (iokit)
+ :platform: Windows (setupapi, registry)
+
+
+.. function:: grep(regexp)
+
+ :param regexp: regular expression (see stdlib :mod:`re`)
+ :return: filtered sequence, see :func:`comports`.
+
+ Search for ports using a regular expression. Port name, description and
+ hardware ID are searched (case insensitive). The function returns an
+ iterable that contains the same tuples that :func:`comport` generates but
+ only those that match the regexp.
+
+
+Command line usage
+
+Help for ``python -m serial.tools.list_ports``::
+
+ usage: list_ports.py [-h] [-v] [-q] [-n N] [regexp]
+
+ Serial port enumeration
+
+ positional arguments:
+ regexp only show ports that match this regex
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose show more messages
+ -q, --quiet suppress all messages
+ -n N only output the N-th entry
+
+Examples:
+
+- List all ports with details::
+
+ python -m serial.tools.list_ports -v
+
+- List the 2nd port matching a USB VID:PID pattern::
+
+ python -m serial.tools.list_ports 1234:5678 -q -n 2
+
+.. versionadded:: 2.6
+
+
+.. _miniterm:
+
+serial.tools.miniterm
+=====================
+.. module:: serial.tools.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 may inherit 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 :ref:`URLs`
+such as ``rfc2217:://<host>:<port>`` respectively ``socket://<host>:<port>`` as
+*port* argument when invoking.
+
+Command line options ``python -m serial.tools.miniterm -h``::
+
+ usage: miniterm.py [-h] [--parity {N,E,O,S,M}] [--rtscts] [--xonxoff]
+ [--rts RTS] [--dtr DTR] [-e] [--encoding CODEC] [-f NAME]
+ [--eol {CR,LF,CRLF}] [--raw] [--exit-char NUM]
+ [--menu-char NUM] [-q] [--develop]
+ [port] [baudrate]
+
+ Miniterm - A simple terminal program for the serial port.
+
+ positional arguments:
+ port serial port name
+ baudrate set baud rate, default: 9600
+
+ optional arguments:
+ -h, --help show this help message and exit
+
+ port settings:
+ --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)
+
+ data handling:
+ -e, --echo enable local echo (default off)
+ --encoding CODEC set the encoding for the serial port (e.g. hexlify,
+ Latin1, UTF-8), default: UTF-8
+ -f NAME, --filter NAME
+ add text transformation
+ --eol {CR,LF,CRLF} end of line mode
+ --raw Do no apply any encodings/transformations
+
+ hotkeys:
+ --exit-char NUM Unicode of special character that is used to exit the
+ application, default: 29
+ --menu-char NUM Unicode code of special character that is used to
+ control miniterm (menu), default: 20
+
+ diagnostics:
+ -q, --quiet suppress non-error messages
+ --develop show Python traceback on error
+
+
+Miniterm supports some control functions. Typing :kbd:`Ctrl+T Ctrl+H` when it is
+running shows the help text::
+
+ --- pySerial (3.0a) - 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 itself to remote
+ --- Ctrl+I Show info
+ --- Ctrl+U Upload file (prompt will be shown)
+ --- Ctrl+A encoding
+ --- Ctrl+F edit filters
+ --- Toggles:
+ --- Ctrl+R RTS Ctrl+D DTR Ctrl+B BREAK
+ --- Ctrl+E echo Ctrl+L EOL
+ ---
+ --- Port settings (Ctrl+T followed by the following):
+ --- p change port
+ --- 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:`Ctrl+T` menu and added support for opening URLs.
+.. versionchanged:: 2.6
+ File moved from the examples to :mod:`serial.tools.miniterm`.
+.. versionchanged:: 3.0
+ Apply encoding on serial port, convert to Unicode for console.
+ Added new filters, default to stripping terminal control sequences.
+
diff --git a/documentation/url_handlers.rst b/documentation/url_handlers.rst
new file mode 100644
index 0000000..9814f24
--- /dev/null
+++ b/documentation/url_handlers.rst
@@ -0,0 +1,200 @@
+==============
+ URL Handlers
+==============
+
+.. module:: serial
+
+.. _URLs:
+
+Overview
+========
+The function :func:`serial_for_url` accepts the following types of URLs:
+
+- ``rfc2217://<host>:<port>[?<option>[&<option>...]]``
+- ``socket://<host>:<port>[?logging={debug|info|warning|error}]``
+- ``loop://[?logging={debug|info|warning|error}]``
+- ``hwgrep://<regexp>``
+- ``spy://port[?option[=value][&option[=value]]]``
+
+.. versionchanged:: 3.0 Options are specified with ``?`` and ``&`` instead of ``/``
+
+Device names are also supported, e.g.:
+
+- ``/dev/ttyUSB0`` (Linux)
+- ``COM3`` (Windows)
+
+Future releases of pySerial might add more types. Since pySerial 2.6 it is also
+possible for the user to add protocol handlers using
+:attr:`protocol_handler_packages`.
+
+
+``rfc2217://``
+==============
+Used to connect to :rfc:`2217` compatible servers. All serial port
+functions are supported. Implemented by :class:`rfc2217.Serial`.
+
+Supported options in the URL are:
+
+- ``ign_set_control`` does not wait for acknowledges to SET_CONTROL. This
+ option can be used for non compliant servers (i.e. when getting an
+ ``remote rejected value for option 'control'`` error when connecting).
+
+- ``poll_modem``: The client issues NOTIFY_MODEMSTATE requests when status
+ lines are read (CTS/DTR/RI/CD). Without this option it relies on the server
+ sending the notifications automatically (that's what the RFC suggests and
+ most servers do). Enable this option when :attr:`cts` does not work as
+ expected, i.e. for servers that do not send notifications.
+
+- ``timeout=<value>``: Change network timeout (default 3 seconds). This is
+ useful when the server takes a little more time to send its answers. The
+ timeout applies to the initial Telnet / :rfc:`2271` negotiation as well
+ as changing port settings or control line change commands.
+
+- ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
+ useful for end users). It uses the logging module and a logger called
+ ``pySerial.rfc2217`` so that the application can setup up logging
+ handlers etc. It will call :meth:`logging.basicConfig` which initializes
+ for output on ``sys.stderr`` (if no logging was set up already).
+
+.. warning:: The connection is not encrypted and no authentication is
+ supported! Only use it in trusted environments.
+
+
+``socket://``
+=============
+The purpose of this connection type is that applications using pySerial can
+connect to TCP/IP to serial port converters that do not support :rfc:`2217`.
+
+Uses a TCP/IP socket. All serial port settings, control and status lines
+are ignored. Only data is transmitted and received.
+
+Supported options in the URL are:
+
+- ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
+ useful for end users). It uses the logging module and a logger called
+ ``pySerial.socket`` so that the application can setup up logging handlers
+ etc. It will call :meth:`logging.basicConfig` which initializes for
+ output on ``sys.stderr`` (if no logging was set up already).
+
+.. warning:: The connection is not encrypted and no authentication is
+ supported! Only use it in trusted environments.
+
+
+``loop://``
+===========
+The least useful type. It simulates a loop back connection
+(``RX<->TX`` ``RTS<->CTS`` ``DTR<->DSR``). It could be used to test
+applications or run the unit tests.
+
+Supported options in the URL are:
+
+- ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
+ useful for end users). It uses the logging module and a logger called
+ ``pySerial.loop`` so that the application can setup up logging handlers
+ etc. It will call :meth:`logging.basicConfig` which initializes for
+ output on ``sys.stderr`` (if no logging was set up already).
+
+
+``hwgrep://``
+=============
+This type uses :mod:`serial.tools.list_ports` to obtain a list of ports and
+searches the list for matches by a regexp (see :py:mod:`re`) that follows
+the slashes.
+
+Depending on the capabilities of the list_ports module on the system, it is
+possible to search for the description or hardware ID of a device, e.g. USB
+VID:PID or texts.
+
+Unfortunately, on some systems list_ports only lists a subset of the port
+names with no additional information. Currently, on Windows and Linux and
+OSX it should find additional information.
+
+
+``spy://``
+==========
+Wrapping the native serial port, this protocol makes it possible to
+intercept the data received and transmitted as well as the access to the
+control lines, break and flush commands. It is mainly used to debug
+applications.
+
+Supported options in the URL are:
+
+- ``file=FILENAME`` output to given file or device instead of stderr
+- ``color`` enable ANSI escape sequences to colorize output
+- ``raw`` output the read and written data directly (default is to create a
+ hex dump). In this mode, no control line and other commands are logged.
+- ``all`` also show ``in_waiting`` and empty ``read()`` calls (hidden by
+ default because of high traffic).
+
+Example::
+
+ import serial
+
+ with serial.serial_for_url('spy:///dev/ttyUSB0?file=test.txt', timeout=1) as s:
+ s.dtr = False
+ s.write('hello world')
+ s.read(20)
+ s.dtr = True
+ s.write(serial.to_bytes(range(256)))
+ s.read(400)
+ s.send_break()
+
+ with open('test.txt') as f:
+ print(f.read())
+
+Outputs::
+
+ 000000.002 Q-RX reset_input_buffer
+ 000000.002 DTR inactive
+ 000000.002 TX 0000 68 65 6C 6C 6F 20 77 6F 72 6C 64 hello world
+ 000001.015 RX 0000 68 65 6C 6C 6F 20 77 6F 72 6C 64 hello world
+ 000001.015 DTR active
+ 000001.015 TX 0000 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ................
+ 000001.015 TX 0010 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F ................
+ 000001.015 TX 0020 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F !"#$%&'()*+,-./
+ 000001.015 TX 0030 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 0123456789:;<=>?
+ 000001.015 TX 0040 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F @ABCDEFGHIJKLMNO
+ 000001.016 TX 0050 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F PQRSTUVWXYZ[\]^_
+ 000001.016 TX 0060 60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F `abcdefghijklmno
+ 000001.016 TX 0070 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F pqrstuvwxyz{|}~.
+ 000001.016 TX 0080 80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F ................
+ 000001.016 TX 0090 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F ................
+ 000001.016 TX 00A0 A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF ................
+ 000001.016 TX 00B0 B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF ................
+ 000001.016 TX 00C0 C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF ................
+ 000001.016 TX 00D0 D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF ................
+ 000001.016 TX 00E0 E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF ................
+ 000001.016 TX 00F0 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF ................
+ 000002.284 RX 0000 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ................
+ 000002.284 RX 0010 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F ................
+ 000002.284 RX 0020 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F !"#$%&'()*+,-./
+ 000002.284 RX 0030 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 0123456789:;<=>?
+ 000002.284 RX 0040 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F @ABCDEFGHIJKLMNO
+ 000002.284 RX 0050 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F PQRSTUVWXYZ[\]^_
+ 000002.284 RX 0060 60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F `abcdefghijklmno
+ 000002.284 RX 0070 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F pqrstuvwxyz{|}~.
+ 000002.284 RX 0080 80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F ................
+ 000002.284 RX 0090 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F ................
+ 000002.284 RX 00A0 A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF ................
+ 000002.284 RX 00B0 B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF ................
+ 000002.284 RX 00C0 C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF ................
+ 000002.284 RX 00D0 D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF ................
+ 000002.284 RX 00E0 E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF ................
+ 000002.284 RX 00F0 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF ................
+ 000002.284 BRK send_break 0.25
+
+.. versionadded:: 3.0
+
+
+Examples
+========
+
+- ``rfc2217://localhost:7000``
+- ``rfc2217://localhost:7000?poll_modem``
+- ``rfc2217://localhost:7000?ign_set_control&timeout=5.5``
+- ``socket://localhost:7777``
+- ``loop://?logging=debug``
+- ``hwgrep://0451:f432`` (USB VID:PID)
+- ``spy://COM54?file=log.txt``
+
+