1============== 2 pySerial API 3============== 4 5.. module:: serial 6 7Classes 8======= 9 10Native ports 11------------ 12 13.. class:: Serial 14 15 .. 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) 16 17 :param port: 18 Device name or :const:`None`. 19 20 :param int baudrate: 21 Baud rate such as 9600 or 115200 etc. 22 23 :param bytesize: 24 Number of data bits. Possible values: 25 :const:`FIVEBITS`, :const:`SIXBITS`, :const:`SEVENBITS`, 26 :const:`EIGHTBITS` 27 28 :param parity: 29 Enable parity checking. Possible values: 30 :const:`PARITY_NONE`, :const:`PARITY_EVEN`, :const:`PARITY_ODD` 31 :const:`PARITY_MARK`, :const:`PARITY_SPACE` 32 33 :param stopbits: 34 Number of stop bits. Possible values: 35 :const:`STOPBITS_ONE`, :const:`STOPBITS_ONE_POINT_FIVE`, 36 :const:`STOPBITS_TWO` 37 38 :param float timeout: 39 Set a read timeout value in seconds. 40 41 :param bool xonxoff: 42 Enable software flow control. 43 44 :param bool rtscts: 45 Enable hardware (RTS/CTS) flow control. 46 47 :param bool dsrdtr: 48 Enable hardware (DSR/DTR) flow control. 49 50 :param float write_timeout: 51 Set a write timeout value in seconds. 52 53 :param float inter_byte_timeout: 54 Inter-character timeout, :const:`None` to disable (default). 55 56 :param bool exclusive: 57 Set exclusive access mode (POSIX only). A port cannot be opened in 58 exclusive access mode if it is already open in exclusive access mode. 59 60 :exception ValueError: 61 Will be raised when parameter are out of range, e.g. baud rate, data bits. 62 63 :exception SerialException: 64 In case the device can not be found or can not be configured. 65 66 67 The port is immediately opened on object creation, when a *port* is 68 given. It is not opened when *port* is :const:`None` and a successive call 69 to :meth:`open` is required. 70 71 *port* is a device name: depending on operating system. e.g. 72 ``/dev/ttyUSB0`` on GNU/Linux or ``COM3`` on Windows. 73 74 The parameter *baudrate* can be one of the standard values: 75 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 76 9600, 19200, 38400, 57600, 115200. 77 These are well supported on all platforms. 78 79 Standard values above 115200, such as: 230400, 460800, 500000, 576000, 80 921600, 1000000, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 81 4000000 also work on many platforms and devices. 82 83 Non-standard values are also supported on some platforms (GNU/Linux, MAC 84 OSX >= Tiger, Windows). Though, even on these platforms some serial 85 ports may reject non-standard values. 86 87 Possible values for the parameter *timeout* which controls the behavior 88 of :meth:`read`: 89 90 - ``timeout = None``: wait forever / until requested number of bytes 91 are received 92 - ``timeout = 0``: non-blocking mode, return immediately in any case, 93 returning zero or more, up to the requested number of bytes 94 - ``timeout = x``: set timeout to ``x`` seconds (float allowed) 95 returns immediately when the requested number of bytes are available, 96 otherwise wait until the timeout expires and return all bytes that 97 were received until then. 98 99 :meth:`write` is blocking by default, unless *write_timeout* is set. 100 For possible values refer to the list for *timeout* above. 101 102 Note that enabling both flow control methods (*xonxoff* and *rtscts*) 103 together may not be supported. It is common to use one of the methods 104 at once, not both. 105 106 *dsrdtr* is not supported by all platforms (silently ignored). Setting 107 it to ``None`` has the effect that its state follows *rtscts*. 108 109 Also consider using the function :func:`serial_for_url` instead of 110 creating Serial instances directly. 111 112 .. versionchanged:: 2.5 113 *dsrdtr* now defaults to ``False`` (instead of *None*) 114 .. versionchanged:: 3.0 numbers as *port* argument are no longer supported 115 .. versionadded:: 3.3 ``exclusive`` flag 116 117 .. method:: open() 118 119 Open port. The state of :attr:`rts` and :attr:`dtr` is applied. 120 121 .. note:: 122 123 Some OS and/or drivers may activate RTS and or DTR automatically, 124 as soon as the port is opened. There may be a glitch on RTS/DTR 125 when :attr:`rts` or :attr:`dtr` are set differently from their 126 default value (``True`` / active). 127 128 .. note:: 129 130 For compatibility reasons, no error is reported when applying 131 :attr:`rts` or :attr:`dtr` fails on POSIX due to EINVAL (22) or 132 ENOTTY (25). 133 134 .. method:: close() 135 136 Close port immediately. 137 138 .. method:: __del__() 139 140 Destructor, close port when serial port instance is freed. 141 142 143 The following methods may raise :exc:`SerialException` when applied to a closed 144 port. 145 146 .. method:: read(size=1) 147 148 :param size: Number of bytes to read. 149 :return: Bytes read from the port. 150 :rtype: bytes 151 152 Read *size* bytes from the serial port. If a timeout is set it may 153 return less characters as requested. With no timeout it will block 154 until the requested number of bytes is read. 155 156 .. versionchanged:: 2.5 157 Returns an instance of :class:`bytes` when available (Python 2.6 158 and newer) and :class:`str` otherwise. 159 160 .. method:: read_until(expected=LF, size=None) 161 162 :param expected: The byte string to search for. 163 :param size: Number of bytes to read. 164 :return: Bytes read from the port. 165 :rtype: bytes 166 167 Read until an expected sequence is found ('\\n' by default), the size 168 is exceeded or until timeout occurs. If a timeout is set it may 169 return less characters as requested. With no timeout it will block 170 until the requested number of bytes is read. 171 172 .. versionchanged:: 2.5 173 Returns an instance of :class:`bytes` when available (Python 2.6 174 and newer) and :class:`str` otherwise. 175 176 .. method:: write(data) 177 178 :param data: Data to send. 179 :return: Number of bytes written. 180 :rtype: int 181 :exception SerialTimeoutException: 182 In case a write timeout is configured for the port and the time is 183 exceeded. 184 185 Write the bytes *data* to the port. This should be of type ``bytes`` 186 (or compatible such as ``bytearray`` or ``memoryview``). Unicode 187 strings must be encoded (e.g. ``'hello'.encode('utf-8')``. 188 189 .. versionchanged:: 2.5 190 Accepts instances of :class:`bytes` and :class:`bytearray` when 191 available (Python 2.6 and newer) and :class:`str` otherwise. 192 193 .. versionchanged:: 2.5 194 Write returned ``None`` in previous versions. 195 196 .. method:: flush() 197 198 Flush of file like objects. In this case, wait until all data is 199 written. 200 201 .. attribute:: in_waiting 202 203 :getter: Get the number of bytes in the input buffer 204 :type: int 205 206 Return the number of bytes in the receive buffer. 207 208 .. versionchanged:: 3.0 changed to property from ``inWaiting()`` 209 210 .. attribute:: out_waiting 211 212 :getter: Get the number of bytes in the output buffer 213 :type: int 214 :platform: Posix 215 :platform: Windows 216 217 Return the number of bytes in the output buffer. 218 219 .. versionchanged:: 2.7 (Posix support added) 220 .. versionchanged:: 3.0 changed to property from ``outWaiting()`` 221 222 .. method:: reset_input_buffer() 223 224 Flush input buffer, discarding all its contents. 225 226 .. versionchanged:: 3.0 renamed from ``flushInput()`` 227 228 .. method:: reset_output_buffer() 229 230 Clear output buffer, aborting the current output and 231 discarding all that is in the buffer. 232 233 Note, for some USB serial adapters, this may only flush the buffer of 234 the OS and not all the data that may be present in the USB part. 235 236 .. versionchanged:: 3.0 renamed from ``flushOutput()`` 237 238 .. method:: send_break(duration=0.25) 239 240 :param float duration: Time in seconds, to activate the BREAK condition. 241 242 Send break condition. Timed, returns to idle state after given 243 duration. 244 245 246 .. attribute:: break_condition 247 248 :getter: Get the current BREAK state 249 :setter: Control the BREAK state 250 :type: bool 251 252 When set to ``True`` activate BREAK condition, else disable. 253 Controls TXD. When active, no transmitting is possible. 254 255 .. attribute:: rts 256 257 :setter: Set the state of the RTS line 258 :getter: Return the state of the RTS line 259 :type: bool 260 261 Set RTS line to specified logic level. It is possible to assign this 262 value before opening the serial port, then the value is applied upon 263 :meth:`open` (with restrictions, see :meth:`open`). 264 265 .. attribute:: dtr 266 267 :setter: Set the state of the DTR line 268 :getter: Return the state of the DTR line 269 :type: bool 270 271 Set DTR line to specified logic level. It is possible to assign this 272 value before opening the serial port, then the value is applied upon 273 :meth:`open` (with restrictions, see :meth:`open`). 274 275 Read-only attributes: 276 277 .. attribute:: name 278 279 :getter: Device name. 280 :type: str 281 282 .. versionadded:: 2.5 283 284 .. attribute:: cts 285 286 :getter: Get the state of the CTS line 287 :type: bool 288 289 Return the state of the CTS line. 290 291 .. attribute:: dsr 292 293 :getter: Get the state of the DSR line 294 :type: bool 295 296 Return the state of the DSR line. 297 298 .. attribute:: ri 299 300 :getter: Get the state of the RI line 301 :type: bool 302 303 Return the state of the RI line. 304 305 .. attribute:: cd 306 307 :getter: Get the state of the CD line 308 :type: bool 309 310 Return the state of the CD line 311 312 .. attribute:: is_open 313 314 :getter: Get the state of the serial port, whether it's open. 315 :type: bool 316 317 New values can be assigned to the following attributes (properties), the 318 port will be reconfigured, even if it's opened at that time: 319 320 321 .. attribute:: port 322 323 :type: str 324 325 Read or write port. When the port is already open, it will be closed 326 and reopened with the new setting. 327 328 .. attribute:: baudrate 329 330 :getter: Get current baud rate 331 :setter: Set new baud rate 332 :type: int 333 334 Read or write current baud rate setting. 335 336 .. attribute:: bytesize 337 338 :getter: Get current byte size 339 :setter: Set new byte size. Possible values: 340 :const:`FIVEBITS`, :const:`SIXBITS`, :const:`SEVENBITS`, 341 :const:`EIGHTBITS` 342 :type: int 343 344 Read or write current data byte size setting. 345 346 .. attribute:: parity 347 348 :getter: Get current parity setting 349 :setter: Set new parity mode. Possible values: 350 :const:`PARITY_NONE`, :const:`PARITY_EVEN`, :const:`PARITY_ODD` 351 :const:`PARITY_MARK`, :const:`PARITY_SPACE` 352 353 Read or write current parity setting. 354 355 .. attribute:: stopbits 356 357 :getter: Get current stop bit setting 358 :setter: Set new stop bit setting. Possible values: 359 :const:`STOPBITS_ONE`, :const:`STOPBITS_ONE_POINT_FIVE`, 360 :const:`STOPBITS_TWO` 361 362 Read or write current stop bit width setting. 363 364 .. attribute:: timeout 365 366 :getter: Get current read timeout setting 367 :setter: Set read timeout 368 :type: float (seconds) 369 370 Read or write current read timeout setting. 371 372 .. attribute:: write_timeout 373 374 :getter: Get current write timeout setting 375 :setter: Set write timeout 376 :type: float (seconds) 377 378 Read or write current write timeout setting. 379 380 .. versionchanged:: 3.0 renamed from ``writeTimeout`` 381 382 .. attribute:: inter_byte_timeout 383 384 :getter: Get current inter byte timeout setting 385 :setter: Disable (``None``) or enable the inter byte timeout 386 :type: float or None 387 388 Read or write current inter byte timeout setting. 389 390 .. versionchanged:: 3.0 renamed from ``interCharTimeout`` 391 392 .. attribute:: xonxoff 393 394 :getter: Get current software flow control setting 395 :setter: Enable or disable software flow control 396 :type: bool 397 398 Read or write current software flow control rate setting. 399 400 .. attribute:: rtscts 401 402 :getter: Get current hardware flow control setting 403 :setter: Enable or disable hardware flow control 404 :type: bool 405 406 Read or write current hardware flow control setting. 407 408 .. attribute:: dsrdtr 409 410 :getter: Get current hardware flow control setting 411 :setter: Enable or disable hardware flow control 412 :type: bool 413 414 Read or write current hardware flow control setting. 415 416 .. attribute:: rs485_mode 417 418 :getter: Get the current RS485 settings 419 :setter: Disable (``None``) or enable the RS485 settings 420 :type: :class:`rs485.RS485Settings` or ``None`` 421 :platform: Posix (Linux, limited set of hardware) 422 :platform: Windows (only RTS on TX possible) 423 424 Attribute to configure RS485 support. When set to an instance of 425 :class:`rs485.RS485Settings` and supported by OS, RTS will be active 426 when data is sent and inactive otherwise (for reception). The 427 :class:`rs485.RS485Settings` class provides additional settings 428 supported on some platforms. 429 430 .. versionadded:: 3.0 431 432 433 The following constants are also provided: 434 435 .. attribute:: BAUDRATES 436 437 A list of valid baud rates. The list may be incomplete, such that higher 438 and/or intermediate baud rates may also be supported by the device 439 (Read Only). 440 441 .. attribute:: BYTESIZES 442 443 A list of valid byte sizes for the device (Read Only). 444 445 .. attribute:: PARITIES 446 447 A list of valid parities for the device (Read Only). 448 449 .. attribute:: STOPBITS 450 451 A list of valid stop bit widths for the device (Read Only). 452 453 454 The following methods are for compatibility with the :mod:`io` library. 455 456 .. method:: readable() 457 458 :return: True 459 460 .. versionadded:: 2.5 461 462 .. method:: writable() 463 464 :return: True 465 466 .. versionadded:: 2.5 467 468 .. method:: seekable() 469 470 :return: False 471 472 .. versionadded:: 2.5 473 474 .. method:: readinto(b) 475 476 :param b: bytearray or array instance 477 :return: Number of byte read 478 479 Read up to len(b) bytes into :class:`bytearray` *b* and return the 480 number of bytes read. 481 482 .. versionadded:: 2.5 483 484 .. method:: readline(size=-1) 485 486 Provided via :meth:`io.IOBase.readline` 487 488 .. method:: readlines(hint=-1) 489 490 Provided via :meth:`io.IOBase.readlines` 491 492 .. method:: writelines(lines) 493 494 Provided via :meth:`io.IOBase.writelines` 495 496 The port settings can be read and written as dictionary. The following 497 keys are supported: ``write_timeout``, ``inter_byte_timeout``, 498 ``dsrdtr``, ``baudrate``, ``timeout``, ``parity``, ``bytesize``, 499 ``rtscts``, ``stopbits``, ``xonxoff`` 500 501 .. method:: get_settings() 502 503 :return: a dictionary with current port settings. 504 :rtype: dict 505 506 Get a dictionary with port settings. This is useful to backup the 507 current settings so that a later point in time they can be restored 508 using :meth:`apply_settings`. 509 510 Note that the state of control lines (RTS/DTR) are not part of the 511 settings. 512 513 .. versionadded:: 2.5 514 .. versionchanged:: 3.0 renamed from ``getSettingsDict`` 515 516 .. method:: apply_settings(d) 517 518 :param dict d: a dictionary with port settings. 519 520 Applies a dictionary that was created by :meth:`get_settings`. Only 521 changes are applied and when a key is missing, it means that the 522 setting stays unchanged. 523 524 Note that control lines (RTS/DTR) are not changed. 525 526 .. versionadded:: 2.5 527 .. versionchanged:: 3.0 renamed from ``applySettingsDict`` 528 529 530 .. _context-manager: 531 532 This class can be used as context manager. The serial port is closed when 533 the context is left. 534 535 .. method:: __enter__() 536 537 :returns: Serial instance 538 539 Returns the instance that was used in the ``with`` statement. 540 541 Example: 542 543 >>> with serial.serial_for_url(port) as s: 544 ... s.write(b'hello') 545 546 The port is opened automatically: 547 548 >>> port = serial.Serial() 549 >>> port.port = '...' 550 >>> with port as s: 551 ... s.write(b'hello') 552 553 Which also means that ``with`` statements can be used repeatedly, 554 each time opening and closing the port. 555 556 .. versionchanged:: 3.4 the port is automatically opened 557 558 559 .. method:: __exit__(exc_type, exc_val, exc_tb) 560 561 Closes serial port (exceptions are not handled by ``__exit__``). 562 563 564 Platform specific methods. 565 566 .. warning:: Programs using the following methods and attributes are not 567 portable to other platforms! 568 569 .. method:: nonblocking() 570 571 :platform: Posix 572 573 .. deprecated:: 3.2 574 The serial port is already opened in this mode. This method is not 575 needed and going away. 576 577 578 .. method:: fileno() 579 580 :platform: Posix 581 :return: File descriptor. 582 583 Return file descriptor number for the port that is opened by this object. 584 It is useful when serial ports are used with :mod:`select`. 585 586 .. method:: set_input_flow_control(enable) 587 588 :platform: Posix 589 :param bool enable: Set flow control state. 590 591 Manually control flow - when software flow control is enabled. 592 593 This will send XON (true) and XOFF (false) to the other device. 594 595 .. versionadded:: 2.7 (Posix support added) 596 .. versionchanged:: 3.0 renamed from ``flowControlOut`` 597 598 .. method:: set_output_flow_control(enable) 599 600 :platform: Posix (HW and SW flow control) 601 :platform: Windows (SW flow control only) 602 :param bool enable: Set flow control state. 603 604 Manually control flow of outgoing data - when hardware or software flow 605 control is enabled. 606 607 Sending will be suspended when called with ``False`` and enabled when 608 called with ``True``. 609 610 .. versionchanged:: 2.7 (renamed on Posix, function was called ``flowControl``) 611 .. versionchanged:: 3.0 renamed from ``setXON`` 612 613 .. method:: cancel_read() 614 615 :platform: Posix 616 :platform: Windows 617 618 Cancel a pending read operation from another thread. A blocking 619 :meth:`read` call is aborted immediately. :meth:`read` will not report 620 any error but return all data received up to that point (similar to a 621 timeout). 622 623 On Posix a call to `cancel_read()` may cancel a future :meth:`read` call. 624 625 .. versionadded:: 3.1 626 627 .. method:: cancel_write() 628 629 :platform: Posix 630 :platform: Windows 631 632 Cancel a pending write operation from another thread. The 633 :meth:`write` method will return immediately (no error indicated). 634 However the OS may still be sending from the buffer, a separate call to 635 :meth:`reset_output_buffer` may be needed. 636 637 On Posix a call to `cancel_write()` may cancel a future :meth:`write` call. 638 639 .. versionadded:: 3.1 640 641 .. note:: The following members are deprecated and will be removed in a 642 future release. 643 644 .. attribute:: portstr 645 646 .. deprecated:: 2.5 use :attr:`name` instead 647 648 .. method:: inWaiting() 649 650 .. deprecated:: 3.0 see :attr:`in_waiting` 651 652 .. method:: isOpen() 653 654 .. deprecated:: 3.0 see :attr:`is_open` 655 656 .. attribute:: writeTimeout 657 658 .. deprecated:: 3.0 see :attr:`write_timeout` 659 660 .. attribute:: interCharTimeout 661 662 .. deprecated:: 3.0 see :attr:`inter_byte_timeout` 663 664 .. method:: sendBreak(duration=0.25) 665 666 .. deprecated:: 3.0 see :meth:`send_break` 667 668 .. method:: flushInput() 669 670 .. deprecated:: 3.0 see :meth:`reset_input_buffer` 671 672 .. method:: flushOutput() 673 674 .. deprecated:: 3.0 see :meth:`reset_output_buffer` 675 676 .. method:: setBreak(level=True) 677 678 .. deprecated:: 3.0 see :attr:`break_condition` 679 680 .. method:: setRTS(level=True) 681 682 .. deprecated:: 3.0 see :attr:`rts` 683 684 .. method:: setDTR(level=True) 685 686 .. deprecated:: 3.0 see :attr:`dtr` 687 688 .. method:: getCTS() 689 690 .. deprecated:: 3.0 see :attr:`cts` 691 692 .. method:: getDSR() 693 694 .. deprecated:: 3.0 see :attr:`dsr` 695 696 .. method:: getRI() 697 698 .. deprecated:: 3.0 see :attr:`ri` 699 700 .. method:: getCD() 701 702 .. deprecated:: 3.0 see :attr:`cd` 703 704 .. method:: getSettingsDict() 705 706 .. deprecated:: 3.0 see :meth:`get_settings` 707 708 .. method:: applySettingsDict(d) 709 710 .. deprecated:: 3.0 see :meth:`apply_settings` 711 712 .. method:: outWaiting() 713 714 .. deprecated:: 3.0 see :attr:`out_waiting` 715 716 .. method:: setXON(level=True) 717 718 .. deprecated:: 3.0 see :meth:`set_output_flow_control` 719 720 .. method:: flowControlOut(enable) 721 722 .. deprecated:: 3.0 see :meth:`set_input_flow_control` 723 724 .. attribute:: rtsToggle 725 726 :platform: Windows 727 728 Attribute to configure RTS toggle control setting. When enabled and 729 supported by OS, RTS will be active when data is available and inactive 730 if no data is available. 731 732 .. versionadded:: 2.6 733 .. versionchanged:: 3.0 (removed, see :attr:`rs485_mode` instead) 734 735 736Implementation detail: some attributes and functions are provided by the 737class :class:`serial.SerialBase` which inherits from :class:`io.RawIOBase` 738and some by the platform specific class and others by the base class 739mentioned above. 740 741 742RS485 support 743------------- 744The :class:`Serial` class has a :attr:`Serial.rs485_mode` attribute which allows to 745enable RS485 specific support on some platforms. Currently Windows and Linux 746(only a small number of devices) are supported. 747 748:attr:`Serial.rs485_mode` needs to be set to an instance of 749:class:`rs485.RS485Settings` to enable or to ``None`` to disable this feature. 750 751Usage:: 752 753 import serial 754 import serial.rs485 755 ser = serial.Serial(...) 756 ser.rs485_mode = serial.rs485.RS485Settings(...) 757 ser.write(b'hello') 758 759There is a subclass :class:`rs485.RS485` available to emulate the RS485 support 760on regular serial ports (``serial.rs485`` needs to be imported). 761 762 763.. class:: rs485.RS485Settings 764 765 A class that holds RS485 specific settings which are supported on 766 some platforms. 767 768 .. versionadded:: 3.0 769 770 .. method:: __init__(rts_level_for_tx=True, rts_level_for_rx=False, loopback=False, delay_before_tx=None, delay_before_rx=None): 771 772 :param bool rts_level_for_tx: 773 RTS level for transmission 774 775 :param bool rts_level_for_rx: 776 RTS level for reception 777 778 :param bool loopback: 779 When set to ``True`` transmitted data is also received. 780 781 :param float delay_before_tx: 782 Delay after setting RTS but before transmission starts 783 784 :param float delay_before_rx: 785 Delay after transmission ends and resetting RTS 786 787 .. attribute:: rts_level_for_tx 788 789 RTS level for transmission. 790 791 .. attribute:: rts_level_for_rx 792 793 RTS level for reception. 794 795 .. attribute:: loopback 796 797 When set to ``True`` transmitted data is also received. 798 799 .. attribute:: delay_before_tx 800 801 Delay after setting RTS but before transmission starts (seconds as float). 802 803 .. attribute:: delay_before_rx 804 805 Delay after transmission ends and resetting RTS (seconds as float). 806 807 808.. class:: rs485.RS485 809 810 A subclass that replaces the :meth:`Serial.write` method with one that toggles RTS 811 according to the RS485 settings. 812 813 Usage:: 814 815 ser = serial.rs485.RS485(...) 816 ser.rs485_mode = serial.rs485.RS485Settings(...) 817 ser.write(b'hello') 818 819 .. warning:: This may work unreliably on some serial ports (control signals not 820 synchronized or delayed compared to data). Using delays may be unreliable 821 (varying times, larger than expected) as the OS may not support very fine 822 grained delays (no smaller than in the order of tens of milliseconds). 823 824 .. note:: Some implementations support this natively in the class 825 :class:`Serial`. Better performance can be expected when the native version 826 is used. 827 828 .. note:: The loopback property is ignored by this implementation. The actual 829 behavior depends on the used hardware. 830 831 832 833:rfc:`2217` Network ports 834------------------------- 835 836.. warning:: This implementation is currently in an experimental state. Use 837 at your own risk. 838 839.. class:: rfc2217.Serial 840 841 This implements a :rfc:`2217` compatible client. Port names are :ref:`URL 842 <URLs>` in the form: ``rfc2217://<host>:<port>[?<option>[&<option>]]`` 843 844 This class API is compatible to :class:`Serial` with a few exceptions: 845 846 - ``write_timeout`` is not implemented 847 - The current implementation starts a thread that keeps reading from the 848 (internal) socket. The thread is managed automatically by the 849 :class:`rfc2217.Serial` port object on :meth:`open`/:meth:`close`. 850 However it may be a problem for user applications that like to use select 851 instead of threads. 852 853 Due to the nature of the network and protocol involved there are a few 854 extra points to keep in mind: 855 856 - All operations have an additional latency time. 857 - Setting control lines (RTS/CTS) needs more time. 858 - Reading the status lines (DSR/DTR etc.) returns a cached value. When that 859 cache is updated depends entirely on the server. The server itself may 860 implement a polling at a certain rate and quick changes may be invisible. 861 - The network layer also has buffers. This means that :meth:`flush`, 862 :meth:`reset_input_buffer` and :meth:`reset_output_buffer` may work with 863 additional delay. Likewise :attr:`in_waiting` returns the size of the 864 data arrived at the objects internal buffer and excludes any bytes in the 865 network buffers or any server side buffer. 866 - Closing and immediately reopening the same port may fail due to time 867 needed by the server to get ready again. 868 869 Not implemented yet / Possible problems with the implementation: 870 871 - :rfc:`2217` flow control between client and server (objects internal 872 buffer may eat all your memory when never read). 873 - No authentication support (servers may not prompt for a password etc.) 874 - No encryption. 875 876 Due to lack of authentication and encryption it is not suitable to use this 877 client for connections across the internet and should only be used in 878 controlled environments. 879 880 .. versionadded:: 2.5 881 882 883.. class:: rfc2217.PortManager 884 885 This class provides helper functions for implementing :rfc:`2217` 886 compatible servers. 887 888 Basically, it implements everything needed for the :rfc:`2217` protocol. 889 It just does not open sockets and read/write to serial ports (though it 890 changes other port settings). The user of this class must take care of the 891 data transmission itself. The reason for that is, that this way, this class 892 supports all programming models such as threads and select. 893 894 Usage examples can be found in the examples where two TCP/IP - serial 895 converters are shown, one using threads (the single port server) and an 896 other using select (the multi port server). 897 898 .. note:: Each new client connection must create a new instance as this 899 object (and the :rfc:`2217` protocol) has internal state. 900 901 .. method:: __init__(serial_port, connection, debug_output=False) 902 903 :param serial_port: a :class:`Serial` instance that is managed. 904 :param connection: an object implementing :meth:`write`, used to write 905 to the network. 906 :param debug_output: enables debug messages: a :class:`logging.Logger` 907 instance or None. 908 909 Initializes the Manager and starts negotiating with client in Telnet 910 and :rfc:`2217` protocol. The negotiation starts immediately so that 911 the class should be instantiated in the moment the client connects. 912 913 The *serial_port* can be controlled by :rfc:`2217` commands. This 914 object will modify the port settings (baud rate etc.) and control lines 915 (RTS/DTR) send BREAK etc. when the corresponding commands are found by 916 the :meth:`filter` method. 917 918 The *connection* object must implement a :meth:`write` function. 919 This function must ensure that *data* is written at once (no user data 920 mixed in, i.e. it must be thread-safe). All data must be sent in its 921 raw form (:meth:`escape` must not be used) as it is used to send Telnet 922 and :rfc:`2217` control commands. 923 924 For diagnostics of the connection or the implementation, *debug_output* 925 can be set to an instance of a :class:`logging.Logger` (e.g. 926 ``logging.getLogger('rfc2217.server')``). The caller should configure 927 the logger using ``setLevel`` for the desired detail level of the logs. 928 929 .. method:: escape(data) 930 931 :param data: data to be sent over the network. 932 :return: data, escaped for Telnet/:rfc:`2217` 933 934 A generator that escapes all data to be compatible with :rfc:`2217`. 935 Implementors of servers should use this function to process all data 936 sent over the network. 937 938 The function returns a generator which can be used in ``for`` loops. 939 It can be converted to bytes using :func:`serial.to_bytes`. 940 941 .. method:: filter(data) 942 943 :param data: data read from the network, including Telnet and 944 :rfc:`2217` controls. 945 :return: data, free from Telnet and :rfc:`2217` controls. 946 947 A generator that filters and processes all data related to :rfc:`2217`. 948 Implementors of servers should use this function to process all data 949 received from the network. 950 951 The function returns a generator which can be used in ``for`` loops. 952 It can be converted to bytes using :func:`serial.to_bytes`. 953 954 .. method:: check_modem_lines(force_notification=False) 955 956 :param force_notification: Set to false. Parameter is for internal use. 957 958 This function needs to be called periodically (e.g. every second) when 959 the server wants to send NOTIFY_MODEMSTATE messages. This is required 960 to support the client for reading CTS/DSR/RI/CD status lines. 961 962 The function reads the status line and issues the notifications 963 automatically. 964 965 .. versionadded:: 2.5 966 967.. seealso:: 968 969 :rfc:`2217` - Telnet Com Port Control Option 970 971 972Exceptions 973========== 974 975.. exception:: SerialException 976 977 Base class for serial port exceptions. 978 979 .. versionchanged:: 2.5 980 Now derives from :exc:`IOError` instead of :exc:`Exception` 981 982.. exception:: SerialTimeoutException 983 984 Exception that is raised on write timeouts. 985 986 987Constants 988========= 989 990*Parity* 991 992.. data:: PARITY_NONE 993.. data:: PARITY_EVEN 994.. data:: PARITY_ODD 995.. data:: PARITY_MARK 996.. data:: PARITY_SPACE 997 998*Stop bits* 999 1000.. data:: STOPBITS_ONE 1001.. data:: STOPBITS_ONE_POINT_FIVE 1002.. data:: STOPBITS_TWO 1003 1004Note that 1.5 stop bits are not supported on POSIX. It will fall back to 2 stop 1005bits. 1006 1007*Byte size* 1008 1009.. data:: FIVEBITS 1010.. data:: SIXBITS 1011.. data:: SEVENBITS 1012.. data:: EIGHTBITS 1013 1014 1015*Others* 1016 1017Default control characters (instances of :class:`bytes` for Python 3.0+) for 1018software flow control: 1019 1020.. data:: XON 1021.. data:: XOFF 1022 1023Module version: 1024 1025.. data:: VERSION 1026 1027 A string indicating the pySerial version, such as ``3.0``. 1028 1029 .. versionadded:: 2.3 1030 1031 1032Module functions and attributes 1033=============================== 1034 1035.. function:: device(number) 1036 1037 .. versionchanged:: 3.0 removed, use ``serial.tools.list_ports`` instead 1038 1039 1040.. function:: serial_for_url(url, \*args, \*\*kwargs) 1041 1042 :param url: Device name, number or :ref:`URL <URLs>` 1043 :param do_not_open: When set to true, the serial port is not opened. 1044 :return: an instance of :class:`Serial` or a compatible object. 1045 1046 Get a native or a :rfc:`2217` implementation of the Serial class, depending 1047 on port/url. This factory function is useful when an application wants 1048 to support both, local ports and remote ports. There is also support 1049 for other types, see :ref:`URL <URLs>` section. 1050 1051 The port is not opened when a keyword parameter called *do_not_open* is 1052 given and true, by default it is opened. 1053 1054 .. versionadded:: 2.5 1055 1056 1057.. attribute:: protocol_handler_packages 1058 1059 This attribute is a list of package names (strings) that is searched for 1060 protocol handlers. 1061 1062 e.g. we want to support a URL ``foobar://``. A module 1063 ``my_handlers.protocol_foobar`` is provided by the user:: 1064 1065 serial.protocol_handler_packages.append("my_handlers") 1066 s = serial.serial_for_url("foobar://") 1067 1068 For an URL starting with ``XY://`` is the function :func:`serial_for_url` 1069 attempts to import ``PACKAGE.protocol_XY`` with each candidate for 1070 ``PACKAGE`` from this list. 1071 1072 .. versionadded:: 2.6 1073 1074 1075.. function:: to_bytes(sequence) 1076 1077 :param sequence: bytes, bytearray or memoryview 1078 :returns: an instance of ``bytes`` 1079 1080 Convert a sequence to a ``bytes`` type. This is used to write code that is 1081 compatible to Python 2.x and 3.x. 1082 1083 In Python versions prior 3.x, ``bytes`` is a subclass of str. They convert 1084 ``str([17])`` to ``'[17]'`` instead of ``'\x11'`` so a simple 1085 ``bytes(sequence)`` doesn't work for all versions of Python. 1086 1087 This function is used internally and in the unit tests. 1088 1089 .. versionadded:: 2.5 1090 1091.. function:: iterbytes(sequence) 1092 1093 :param sequence: bytes, bytearray or memoryview 1094 :returns: a generator that yields bytes 1095 1096 Some versions of Python (3.x) would return integers instead of bytes when 1097 looping over an instance of ``bytes``. This helper function ensures that 1098 bytes are returned. 1099 1100 .. versionadded:: 3.0 1101 1102 1103Threading 1104========= 1105 1106.. module:: serial.threaded 1107.. versionadded:: 3.0 1108 1109.. warning:: This implementation is currently in an experimental state. Use 1110 at your own risk. 1111 1112This module provides classes to simplify working with threads and protocols. 1113 1114.. class:: Protocol 1115 1116 Protocol as used by the :class:`ReaderThread`. This base class provides empty 1117 implementations of all methods. 1118 1119 1120 .. method:: connection_made(transport) 1121 1122 :param transport: instance used to write to serial port. 1123 1124 Called when reader thread is started. 1125 1126 .. method:: data_received(data) 1127 1128 :param bytes data: received bytes 1129 1130 Called with snippets received from the serial port. 1131 1132 .. method:: connection_lost(exc) 1133 1134 :param exc: Exception if connection was terminated by error else ``None`` 1135 1136 Called when the serial port is closed or the reader loop terminated 1137 otherwise. 1138 1139.. class:: Packetizer(Protocol) 1140 1141 Read binary packets from serial port. Packets are expected to be terminated 1142 with a ``TERMINATOR`` byte (null byte by default). 1143 1144 The class also keeps track of the transport. 1145 1146 .. attribute:: TERMINATOR = b'\\0' 1147 1148 .. method:: __init__() 1149 1150 .. method:: connection_made(transport) 1151 1152 Stores transport. 1153 1154 .. method:: connection_lost(exc) 1155 1156 Forgets transport. 1157 1158 .. method:: data_received(data) 1159 1160 :param bytes data: partial received data 1161 1162 Buffer received data and search for :attr:`TERMINATOR`, when found, 1163 call :meth:`handle_packet`. 1164 1165 .. method:: handle_packet(packet) 1166 1167 :param bytes packet: a packet as defined by ``TERMINATOR`` 1168 1169 Process packets - to be overridden by subclassing. 1170 1171 1172.. class:: LineReader(Packetizer) 1173 1174 Read and write (Unicode) lines from/to serial port. 1175 The encoding is applied. 1176 1177 1178 .. attribute:: TERMINATOR = b'\\r\\n' 1179 1180 Line ending. 1181 1182 .. attribute:: ENCODING = 'utf-8' 1183 1184 Encoding of the send and received data. 1185 1186 .. attribute:: UNICODE_HANDLING = 'replace' 1187 1188 Unicode error handly policy. 1189 1190 .. method:: handle_packet(packet) 1191 1192 :param bytes packet: a packet as defined by ``TERMINATOR`` 1193 1194 In this case it will be a line, calls :meth:`handle_line` after applying 1195 the :attr:`ENCODING`. 1196 1197 .. method:: handle_line(line) 1198 1199 :param str line: Unicode string with one line (excluding line terminator) 1200 1201 Process one line - to be overridden by subclassing. 1202 1203 .. method:: write_line(text) 1204 1205 :param str text: Unicode string with one line (excluding line terminator) 1206 1207 Write *text* to the transport. *text* is expected to be a Unicode 1208 string and the encoding is applied before sending and also the 1209 :attr:`TERMINATOR` (new line) is appended. 1210 1211 1212.. class:: ReaderThread(threading.Thread) 1213 1214 Implement a serial port read loop and dispatch to a Protocol instance (like 1215 the :class:`asyncio.Protocol`) but do it with threads. 1216 1217 Calls to :meth:`close` will close the serial port but it is also possible 1218 to just :meth:`stop` this thread and continue to use the serial port 1219 instance otherwise. 1220 1221 .. method:: __init__(serial_instance, protocol_factory) 1222 1223 :param serial_instance: serial port instance (opened) to be used. 1224 :param protocol_factory: a callable that returns a Protocol instance 1225 1226 Initialize thread. 1227 1228 Note that the ``serial_instance`` 's timeout is set to one second! 1229 Other settings are not changed. 1230 1231 .. method:: stop() 1232 1233 Stop the reader thread. 1234 1235 .. method:: run() 1236 1237 The actual reader loop driven by the thread. It calls 1238 :meth:`Protocol.connection_made`, reads from the serial port calling 1239 :meth:`Protocol.data_received` and finally calls :meth:`Protocol.connection_lost` 1240 when :meth:`close` is called or an error occurs. 1241 1242 .. method:: write(data) 1243 1244 :param bytes data: data to write 1245 1246 Thread safe writing (uses lock). 1247 1248 .. method:: close() 1249 1250 Close the serial port and exit reader thread, calls :meth:`stop` (uses lock). 1251 1252 .. method:: connect() 1253 1254 Wait until connection is set up and return the transport and protocol 1255 instances. 1256 1257 1258 This class can be used as context manager, in this case it starts 1259 the thread and connects automatically. The serial port is closed 1260 when the context is left. 1261 1262 .. method:: __enter__() 1263 1264 :returns: protocol 1265 1266 Connect and return protocol instance. 1267 1268 .. method:: __exit__(exc_type, exc_val, exc_tb) 1269 1270 Closes serial port. 1271 1272Example:: 1273 1274 class PrintLines(LineReader): 1275 def connection_made(self, transport): 1276 super(PrintLines, self).connection_made(transport) 1277 sys.stdout.write('port opened\n') 1278 self.write_line('hello world') 1279 1280 def handle_line(self, data): 1281 sys.stdout.write('line received: {}\n'.format(repr(data))) 1282 1283 def connection_lost(self, exc): 1284 if exc: 1285 traceback.print_exc(exc) 1286 sys.stdout.write('port closed\n') 1287 1288 ser = serial.serial_for_url('loop://', baudrate=115200, timeout=1) 1289 with ReaderThread(ser, PrintLines) as protocol: 1290 protocol.write_line('hello') 1291 time.sleep(2) 1292 1293 1294asyncio 1295======= 1296 1297``asyncio`` was introduced with Python 3.4. Experimental support for pySerial 1298is provided via a separate distribution `pyserial-asyncio`_. 1299 1300It is currently under development, see: 1301 1302- http://pyserial-asyncio.readthedocs.io/ 1303- https://github.com/pyserial/pyserial-asyncio 1304 1305.. _`pyserial-asyncio`: https://pypi.python.org/pypi/pyserial-asyncio 1306 1307