1.. _URLs: 2 3============== 4 URL Handlers 5============== 6 7.. module:: serial 8 9Overview 10======== 11The function :func:`serial_for_url` accepts the following types of URLs: 12 13- ``rfc2217://<host>:<port>[?<option>[&<option>...]]`` 14- ``socket://<host>:<port>[?logging={debug|info|warning|error}]`` 15- ``loop://[?logging={debug|info|warning|error}]`` 16- ``hwgrep://<regexp>[&skip_busy][&n=N]`` 17- ``spy://port[?option[=value][&option[=value]]]`` 18- ``alt://port?class=<classname>`` 19- ``cp2110://<bus>:<dev>:<if>`` 20 21.. versionchanged:: 3.0 Options are specified with ``?`` and ``&`` instead of ``/`` 22 23Device names are also supported, e.g.: 24 25- ``/dev/ttyUSB0`` (Linux) 26- ``COM3`` (Windows) 27 28Future releases of pySerial might add more types. Since pySerial 2.6 it is also 29possible for the user to add protocol handlers using 30:attr:`protocol_handler_packages`. 31 32 33``rfc2217://`` 34============== 35Used to connect to :rfc:`2217` compatible servers. All serial port 36functions are supported. Implemented by :class:`rfc2217.Serial`. 37 38Supported options in the URL are: 39 40- ``ign_set_control`` does not wait for acknowledges to SET_CONTROL. This 41 option can be used for non compliant servers (i.e. when getting an 42 ``remote rejected value for option 'control'`` error when connecting). 43 44- ``poll_modem``: The client issues NOTIFY_MODEMSTATE requests when status 45 lines are read (CTS/DTR/RI/CD). Without this option it relies on the server 46 sending the notifications automatically (that's what the RFC suggests and 47 most servers do). Enable this option when :attr:`cts` does not work as 48 expected, i.e. for servers that do not send notifications. 49 50- ``timeout=<value>``: Change network timeout (default 3 seconds). This is 51 useful when the server takes a little more time to send its answers. The 52 timeout applies to the initial Telnet / :rfc:`2217` negotiation as well 53 as changing port settings or control line change commands. 54 55- ``logging={debug|info|warning|error}``: Prints diagnostic messages (not 56 useful for end users). It uses the logging module and a logger called 57 ``pySerial.rfc2217`` so that the application can setup up logging 58 handlers etc. It will call :meth:`logging.basicConfig` which initializes 59 for output on ``sys.stderr`` (if no logging was set up already). 60 61.. warning:: The connection is not encrypted and no authentication is 62 supported! Only use it in trusted environments. 63 64 65``socket://`` 66============= 67The purpose of this connection type is that applications using pySerial can 68connect to TCP/IP to serial port converters that do not support :rfc:`2217`. 69 70Uses a TCP/IP socket. All serial port settings, control and status lines 71are ignored. Only data is transmitted and received. 72 73Supported options in the URL are: 74 75- ``logging={debug|info|warning|error}``: Prints diagnostic messages (not 76 useful for end users). It uses the logging module and a logger called 77 ``pySerial.socket`` so that the application can setup up logging handlers 78 etc. It will call :meth:`logging.basicConfig` which initializes for 79 output on ``sys.stderr`` (if no logging was set up already). 80 81.. warning:: The connection is not encrypted and no authentication is 82 supported! Only use it in trusted environments. 83 84 85``loop://`` 86=========== 87The least useful type. It simulates a loop back connection 88(``RX<->TX`` ``RTS<->CTS`` ``DTR<->DSR``). It could be used to test 89applications or run the unit tests. 90 91Supported options in the URL are: 92 93- ``logging={debug|info|warning|error}``: Prints diagnostic messages (not 94 useful for end users). It uses the logging module and a logger called 95 ``pySerial.loop`` so that the application can setup up logging handlers 96 etc. It will call :meth:`logging.basicConfig` which initializes for 97 output on ``sys.stderr`` (if no logging was set up already). 98 99 100``hwgrep://`` 101============= 102This type uses :mod:`serial.tools.list_ports` to obtain a list of ports and 103searches the list for matches by a regexp that follows the slashes (see Pythons 104:py:mod:`re` module for detailed syntax information). 105 106Note that options are separated using the character ``&``, this also applies to 107the first, where URLs usually use ``?``. This exception is made as the question 108mark is used in regexp itself. 109 110Depending on the capabilities of the ``list_ports`` module on the system, it is 111possible to search for the description or hardware ID of a device, e.g. USB 112VID:PID or texts. 113 114Unfortunately, on some systems ``list_ports`` only lists a subset of the port 115names with no additional information. Currently, on Windows and Linux and 116OSX it should find additional information. 117 118Supported options in the URL are: 119 120- ``n=N``: pick the N'th entry instead of the first 121- ``skip_busy``: skip ports that can not be opened, e.g. because they are 122 already in use. This may not work as expected on platforms where the file is 123 not locked automatically (e.g. Posix). 124 125 126.. _spy: 127 128``spy://`` 129========== 130Wrapping the native serial port, this protocol makes it possible to 131intercept the data received and transmitted as well as the access to the 132control lines, break and flush commands. It is mainly used to debug 133applications. 134 135Supported options in the URL are: 136 137- ``file=FILENAME`` output to given file or device instead of stderr 138- ``color`` enable ANSI escape sequences to colorize output 139- ``raw`` output the read and written data directly (default is to create a 140 hex dump). In this mode, no control line and other commands are logged. 141- ``all`` also show ``in_waiting`` and empty ``read()`` calls (hidden by 142 default because of high traffic). 143- ``log`` or ``log=LOGGERNAME`` output to stdlib ``logging`` module. Default 144 channel name is ``serial``. This variant outputs hex dump. 145- ``rawlog`` or ``rawlog=LOGGERNAME`` output to stdlib ``logging`` module. Default 146 channel name is ``serial``. This variant outputs text (``repr``). 147 148The ``log`` and ``rawlog`` options require that the logging is set up, in order 149to see the log output. 150 151Example:: 152 153 import serial 154 155 with serial.serial_for_url('spy:///dev/ttyUSB0?file=test.txt', timeout=1) as s: 156 s.dtr = False 157 s.write('hello world') 158 s.read(20) 159 s.dtr = True 160 s.write(serial.to_bytes(range(256))) 161 s.read(400) 162 s.send_break() 163 164 with open('test.txt') as f: 165 print(f.read()) 166 167Outputs:: 168 169 000000.002 Q-RX reset_input_buffer 170 000000.002 DTR inactive 171 000000.002 TX 0000 68 65 6C 6C 6F 20 77 6F 72 6C 64 hello world 172 000001.015 RX 0000 68 65 6C 6C 6F 20 77 6F 72 6C 64 hello world 173 000001.015 DTR active 174 000001.015 TX 0000 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ................ 175 000001.015 TX 0010 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F ................ 176 000001.015 TX 0020 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F !"#$%&'()*+,-./ 177 000001.015 TX 0030 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 0123456789:;<=>? 178 000001.015 TX 0040 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F @ABCDEFGHIJKLMNO 179 000001.016 TX 0050 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F PQRSTUVWXYZ[\]^_ 180 000001.016 TX 0060 60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F `abcdefghijklmno 181 000001.016 TX 0070 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F pqrstuvwxyz{|}~. 182 000001.016 TX 0080 80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F ................ 183 000001.016 TX 0090 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F ................ 184 000001.016 TX 00A0 A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF ................ 185 000001.016 TX 00B0 B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF ................ 186 000001.016 TX 00C0 C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF ................ 187 000001.016 TX 00D0 D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF ................ 188 000001.016 TX 00E0 E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF ................ 189 000001.016 TX 00F0 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF ................ 190 000002.284 RX 0000 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ................ 191 000002.284 RX 0010 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F ................ 192 000002.284 RX 0020 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F !"#$%&'()*+,-./ 193 000002.284 RX 0030 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 0123456789:;<=>? 194 000002.284 RX 0040 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F @ABCDEFGHIJKLMNO 195 000002.284 RX 0050 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F PQRSTUVWXYZ[\]^_ 196 000002.284 RX 0060 60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F `abcdefghijklmno 197 000002.284 RX 0070 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F pqrstuvwxyz{|}~. 198 000002.284 RX 0080 80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F ................ 199 000002.284 RX 0090 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F ................ 200 000002.284 RX 00A0 A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF ................ 201 000002.284 RX 00B0 B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF ................ 202 000002.284 RX 00C0 C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF ................ 203 000002.284 RX 00D0 D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF ................ 204 000002.284 RX 00E0 E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF ................ 205 000002.284 RX 00F0 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF ................ 206 000002.284 BRK send_break 0.25 207 208Another example, on POSIX, open a second terminal window and find out it's 209device (e.g. with the ``ps`` command in the TTY column), assumed to be 210``/dev/pts/2`` here, double quotes are used so that the ampersand in the URL is 211not interpreted by the shell:: 212 213 python -m serial.tools.miniterm "spy:///dev/ttyUSB0?file=/dev/pts/2&color" 115200 214 215The spy output will be live in the second terminal window. 216 217.. versionadded:: 3.0 218.. versionchanged:: 3.6 Added ``log`` and ``rawlog`` options 219 220 221``alt://`` 222========== 223This handler allows to select alternate implementations of the native serial 224port. 225 226Currently only the POSIX platform provides alternative implementations. 227 228``PosixPollSerial`` 229 Poll based read implementation. Not all systems support poll properly. 230 However this one has better handling of errors, such as a device 231 disconnecting while it's in use (e.g. USB-serial unplugged). 232 233``VTIMESerial`` 234 Implement timeout using ``VTIME``/``VMIN`` of TTY device instead of using 235 ``select``. This means that inter character timeout and overall timeout 236 can not be used at the same time. Overall timeout is disabled when 237 inter-character timeout is used. The error handling is degraded. 238 239 240Examples:: 241 242 alt:///dev/ttyUSB0?class=PosixPollSerial 243 alt:///dev/ttyUSB0?class=VTIMESerial 244 245.. versionadded:: 3.0 246 247 248``cp2110://`` 249============= 250This backend implements support for HID-to-UART devices manufactured by Silicon 251Labs and marketed as CP2110 and CP2114. The implementation is (mostly) 252OS-independent and in userland. It relies on `cython-hidapi`_. 253 254.. _cython-hidapi: https://github.com/trezor/cython-hidapi 255 256Examples:: 257 258 cp2110://0001:004a:00 259 cp2110://0002:0077:00 260 261.. versionadded:: 3.5 262 263Examples 264======== 265 266- ``rfc2217://localhost:7000`` 267- ``rfc2217://localhost:7000?poll_modem`` 268- ``rfc2217://localhost:7000?ign_set_control&timeout=5.5`` 269- ``socket://localhost:7777`` 270- ``loop://?logging=debug`` 271- ``hwgrep://0451:f432`` (USB VID:PID) 272- ``spy://COM54?file=log.txt`` 273- ``alt:///dev/ttyUSB0?class=PosixPollSerial`` 274- ``cp2110://0001:004a:00`` 275