diff options
Diffstat (limited to 'documentation/pyserial_api.rst')
| -rw-r--r-- | documentation/pyserial_api.rst | 1309 |
1 files changed, 1309 insertions, 0 deletions
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst new file mode 100644 index 0000000..12a7765 --- /dev/null +++ b/documentation/pyserial_api.rst @@ -0,0 +1,1309 @@ +============== + 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 + |