Tools¶
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.
-
serial.tools.list_ports.
comports
(include_links=False)¶ Parameters: include_links (bool) – include symlinks under /dev
when they point to a serial portReturns: a list containing ListPortInfo
objects.The function returns a list of
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
ListPortInfo.hwid
string contains VID:PID, SER (serial number), LOCATION (hierarchy), which makes them searchable viagrep()
. The USB info is also available as attributes ofListPortInfo
.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 includeLINK
in theirhwid
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)
-
serial.tools.list_ports.
grep
(regexp, include_links=False)¶ Parameters: Returns: an iterable that yields
ListPortInfo
objects, see alsocomports()
.Search for ports using a regular expression. Port
name
,description
andhwid
are searched (case insensitive). The function returns an iterable that contains the same data thatcomports()
generates, but includes only those entries that match the regexp.
-
class
serial.tools.list_ports.
ListPortInfo
¶ This object holds information about a serial port. It supports indexed access for backwards compatibility, as in
port, desc, hwid = info
.-
device
¶ Full device name/path, e.g.
/dev/ttyUSB0
. This is also the information returned as first element when accessed by index.
-
name
¶ Short device name, e.g.
ttyUSB0
.
-
description
¶ Human readable description or
n/a
. This is also the information returned as second element when accessed by index.
-
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).-
vid
¶ USB Vendor ID (integer, 0…65535).
-
pid
¶ USB product ID (integer, 0…65535).
-
serial_number
¶ USB serial number as a string.
-
location
¶ USB device location string (“<bus>-<port>[-<port>]…”)
-
manufacturer
¶ USB manufacturer string, as reported by device.
-
product
¶ USB product string, as reported by device.
-
interface
¶ Interface specific description, e.g. used in compound USB devices.
Comparison operators are implemented such that the
ListPortInfo
objects can be sorted bydevice
. 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
New in version 2.6.
Changed in version 3.0: returning ListPortInfo
objects instead of a tuple
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 URL Handlers
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 echodebug
: Print what is sent and receiveddefault
: remove typical terminal control codes from inputdirect
: do-nothing: forward all data unchangednocontrol
: 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 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
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 (Ctrl+]) or change the port (p).
Changed in version 2.5: Added Ctrl+T menu and added support for opening URLs.
Changed in version 2.6: File moved from the examples to serial.tools.miniterm
.
Changed in version 3.0: Apply encoding on serial port, convert to Unicode for console.
Added new filters, default to stripping terminal control sequences.
Added --ask
option.
Changed in version 3.5: Enable escape code handling on Windows 10 console.