esptool 5.3.dev3__tar.gz → 5.4.0__tar.gz

{esptool-5.3.dev3/esptool.egg-info → esptool-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: esptool
-Version: 5.3.dev3
+Version: 5.4.0
 Summary: A serial utility for flashing, provisioning, and interacting with Espressif SoCs.
 Author: Fredrik Ahlberg (themadinventor), Angus Gratton (projectgus), Espressif Systems
 License: GPLv2+
@@ -34,6 +34,7 @@ Requires-Dist: PyYAML>=5.1
 Requires-Dist: intelhex
 Requires-Dist: rich_click<2
 Requires-Dist: click<9
+Requires-Dist: esp-pylib[cli,ide,serial]>=1.0.0
 Provides-Extra: dev
 Requires-Dist: pyelftools; extra == "dev"
 Requires-Dist: coverage~=6.0; extra == "dev"
@@ -45,7 +46,7 @@ Requires-Dist: czespressif; extra == "dev"
 Provides-Extra: hsm
 Requires-Dist: python-pkcs11; extra == "hsm"
 Provides-Extra: docs
-Requires-Dist: esp-docs~=2.1; extra == "docs"
+Requires-Dist: esp-docs<3,>=2.1.4; extra == "docs"
 Requires-Dist: sphinx-tabs; extra == "docs"
 Dynamic: license-file
 
@@ -60,6 +61,10 @@ A Python-based, open-source, platform-independent serial utility for flashing, p
 
 Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool -h`.
 
+## Flasher Stub
+
+esptool uploads a small [flasher stub](https://docs.espressif.com/projects/esptool/en/latest/esptool/flasher-stub.html) program to the chip to improve flashing performance and work around ROM bootloader limitations. The stub is developed in the [esp-flasher-stub](https://github.com/espressif/esp-flasher-stub) repository. Prebuilt binaries are bundled with esptool releases.
+
 ## Contribute
 
 If you're interested in contributing to esptool, please check the [contributions guide](https://docs.espressif.com/projects/esptool/en/latest/contributing.html).

{esptool-5.3.dev3 → esptool-5.4.0}/README.md

@@ -9,6 +9,10 @@ A Python-based, open-source, platform-independent serial utility for flashing, p
 
 Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool -h`.
 
+## Flasher Stub
+
+esptool uploads a small [flasher stub](https://docs.espressif.com/projects/esptool/en/latest/esptool/flasher-stub.html) program to the chip to improve flashing performance and work around ROM bootloader limitations. The stub is developed in the [esp-flasher-stub](https://github.com/espressif/esp-flasher-stub) repository. Prebuilt binaries are bundled with esptool releases.
+
 ## Contribute
 
 If you're interested in contributing to esptool, please check the [contributions guide](https://docs.espressif.com/projects/esptool/en/latest/contributing.html).

{esptool-5.3.dev3 → esptool-5.4.0}/esp_rfc2217_server/__init__.py

@@ -1,150 +1,156 @@
-# SPDX-FileCopyrightText: 2009-2015 Chris Liechti
-# SPDX-FileContributor: 2020-2024 Espressif Systems (Shanghai) CO LTD
-# SPDX-License-Identifier: BSD-3-Clause
-#
-# Redirect data from a TCP/IP connection to a serial port and vice versa using RFC 2217.
-
-###################################################################################
-# redirect data from a TCP/IP connection to a serial port and vice versa
-# using RFC 2217
-#
-# (C) 2009-2015 Chris Liechti <cliechti@gmx.net>
-#
-# SPDX-License-Identifier: BSD-3-Clause
-
-import logging
-import socket
-import sys
-
-import serial
-
-from esp_rfc2217_server.redirector import Redirector
-from esptool.util import check_deprecated_py_suffix
-
-
-def main():
-    check_deprecated_py_suffix("esp_rfc2217_server")
-    import argparse
-
-    parser = argparse.ArgumentParser(
-        description="RFC 2217 Serial to Network (TCP/IP) redirector.",
-        epilog="NOTE: no security measures are implemented. "
-        "Anyone can remotely connect to this service over the network.\n"
-        "Only one connection at once is supported. "
-        "When the connection is terminated it waits for the next connect.",
-    )
-
-    parser.add_argument("SERIALPORT")
-
-    parser.add_argument(
-        "-p",
-        "--localport",
-        type=int,
-        help="local TCP port, default: %(default)s",
-        metavar="TCPPORT",
-        default=2217,
-    )
-
-    parser.add_argument(
-        "-v",
-        "--verbose",
-        dest="verbosity",
-        action="count",
-        help="print more diagnostic messages (option can be given multiple times)",
-        default=0,
-    )
-
-    parser.add_argument(
-        "--r0",
-        help="Use delays necessary for ESP32 revision 0 chips",
-        action="store_true",
-    )
-
-    args = parser.parse_args()
-
-    if args.verbosity > 3:
-        args.verbosity = 3
-    level = (logging.WARNING, logging.INFO, logging.DEBUG, logging.NOTSET)[
-        args.verbosity
-    ]
-    logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.INFO)
-    logging.getLogger("rfc2217").setLevel(level)
-
-    # connect to serial port
-    ser = serial.serial_for_url(args.SERIALPORT, do_not_open=True, exclusive=True)
-    ser.timeout = 3  # required so that the reader thread can exit
-    # reset control line as no _remote_ "terminal" has been connected yet
-    ser.dtr = False
-    ser.rts = False
-
-    logging.info("RFC 2217 TCP/IP to Serial redirector - type Ctrl-C / BREAK to quit")
-
-    try:
-        ser.open()
-    except serial.SerialException as e:
-        logging.error(f"Could not open serial port {ser.name}: {e}")
-        sys.exit(1)
-
-    logging.info(f"Serving serial port: {ser.name}")
-    settings = ser.get_settings()
-
-    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-    srv.bind(("", args.localport))
-    srv.listen(1)
-    logging.info(f"TCP/IP port: {args.localport}")
-
-    try:
-        host_ip = socket.gethostbyname(socket.gethostname())
-    except OSError:
-        # CI/minimal containers often have no DNS for gethostname(); the server
-        # is still reachable on loopback.
-        host_ip = "127.0.0.1"
-    wait_msg = (
-        "Waiting for connection ... use the 'rfc2217://"
-        f"{host_ip}:{args.localport}?ign_set_control' as a PORT"
-    )
-    logging.info(wait_msg)
-
-    while True:
-        srv.settimeout(5)
-        client_socket = None
-        try:
-            while client_socket is None:
-                try:
-                    client_socket, addr = srv.accept()
-                except TimeoutError:
-                    print(".", end="", flush=True)
-        except KeyboardInterrupt:
-            print("")  # resetting inline print
-            logging.info("Exited with keyboard interrupt")
-            break
-        try:
-            logging.info(f"Connected by {addr[0]}:{addr[1]}")
-            client_socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
-            ser.rts = True
-            ser.dtr = True
-            # enter network <-> serial loop
-            r = Redirector(ser, client_socket, args.verbosity > 0, args.r0)
-            try:
-                r.shortcircuit()
-            finally:
-                logging.info("Disconnected")
-                r.stop()
-                client_socket.close()
-                ser.dtr = False
-                ser.rts = False
-                # Restore port settings (may have been changed by RFC 2217
-                # capable client)
-                ser.apply_settings(settings)
-        except KeyboardInterrupt:
-            print(flush=True)
-            break
-        except OSError as msg:
-            logging.error(str(msg))
-
-    logging.info("--- exit ---")
-
-
-if __name__ == "__main__":
-    main()
+# SPDX-FileCopyrightText: 2009-2015 Chris Liechti
+# SPDX-FileContributor: 2020-2026 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Redirect data from a TCP/IP connection to a serial port and vice versa using RFC 2217.
+
+###################################################################################
+# redirect data from a TCP/IP connection to a serial port and vice versa
+# using RFC 2217
+#
+# (C) 2009-2015 Chris Liechti <cliechti@gmx.net>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+import logging
+import socket
+
+import rich_click as click
+import serial
+from esp_pylib.cli_types import SerialPortType
+from rich.markup import escape
+
+from esp_rfc2217_server.redirector import Redirector
+from esptool.logger import log
+from esptool.util import check_deprecated_py_suffix
+
+
+@click.command(
+    no_args_is_help=True,
+    context_settings=dict(help_option_names=["-h", "--help"], max_content_width=120),
+    help="RFC 2217 Serial to Network (TCP/IP) redirector.",
+    epilog="NOTE: no security measures are implemented. "
+    "Anyone can remotely connect to this service over the network. "
+    "Only one connection at once is supported. "
+    "When the connection is terminated it waits for the next connect.",
+)
+@click.argument("serialport", metavar="SERIALPORT", type=SerialPortType())
+@click.option(
+    "--localport",
+    "-p",
+    type=int,
+    metavar="TCPPORT",
+    default=2217,
+    show_default=True,
+    help="Local TCP port.",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    "verbosity",
+    count=True,
+    help="Print more diagnostic messages (option can be given multiple times).",
+)
+@click.option(
+    "--r0",
+    is_flag=True,
+    help="Use delays necessary for ESP32 revision 0 chips.",
+)
+def cli(serialport: str, localport: int, verbosity: int, r0: bool):
+    if verbosity > 3:
+        verbosity = 3
+    # The ``-v`` count only tunes pyserial's RFC2217 ``PortManager``, which
+    # logs through the stdlib ``logging`` module (it expects a
+    # ``logging.Logger``). The server's own status/error output below goes
+    # through the shared esptool/esp-pylib logger instead.
+    level = (logging.WARNING, logging.INFO, logging.DEBUG, logging.NOTSET)[verbosity]
+    logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.INFO)
+    logging.getLogger("rfc2217").setLevel(level)
+
+    # connect to serial port
+    ser = serial.serial_for_url(serialport, do_not_open=True, exclusive=True)
+    ser.timeout = 3  # required so that the reader thread can exit
+    # reset control line as no _remote_ "terminal" has been connected yet
+    ser.dtr = False
+    ser.rts = False
+
+    log.print("RFC 2217 TCP/IP to Serial redirector - type Ctrl-C / BREAK to quit")
+
+    try:
+        ser.open()
+    except serial.SerialException as e:
+        log.die(f"Could not open serial port {escape(str(ser.name))}: {escape(str(e))}")
+
+    log.print(f"Serving serial port: {ser.name}")
+    settings = ser.get_settings()
+
+    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    srv.bind(("", localport))
+    srv.listen(1)
+    log.print(f"TCP/IP port: {localport}")
+
+    try:
+        host_ip = socket.gethostbyname(socket.gethostname())
+    except OSError:
+        # CI/minimal containers often have no DNS for gethostname(); the server
+        # is still reachable on loopback.
+        host_ip = "127.0.0.1"
+    wait_msg = (
+        "Waiting for connection ... use the 'rfc2217://"
+        f"{host_ip}:{localport}?ign_set_control' as a PORT"
+    )
+    log.print(wait_msg)
+
+    while True:
+        srv.settimeout(5)
+        client_socket = None
+        try:
+            while client_socket is None:
+                try:
+                    client_socket, addr = srv.accept()
+                except TimeoutError:
+                    print(".", end="", flush=True)
+        except KeyboardInterrupt:
+            print("")  # resetting inline print
+            log.print("Exited with keyboard interrupt")
+            break
+        try:
+            log.print(f"Connected by {addr[0]}:{addr[1]}")
+            client_socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+            ser.rts = True
+            ser.dtr = True
+            # enter network <-> serial loop
+            r = Redirector(ser, client_socket, verbosity > 0, r0)
+            try:
+                r.shortcircuit()
+            finally:
+                log.print("Disconnected")
+                r.stop()
+                client_socket.close()
+                ser.dtr = False
+                ser.rts = False
+                # Restore port settings (may have been changed by RFC 2217
+                # capable client)
+                ser.apply_settings(settings)
+        except KeyboardInterrupt:
+            print(flush=True)
+            break
+        except OSError as msg:
+            log.err(str(msg))
+
+    log.print("--- exit ---")
+
+
+def main(argv: list[str] | None = None):
+    """Entry point for the ``esp_rfc2217_server`` console script.
+
+    ``argv`` is an optional override for ``sys.argv`` (a list of argument
+    strings) to ease programmatic invocation and testing.
+    """
+    check_deprecated_py_suffix("esp_rfc2217_server")
+    cli.main(args=argv)
+
+
+if __name__ == "__main__":
+    main()

