diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/pyserial_api.rst | 10 | ||||
| -rw-r--r-- | documentation/shortintro.rst | 17 | ||||
| -rw-r--r-- | documentation/url_handlers.rst | 11 |
3 files changed, 28 insertions, 10 deletions
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst index 12a7765..fd15db5 100644 --- a/documentation/pyserial_api.rst +++ b/documentation/pyserial_api.rst @@ -150,7 +150,7 @@ Native ports :rtype: bytes Read *size* bytes from the serial port. If a timeout is set it may - return less characters as requested. With no timeout it will block + return fewer characters than requested. With no timeout it will block until the requested number of bytes is read. .. versionchanged:: 2.5 @@ -166,7 +166,7 @@ Native ports 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 + return fewer characters than requested. With no timeout it will block until the requested number of bytes is read. .. versionchanged:: 2.5 @@ -486,11 +486,11 @@ Native ports .. method:: readline(size=-1) - Provided via :meth:`io.IOBase.readline` + Provided via :meth:`io.IOBase.readline` See also ref:`shortintro_readline`. .. method:: readlines(hint=-1) - Provided via :meth:`io.IOBase.readlines` + Provided via :meth:`io.IOBase.readlines`. See also ref:`shortintro_readline`. .. method:: writelines(lines) @@ -1188,7 +1188,7 @@ This module provides classes to simplify working with threads and protocols. .. attribute:: UNICODE_HANDLING = 'replace' - Unicode error handly policy. + Unicode error handling policy. .. method:: handle_packet(packet) diff --git a/documentation/shortintro.rst b/documentation/shortintro.rst index b9230e3..11b2ea0 100644 --- a/documentation/shortintro.rst +++ b/documentation/shortintro.rst @@ -53,13 +53,24 @@ Also supported with :ref:`context manager <context-manager>`:: ser.write(b'hello') +.. _shortintro_readline: + Readline ======== +:meth:`readline` reads up to one line, including the `\n` at the end. Be careful when using :meth:`readline`. Do specify a timeout when opening the serial port otherwise it could block forever if no newline character is -received. Also note that :meth:`readlines` only works with a timeout. -:meth:`readlines` depends on having a timeout and interprets that as EOF (end -of file). It raises an exception if the port is not opened correctly. +received. If the `\n` is missing in the return value, it returned on timeout. + +:meth:`readlines` tries to read "all" lines which is not well defined for a +serial port that is still open. Therefore :meth:`readlines` depends on having +a timeout on the port and interprets that as EOF (end of file). It raises an +exception if the port is not opened correctly. The returned list of lines do +not include the `\n`. + +Both functions call :meth:`read` to get their data and the serial port timeout +is acting on this function. Therefore the effective timeout, especially for +:meth:`readlines`, can be much larger. Do also have a look at the example files in the examples directory in the source distribution or online. diff --git a/documentation/url_handlers.rst b/documentation/url_handlers.rst index 42a53fa..5c57615 100644 --- a/documentation/url_handlers.rst +++ b/documentation/url_handlers.rst @@ -140,6 +140,13 @@ Supported options in the URL are: hex dump). In this mode, no control line and other commands are logged. - ``all`` also show ``in_waiting`` and empty ``read()`` calls (hidden by default because of high traffic). +- ``log`` or ``log=LOGGERNAME`` output to stdlib ``logging`` module. Default + channel name is ``serial``. This variant outputs hex dump. +- ``rawlog`` or ``rawlog=LOGGERNAME`` output to stdlib ``logging`` module. Default + channel name is ``serial``. This variant outputs text (``repr``). + +The ``log`` and ``rawlog`` options require that the logging is set up, in order +to see the log output. Example:: @@ -208,6 +215,7 @@ not interpreted by the shell:: The spy output will be live in the second terminal window. .. versionadded:: 3.0 +.. versionchanged:: 3.6 Added ``log`` and ``rawlog`` options ``alt://`` @@ -236,9 +244,9 @@ Examples:: .. versionadded:: 3.0 + ``cp2110://`` ============= - This backend implements support for HID-to-UART devices manufactured by Silicon Labs and marketed as CP2110 and CP2114. The implementation is (mostly) OS-independent and in userland. It relies on `cython-hidapi`_. @@ -264,4 +272,3 @@ Examples - ``spy://COM54?file=log.txt`` - ``alt:///dev/ttyUSB0?class=PosixPollSerial`` - ``cp2110://0001:004a:00`` - |