esptool 4.8.dev4__tar.gz → 4.8.1__tar.gz

{esptool-4.8.dev4 → esptool-4.8.1}/MANIFEST.in

@@ -1,11 +1,11 @@
 include README.md
 include LICENSE
-include esptool/targets/stub_flasher/*.json
+include esptool/targets/stub_flasher/1/*
+include esptool/targets/stub_flasher/2/*
 include espefuse/efuse_defs/*.yaml
 # sdist includes test/test*.py by default, but esptool.py tests
 # are so far only intended to run from the git repo itself
 prune test
-prune flasher_stub
 prune .github
 prune docs
 exclude .git*

esptool-4.8.1/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.1
+Name: esptool
+Version: 4.8.1
+Summary: A serial utility to communicate & flash code to Espressif chips.
+Author: Fredrik Ahlberg (themadinventor), Angus Gratton (projectgus), Espressif Systems
+License: GPLv2+
+Project-URL: Homepage, https://github.com/espressif/esptool/
+Project-URL: Documentation, https://docs.espressif.com/projects/esptool/
+Project-URL: Source, https://github.com/espressif/esptool/
+Project-URL: Tracker, https://github.com/espressif/esptool/issues/
+Project-URL: Changelog, https://github.com/espressif/esptool/blob/master/CHANGELOG.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Provides-Extra: hsm
+License-File: LICENSE
+
+# esptool.py
+
+A Python-based, open-source, platform-independent utility to communicate with the ROM bootloader in Espressif chips.
+
+[![Test esptool](https://github.com/espressif/esptool/actions/workflows/test_esptool.yml/badge.svg?branch=master)](https://github.com/espressif/esptool/actions/workflows/test_esptool.yml) [![Build esptool](https://github.com/espressif/esptool/actions/workflows/build_esptool.yml/badge.svg?branch=master)](https://github.com/espressif/esptool/actions/workflows/build_esptool.yml)
+
+## Documentation
+
+Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool.py -h`.
+
+## Contribute
+
+If you're interested in contributing to esptool.py, please check the [contributions guide](https://docs.espressif.com/projects/esptool/en/latest/contributing.html).
+
+## About
+
+esptool.py was initially created by Fredrik Ahlberg (@[themadinventor](https://github.com/themadinventor/)), and later maintained by Angus Gratton (@[projectgus](https://github.com/projectgus/)). It is now supported by Espressif Systems. It has also received improvements from many members of the community.
+
+## License
+
+This document and the attached source code are released as Free Software under GNU General Public License Version 2 or later. See the accompanying [LICENSE file](https://github.com/espressif/esptool/blob/master/LICENSE) for a copy.

esptool-4.8.1/esp_rfc2217_server/__init__.py

@@ -0,0 +1,124 @@
+# 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
+
+
+def main():
+    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(level=logging.INFO)
+    # logging.getLogger('root').setLevel(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(" Could not open serial port {}: {}".format(ser.name, e))
+        sys.exit(1)
+
+    logging.info(" Serving serial port: {}".format(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(" TCP/IP port: {}".format(args.localport))
+    while True:
+        try:
+            client_socket, addr = srv.accept()
+            logging.info("Connected by {}:{}".format(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:
+            sys.stdout.write("\n")
+            break
+        except socket.error as msg:
+            logging.error(str(msg))
+
+    logging.info("--- exit ---")
+
+
+if __name__ == "__main__":
+    main()

esptool-4.8.1/esp_rfc2217_server/__main__.py

@@ -0,0 +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()

esptool-4.8.1/esp_rfc2217_server/esp_port_manager.py

@@ -0,0 +1,97 @@
+# 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
+from esptool.reset import (
+    ClassicReset,
+    CustomReset,
+    DEFAULT_RESET_DELAY,
+    HardReset,
+    UnixTightReset,
+)
+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
+
+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(EspPortManager, self).__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(EspPortManager, self)._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")
+        HardReset(self.serial)()
+
+    def _reset_thread(self):
+        """
+        The reset logic is used from esptool.py 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)()

esptool-4.8.1/esp_rfc2217_server/redirector.py

@@ -0,0 +1,89 @@
+# SPDX-FileCopyrightText: 2014-2024 Fredrik Ahlberg, Angus Gratton,
+# Espressif Systems (Shanghai) CO LTD, other contributors as noted.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+import threading
+import time
+import logging
+import socket
+
+from esp_rfc2217_server.esp_port_manager import EspPortManager
+
+
+class Redirector(object):
+    def __init__(self, serial_instance, socket, debug=False, esp32r0delay=False):
+        self.serial = serial_instance
+        self.socket = socket
+        self._write_lock = threading.Lock()
+        self.rfc2217 = EspPortManager(
+            self.serial,
+            self,
+            esp32r0delay,
+            logger=logging.getLogger("rfc2217.server") if debug else None,
+        )
+        self.log = logging.getLogger("redirector")
+        self.force_exit = False
+
+    def statusline_poller(self):
+        self.log.debug("status line poll thread started")
+        while self.alive:
+            time.sleep(1)
+            self.rfc2217.check_modem_lines()
+        self.log.debug("status line poll thread terminated")
+
+    def shortcircuit(self):
+        """connect the serial port to the TCP port by copying everything
+        from one side to the other"""
+        self.alive = True
+        self.thread_read = threading.Thread(target=self.reader)
+        self.thread_read.daemon = True
+        self.thread_read.name = "serial->socket"
+        self.thread_read.start()
+        self.thread_poll = threading.Thread(target=self.statusline_poller)
+        self.thread_poll.daemon = True
+        self.thread_poll.name = "status line poll"
+        self.thread_poll.start()
+        self.writer()
+
+    def reader(self):
+        """loop forever and copy serial->socket"""
+        self.log.debug("reader thread started")
+        while self.alive:
+            try:
+                data = self.serial.read(self.serial.in_waiting or 1)
+                if data:
+                    # escape outgoing data when needed (Telnet IAC (0xff) character)
+                    self.write(b"".join(self.rfc2217.escape(data)))
+            except socket.error as msg:
+                self.log.error("{}".format(msg))
+                # probably got disconnected
+                break
+        self.alive = False
+        self.log.debug("reader thread terminated")
+
+    def write(self, data):
+        """thread safe socket write with no data escaping. used to send telnet stuff"""
+        with self._write_lock:
+            self.socket.sendall(data)
+
+    def writer(self):
+        """loop forever and copy socket->serial"""
+        while self.alive:
+            try:
+                data = self.socket.recv(1024)
+                if not data:
+                    break
+                self.serial.write(b"".join(self.rfc2217.filter(data)))
+            except socket.error as msg:
+                self.log.error("{}".format(msg))
+                # probably got disconnected
+                break
+        self.stop()
+
+    def stop(self):
+        """Stop copying"""
+        self.log.debug("stopping")
+        if self.alive:
+            self.alive = False
+            self.thread_read.join()
+            self.thread_poll.join()

esptool-4.8.1/esp_rfc2217_server.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python
+#
+# SPDX-FileCopyrightText: 2014-2024 Fredrik Ahlberg, Angus Gratton,
+# Espressif Systems (Shanghai) CO LTD, other contributors as noted.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+# This executable script is a thin wrapper around the main functionality
+# in the esp_rfc2217_server Python package
+
+# When updating this script, please also update esptool.py, espefuse.py and espsecure.py
+
+###################################################################################
+# Redirect data from a TCP/IP connection to a serial port and vice versa using RFC 2217.
+#
+# This is a modified version of rfc2217_server.py provided by the pyserial package
+# (pythonhosted.org/pyserial/examples.html#single-port-tcp-ip-serial-bridge-rfc-2217).
+# It uses a custom PortManager to properly apply the RTS & DTR signals
+# for resetting ESP chips.
+#
+# Run the following command on the server side to make
+# connection between /dev/ttyUSB1 and TCP port 4000:
+#
+#   python esp_rfc2217_server.py -p 4000 /dev/ttyUSB1
+#
+# Esptool can connect to the ESP device through that server as it is
+# demonstrated in the following example:
+#
+#   esptool.py --port rfc2217://localhost:4000?ign_set_control flash_id
+#
+
+import contextlib
+import os
+import sys
+
+if os.name != "nt":
+    # Linux/macOS: remove current script directory to avoid importing this file
+    # as a module; we want to import the installed esp_rfc2217_server module instead
+    with contextlib.suppress(ValueError):
+        executable_dir = os.path.dirname(sys.executable)
+        sys.path = [
+            path
+            for path in sys.path
+            if not path.endswith(("/bin", "/sbin")) and path != executable_dir
+        ]
+
+    # Linux/macOS: delete imported module entry to force Python to load
+    # the module from scratch; this enables importing esp_rfc2217_server module in
+    # other Python scripts
+    with contextlib.suppress(KeyError):
+        del sys.modules["esp_rfc2217_server"]
+
+import esp_rfc2217_server
+
+if __name__ == "__main__":
+    esp_rfc2217_server.main()

{esptool-4.8.dev4 → esptool-4.8.1}/espefuse/__init__.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
+# PYTHON_ARGCOMPLETE_OK
 
 import argparse
 import os
@@ -39,13 +40,15 @@ SUPPORTED_BURN_COMMANDS = [
     "execute_scripts",
 ]
 
-SUPPORTED_COMMANDS = [
+SUPPORTED_READ_COMMANDS = [
     "summary",
     "dump",
     "get_custom_mac",
     "adc_info",
     "check_error",
-] + SUPPORTED_BURN_COMMANDS
+]
+
+SUPPORTED_COMMANDS = SUPPORTED_READ_COMMANDS + SUPPORTED_BURN_COMMANDS
 
 SUPPORTED_CHIPS = {
     "esp32": DefChip("ESP32", esp32_efuse, esptool.targets.ESP32ROM),
@@ -94,15 +97,25 @@ def get_esp(
             )
             if not skip_connect:
                 esp.connect(connect_mode)
+                if esp.sync_stub_detected:
+                    esp = esp.STUB_CLASS(esp)
     return esp
 
 
-def get_efuses(esp, skip_connect=False, debug_mode=False, do_not_confirm=False):
+def get_efuses(
+    esp,
+    skip_connect=False,
+    debug_mode=False,
+    do_not_confirm=False,
+    extend_efuse_table=None,
+):
     for name in SUPPORTED_CHIPS:
         if SUPPORTED_CHIPS[name].chip_name == esp.CHIP_NAME:
             efuse = SUPPORTED_CHIPS[name].efuse_lib
             return (
-                efuse.EspEfuses(esp, skip_connect, debug_mode, do_not_confirm),
+                efuse.EspEfuses(
+                    esp, skip_connect, debug_mode, do_not_confirm, extend_efuse_table
+                ),
                 efuse.operations,
             )
     else:
@@ -224,9 +237,15 @@ def main(custom_commandline=None, esp=None):
         "(efuses which disable access to blocks or chip).",
         action="store_true",
     )
+    init_parser.add_argument(
+        "--extend-efuse-table",
+        help="CSV file from ESP-IDF (esp_efuse_custom_table.csv)",
+        type=argparse.FileType("r"),
+        default=None,
+    )
 
     common_args, remaining_args = init_parser.parse_known_args(custom_commandline)
-    debug_mode = common_args.debug or ("dump" in remaining_args)
+    debug_mode = common_args.debug
     just_print_help = [
         True for arg in remaining_args if arg in ["--help", "-h"]
     ] or remaining_args == []
@@ -253,7 +272,11 @@ def main(custom_commandline=None, esp=None):
             # TODO: Require the --port argument in the next major release, ESPTOOL-490
 
     efuses, efuse_operations = get_efuses(
-        esp, just_print_help, debug_mode, common_args.do_not_confirm
+        esp,
+        just_print_help,
+        debug_mode,
+        common_args.do_not_confirm,
+        common_args.extend_efuse_table,
     )
 
     parser = argparse.ArgumentParser(parents=[init_parser])
@@ -263,6 +286,15 @@ def main(custom_commandline=None, esp=None):
 
     efuse_operations.add_commands(subparsers, efuses)
 
+    # Enable argcomplete only on Unix-like systems
+    if sys.platform != "win32":
+        try:
+            import argcomplete
+
+            argcomplete.autocomplete(parser)
+        except ImportError:
+            pass
+
     grouped_remaining_args, used_cmds = split_on_groups(remaining_args)
     if len(grouped_remaining_args) == 0:
         parser.print_help()
@@ -302,6 +334,22 @@ def main(custom_commandline=None, esp=None):
             if not efuses.burn_all(check_batch_mode=True):
                 raise esptool.FatalError("BURN was not done")
             print("Successful")
+
+        if (
+            sum(cmd in SUPPORTED_BURN_COMMANDS for cmd in used_cmds) > 0
+            and sum(cmd in SUPPORTED_READ_COMMANDS for cmd in used_cmds) > 0
+        ):
+            # [burn_cmd1] [burn_cmd2] [read_cmd1] [burn_cmd3] [read_cmd2]
+            print("\n=== Run read commands after burn commands ===")
+            for rem_args in grouped_remaining_args:
+                args, unused_args = parser.parse_known_args(
+                    rem_args, namespace=common_args
+                )
+                current_cmd = args.operation
+                if current_cmd in SUPPORTED_READ_COMMANDS:
+                    print(f"\n=== Run {args.operation} command ===")
+                    operation_func = vars(efuse_operations)[current_cmd]
+                    operation_func(esp, efuses, args)
     finally:
         if not external_esp and not common_args.virt and esp._port:
             esp._port.close()

{esptool-4.8.dev4 → esptool-4.8.1}/espefuse/efuse/base_fields.py

@@ -649,6 +649,10 @@ class EspEfusesBase(object):
         """Returns (error count, failure boolean flag)"""
         return self.blocks[block_num].num_errors, self.blocks[block_num].fail
 
+    def is_efuses_incompatible_for_burn(self):
+        # Overwrite this function for a specific target if you want to check if a certain eFuse(s) can be burned.
+        return False
+
 
 class EfuseFieldBase(EfuseProtectBase):
     def __init__(self, parent, param):