| ============== | |
| 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 | |