Appendix

How To

Enable RFC 2217 (and other URL handlers) in programs using pySerial.

Patch the code where the serial.Serial is instantiated. E.g. replace:

s = serial.Serial(...)

it with:

s = serial.serial_for_url(...)

or for backwards compatibility to old pySerial installations:

try:
    s = serial.serial_for_url(...)
except AttributeError:
    s = serial.Serial(...)

Assuming the application already stores port names as strings that’s all that is required. The user just needs a way to change the port setting of your application to an rfc2217:// URL (e.g. by editing a configuration file, GUI dialog etc.).

Please note that this enables all URL types supported by pySerial and that those involving the network are unencrypted and not protected against eavesdropping.

Test your setup.

Is the device not working as expected? Maybe it’s time to check the connection before proceeding. serial.tools.miniterm from the Examples can be used to open the serial port and do some basic tests.

To test cables, connecting RX to TX (loop back) and typing some characters in serial.tools.miniterm is a simple test. When the characters are displayed on the screen, then at least RX and TX work (they still could be swapped though).

There is also a spy::// URL handler. It prints all calls (read/write, control lines) to the serial port to a file or stderr. See spy:// for details.

FAQ

Example works in serial.tools.miniterm but not in script.

The RTS and DTR lines are switched when the port is opened. This may cause some processing or reset on the connected device. In such a cases an immediately following call to write() may not be received by the device.

A delay after opening the port, before the first write(), is recommended in this situation. E.g. a time.sleep(1)

Application works when .py file is run, but fails when packaged (py2exe etc.)

py2exe and similar packaging programs scan the sources for import statements and create a list of modules that they package. pySerial may create two issues with that:

  • implementations for other modules are found. On Windows, it’s safe to exclude ‘serialposix’, ‘serialjava’ and ‘serialcli’ as these are not used.

  • serial.serial_for_url() does a dynamic lookup of protocol handlers at runtime. If this function is used, the desired handlers have to be included manually (e.g. ‘serial.urlhandler.protocol_socket’, ‘serial.urlhandler.protocol_rfc2217’, etc.). This can be done either with the “includes” option in setup.py or by a dummy import in one of the packaged modules.

User supplied URL handlers

serial.serial_for_url() can be used to access “virtual” serial ports identified by an URL scheme. E.g. for the RFC 2217: rfc2217://.

Custom URL handlers can be added by extending the module search path in serial.protocol_handler_packages. This is possible starting from pySerial V2.6.

Permission denied errors

On POSIX based systems, the user usually needs to be in a special group to have access to serial ports.

On Debian based systems, serial ports are usually in the group dialout, so running sudo adduser $USER dialout (and logging-out and -in) enables the user to access the port.

Parity on Raspberry Pi

The Raspi has one full UART and a restricted one. On devices with built in wireless (WIFI/BT) use the restricted one on the GPIO header pins. If enhanced features are required, it is possible to swap UARTs, see https://www.raspberrypi.org/documentation/configuration/uart.md

Support for Python 2.6 or earlier

Support for older Python releases than 2.7 will not return to pySerial 3.x. Python 2.7 is now many years old (released 2010). If you insist on using Python 2.6 or earlier, it is recommend to use pySerial 2.7 (or any 2.x version).

License

Copyright (c) 2001-2020 Chris Liechti <cliechti@gmx.net> All Rights Reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.