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