doc: update RS485 related docs
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index f6117d1..202bcbc 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -17,7 +17,7 @@
:param port:
Device name or port number number or :const:`None`.
- :param baudrate:
+ :param int baudrate:
Baud rate such as 9600 or 115200 etc.
:param bytesize:
@@ -35,22 +35,22 @@
:const:`STOPBITS_ONE`, :const:`STOPBITS_ONE_POINT_FIVE`,
:const:`STOPBITS_TWO`
- :param timeout:
+ :param float timeout:
Set a read timeout value.
- :param xonxoff:
+ :param bool xonxoff:
Enable software flow control.
- :param rtscts:
+ :param bool rtscts:
Enable hardware (RTS/CTS) flow control.
- :param dsrdtr:
+ :param bool dsrdtr:
Enable hardware (DSR/DTR) flow control.
- :param writeTimeout:
+ :param float writeTimeout:
Set a write timeout value.
- :param interCharTimeout:
+ :param float interCharTimeout:
Inter-character timeout, :const:`None` to disable (default).
:exception ValueError:
@@ -280,6 +280,20 @@
Read or write current inter character timeout setting.
+ .. attribute:: rs485_mode
+
+ :platform: Posix
+ :platform: Windows
+
+ Attribute to configure RS485 support. When set to an instance of
+ :class:`rs485.RS485Settings` and supported by OS, RTS will be active
+ when data is sent and inactive otherwise (for reception). The
+ :class:`rs485.RS485Settings` class provides additional settings
+ supported on some platforms.
+
+ .. versionadded:: 3.0
+
+
The following constants are also provided:
.. attribute:: BAUDRATES
@@ -364,7 +378,7 @@
.. method:: outWaiting()
- :platform: Unix
+ :platform: Posix
:platform: Windows
Return the number of bytes in the output buffer.
@@ -373,14 +387,14 @@
.. method:: nonblocking()
- :platform: Unix
+ :platform: Posix
Configure the device for nonblocking operation. This can be useful if
the port is used with :mod:`select`.
.. method:: fileno()
- :platform: Unix
+ :platform: Posix
:return: File descriptor.
Return file descriptor number for the port that is opened by this object.
@@ -420,122 +434,101 @@
if no data is available.
.. versionadded:: 2.6
+ .. versionchanged:: 3.0 (removed, see :meth:`rs485_mode` instead)
-.. note::
-
- For systems that provide the :py:mod:`io` library (Python 2.6 and newer), the
- class :class:`Serial` will derive from :py:class:`io.RawIOBase`. For all
- others from :class:`FileLike`.
-
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:: FileLike
+RS485 support
+-------------
+The :class:`Serial` class has a :attr:`Serial.rs485_mode` attribute which allows to
+enable RS485 specific support on some platforms. Currently Windows and Linux
+(only a small number of devices) are supported.
- An abstract file like class. It is used as base class for :class:`Serial`
- when no :py:mod:`io` module is available.
+:attr:`Serial.rs485_mode` needs to be set to an instance of
+:class:`rs485.RS485Settings` to enable or to ``None`` to disable this feature.
- This class implements :meth:`readline` and :meth:`readlines` based on
- :meth:`read` and :meth:`writelines` based on :meth:`write`.
+Usage::
- Note that when the serial port was opened with no timeout, that
- :meth:`readline` blocks until it sees a newline (or the specified size is
- reached) and that :meth:`readlines` would never return and therefore
- refuses to work (it raises an exception in this case)!
+ ser = serial.Serial(...)
+ ser.rs485_mode = serial.rs485.RS485Settings(...)
+ ser.write(b'hello')
- .. method:: writelines(sequence)
+There is a subclass :class:`rs485.RS485` available to emulate the RS485 support
+on regular serial ports.
- Write a list of strings to the port.
+Usage::
+
+ ser = serial.rs485.RS485(...)
+ ser.rs485_mode = serial.rs485.RS485Settings(...)
+ ser.write(b'hello')
- The following three methods are overridden in :class:`Serial`.
+.. class:: rs485.RS485Settings
- .. method:: flush()
+ A class that holds RS485 specific settings which are supported on
+ some platforms.
- Flush of file like objects. It's a no-op in this class, may be overridden.
+ .. versionadded:: 3.0
- .. method:: read()
+ .. method:: __init__(rts_level_for_tx=True, rts_level_for_rx=False, loopback=False, delay_before_tx=None, delay_before_rx=None):
- Raises NotImplementedError, needs to be overridden by subclass.
+ :param bool rts_level_for_tx:
+ RTS level for transmission
- .. method:: write(data)
+ :param bool rts_level_for_rx:
+ RTS level for reception
- Raises NotImplementedError, needs to be overridden by subclass.
+ :param bool loopback:
+ When set to ``True`` transmitted data is also received.
- The following functions are implemented for compatibility with other
- file-like objects, however serial ports are not seekable.
+ :param float delay_before_tx:
+ Delay after setting RTS but before transmission starts
+
+ :param float delay_before_rx:
+ Delay after transmission ends and resetting RTS
+
+ .. attribute:: rts_level_for_tx
+
+ RTS level for transmission.
+
+ .. attribute:: rts_level_for_rx
+
+ RTS level for reception.
+
+ .. attribute:: loopback
+
+ When set to ``True`` transmitted data is also received.
+
+ .. attribute:: delay_before_tx
+
+ Delay after setting RTS but before transmission starts (seconds as float).
+
+ .. attribute:: delay_before_rx
+
+ Delay after transmission ends and resetting RTS (seconds as float).
- .. method:: seek(pos, whence=0)
+.. class:: rs485.RS485
- :exception IOError: always, as method is not supported on serial port
+ A subclass that replaces the :meth:`Serial.write` method with one that toggles RTS
+ according to the RS485 settings.
- .. versionadded:: 2.5
+ .. warning:: This may work unreliably on some serial ports (control signals not
+ synchronized or delayed compared to data). Using delays may be unreliable
+ (varying times, larger than expected) as the OS may not support very fine
+ grained delays (no smaller than in the order of tens of milliseconds).
- .. method:: tell()
+ .. note:: Some implementations support this natively in the class
+ :class:`Serial`. Better performance can be expected when the native version
+ is used.
- :exception IOError: always, as method is not supported on serial port
+ .. note:: The loopback property is ignored by this implementation. The actual
+ behavior depends on the used hardware.
- .. versionadded:: 2.5
- .. method:: truncate(self, n=None)
-
- :exception IOError: always, as method is not supported on serial port
-
- .. versionadded:: 2.5
-
- .. method:: isatty()
-
- :exception IOError: always, as method is not supported on serial port
-
- .. versionadded:: 2.5
-
- To be able to use the file like object as iterator for e.g.
- ``for line in Serial(0): ...`` usage:
-
- .. method:: next()
-
- Return the next line by calling :meth:`readline`.
-
- .. method:: __iter__()
-
- Returns self.
-
- Other high level access functions.
-
- .. method:: readline(size=None, eol='\\n')
-
- :param size: Max number of bytes to read, ``None`` -> no limit.
- :param eol: The end of line character.
-
- Read a line which is terminated with end-of-line (*eol*) character
- (``\n`` by default) or until timeout.
-
- .. method:: readlines(sizehint=None, eol='\\n')
-
- :param sizehint: Ignored parameter.
- :param eol: The end of line character.
-
- Read a list of lines, until timeout. *sizehint* is ignored and only
- present for API compatibility with built-in File objects.
-
- Note that this function only returns on a timeout.
-
- .. method:: xreadlines(sizehint=None)
-
- Read lines, implemented as generator. Unlike *readlines* (that only
- returns on a timeout) is this function yielding lines as they are
- received.
-
- .. deprecated:: 2.5
- Use ``for line in Serial(...): ...`` instead. This method is not
- available in Python 2.6 and newer where the :mod:`io` library is
- available and pySerial bases on it.
-
- .. versionchanged:: 2.5
- Implement as generator.
:rfc:`2217` Network ports
@@ -892,8 +885,8 @@
VID:PID or texts.
Unfortunately, on some systems list_ports only lists a subset of the port
- names with no additional information. Currently, on Windows and Linux it
- should find additional information.
+ names with no additional information. Currently, on Windows and Linux and
+ OSX it should find additional information.