1========== 2 Appendix 3========== 4 5How To 6====== 7 8Enable :rfc:`2217` (and other URL handlers) in programs using pySerial. 9 Patch the code where the :class:`serial.Serial` is instantiated. 10 E.g. replace:: 11 12 s = serial.Serial(...) 13 14 it with:: 15 16 s = serial.serial_for_url(...) 17 18 or for backwards compatibility to old pySerial installations:: 19 20 try: 21 s = serial.serial_for_url(...) 22 except AttributeError: 23 s = serial.Serial(...) 24 25 Assuming the application already stores port names as strings that's all 26 that is required. The user just needs a way to change the port setting of 27 your application to an ``rfc2217://`` :ref:`URL <URLs>` (e.g. by editing a 28 configuration file, GUI dialog etc.). 29 30 Please note that this enables all :ref:`URL <URLs>` types supported by 31 pySerial and that those involving the network are unencrypted and not 32 protected against eavesdropping. 33 34Test your setup. 35 Is the device not working as expected? Maybe it's time to check the 36 connection before proceeding. :ref:`miniterm` from the :ref:`examples` 37 can be used to open the serial port and do some basic tests. 38 39 To test cables, connecting RX to TX (loop back) and typing some characters 40 in :ref:`miniterm` is a simple test. When the characters are displayed 41 on the screen, then at least RX and TX work (they still could be swapped 42 though). 43 44 There is also a ``spy:://`` URL handler. It prints all calls (read/write, 45 control lines) to the serial port to a file or stderr. See :ref:`spy` 46 for details. 47 48 49FAQ 50=== 51Example works in :ref:`miniterm` but not in script. 52 The RTS and DTR lines are switched when the port is opened. This may cause 53 some processing or reset on the connected device. In such a cases an 54 immediately following call to :meth:`write` may not be received by the 55 device. 56 57 A delay after opening the port, before the first :meth:`write`, is 58 recommended in this situation. E.g. a ``time.sleep(1)`` 59 60 61Application works when .py file is run, but fails when packaged (py2exe etc.) 62 py2exe and similar packaging programs scan the sources for import 63 statements and create a list of modules that they package. pySerial may 64 create two issues with that: 65 66 - implementations for other modules are found. On Windows, it's safe to 67 exclude 'serialposix', 'serialjava' and 'serialcli' as these are not 68 used. 69 70 - :func:`serial.serial_for_url` does a dynamic lookup of protocol handlers 71 at runtime. If this function is used, the desired handlers have to be 72 included manually (e.g. 'serial.urlhandler.protocol_socket', 73 'serial.urlhandler.protocol_rfc2217', etc.). This can be done either with 74 the "includes" option in ``setup.py`` or by a dummy import in one of the 75 packaged modules. 76 77User supplied URL handlers 78 :func:`serial.serial_for_url` can be used to access "virtual" serial ports 79 identified by an :ref:`URL <URLs>` scheme. E.g. for the :rfc:`2217`: 80 ``rfc2217://``. 81 82 Custom :ref:`URL <URLs>` handlers can be added by extending the module 83 search path in :data:`serial.protocol_handler_packages`. This is possible 84 starting from pySerial V2.6. 85 86``Permission denied`` errors 87 On POSIX based systems, the user usually needs to be in a special group to 88 have access to serial ports. 89 90 On Debian based systems, serial ports are usually in the group ``dialout``, 91 so running ``sudo adduser $USER dialout`` (and logging-out and -in) enables 92 the user to access the port. 93 94Parity on Raspberry Pi 95 The Raspi has one full UART and a restricted one. On devices with built 96 in wireless (WIFI/BT) use the restricted one on the GPIO header pins. 97 If enhanced features are required, it is possible to swap UARTs, see 98 https://www.raspberrypi.org/documentation/configuration/uart.md 99 100Support for Python 2.6 or earlier 101 Support for older Python releases than 2.7 will not return to pySerial 3.x. 102 Python 2.7 is now many years old (released 2010). If you insist on using 103 Python 2.6 or earlier, it is recommend to use pySerial `2.7`_ 104 (or any 2.x version). 105 106.. _`2.7`: https://pypi.python.org/pypi/pyserial/2.7 107 108 109Related software 110================ 111 112com0com - http://com0com.sourceforge.net/ 113 Provides virtual serial ports for Windows. 114 115 116License 117======= 118Copyright (c) 2001-2020 Chris Liechti <cliechti@gmx.net> 119All Rights Reserved. 120 121Redistribution and use in source and binary forms, with or without 122modification, are permitted provided that the following conditions are 123met: 124 125 * Redistributions of source code must retain the above copyright 126 notice, this list of conditions and the following disclaimer. 127 128 * Redistributions in binary form must reproduce the above 129 copyright notice, this list of conditions and the following 130 disclaimer in the documentation and/or other materials provided 131 with the distribution. 132 133 * Neither the name of the copyright holder nor the names of its 134 contributors may be used to endorse or promote products derived 135 from this software without specific prior written permission. 136 137THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 138"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 139LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 140A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 141HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 142SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 143LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 144DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 145THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 146(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 147OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 148 149