1======= 2 Tools 3======= 4 5.. module:: serial 6 7serial.tools.list_ports 8======================= 9.. module:: serial.tools.list_ports 10 11This module can be executed to get a list of ports (``python -m 12serial.tools.list_ports``). It also contains the following functions. 13 14 15.. function:: comports(include_links=False) 16 17 :param bool include_links: include symlinks under ``/dev`` when they point 18 to a serial port 19 :return: a list containing :class:`ListPortInfo` objects. 20 21 The function returns a list of :obj:`ListPortInfo` objects. 22 23 Items are returned in no particular order. It may make sense to sort the 24 items. Also note that the reported strings are different across platforms 25 and operating systems, even for the same device. 26 27 .. note:: Support is limited to a number of operating systems. On some 28 systems description and hardware ID will not be available 29 (``None``). 30 31 Under Linux, OSX and Windows, extended information will be available for 32 USB devices (e.g. the :attr:`ListPortInfo.hwid` string contains `VID:PID`, 33 `SER` (serial number), `LOCATION` (hierarchy), which makes them searchable 34 via :func:`grep`. The USB info is also available as attributes of 35 :attr:`ListPortInfo`. 36 37 If *include_links* is true, all devices under ``/dev`` are inspected and 38 tested if they are a link to a known serial port device. These entries 39 will include ``LINK`` in their ``hwid`` string. This implies that the same 40 device listed twice, once under its original name and once under linked 41 name. 42 43 :platform: Posix (/dev files) 44 :platform: Linux (/dev files, sysfs) 45 :platform: OSX (iokit) 46 :platform: Windows (setupapi, registry) 47 48 49.. function:: grep(regexp, include_links=False) 50 51 :param regexp: regular expression (see stdlib :mod:`re`) 52 :param bool include_links: include symlinks under ``/dev`` when they point 53 to a serial port 54 :return: an iterable that yields :class:`ListPortInfo` objects, see also 55 :func:`comports`. 56 57 Search for ports using a regular expression. Port ``name``, 58 ``description`` and ``hwid`` are searched (case insensitive). The function 59 returns an iterable that contains the same data that :func:`comports` 60 generates, but includes only those entries that match the regexp. 61 62 63.. class:: ListPortInfo 64 65 This object holds information about a serial port. It supports indexed 66 access for backwards compatibility, as in ``port, desc, hwid = info``. 67 68 .. attribute:: device 69 70 Full device name/path, e.g. ``/dev/ttyUSB0``. This is also the 71 information returned as first element when accessed by index. 72 73 .. attribute:: name 74 75 Short device name, e.g. ``ttyUSB0``. 76 77 .. attribute:: description 78 79 Human readable description or ``n/a``. This is also the information 80 returned as second element when accessed by index. 81 82 .. attribute:: hwid 83 84 Technical description or ``n/a``. This is also the information 85 returned as third element when accessed by index. 86 87 USB specific data, these are all ``None`` if it is not an USB device (or the 88 platform does not support extended info). 89 90 .. attribute:: vid 91 92 USB Vendor ID (integer, 0...65535). 93 94 .. attribute:: pid 95 96 USB product ID (integer, 0...65535). 97 98 .. attribute:: serial_number 99 100 USB serial number as a string. 101 102 .. attribute:: location 103 104 USB device location string ("<bus>-<port>[-<port>]...") 105 106 .. attribute:: manufacturer 107 108 USB manufacturer string, as reported by device. 109 110 .. attribute:: product 111 112 USB product string, as reported by device. 113 114 .. attribute:: interface 115 116 Interface specific description, e.g. used in compound USB devices. 117 118 Comparison operators are implemented such that the :obj:`ListPortInfo` objects 119 can be sorted by ``device``. Strings are split into groups of numbers and 120 text so that the order is "natural" (i.e. ``com1`` < ``com2`` < 121 ``com10``). 122 123 124**Command line usage** 125 126Help for ``python -m serial.tools.list_ports``:: 127 128 usage: list_ports.py [-h] [-v] [-q] [-n N] [-s] [regexp] 129 130 Serial port enumeration 131 132 positional arguments: 133 regexp only show ports that match this regex 134 135 optional arguments: 136 -h, --help show this help message and exit 137 -v, --verbose show more messages 138 -q, --quiet suppress all messages 139 -n N only output the N-th entry 140 -s, --include-links include entries that are symlinks to real devices 141 142 143Examples: 144 145- List all ports with details:: 146 147 $ python -m serial.tools.list_ports -v 148 /dev/ttyS0 149 desc: ttyS0 150 hwid: PNP0501 151 /dev/ttyUSB0 152 desc: CP2102 USB to UART Bridge Controller 153 hwid: USB VID:PID=10C4:EA60 SER=0001 LOCATION=2-1.6 154 2 ports found 155 156 157- List the 2nd port matching a USB VID:PID pattern:: 158 159 $ python -m serial.tools.list_ports 1234:5678 -q -n 2 160 /dev/ttyUSB1 161 162.. versionadded:: 2.6 163.. versionchanged:: 3.0 returning ``ListPortInfo`` objects instead of a tuple 164 165 166.. _miniterm: 167 168serial.tools.miniterm 169===================== 170.. module:: serial.tools.miniterm 171 172This is a console application that provides a small terminal application. 173 174Miniterm itself does not implement any terminal features such as VT102 175compatibility. However it may inherit these features from the terminal it is run. 176For example on GNU/Linux running from an xterm it will support the escape 177sequences of the xterm. On Windows the typical console window is dumb and does 178not support any escapes. When ANSI.sys is loaded it supports some escapes. 179 180The default is to filter terminal control characters, see ``--filter`` for 181different options. 182 183Miniterm:: 184 185 --- Miniterm on /dev/ttyS0: 9600,8,N,1 --- 186 --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- 187 188Command line options can be given so that binary data including escapes for 189terminals are escaped or output as hex. 190 191Miniterm supports :rfc:`2217` remote serial ports and raw sockets using :ref:`URLs` 192such as ``rfc2217://<host>:<port>`` respectively ``socket://<host>:<port>`` as 193*port* argument when invoking. 194 195Command line options ``python -m serial.tools.miniterm -h``:: 196 197 usage: miniterm.py [-h] [--parity {N,E,O,S,M}] [--rtscts] [--xonxoff] 198 [--rts RTS] [--dtr DTR] [-e] [--encoding CODEC] [-f NAME] 199 [--eol {CR,LF,CRLF}] [--raw] [--exit-char NUM] 200 [--menu-char NUM] [-q] [--develop] 201 [port] [baudrate] 202 203 Miniterm - A simple terminal program for the serial port. 204 205 positional arguments: 206 port serial port name 207 baudrate set baud rate, default: 9600 208 209 optional arguments: 210 -h, --help show this help message and exit 211 212 port settings: 213 --parity {N,E,O,S,M} set parity, one of {N E O S M}, default: N 214 --rtscts enable RTS/CTS flow control (default off) 215 --xonxoff enable software flow control (default off) 216 --rts RTS set initial RTS line state (possible values: 0, 1) 217 --dtr DTR set initial DTR line state (possible values: 0, 1) 218 --ask ask again for port when open fails 219 220 data handling: 221 -e, --echo enable local echo (default off) 222 --encoding CODEC set the encoding for the serial port (e.g. hexlify, 223 Latin1, UTF-8), default: UTF-8 224 -f NAME, --filter NAME 225 add text transformation 226 --eol {CR,LF,CRLF} end of line mode 227 --raw Do no apply any encodings/transformations 228 229 hotkeys: 230 --exit-char NUM Unicode of special character that is used to exit the 231 application, default: 29 232 --menu-char NUM Unicode code of special character that is used to 233 control miniterm (menu), default: 20 234 235 diagnostics: 236 -q, --quiet suppress non-error messages 237 --develop show Python traceback on error 238 239 240Available filters (``--filter`` option): 241 242- ``colorize``: Apply different colors for received and echo 243- ``debug``: Print what is sent and received 244- ``default``: remove typical terminal control codes from input 245- ``direct``: do-nothing: forward all data unchanged 246- ``nocontrol``: Remove all control codes, incl. ``CR+LF`` 247- ``printable``: Show decimal code for all non-ASCII characters and replace most control codes 248 249 250Miniterm supports some control functions while being connected. 251Typing :kbd:`Ctrl+T Ctrl+H` when it is running shows the help text:: 252 253 --- pySerial (3.0a) - miniterm - help 254 --- 255 --- Ctrl+] Exit program 256 --- Ctrl+T Menu escape key, followed by: 257 --- Menu keys: 258 --- Ctrl+T Send the menu character itself to remote 259 --- Ctrl+] Send the exit character itself to remote 260 --- Ctrl+I Show info 261 --- Ctrl+U Upload file (prompt will be shown) 262 --- Ctrl+A encoding 263 --- Ctrl+F edit filters 264 --- Toggles: 265 --- Ctrl+R RTS Ctrl+D DTR Ctrl+B BREAK 266 --- Ctrl+E echo Ctrl+L EOL 267 --- 268 --- Port settings (Ctrl+T followed by the following): 269 --- p change port 270 --- 7 8 set data bits 271 --- N E O S M change parity (None, Even, Odd, Space, Mark) 272 --- 1 2 3 set stop bits (1, 2, 1.5) 273 --- b change baud rate 274 --- x X disable/enable software flow control 275 --- r R disable/enable hardware flow control 276 277:kbd:`Ctrl+T z` suspends the connection (port is opened) and reconnects when a 278key is pressed. This can be used to temporarily access the serial port with an 279other application, without exiting miniterm. If reconnecting fails it is 280also possible to exit (:kbd:`Ctrl+]`) or change the port (:kbd:`p`). 281 282.. versionchanged:: 2.5 283 Added :kbd:`Ctrl+T` menu and added support for opening URLs. 284.. versionchanged:: 2.6 285 File moved from the examples to :mod:`serial.tools.miniterm`. 286.. versionchanged:: 3.0 287 Apply encoding on serial port, convert to Unicode for console. 288 Added new filters, default to stripping terminal control sequences. 289 Added ``--ask`` option. 290.. versionchanged:: 3.5 291 Enable escape code handling on Windows 10 console. 292