| ======= |
| 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(include_links=False) |
| |
| :param bool include_links: include symlinks under ``/dev`` when they point |
| to a serial port |
| :return: a list containing :class:`ListPortInfo` objects. |
| |
| The function returns a list of :obj:`ListPortInfo` objects. |
| |
| 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``). |
| |
| Under Linux, OSX and Windows, extended information will be available for |
| USB devices (e.g. the :attr:`ListPortInfo.hwid` string contains `VID:PID`, |
| `SER` (serial number), `LOCATION` (hierarchy), which makes them searchable |
| via :func:`grep`. The USB info is also available as attributes of |
| :attr:`ListPortInfo`. |
| |
| If *include_links* is true, all devices under ``/dev`` are inspected and |
| tested if they are a link to a known serial port device. These entries |
| will include ``LINK`` in their ``hwid`` string. This implies that the same |
| device listed twice, once under its original name and once under linked |
| name. |
| |
| :platform: Posix (/dev files) |
| :platform: Linux (/dev files, sysfs) |
| :platform: OSX (iokit) |
| :platform: Windows (setupapi, registry) |
| |
| |
| .. function:: grep(regexp, include_links=False) |
| |
| :param regexp: regular expression (see stdlib :mod:`re`) |
| :param bool include_links: include symlinks under ``/dev`` when they point |
| to a serial port |
| :return: an iterable that yields :class:`ListPortInfo` objects, see also |
| :func:`comports`. |
| |
| Search for ports using a regular expression. Port ``name``, |
| ``description`` and ``hwid`` are searched (case insensitive). The function |
| returns an iterable that contains the same data that :func:`comports` |
| generates, but includes only those entries that match the regexp. |
| |
| |
| .. class:: ListPortInfo |
| |
| This object holds information about a serial port. It supports indexed |
| access for backwards compatibility, as in ``port, desc, hwid = info``. |
| |
| .. attribute:: device |
| |
| Full device name/path, e.g. ``/dev/ttyUSB0``. This is also the |
| information returned as first element when accessed by index. |
| |
| .. attribute:: name |
| |
| Short device name, e.g. ``ttyUSB0``. |
| |
| .. attribute:: description |
| |
| Human readable description or ``n/a``. This is also the information |
| returned as second element when accessed by index. |
| |
| .. attribute:: hwid |
| |
| Technical description or ``n/a``. This is also the information |
| returned as third element when accessed by index. |
| |
| USB specific data, these are all ``None`` if it is not an USB device (or the |
| platform does not support extended info). |
| |
| .. attribute:: vid |
| |
| USB Vendor ID (integer, 0...65535). |
| |
| .. attribute:: pid |
| |
| USB product ID (integer, 0...65535). |
| |
| .. attribute:: serial_number |
| |
| USB serial number as a string. |
| |
| .. attribute:: location |
| |
| USB device location string ("<bus>-<port>[-<port>]...") |
| |
| .. attribute:: manufacturer |
| |
| USB manufacturer string, as reported by device. |
| |
| .. attribute:: product |
| |
| USB product string, as reported by device. |
| |
| .. attribute:: interface |
| |
| Interface specific description, e.g. used in compound USB devices. |
| |
| Comparison operators are implemented such that the :obj:`ListPortInfo` objects |
| can be sorted by ``device``. Strings are split into groups of numbers and |
| text so that the order is "natural" (i.e. ``com1`` < ``com2`` < |
| ``com10``). |
| |
| |
| **Command line usage** |
| |
| Help for ``python -m serial.tools.list_ports``:: |
| |
| usage: list_ports.py [-h] [-v] [-q] [-n N] [-s] [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 |
| -s, --include-links include entries that are symlinks to real devices |
| |
| |
| Examples: |
| |
| - List all ports with details:: |
| |
| $ python -m serial.tools.list_ports -v |
| /dev/ttyS0 |
| desc: ttyS0 |
| hwid: PNP0501 |
| /dev/ttyUSB0 |
| desc: CP2102 USB to UART Bridge Controller |
| hwid: USB VID:PID=10C4:EA60 SER=0001 LOCATION=2-1.6 |
| 2 ports found |
| |
| |
| - List the 2nd port matching a USB VID:PID pattern:: |
| |
| $ python -m serial.tools.list_ports 1234:5678 -q -n 2 |
| /dev/ttyUSB1 |
| |
| .. versionadded:: 2.6 |
| .. versionchanged:: 3.0 returning ``ListPortInfo`` objects instead of a tuple |
| |
| |
| .. _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. |
| |
| The default is to filter terminal control characters, see ``--filter`` for |
| different options. |
| |
| 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) |
| --ask ask again for port when open fails |
| |
| 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 |
| |
| |
| Available filters (``--filter`` option): |
| |
| - ``colorize``: Apply different colors for received and echo |
| - ``debug``: Print what is sent and received |
| - ``default``: remove typical terminal control codes from input |
| - ``direct``: do-nothing: forward all data unchanged |
| - ``nocontrol``: Remove all control codes, incl. ``CR+LF`` |
| - ``printable``: Show decimal code for all non-ASCII characters and replace most control codes |
| |
| |
| Miniterm supports some control functions while being connected. |
| 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 |
| |
| :kbd:`Ctrl+T z` suspends the connection (port is opened) and reconnects when a |
| key is pressed. This can be used to temporarily access the serial port with an |
| other application, without exiting miniterm. If reconnecting fails it is |
| also possible to exit (:kbd:`Ctrl+]`) or change the port (:kbd:`p`). |
| |
| .. 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. |
| Added ``--ask`` option. |
| .. versionchanged:: 3.5 |
| Enable escape code handling on Windows 10 console. |
