292 lines
10 KiB
ReStructuredText
292 lines
10 KiB
ReStructuredText
|
=======
|
||
|
|
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.
|