{esptool-5.3.dev3 → esptool-5.4.0}/esp_rfc2217_server/__main__.py

@@ -1,9 +1,9 @@
-# SPDX-FileCopyrightText: 2014-2024 Fredrik Ahlberg, Angus Gratton,
-# Espressif Systems (Shanghai) CO LTD, other contributors as noted.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-
-import esp_rfc2217_server
-
-if __name__ == "__main__":
-    esp_rfc2217_server.main()
+# SPDX-FileCopyrightText: 2014-2024 Fredrik Ahlberg, Angus Gratton,
+# Espressif Systems (Shanghai) CO LTD, other contributors as noted.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+import esp_rfc2217_server
+
+if __name__ == "__main__":
+    esp_rfc2217_server.main()

{esptool-5.3.dev3 → esptool-5.4.0}/esp_rfc2217_server/esp_port_manager.py

@@ -1,102 +1,102 @@
-# SPDX-FileCopyrightText: 2014-2024 Fredrik Ahlberg, Angus Gratton,
-# Espressif Systems (Shanghai) CO LTD, other contributors as noted.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-import os
-import threading
-
-import serial
-import serial.rfc2217
-from serial.rfc2217 import (
-    COM_PORT_OPTION,
-    SET_CONTROL,
-    SET_CONTROL_DTR_OFF,
-    SET_CONTROL_DTR_ON,
-    SET_CONTROL_RTS_OFF,
-    SET_CONTROL_RTS_ON,
-)
-
-from esptool.config import load_config_file
-from esptool.reset import (
-    DEFAULT_RESET_DELAY,
-    ClassicReset,
-    CustomReset,
-    HardReset,
-    UnixTightReset,
-)
-
-cfg, _ = load_config_file(verbose=True)
-cfg = cfg["esptool"]
-
-
-class EspPortManager(serial.rfc2217.PortManager):
-    """
-    The beginning of the reset sequence is detected and the proper reset sequence
-    is applied in a thread. The rest of the reset sequence received is just ignored
-    and not sent to the serial port.
-    """
-
-    def __init__(self, serial_port, connection, esp32r0_delay, logger=None):
-        self.esp32r0_delay = esp32r0_delay
-        self.is_download_mode = False
-        super().__init__(serial_port, connection, logger)
-
-    def _telnet_process_subnegotiation(self, suboption):
-        if suboption[0:1] == COM_PORT_OPTION and suboption[1:2] == SET_CONTROL:
-            if suboption[2:3] == SET_CONTROL_DTR_OFF:
-                self.is_download_mode = False
-                self.serial.dtr = False
-                return
-            elif suboption[2:3] == SET_CONTROL_RTS_OFF and not self.is_download_mode:
-                reset_thread = threading.Thread(target=self._hard_reset_thread)
-                reset_thread.daemon = True
-                reset_thread.name = "hard_reset_thread"
-                reset_thread.start()
-                return
-            elif suboption[2:3] == SET_CONTROL_DTR_ON and not self.is_download_mode:
-                self.is_download_mode = True
-                reset_thread = threading.Thread(target=self._reset_thread)
-                reset_thread.daemon = True
-                reset_thread.name = "reset_thread"
-                reset_thread.start()
-                return
-            elif suboption[2:3] in [
-                SET_CONTROL_DTR_ON,
-                SET_CONTROL_RTS_ON,
-                SET_CONTROL_RTS_OFF,
-            ]:
-                return
-        # only in cases not handled above do the original implementation in PortManager
-        super()._telnet_process_subnegotiation(suboption)
-
-    def _hard_reset_thread(self):
-        """
-        The reset logic used for hard resetting the chip.
-        """
-        if self.logger:
-            self.logger.info("Activating hard reset in thread")
-        cfg_custom_hard_reset_sequence = cfg.get("custom_hard_reset_sequence")
-        if cfg_custom_hard_reset_sequence is not None:
-            CustomReset(self.serial, cfg_custom_hard_reset_sequence)()
-        else:
-            HardReset(self.serial)()
-
-    def _reset_thread(self):
-        """
-        The reset logic is used from esptool because the RTS and DTR signals
-        cannot be retransmitted through RFC 2217 with proper timing.
-        """
-        if self.logger:
-            self.logger.info("Activating reset in thread")
-
-        delay = DEFAULT_RESET_DELAY
-        if self.esp32r0_delay:
-            delay += 0.5
-
-        cfg_custom_reset_sequence = cfg.get("custom_reset_sequence")
-        if cfg_custom_reset_sequence is not None:
-            CustomReset(self.serial, cfg_custom_reset_sequence)()
-        elif os.name != "nt":
-            UnixTightReset(self.serial, delay)()
-        else:
-            ClassicReset(self.serial, delay)()
+# SPDX-FileCopyrightText: 2014-2024 Fredrik Ahlberg, Angus Gratton,
+# Espressif Systems (Shanghai) CO LTD, other contributors as noted.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+import os
+import threading
+
+import serial
+import serial.rfc2217
+from serial.rfc2217 import (
+    COM_PORT_OPTION,
+    SET_CONTROL,
+    SET_CONTROL_DTR_OFF,
+    SET_CONTROL_DTR_ON,
+    SET_CONTROL_RTS_OFF,
+    SET_CONTROL_RTS_ON,
+)
+
+from esptool.config import load_config_file
+from esptool.reset import (
+    DEFAULT_RESET_DELAY,
+    ClassicReset,
+    CustomReset,
+    HardReset,
+    UnixTightReset,
+)
+
+cfg, _ = load_config_file(verbose=True)
+cfg = cfg["esptool"]
+
+
+class EspPortManager(serial.rfc2217.PortManager):
+    """
+    The beginning of the reset sequence is detected and the proper reset sequence
+    is applied in a thread. The rest of the reset sequence received is just ignored
+    and not sent to the serial port.
+    """
+
+    def __init__(self, serial_port, connection, esp32r0_delay, logger=None):
+        self.esp32r0_delay = esp32r0_delay
+        self.is_download_mode = False
+        super().__init__(serial_port, connection, logger)
+
+    def _telnet_process_subnegotiation(self, suboption):
+        if suboption[0:1] == COM_PORT_OPTION and suboption[1:2] == SET_CONTROL:
+            if suboption[2:3] == SET_CONTROL_DTR_OFF:
+                self.is_download_mode = False
+                self.serial.dtr = False
+                return
+            elif suboption[2:3] == SET_CONTROL_RTS_OFF and not self.is_download_mode:
+                reset_thread = threading.Thread(target=self._hard_reset_thread)
+                reset_thread.daemon = True
+                reset_thread.name = "hard_reset_thread"
+                reset_thread.start()
+                return
+            elif suboption[2:3] == SET_CONTROL_DTR_ON and not self.is_download_mode:
+                self.is_download_mode = True
+                reset_thread = threading.Thread(target=self._reset_thread)
+                reset_thread.daemon = True
+                reset_thread.name = "reset_thread"
+                reset_thread.start()
+                return
+            elif suboption[2:3] in [
+                SET_CONTROL_DTR_ON,
+                SET_CONTROL_RTS_ON,
+                SET_CONTROL_RTS_OFF,
+            ]:
+                return
+        # only in cases not handled above do the original implementation in PortManager
+        super()._telnet_process_subnegotiation(suboption)
+
+    def _hard_reset_thread(self):
+        """
+        The reset logic used for hard resetting the chip.
+        """
+        if self.logger:
+            self.logger.info("Activating hard reset in thread")
+        cfg_custom_hard_reset_sequence = cfg.get("custom_hard_reset_sequence")
+        if cfg_custom_hard_reset_sequence is not None:
+            CustomReset(self.serial, cfg_custom_hard_reset_sequence)()
+        else:
+            HardReset(self.serial)()
+
+    def _reset_thread(self):
+        """
+        The reset logic is used from esptool because the RTS and DTR signals
+        cannot be retransmitted through RFC 2217 with proper timing.
+        """
+        if self.logger:
+            self.logger.info("Activating reset in thread")
+
+        delay = DEFAULT_RESET_DELAY
+        if self.esp32r0_delay:
+            delay += 0.5
+
+        cfg_custom_reset_sequence = cfg.get("custom_reset_sequence")
+        if cfg_custom_reset_sequence is not None:
+            CustomReset(self.serial, cfg_custom_reset_sequence)()
+        elif os.name != "nt":
+            UnixTightReset(self.serial, delay)()
+        else:
+            ClassicReset(self.serial, delay)()