| ============== |
| pySerial API |
| ============== |
| |
| .. module:: serial |
| |
| Classes |
| ======= |
| |
| Native ports |
| ------------ |
| |
| .. class:: Serial |
| |
| .. method:: __init__(port=None, baudrate=9600, bytesize=EIGHTBITS, parity=PARITY_NONE, stopbits=STOPBITS_ONE, timeout=None, xonxoff=False, rtscts=False, write_timeout=None, dsrdtr=False, inter_byte_timeout=None, exclusive=None) |
| |
| :param port: |
| Device name or :const:`None`. |
| |
| :param int baudrate: |
| Baud rate such as 9600 or 115200 etc. |
| |
| :param bytesize: |
| Number of data bits. Possible values: |
| :const:`FIVEBITS`, :const:`SIXBITS`, :const:`SEVENBITS`, |
| :const:`EIGHTBITS` |
| |
| :param parity: |
| Enable parity checking. Possible values: |
| :const:`PARITY_NONE`, :const:`PARITY_EVEN`, :const:`PARITY_ODD` |
| :const:`PARITY_MARK`, :const:`PARITY_SPACE` |
| |
| :param stopbits: |
| Number of stop bits. Possible values: |
| :const:`STOPBITS_ONE`, :const:`STOPBITS_ONE_POINT_FIVE`, |
| :const:`STOPBITS_TWO` |
| |
| :param float timeout: |
| Set a read timeout value in seconds. |
| |
| :param bool xonxoff: |
| Enable software flow control. |
| |
| :param bool rtscts: |
| Enable hardware (RTS/CTS) flow control. |
| |
| :param bool dsrdtr: |
| Enable hardware (DSR/DTR) flow control. |
| |
| :param float write_timeout: |
| Set a write timeout value in seconds. |
| |
| :param float inter_byte_timeout: |
| Inter-character timeout, :const:`None` to disable (default). |
| |
| :param bool exclusive: |
| Set exclusive access mode (POSIX only). A port cannot be opened in |
| exclusive access mode if it is already open in exclusive access mode. |
| |
| :exception ValueError: |
| Will be raised when parameter are out of range, e.g. baud rate, data bits. |
| |
| :exception SerialException: |
| In case the device can not be found or can not be configured. |
| |
| |
| The port is immediately opened on object creation, when a *port* is |
| given. It is not opened when *port* is :const:`None` and a successive call |
| to :meth:`open` is required. |
| |
| *port* is a device name: depending on operating system. e.g. |
| ``/dev/ttyUSB0`` on GNU/Linux or ``COM3`` on Windows. |
| |
| The parameter *baudrate* can be one of the standard values: |
| 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, |
| 9600, 19200, 38400, 57600, 115200. |
| These are well supported on all platforms. |
| |
| Standard values above 115200, such as: 230400, 460800, 500000, 576000, |
| 921600, 1000000, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, |
| 4000000 also work on many platforms and devices. |
| |
| Non-standard values are also supported on some platforms (GNU/Linux, MAC |
| OSX >= Tiger, Windows). Though, even on these platforms some serial |
| ports may reject non-standard values. |
| |
| Possible values for the parameter *timeout* which controls the behavior |
| of :meth:`read`: |
| |
| - ``timeout = None``: wait forever / until requested number of bytes |
| are received |
| - ``timeout = 0``: non-blocking mode, return immediately in any case, |
| returning zero or more, up to the requested number of bytes |
| - ``timeout = x``: set timeout to ``x`` seconds (float allowed) |
| returns immediately when the requested number of bytes are available, |
| otherwise wait until the timeout expires and return all bytes that |
| were received until then. |
| |
| :meth:`write` is blocking by default, unless *write_timeout* is set. |
| For possible values refer to the list for *timeout* above. |
| |
| Note that enabling both flow control methods (*xonxoff* and *rtscts*) |
| together may not be supported. It is common to use one of the methods |
| at once, not both. |
| |
| *dsrdtr* is not supported by all platforms (silently ignored). Setting |
| it to ``None`` has the effect that its state follows *rtscts*. |
| |
| Also consider using the function :func:`serial_for_url` instead of |
| creating Serial instances directly. |
| |
| .. versionchanged:: 2.5 |
| *dsrdtr* now defaults to ``False`` (instead of *None*) |
| .. versionchanged:: 3.0 numbers as *port* argument are no longer supported |
| .. versionadded:: 3.3 ``exclusive`` flag |
| |
| .. method:: open() |
| |
| Open port. The state of :attr:`rts` and :attr:`dtr` is applied. |
| |
| .. note:: |
| |
| 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 |
| default value (``True`` / active). |
| |
| .. note:: |
| |
| For compatibility reasons, no error is reported when applying |
| :attr:`rts` or :attr:`dtr` fails on POSIX due to EINVAL (22) or |
| ENOTTY (25). |
| |
| .. method:: close() |
| |
| Close port immediately. |
| |
| .. method:: __del__() |
| |
| Destructor, close port when serial port instance is freed. |
| |
| |
| The following methods may raise :exc:`SerialException` when applied to a closed |
| port. |
| |
| .. method:: read(size=1) |
| |
| :param size: Number of bytes to read. |
| :return: Bytes read from the port. |
| :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 |
| 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:: 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. |
| |
| .. versionchanged:: 3.5 |
| First argument was called ``terminator`` in previous versions. |
| |
| .. method:: write(data) |
| |
| :param data: Data to send. |
| :return: Number of bytes written. |
| :rtype: int |
| :exception SerialTimeoutException: |
| In case a write timeout is configured for the port and the time is |
| exceeded. |
| |
| Write the bytes *data* to the port. This should be of type ``bytes`` |
| (or compatible such as ``bytearray`` or ``memoryview``). Unicode |
| strings must be encoded (e.g. ``'hello'.encode('utf-8')``. |
| |
| .. versionchanged:: 2.5 |
| Accepts instances of :class:`bytes` and :class:`bytearray` when |
| available (Python 2.6 and newer) and :class:`str` otherwise. |
| |
| .. versionchanged:: 2.5 |
| Write returned ``None`` in previous versions. |
| |
| .. method:: flush() |
| |
| Flush of file like objects. In this case, wait until all data is |
| written. |
| |
| .. attribute:: in_waiting |
| |
| :getter: Get the number of bytes in the input buffer |
| :type: int |
| |
| Return the number of bytes in the receive buffer. |
| |
| .. versionchanged:: 3.0 changed to property from ``inWaiting()`` |
| |
| .. attribute:: out_waiting |
| |
| :getter: Get the number of bytes in the output buffer |
| :type: int |
| :platform: Posix |
| :platform: Windows |
| |
| Return the number of bytes in the output buffer. |
| |
| .. versionchanged:: 2.7 (Posix support added) |
| .. versionchanged:: 3.0 changed to property from ``outWaiting()`` |
| |
| .. method:: reset_input_buffer() |
| |
| Flush input buffer, discarding all its contents. |
| |
| .. versionchanged:: 3.0 renamed from ``flushInput()`` |
| |
| .. method:: reset_output_buffer() |
| |
| Clear output buffer, aborting the current output and |
| discarding all that is in the buffer. |
| |
| Note, for some USB serial adapters, this may only flush the buffer of |
| the OS and not all the data that may be present in the USB part. |
| |
| .. versionchanged:: 3.0 renamed from ``flushOutput()`` |
| |
| .. method:: send_break(duration=0.25) |
| |
| :param float duration: Time in seconds, to activate the BREAK condition. |
| |
| Send break condition. Timed, returns to idle state after given |
| duration. |
| |
| |
| .. attribute:: break_condition |
| |
| :getter: Get the current BREAK state |
| :setter: Control the BREAK state |
| :type: bool |
| |
| When set to ``True`` activate BREAK condition, else disable. |
| Controls TXD. When active, no transmitting is possible. |
| |
| .. attribute:: rts |
| |
| :setter: Set the state of the RTS line |
| :getter: Return the state of the RTS line |
| :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 upon |
| :meth:`open` (with restrictions, see :meth:`open`). |
| |
| .. attribute:: dtr |
| |
| :setter: Set the state of the DTR line |
| :getter: Return the state of the DTR line |
| :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 upon |
| :meth:`open` (with restrictions, see :meth:`open`). |
| |
| Read-only attributes: |
| |
| .. attribute:: name |
| |
| :getter: Device name. |
| :type: str |
| |
| .. versionadded:: 2.5 |
| |
| .. attribute:: cts |
| |
| :getter: Get the state of the CTS line |
| :type: bool |
| |
| Return the state of the CTS line. |
| |
| .. attribute:: dsr |
| |
| :getter: Get the state of the DSR line |
| :type: bool |
| |
| Return the state of the DSR line. |
| |
| .. attribute:: ri |
| |
| :getter: Get the state of the RI line |
| :type: bool |
| |
| Return the state of the RI line. |
| |
| .. attribute:: cd |
| |
| :getter: Get the state of the CD line |
| :type: bool |
| |
| Return the state of the CD line |
| |
| .. attribute:: is_open |
| |
| :getter: Get the state of the serial port, whether it's open. |
| :type: bool |
| |
| New values can be assigned to the following attributes (properties), the |
| port will be reconfigured, even if it's opened at that time: |
| |
| |
| .. attribute:: port |
| |
| :type: str |
| |
| Read or write port. When the port is already open, it will be closed |
| and reopened with the new setting. |
| |
| .. attribute:: baudrate |
| |
| :getter: Get current baud rate |
| :setter: Set new baud rate |
| :type: int |
| |
| Read or write current baud rate setting. |
| |
| .. attribute:: bytesize |
| |
| :getter: Get current byte size |
| :setter: Set new byte size. Possible values: |
| :const:`FIVEBITS`, :const:`SIXBITS`, :const:`SEVENBITS`, |
| :const:`EIGHTBITS` |
| :type: int |
| |
| Read or write current data byte size setting. |
| |
| .. attribute:: parity |
| |
| :getter: Get current parity setting |
| :setter: Set new parity mode. Possible values: |
| :const:`PARITY_NONE`, :const:`PARITY_EVEN`, :const:`PARITY_ODD` |
| :const:`PARITY_MARK`, :const:`PARITY_SPACE` |
| |
| Read or write current parity setting. |
| |
| .. attribute:: stopbits |
| |
| :getter: Get current stop bit setting |
| :setter: Set new stop bit setting. Possible values: |
| :const:`STOPBITS_ONE`, :const:`STOPBITS_ONE_POINT_FIVE`, |
| :const:`STOPBITS_TWO` |
| |
| Read or write current stop bit width setting. |
| |
| .. attribute:: timeout |
| |
| :getter: Get current read timeout setting |
| :setter: Set read timeout |
| :type: float (seconds) |
| |
| Read or write current read timeout setting. |
| |
| .. attribute:: write_timeout |
| |
| :getter: Get current write timeout setting |
| :setter: Set write timeout |
| :type: float (seconds) |
| |
| Read or write current write timeout setting. |
| |
| .. versionchanged:: 3.0 renamed from ``writeTimeout`` |
| |
| .. attribute:: inter_byte_timeout |
| |
| :getter: Get current inter byte timeout setting |
| :setter: Disable (``None``) or enable the inter byte timeout |
| :type: float or None |
| |
| Read or write current inter byte timeout setting. |
| |
| .. versionchanged:: 3.0 renamed from ``interCharTimeout`` |
| |
| .. attribute:: xonxoff |
| |
| :getter: Get current software flow control setting |
| :setter: Enable or disable software flow control |
| :type: bool |
| |
| Read or write current software flow control rate setting. |
| |
| .. attribute:: rtscts |
| |
| :getter: Get current hardware flow control setting |
| :setter: Enable or disable hardware flow control |
| :type: bool |
| |
| Read or write current hardware flow control setting. |
| |
| .. attribute:: dsrdtr |
| |
| :getter: Get current hardware flow control setting |
| :setter: Enable or disable hardware flow control |
| :type: bool |
| |
| Read or write current hardware flow control setting. |
| |
| .. attribute:: rs485_mode |
| |
| :getter: Get the current RS485 settings |
| :setter: Disable (``None``) or enable the RS485 settings |
| :type: :class:`rs485.RS485Settings` or ``None`` |
| :platform: Posix (Linux, limited set of hardware) |
| :platform: Windows (only RTS on TX possible) |
| |
| 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 |
| |
| A list of valid baud rates. The list may be incomplete, such that higher |
| and/or intermediate baud rates may also be supported by the device |
| (Read Only). |
| |
| .. attribute:: BYTESIZES |
| |
| A list of valid byte sizes for the device (Read Only). |
| |
| .. attribute:: PARITIES |
| |
| A list of valid parities for the device (Read Only). |
| |
| .. attribute:: STOPBITS |
| |
| A list of valid stop bit widths for the device (Read Only). |
| |
| |
| The following methods are for compatibility with the :mod:`io` library. |
| |
| .. method:: readable() |
| |
| :return: True |
| |
| .. versionadded:: 2.5 |
| |
| .. method:: writable() |
| |
| :return: True |
| |
| .. versionadded:: 2.5 |
| |
| .. method:: seekable() |
| |
| :return: False |
| |
| .. versionadded:: 2.5 |
| |
| .. method:: readinto(b) |
| |
| :param b: bytearray or array instance |
| :return: Number of byte read |
| |
| Read up to len(b) bytes into :class:`bytearray` *b* and return the |
| number of bytes read. |
| |
| .. 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``, |
| ``rtscts``, ``stopbits``, ``xonxoff`` |
| |
| .. method:: get_settings() |
| |
| :return: a dictionary with current port settings. |
| :rtype: dict |
| |
| Get a dictionary with port settings. This is useful to backup the |
| current settings so that a later point in time they can be restored |
| using :meth:`apply_settings`. |
| |
| Note that the state of control lines (RTS/DTR) are not part of the |
| settings. |
| |
| .. versionadded:: 2.5 |
| .. versionchanged:: 3.0 renamed from ``getSettingsDict`` |
| |
| .. method:: apply_settings(d) |
| |
| :param dict d: a dictionary with port settings. |
| |
| Applies a dictionary that was created by :meth:`get_settings`. Only |
| changes are applied and when a key is missing, it means that the |
| setting stays unchanged. |
| |
| Note that control lines (RTS/DTR) are not changed. |
| |
| .. versionadded:: 2.5 |
| .. versionchanged:: 3.0 renamed from ``applySettingsDict`` |
| |
| |
| .. _context-manager: |
| |
| This class can be used as context manager. The serial port is closed when |
| the context is left. |
| |
| .. method:: __enter__() |
| |
| :returns: Serial instance |
| |
| Returns the instance that was used in the ``with`` statement. |
| |
| Example: |
| |
| >>> with serial.serial_for_url(port) as s: |
| ... s.write(b'hello') |
| |
| The port is opened automatically: |
| |
| >>> 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 (exceptions are not handled by ``__exit__``). |
| |
| |
| Platform specific methods. |
| |
| .. warning:: Programs using the following methods and attributes are not |
| portable to other platforms! |
| |
| .. method:: nonblocking() |
| |
| :platform: Posix |
| |
| .. deprecated:: 3.2 |
| The serial port is already opened in this mode. This method is not |
| needed and going away. |
| |
| |
| .. method:: fileno() |
| |
| :platform: Posix |
| :return: File descriptor. |
| |
| Return file descriptor number for the port that is opened by this object. |
| It is useful when serial ports are used with :mod:`select`. |
| |
| .. method:: set_input_flow_control(enable) |
| |
| :platform: Posix |
| :param bool enable: Set flow control state. |
| |
| Manually control flow - when software flow control is enabled. |
| |
| This will send XON (true) and XOFF (false) to the other device. |
| |
| .. versionadded:: 2.7 (Posix support added) |
| .. versionchanged:: 3.0 renamed from ``flowControlOut`` |
| |
| .. method:: set_output_flow_control(enable) |
| |
| :platform: Posix (HW and SW flow control) |
| :platform: Windows (SW flow control only) |
| :param bool enable: Set flow control state. |
| |
| Manually control flow of outgoing data - when hardware or software flow |
| control is enabled. |
| |
| Sending will be suspended when called with ``False`` and enabled when |
| called with ``True``. |
| |
| .. versionchanged:: 2.7 (renamed on Posix, function was called ``flowControl``) |
| .. versionchanged:: 3.0 renamed from ``setXON`` |
| |
| .. method:: cancel_read() |
| |
| :platform: Posix |
| :platform: Windows |
| |
| Cancel a pending read operation from another thread. A blocking |
| :meth:`read` call is aborted immediately. :meth:`read` will not report |
| any error but return all data received up to that point (similar to a |
| timeout). |
| |
| On Posix a call to `cancel_read()` may cancel a future :meth:`read` call. |
| |
| .. versionadded:: 3.1 |
| |
| .. method:: cancel_write() |
| |
| :platform: Posix |
| :platform: Windows |
| |
| Cancel a pending write operation from another thread. The |
| :meth:`write` method will return immediately (no error indicated). |
| However the OS may still be sending from the buffer, a separate call to |
| :meth:`reset_output_buffer` may be needed. |
| |
| On Posix a call to `cancel_write()` may cancel a future :meth:`write` call. |
| |
| .. versionadded:: 3.1 |
| |
| .. note:: The following members are deprecated and will be removed in a |
| future release. |
| |
| .. attribute:: portstr |
| |
| .. deprecated:: 2.5 use :attr:`name` instead |
| |
| .. method:: inWaiting() |
| |
| .. deprecated:: 3.0 see :attr:`in_waiting` |
| |
| .. method:: isOpen() |
| |
| .. deprecated:: 3.0 see :attr:`is_open` |
| |
| .. attribute:: writeTimeout |
| |
| .. deprecated:: 3.0 see :attr:`write_timeout` |
| |
| .. attribute:: interCharTimeout |
| |
| .. deprecated:: 3.0 see :attr:`inter_byte_timeout` |
| |
| .. method:: sendBreak(duration=0.25) |
| |
| .. deprecated:: 3.0 see :meth:`send_break` |
| |
| .. method:: flushInput() |
| |
| .. deprecated:: 3.0 see :meth:`reset_input_buffer` |
| |
| .. method:: flushOutput() |
| |
| .. deprecated:: 3.0 see :meth:`reset_output_buffer` |
| |
| .. method:: setBreak(level=True) |
| |
| .. deprecated:: 3.0 see :attr:`break_condition` |
| |
| .. method:: setRTS(level=True) |
| |
| .. deprecated:: 3.0 see :attr:`rts` |
| |
| .. method:: setDTR(level=True) |
| |
| .. deprecated:: 3.0 see :attr:`dtr` |
| |
| .. method:: getCTS() |
| |
| .. deprecated:: 3.0 see :attr:`cts` |
| |
| .. method:: getDSR() |
| |
| .. deprecated:: 3.0 see :attr:`dsr` |
| |
| .. method:: getRI() |
| |
| .. deprecated:: 3.0 see :attr:`ri` |
| |
| .. method:: getCD() |
| |
| .. deprecated:: 3.0 see :attr:`cd` |
| |
| .. method:: getSettingsDict() |
| |
| .. deprecated:: 3.0 see :meth:`get_settings` |
| |
| .. method:: applySettingsDict(d) |
| |
| .. deprecated:: 3.0 see :meth:`apply_settings` |
| |
| .. method:: outWaiting() |
| |
| .. deprecated:: 3.0 see :attr:`out_waiting` |
| |
| .. method:: setXON(level=True) |
| |
| .. deprecated:: 3.0 see :meth:`set_output_flow_control` |
| |
| .. method:: flowControlOut(enable) |
| |
| .. deprecated:: 3.0 see :meth:`set_input_flow_control` |
| |
| .. attribute:: rtsToggle |
| |
| :platform: Windows |
| |
| Attribute to configure RTS toggle control setting. When enabled and |
| supported by OS, RTS will be active when data is available and inactive |
| if no data is available. |
| |
| .. versionadded:: 2.6 |
| .. versionchanged:: 3.0 (removed, see :attr:`rs485_mode` instead) |
| |
| |
| Implementation detail: some attributes and functions are provided by the |
| 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 |
| ------------- |
| 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. |
| |
| :attr:`Serial.rs485_mode` needs to be set to an instance of |
| :class:`rs485.RS485Settings` to enable or to ``None`` to disable this feature. |
| |
| Usage:: |
| |
| import serial |
| import serial.rs485 |
| ser = serial.Serial(...) |
| ser.rs485_mode = serial.rs485.RS485Settings(...) |
| ser.write(b'hello') |
| |
| There is a subclass :class:`rs485.RS485` available to emulate the RS485 support |
| on regular serial ports (``serial.rs485`` needs to be imported). |
| |
| |
| .. class:: rs485.RS485Settings |
| |
| A class that holds RS485 specific settings which are supported on |
| some platforms. |
| |
| .. versionadded:: 3.0 |
| |
| .. method:: __init__(rts_level_for_tx=True, rts_level_for_rx=False, loopback=False, delay_before_tx=None, delay_before_rx=None): |
| |
| :param bool rts_level_for_tx: |
| RTS level for transmission |
| |
| :param bool rts_level_for_rx: |
| RTS level for reception |
| |
| :param bool loopback: |
| When set to ``True`` transmitted data is also received. |
| |
| :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). |
| |
| |
| .. class:: rs485.RS485 |
| |
| A subclass that replaces the :meth:`Serial.write` method with one that toggles RTS |
| according to the RS485 settings. |
| |
| Usage:: |
| |
| ser = serial.rs485.RS485(...) |
| ser.rs485_mode = serial.rs485.RS485Settings(...) |
| ser.write(b'hello') |
| |
| .. 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). |
| |
| .. note:: Some implementations support this natively in the class |
| :class:`Serial`. Better performance can be expected when the native version |
| is used. |
| |
| .. note:: The loopback property is ignored by this implementation. The actual |
| behavior depends on the used hardware. |
| |
| |
| |
| :rfc:`2217` Network ports |
| ------------------------- |
| |
| .. warning:: This implementation is currently in an experimental state. Use |
| at your own risk. |
| |
| .. class:: rfc2217.Serial |
| |
| This implements a :rfc:`2217` compatible client. Port names are :ref:`URL |
| <URLs>` in the form: ``rfc2217://<host>:<port>[?<option>[&<option>]]`` |
| |
| This class API is compatible to :class:`Serial` with a few exceptions: |
| |
| - ``write_timeout`` is not implemented |
| - The current implementation starts a thread that keeps reading from the |
| (internal) socket. The thread is managed automatically by the |
| :class:`rfc2217.Serial` port object on :meth:`open`/:meth:`close`. |
| However it may be a problem for user applications that like to use select |
| instead of threads. |
| |
| Due to the nature of the network and protocol involved there are a few |
| extra points to keep in mind: |
| |
| - All operations have an additional latency time. |
| - Setting control lines (RTS/CTS) needs more time. |
| - Reading the status lines (DSR/DTR etc.) returns a cached value. When that |
| cache is updated depends entirely on the server. The server itself may |
| implement a polling at a certain rate and quick changes may be invisible. |
| - The network layer also has buffers. This means that :meth:`flush`, |
| :meth:`reset_input_buffer` and :meth:`reset_output_buffer` may work with |
| additional delay. Likewise :attr:`in_waiting` returns the size of the |
| data arrived at the objects internal buffer and excludes any bytes in the |
| network buffers or any server side buffer. |
| - Closing and immediately reopening the same port may fail due to time |
| needed by the server to get ready again. |
| |
| Not implemented yet / Possible problems with the implementation: |
| |
| - :rfc:`2217` flow control between client and server (objects internal |
| buffer may eat all your memory when never read). |
| - No authentication support (servers may not prompt for a password etc.) |
| - No encryption. |
| |
| Due to lack of authentication and encryption it is not suitable to use this |
| client for connections across the internet and should only be used in |
| controlled environments. |
| |
| .. versionadded:: 2.5 |
| |
| |
| .. class:: rfc2217.PortManager |
| |
| This class provides helper functions for implementing :rfc:`2217` |
| compatible servers. |
| |
| Basically, it implements everything needed for the :rfc:`2217` protocol. |
| It just does not open sockets and read/write to serial ports (though it |
| changes other port settings). The user of this class must take care of the |
| data transmission itself. The reason for that is, that this way, this class |
| supports all programming models such as threads and select. |
| |
| Usage examples can be found in the examples where two TCP/IP - serial |
| converters are shown, one using threads (the single port server) and an |
| other using select (the multi port server). |
| |
| .. note:: Each new client connection must create a new instance as this |
| object (and the :rfc:`2217` protocol) has internal state. |
| |
| .. method:: __init__(serial_port, connection, debug_output=False) |
| |
| :param serial_port: a :class:`Serial` instance that is managed. |
| :param connection: an object implementing :meth:`write`, used to write |
| to the network. |
| :param debug_output: enables debug messages: a :class:`logging.Logger` |
| instance or None. |
| |
| Initializes the Manager and starts negotiating with client in Telnet |
| and :rfc:`2217` protocol. The negotiation starts immediately so that |
| the class should be instantiated in the moment the client connects. |
| |
| The *serial_port* can be controlled by :rfc:`2217` commands. This |
| object will modify the port settings (baud rate etc.) and control lines |
| (RTS/DTR) send BREAK etc. when the corresponding commands are found by |
| the :meth:`filter` method. |
| |
| The *connection* object must implement a :meth:`write` function. |
| This function must ensure that *data* is written at once (no user data |
| mixed in, i.e. it must be thread-safe). All data must be sent in its |
| raw form (:meth:`escape` must not be used) as it is used to send Telnet |
| and :rfc:`2217` control commands. |
| |
| For diagnostics of the connection or the implementation, *debug_output* |
| can be set to an instance of a :class:`logging.Logger` (e.g. |
| ``logging.getLogger('rfc2217.server')``). The caller should configure |
| the logger using ``setLevel`` for the desired detail level of the logs. |
| |
| .. method:: escape(data) |
| |
| :param data: data to be sent over the network. |
| :return: data, escaped for Telnet/:rfc:`2217` |
| |
| A generator that escapes all data to be compatible with :rfc:`2217`. |
| Implementors of servers should use this function to process all data |
| sent over the network. |
| |
| The function returns a generator which can be used in ``for`` loops. |
| It can be converted to bytes using :func:`serial.to_bytes`. |
| |
| .. method:: filter(data) |
| |
| :param data: data read from the network, including Telnet and |
| :rfc:`2217` controls. |
| :return: data, free from Telnet and :rfc:`2217` controls. |
| |
| A generator that filters and processes all data related to :rfc:`2217`. |
| Implementors of servers should use this function to process all data |
| received from the network. |
| |
| The function returns a generator which can be used in ``for`` loops. |
| It can be converted to bytes using :func:`serial.to_bytes`. |
| |
| .. method:: check_modem_lines(force_notification=False) |
| |
| :param force_notification: Set to false. Parameter is for internal use. |
| |
| This function needs to be called periodically (e.g. every second) when |
| the server wants to send NOTIFY_MODEMSTATE messages. This is required |
| to support the client for reading CTS/DSR/RI/CD status lines. |
| |
| The function reads the status line and issues the notifications |
| automatically. |
| |
| .. versionadded:: 2.5 |
| |
| .. seealso:: |
| |
| :rfc:`2217` - Telnet Com Port Control Option |
| |
| |
| Exceptions |
| ========== |
| |
| .. exception:: SerialException |
| |
| Base class for serial port exceptions. |
| |
| .. versionchanged:: 2.5 |
| Now derives from :exc:`IOError` instead of :exc:`Exception` |
| |
| .. exception:: SerialTimeoutException |
| |
| Exception that is raised on write timeouts. |
| |
| |
| Constants |
| ========= |
| |
| *Parity* |
| |
| .. data:: PARITY_NONE |
| .. data:: PARITY_EVEN |
| .. data:: PARITY_ODD |
| .. data:: PARITY_MARK |
| .. data:: PARITY_SPACE |
| |
| *Stop bits* |
| |
| .. data:: STOPBITS_ONE |
| .. data:: STOPBITS_ONE_POINT_FIVE |
| .. data:: STOPBITS_TWO |
| |
| Note that 1.5 stop bits are not supported on POSIX. It will fall back to 2 stop |
| bits. |
| |
| *Byte size* |
| |
| .. data:: FIVEBITS |
| .. data:: SIXBITS |
| .. data:: SEVENBITS |
| .. data:: EIGHTBITS |
| |
| |
| *Others* |
| |
| Default control characters (instances of :class:`bytes` for Python 3.0+) for |
| software flow control: |
| |
| .. data:: XON |
| .. data:: XOFF |
| |
| Module version: |
| |
| .. data:: VERSION |
| |
| A string indicating the pySerial version, such as ``3.0``. |
| |
| .. versionadded:: 2.3 |
| |
| |
| Module functions and attributes |
| =============================== |
| |
| .. function:: device(number) |
| |
| .. versionchanged:: 3.0 removed, use ``serial.tools.list_ports`` instead |
| |
| |
| .. function:: serial_for_url(url, \*args, \*\*kwargs) |
| |
| :param url: Device name, number or :ref:`URL <URLs>` |
| :param do_not_open: When set to true, the serial port is not opened. |
| :return: an instance of :class:`Serial` or a compatible object. |
| |
| Get a native or a :rfc:`2217` implementation of the Serial class, depending |
| on port/url. This factory function is useful when an application wants |
| to support both, local ports and remote ports. There is also support |
| for other types, see :ref:`URL <URLs>` section. |
| |
| The port is not opened when a keyword parameter called *do_not_open* is |
| given and true, by default it is opened. |
| |
| .. versionadded:: 2.5 |
| |
| |
| .. attribute:: protocol_handler_packages |
| |
| This attribute is a list of package names (strings) that is searched for |
| protocol handlers. |
| |
| e.g. we want to support a URL ``foobar://``. A module |
| ``my_handlers.protocol_foobar`` is provided by the user:: |
| |
| serial.protocol_handler_packages.append("my_handlers") |
| s = serial.serial_for_url("foobar://") |
| |
| For an URL starting with ``XY://`` is the function :func:`serial_for_url` |
| attempts to import ``PACKAGE.protocol_XY`` with each candidate for |
| ``PACKAGE`` from this list. |
| |
| .. versionadded:: 2.6 |
| |
| |
| .. function:: to_bytes(sequence) |
| |
| :param sequence: bytes, bytearray or memoryview |
| :returns: an instance of ``bytes`` |
| |
| Convert a sequence to a ``bytes`` type. This is used to write code that is |
| compatible to Python 2.x and 3.x. |
| |
| In Python versions prior 3.x, ``bytes`` is a subclass of str. They convert |
| ``str([17])`` to ``'[17]'`` instead of ``'\x11'`` so a simple |
| ``bytes(sequence)`` doesn't work for all versions of Python. |
| |
| This function is used internally and in the unit tests. |
| |
| .. versionadded:: 2.5 |
| |
| .. function:: iterbytes(sequence) |
| |
| :param sequence: bytes, bytearray or memoryview |
| :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 |
| bytes are returned. |
| |
| .. versionadded:: 3.0 |
| |
| |
| Threading |
| ========= |
| |
| .. module:: serial.threaded |
| .. versionadded:: 3.0 |
| |
| .. warning:: This implementation is currently in an experimental state. Use |
| at your own risk. |
| |
| This module provides classes to simplify working with threads and protocols. |
| |
| .. class:: Protocol |
| |
| Protocol as used by the :class:`ReaderThread`. This base class provides empty |
| implementations of all methods. |
| |
| |
| .. method:: connection_made(transport) |
| |
| :param transport: instance used to write to serial port. |
| |
| Called when reader thread is started. |
| |
| .. method:: data_received(data) |
| |
| :param bytes data: received bytes |
| |
| Called with snippets received from the serial port. |
| |
| .. method:: connection_lost(exc) |
| |
| :param exc: Exception if connection was terminated by error else ``None`` |
| |
| Called when the serial port is closed or the reader loop terminated |
| otherwise. |
| |
| .. class:: Packetizer(Protocol) |
| |
| Read binary packets from serial port. Packets are expected to be terminated |
| with a ``TERMINATOR`` byte (null byte by default). |
| |
| The class also keeps track of the transport. |
| |
| .. attribute:: TERMINATOR = b'\\0' |
| |
| .. method:: __init__() |
| |
| .. method:: connection_made(transport) |
| |
| Stores transport. |
| |
| .. method:: connection_lost(exc) |
| |
| Forgets transport. |
| |
| .. method:: data_received(data) |
| |
| :param bytes data: partial received data |
| |
| Buffer received data and search for :attr:`TERMINATOR`, when found, |
| call :meth:`handle_packet`. |
| |
| .. method:: handle_packet(packet) |
| |
| :param bytes packet: a packet as defined by ``TERMINATOR`` |
| |
| Process packets - to be overridden by subclassing. |
| |
| |
| .. class:: LineReader(Packetizer) |
| |
| Read and write (Unicode) lines from/to serial port. |
| The encoding is applied. |
| |
| |
| .. attribute:: TERMINATOR = b'\\r\\n' |
| |
| Line ending. |
| |
| .. attribute:: ENCODING = 'utf-8' |
| |
| Encoding of the send and received data. |
| |
| .. attribute:: UNICODE_HANDLING = 'replace' |
| |
| Unicode error handly policy. |
| |
| .. method:: handle_packet(packet) |
| |
| :param bytes packet: a packet as defined by ``TERMINATOR`` |
| |
| In this case it will be a line, calls :meth:`handle_line` after applying |
| the :attr:`ENCODING`. |
| |
| .. method:: handle_line(line) |
| |
| :param str line: Unicode string with one line (excluding line terminator) |
| |
| Process one line - to be overridden by subclassing. |
| |
| .. method:: write_line(text) |
| |
| :param str text: Unicode string with one line (excluding line terminator) |
| |
| Write *text* to the transport. *text* is expected to be a Unicode |
| string and the encoding is applied before sending and also the |
| :attr:`TERMINATOR` (new line) is appended. |
| |
| |
| .. class:: ReaderThread(threading.Thread) |
| |
| Implement a serial port read loop and dispatch to a Protocol instance (like |
| the :class:`asyncio.Protocol`) but do it with threads. |
| |
| Calls to :meth:`close` will close the serial port but it is also possible |
| to just :meth:`stop` this thread and continue to use the serial port |
| instance otherwise. |
| |
| .. method:: __init__(serial_instance, protocol_factory) |
| |
| :param serial_instance: serial port instance (opened) to be used. |
| :param protocol_factory: a callable that returns a Protocol instance |
| |
| Initialize thread. |
| |
| Note that the ``serial_instance`` 's timeout is set to one second! |
| Other settings are not changed. |
| |
| .. method:: stop() |
| |
| Stop the reader thread. |
| |
| .. method:: run() |
| |
| The actual reader loop driven by the thread. It calls |
| :meth:`Protocol.connection_made`, reads from the serial port calling |
| :meth:`Protocol.data_received` and finally calls :meth:`Protocol.connection_lost` |
| when :meth:`close` is called or an error occurs. |
| |
| .. method:: write(data) |
| |
| :param bytes data: data to write |
| |
| Thread safe writing (uses lock). |
| |
| .. method:: close() |
| |
| Close the serial port and exit reader thread, calls :meth:`stop` (uses lock). |
| |
| .. method:: connect() |
| |
| Wait until connection is set up and return the transport and protocol |
| instances. |
| |
| |
| This class can be used as context manager, in this case it starts |
| the thread and connects automatically. The serial port is closed |
| when the context is left. |
| |
| .. method:: __enter__() |
| |
| :returns: protocol |
| |
| Connect and return protocol instance. |
| |
| .. method:: __exit__(exc_type, exc_val, exc_tb) |
| |
| Closes serial port. |
| |
| Example:: |
| |
| class PrintLines(LineReader): |
| def connection_made(self, transport): |
| super(PrintLines, self).connection_made(transport) |
| sys.stdout.write('port opened\n') |
| self.write_line('hello world') |
| |
| def handle_line(self, data): |
| sys.stdout.write('line received: {}\n'.format(repr(data))) |
| |
| def connection_lost(self, exc): |
| if exc: |
| traceback.print_exc(exc) |
| sys.stdout.write('port closed\n') |
| |
| ser = serial.serial_for_url('loop://', baudrate=115200, timeout=1) |
| with ReaderThread(ser, PrintLines) as protocol: |
| protocol.write_line('hello') |
| time.sleep(2) |
| |
| |
| asyncio |
| ======= |
| |
| ``asyncio`` was introduced with Python 3.4. Experimental support for pySerial |
| is provided via a separate distribution `pyserial-asyncio`_. |
| |
| It is currently under development, see: |
| |
| - http://pyserial-asyncio.readthedocs.io/ |
| - https://github.com/pyserial/pyserial-asyncio |
| |
| .. _`pyserial-asyncio`: https://pypi.python.org/pypi/pyserial-asyncio |
| |