diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/appendix.rst | 6 | ||||
| -rw-r--r-- | documentation/conf.py | 4 | ||||
| -rw-r--r-- | documentation/examples.rst | 8 | ||||
| -rw-r--r-- | documentation/index.rst | 1 | ||||
| -rw-r--r-- | documentation/pyserial.rst | 19 | ||||
| -rw-r--r-- | documentation/pyserial_api.rst | 68 | ||||
| -rw-r--r-- | documentation/shortintro.rst | 2 | ||||
| -rw-r--r-- | documentation/tools.rst | 47 | ||||
| -rw-r--r-- | documentation/url_handlers.rst | 9 |
9 files changed, 120 insertions, 44 deletions
diff --git a/documentation/appendix.rst b/documentation/appendix.rst index 80ade6d..57e8e2f 100644 --- a/documentation/appendix.rst +++ b/documentation/appendix.rst @@ -68,7 +68,7 @@ Application works when .py file is run, but fails when packaged (py2exe etc.) used. - :func:`serial.serial_for_url` does a dynamic lookup of protocol handlers - at runtime. If this function is used, the desired handlers have to be + 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 @@ -93,7 +93,7 @@ User supplied URL handlers 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.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). @@ -109,7 +109,7 @@ com0com - http://com0com.sourceforge.net/ License ======= -Copyright (c) 2001-2016 Chris Liechti <cliechti@gmx.net> +Copyright (c) 2001-2017 Chris Liechti <cliechti@gmx.net> All Rights Reserved. Redistribution and use in source and binary forms, with or without diff --git a/documentation/conf.py b/documentation/conf.py index 64605a6..df9d14e 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -45,9 +45,9 @@ copyright = u'2001-2017, Chris Liechti' # built documents. # # The short X.Y version. -version = '3.3' +version = '3.4' # The full version, including alpha/beta/rc tags. -release = '3.3' +release = '3.4' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/documentation/examples.rst b/documentation/examples.rst index 787fd00..0430267 100644 --- a/documentation/examples.rst +++ b/documentation/examples.rst @@ -237,8 +237,10 @@ The project uses a number of unit test to verify the functionality. They all need a loop back connector. The scripts itself contain more information. All test scripts are contained in the directory ``test``. -The unit tests are performed on port ``0`` unless a different device name or -``rfc2217://`` URL is given on the command line (argv[1]). +The unit tests are performed on port ``loop://`` unless a different device +name or URL is given on the command line (``sys.argv[1]``). e.g. to run the +test on an attached USB-serial converter ``hwgrep://USB`` could be used or +the actual name such as ``/dev/ttyUSB0`` or ``COM1`` (depending on platform). run_all_tests.py_ Collect all tests from all ``test*`` files and run them. By default, the @@ -254,7 +256,7 @@ test_high_load.py_ Tests involving sending a lot of data. test_readline.py_ - Tests involving readline. + Tests involving ``readline``. test_iolib.py_ Tests involving the :mod:`io` library. Only available for Python 2.6 and diff --git a/documentation/index.rst b/documentation/index.rst index 10bf305..c3ca19d 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -1,4 +1,5 @@ .. pySerial documentation master file +.. _welcome: Welcome to pySerial's documentation =================================== diff --git a/documentation/pyserial.rst b/documentation/pyserial.rst index 602134d..8a1afa8 100644 --- a/documentation/pyserial.rst +++ b/documentation/pyserial.rst @@ -48,7 +48,7 @@ Requirements ============ - Python 2.7 or Python 3.4 and newer -- If running on Windows: Something newer than WinXP +- If running on Windows: Windows 7 or newer - If running on Jython: "Java Communications" (JavaComm) or compatible extension for Java @@ -76,6 +76,21 @@ Using the `python`/`python3` executable of the desired version (2.7/3.x). Developers also may be interested to get the source archive, because it contains examples, tests and the this documentation. +From Conda +---------- +pySerial can be installed from Conda:: + + conda install pyserial + + or + + conda install -c conda-forge pyserial + +Currently the default conda channel will provide version 3.4 whereas the +conda-forge channel provides the current 3.x version. + +Conda: https://www.continuum.io/downloads + From source (zip/tar.gz or checkout) ------------------------------------ Download the archive from http://pypi.python.org/pypi/pyserial or @@ -93,7 +108,7 @@ There are also packaged versions for some Linux distributions: - Debian/Ubuntu: "python-serial", "python3-serial" - Fedora / RHEL / CentOS / EPEL: "pyserial" - Arch Linux: "python-pyserial" -- Gento: "dev-python/pyserial" +- Gentoo: "dev-python/pyserial" Note that some distributions may package an older version of pySerial. These packages are created and maintained by developers working on diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst index 65eeae5..76177dd 100644 --- a/documentation/pyserial_api.rst +++ b/documentation/pyserial_api.rst @@ -36,7 +36,7 @@ Native ports :const:`STOPBITS_TWO` :param float timeout: - Set a read timeout value. + Set a read timeout value in seconds. :param bool xonxoff: Enable software flow control. @@ -48,7 +48,7 @@ Native ports Enable hardware (DSR/DTR) flow control. :param float write_timeout: - Set a write timeout value. + Set a write timeout value in seconds. :param float inter_byte_timeout: Inter-character timeout, :const:`None` to disable (default). @@ -122,7 +122,7 @@ Native ports Some OS and/or drivers may activate RTS and or DTR automatically, as soon as the port is opened. There may be a glitch on RTS/DTR - when :attr:`rts`` or :attr:`dtr` are set differently from their + when :attr:`rts` or :attr:`dtr` are set differently from their default value (``True`` / active). .. note:: @@ -157,6 +157,22 @@ Native ports Returns an instance of :class:`bytes` when available (Python 2.6 and newer) and :class:`str` otherwise. + .. method:: read_until(expected=LF, size=None) + + :param expected: The byte string to search for. + :param size: Number of bytes to read. + :return: Bytes read from the port. + :rtype: bytes + + Read until an expected sequence is found ('\\n' by default), the size + is exceeded or until timeout occurs. If a timeout is set it may + return less characters as requested. With no timeout it will block + until the requested number of bytes is read. + + .. versionchanged:: 2.5 + Returns an instance of :class:`bytes` when available (Python 2.6 + and newer) and :class:`str` otherwise. + .. method:: write(data) :param data: Data to send. @@ -205,7 +221,7 @@ Native ports .. method:: reset_input_buffer() - Flush input buffer, discarding all it's contents. + Flush input buffer, discarding all its contents. .. versionchanged:: 3.0 renamed from ``flushInput()`` @@ -221,7 +237,7 @@ Native ports .. method:: send_break(duration=0.25) - :param float duration: Time to activate the BREAK condition. + :param float duration: Time in seconds, to activate the BREAK condition. Send break condition. Timed, returns to idle state after given duration. @@ -243,7 +259,7 @@ Native ports :type: bool Set RTS line to specified logic level. It is possible to assign this - value before opening the serial port, then the value is applied uppon + value before opening the serial port, then the value is applied upon :meth:`open` (with restrictions, see :meth:`open`). .. attribute:: dtr @@ -253,7 +269,7 @@ Native ports :type: bool Set DTR line to specified logic level. It is possible to assign this - value before opening the serial port, then the value is applied uppon + value before opening the serial port, then the value is applied upon :meth:`open` (with restrictions, see :meth:`open`). Read-only attributes: @@ -465,6 +481,18 @@ Native ports .. versionadded:: 2.5 + .. method:: readline(size=-1) + + Provided via :meth:`io.IOBase.readline` + + .. method:: readlines(hint=-1) + + Provided via :meth:`io.IOBase.readlines` + + .. method:: writelines(lines) + + Provided via :meth:`io.IOBase.writelines` + The port settings can be read and written as dictionary. The following keys are supported: ``write_timeout``, ``inter_byte_timeout``, ``dsrdtr``, ``baudrate``, ``timeout``, ``parity``, ``bytesize``, @@ -515,17 +543,22 @@ Native ports >>> with serial.serial_for_url(port) as s: ... s.write(b'hello') - Here no port argument is given, so it is not opened automatically: + The port is opened automatically: - >>> with serial.Serial() as s: - ... s.port = ... - ... s.open() + >>> port = serial.Serial() + >>> port.port = '...' + >>> with port as s: ... s.write(b'hello') + Which also means that ``with`` statements can be used repeatedly, + each time opening and closing the port. + + .. versionchanged:: 3.4 the port is automatically opened + .. method:: __exit__(exc_type, exc_val, exc_tb) - Closes serial port. + Closes serial port (exceptions are not handled by ``__exit__``). Platform specific methods. @@ -618,7 +651,7 @@ Native ports .. method:: isOpen() - .. deprecated:: 3.0 see :attr:`is_open` + .. deprecated:: 3.0 see :attr:`is_open` .. attribute:: writeTimeout @@ -701,8 +734,10 @@ Native ports Implementation detail: some attributes and functions are provided by the -class :class:`SerialBase` and some by the platform specific class and -others by the base class mentioned above. +class :class:`serial.SerialBase` which inherits from :class:`io.RawIOBase` +and some by the platform specific class and others by the base class +mentioned above. + RS485 support ------------- @@ -795,7 +830,6 @@ on regular serial ports (``serial.rs485`` needs to be imported). - :rfc:`2217` Network ports ------------------------- @@ -1060,7 +1094,7 @@ Module functions and attributes :returns: a generator that yields bytes Some versions of Python (3.x) would return integers instead of bytes when - looping over an instance of ``bytes``. This helper function ensures that + looping over an instance of ``bytes``. This helper function ensures that bytes are returned. .. versionadded:: 3.0 diff --git a/documentation/shortintro.rst b/documentation/shortintro.rst index 02385d9..b9230e3 100644 --- a/documentation/shortintro.rst +++ b/documentation/shortintro.rst @@ -108,5 +108,5 @@ include entries that matched. Accessing ports --------------- pySerial includes a small console based terminal program called -:ref:`miniterm`. It ca be started with ``python -m serial.tools.miniterm <port_name>`` +:ref:`miniterm`. It can be started with ``python -m serial.tools.miniterm <port_name>`` (use option ``-h`` to get a listing of all options). diff --git a/documentation/tools.rst b/documentation/tools.rst index 437a884..8ed7fce 100644 --- a/documentation/tools.rst +++ b/documentation/tools.rst @@ -12,8 +12,10 @@ This module can be executed to get a list of ports (``python -m serial.tools.list_ports``). It also contains the following functions. -.. function:: comports() +.. function:: comports(include_links=False) + :param bool include_links: include symlinks under ``/dev`` when they point + to a serial port :return: a list containing :class:`ListPortInfo` objects. The function returns a list of :obj:`ListPortInfo` objects. @@ -26,22 +28,36 @@ serial.tools.list_ports``). It also contains the following functions. 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 :attr:`ListPortInfo.hwid` string contains `VID:PID`, + `SER` (serial number), `LOCATION` (hierarchy), which makes them searchable + via :func:`grep`. The USB info is also available as attributes of + :attr:`ListPortInfo`. + + 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 include ``LINK`` in their ``hwid`` 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) -.. function:: grep(regexp) +.. function:: grep(regexp, include_links=False) :param regexp: regular expression (see stdlib :mod:`re`) + :param bool include_links: include symlinks under ``/dev`` when they point + to a serial port :return: an iterable that yields :class:`ListPortInfo` objects, see also :func:`comports`. - Search for ports using a regular expression. Port name, description and - hardware ID are searched (case insensitive). The function returns an - iterable that contains the same data that :func:`comports` generates, but - includes only those entries that match the regexp. + Search for ports using a regular expression. Port ``name``, + ``description`` and ``hwid`` are searched (case insensitive). The function + returns an iterable that contains the same data that :func:`comports` + generates, but includes only those entries that match the regexp. .. class:: ListPortInfo @@ -109,18 +125,20 @@ serial.tools.list_ports``). It also contains the following functions. Help for ``python -m serial.tools.list_ports``:: - usage: list_ports.py [-h] [-v] [-q] [-n N] [regexp] + usage: list_ports.py [-h] [-v] [-q] [-n N] [-s] [regexp] Serial port enumeration positional arguments: - regexp only show ports that match this regex + 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 + -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: @@ -256,6 +274,11 @@ Typing :kbd:`Ctrl+T Ctrl+H` when it is running shows the help text:: --- x X disable/enable software flow control --- r R disable/enable hardware flow control +:kbd:`Ctrl+T s` 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 (:kbd:`Ctrl+]`) or change the port (:kbd:`p`). + .. versionchanged:: 2.5 Added :kbd:`Ctrl+T` menu and added support for opening URLs. .. versionchanged:: 2.6 diff --git a/documentation/url_handlers.rst b/documentation/url_handlers.rst index adacc2e..b4f0da7 100644 --- a/documentation/url_handlers.rst +++ b/documentation/url_handlers.rst @@ -211,7 +211,8 @@ The spy output will be live in the second terminal window. ``alt://`` ========== -This handler allows to select alternate implementations of the native serial port. +This handler allows to select alternate implementations of the native serial +port. Currently only the POSIX platform provides alternative implementations. @@ -221,10 +222,10 @@ Currently only the POSIX platform provides alternative implementations. disconnecting while it's in use (e.g. USB-serial unplugged). ``VTIMESerial`` - Implement timeout using ``VTIME``/``VMIN`` of tty device instead of using - ``select``. This means that inter character timeout and overall timeout + Implement timeout using ``VTIME``/``VMIN`` of TTY device instead of using + ``select``. This means that inter character timeout and overall timeout can not be used at the same time. Overall timeout is disabled when - inter-character timeout is used. The error handling is degraded. + inter-character timeout is used. The error handling is degraded. Examples:: |