esptool 5.0.dev1__tar.gz → 5.0.2__tar.gz

{esptool-5.0.dev1 → esptool-5.0.2}/MANIFEST.in

@@ -3,7 +3,7 @@ include LICENSE
 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
+# sdist includes test/test*.py by default, but esptool tests
 # are so far only intended to run from the git repo itself
 prune test
 prune .github

{esptool-5.0.dev1/esptool.egg-info → esptool-5.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: esptool
-Version: 5.0.dev1
+Version: 5.0.2
 Summary: A serial utility for flashing, provisioning, and interacting with Espressif SoCs.
 Author: Fredrik Ahlberg (themadinventor), Angus Gratton (projectgus), Espressif Systems
 License: GPLv2+
@@ -32,7 +32,7 @@ Requires-Dist: reedsolo<1.8,>=1.5.3
 Requires-Dist: PyYAML>=5.1
 Requires-Dist: intelhex
 Requires-Dist: rich_click
-Requires-Dist: click<8.2.0
+Requires-Dist: click<9
 Provides-Extra: dev
 Requires-Dist: pyelftools; extra == "dev"
 Requires-Dist: coverage~=6.0; extra == "dev"
@@ -40,7 +40,7 @@ Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-rerunfailures; extra == "dev"
 Requires-Dist: requests; extra == "dev"
-Requires-Dist: commitizen; extra == "dev"
+Requires-Dist: czespressif; extra == "dev"
 Provides-Extra: hsm
 Requires-Dist: python-pkcs11; extra == "hsm"
 Provides-Extra: docs
@@ -48,7 +48,7 @@ Requires-Dist: esp-docs~=1.10; extra == "docs"
 Requires-Dist: sphinx-tabs; extra == "docs"
 Dynamic: license-file
 
-# esptool.py
+# esptool
 
 A Python-based, open-source, platform-independent serial utility for flashing, provisioning, and interacting with Espressif SoCs.
 
@@ -56,15 +56,15 @@ A Python-based, open-source, platform-independent serial utility for flashing, p
 
 ## Documentation
 
-Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool.py -h`.
+Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool -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).
+If you're interested in contributing to esptool, 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.
+esptool 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
 

{esptool-5.0.dev1 → esptool-5.0.2}/README.md

@@ -1,4 +1,4 @@
-# esptool.py
+# esptool
 
 A Python-based, open-source, platform-independent serial utility for flashing, provisioning, and interacting with Espressif SoCs.
 
@@ -6,15 +6,15 @@ A Python-based, open-source, platform-independent serial utility for flashing, p
 
 ## Documentation
 
-Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool.py -h`.
+Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool -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).
+If you're interested in contributing to esptool, 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.
+esptool 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
 

{esptool-5.0.dev1 → esptool-5.0.2}/esp_rfc2217_server/__init__.py

@@ -18,9 +18,11 @@ 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(

{esptool-5.0.dev1 → esptool-5.0.2}/esp_rfc2217_server/esp_port_manager.py

@@ -82,7 +82,7 @@ class EspPortManager(serial.rfc2217.PortManager):
 
     def _reset_thread(self):
         """
-        The reset logic is used from esptool.py because the RTS and DTR signals
+        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:

{esptool-5.0.dev1 → esptool-5.0.2}/esp_rfc2217_server.py

@@ -26,7 +26,7 @@
 # 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
+#   esptool --port rfc2217://localhost:4000?ign_set_control flash-id
 #
 
 import contextlib

esptool-5.0.2/espefuse/__init__.py

@@ -0,0 +1,233 @@
+# SPDX-FileCopyrightText: 2016-2025 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import sys
+
+import rich_click as click
+
+import esptool
+from esptool.cli_util import ChipType, ResetModeType
+from esptool.logger import log
+
+from espefuse.cli_util import Group
+from espefuse.efuse.base_operations import BaseCommands
+from espefuse.efuse_interface import (
+    DEPRECATED_COMMANDS,
+    get_esp,
+    init_commands,
+    SUPPORTED_COMMANDS,
+    SUPPORTED_BURN_COMMANDS,
+    SUPPORTED_READ_COMMANDS,
+    SUPPORTED_CHIPS,
+)
+from esptool.util import check_deprecated_py_suffix
+
+__all__ = [
+    "get_esp",
+    "init_commands",
+    "BaseCommands",
+    "SUPPORTED_COMMANDS",
+    "SUPPORTED_CHIPS",
+    "SUPPORTED_BURN_COMMANDS",
+    "SUPPORTED_READ_COMMANDS",
+]
+
+
+@click.group(
+    cls=Group,
+    chain=True,  # allow using multiple commands in a single run
+    no_args_is_help=True,
+    context_settings=dict(help_option_names=["-h", "--help"], max_content_width=120),
+    help=f"espefuse v{esptool.__version__} - "
+    "Utility for eFuse configuration in Espressif SoCs.",
+)
+@click.option(
+    "--chip",
+    "-c",
+    type=ChipType(choices=["auto"] + list(SUPPORTED_CHIPS.keys())),
+    default="auto",
+    envvar="ESPTOOL_CHIP",
+    help="Target chip type.",
+)
+@click.option(
+    "--baud",
+    "-b",
+    type=int,
+    default=esptool.ESPLoader.ESP_ROM_BAUD,
+    envvar="ESPTOOL_BAUD",
+    help="Serial port baud rate used when flashing/reading.",
+)
+@click.option(
+    "--port",
+    "-p",
+    envvar="ESPTOOL_PORT",
+    type=click.Path(),
+    help="Serial port device.",
+)
+@click.option(
+    "--before",
+    type=ResetModeType(
+        choices=["default-reset", "usb-reset", "no-reset", "no-reset-no-sync"]
+    ),
+    default="default-reset",
+    help="Which reset to perform before connecting to the chip.",
+)
+@click.option(
+    "--debug", "-d", is_flag=True, help="Show debugging information (loglevel=DEBUG)."
+)
+@click.option(
+    "--virt",
+    is_flag=True,
+    help="For host tests, work in virtual mode (no chip connection).",
+)
+@click.option(
+    "--path-efuse-file",
+    type=click.Path(),
+    help="For host tests, save eFuse memory to file.",
+)
+@click.option(
+    "--do-not-confirm",
+    is_flag=True,
+    help="Do not pause for confirmation before permanently writing eFuses. "
+    "Use with caution!",
+)
+@click.option(
+    "--postpone",
+    is_flag=True,
+    help="Postpone burning some eFuses from BLOCK0 at the end.",
+)
+@click.option(
+    "--extend-efuse-table",
+    type=click.File("r"),
+    help="CSV file from ESP-IDF (esp_efuse_custom_table.csv).",
+)
+@click.pass_context
+def cli(
+    ctx,
+    chip,
+    baud,
+    port,
+    before,
+    debug,
+    virt,
+    path_efuse_file,
+    do_not_confirm,
+    postpone,
+    extend_efuse_table,
+):
+    log.print(f"espefuse v{esptool.__version__}")
+
+    ctx.ensure_object(dict)
+    esp = ctx.obj.get("esp", None)
+    external_esp = esp is not None
+    is_help = ctx.obj.get("is_help", False)
+    used_cmds = ctx.obj.get("used_cmds", [])
+
+    if any(cmd.replace("_", "-") in DEPRECATED_COMMANDS for cmd in used_cmds):
+        return  # do not connect to ESP if any command is deprecated
+
+    if not port and not external_esp and not is_help and not virt:
+        raise click.BadOptionUsage(
+            "--port", "Missing required argument. Please specify the --port option."
+        )
+
+    if not esp:
+        try:
+            esp = get_esp(
+                port, baud, before, chip, is_help, virt, debug, path_efuse_file
+            )
+        except esptool.FatalError as e:
+            raise esptool.FatalError(
+                f"{e}\nPlease make sure you specified the right port with --port."
+            )
+
+    def close_port():
+        if not external_esp and not virt and esp._port:
+            esp._port.close()
+
+    ctx.call_on_close(close_port)
+
+    # handle chip auto
+    if chip == "auto":
+        if ctx.obj.get("is_help", False):
+            log.note(
+                "Chip not specified, showing commands for ESP32 by default. "
+                "Specify the --chip option to get chip-specific help."
+            )
+        chip = esp.CHIP_NAME.lower()
+
+    commands = init_commands(
+        esp=esp,
+        skip_connect=is_help,
+        debug=debug,
+        do_not_confirm=do_not_confirm,
+        extend_efuse_table=extend_efuse_table,
+    )
+    commands.efuses.postpone = postpone
+    commands.add_cli_commands(cli)
+
+    multiple_burn_commands = (
+        sum(cmd.replace("_", "-") in SUPPORTED_BURN_COMMANDS for cmd in used_cmds) > 1
+    )
+    if multiple_burn_commands:
+        commands.use_batch_mode()
+
+    # Add the objects to the context
+    ctx.obj["debug"] = debug
+    ctx.obj["commands"] = commands
+    ctx.obj["efuses"] = commands.efuses
+    ctx.obj["do_not_confirm"] = do_not_confirm
+
+    @cli.result_callback()
+    def process_result(result, *args, **kwargs):
+        if multiple_burn_commands:
+            if not commands.burn_all(check_batch_mode=True):
+                raise esptool.FatalError("BURN was not done.")
+            log.print("Successful.")
+
+
+@cli.command("execute-scripts", hidden=True)
+@click.argument("scripts", nargs=-1, type=click.UNPROCESSED)
+@click.option("--index", type=click.UNPROCESSED)
+@click.option("--configfiles", type=click.UNPROCESSED)
+def execute_scripts_cli(scripts, index, configfiles):
+    """REMOVED: See Migration guide in documentation for details."""
+    log.error(
+        "REMOVED: `execute_scripts` was replaced with the public API in v5. "
+        "Please see Migration Guide in documentation for details: "
+        "https://docs.espressif.com/projects/esptool/en/latest/migration-guide.html#espefuse-py-v5-migration-guide"
+    )
+    sys.exit(2)
+
+
+def main(argv: list[str] | None = None, esp: esptool.ESPLoader | None = None):
+    """
+    Main function for espefuse
+
+    argv - Optional override for default arguments parsing
+    (that uses sys.argv), can be a list of custom arguments as strings.
+    Arguments and their values need to be added as individual items to the list
+    e.g. "--port /dev/ttyUSB1" thus becomes ['--port', '/dev/ttyUSB1'].
+
+    esp - Optional override of the connected device previously
+    returned by esptool.get_default_connected_device()
+    """
+    args = esptool.expand_file_arguments(argv or sys.argv[1:])
+    cli(args=args, esp=esp)
+
+
+def _main():
+    check_deprecated_py_suffix(__name__)
+    try:
+        main()
+    except esptool.FatalError as e:
+        log.error(f"\nA fatal error occurred: {e}")
+        sys.exit(2)
+    except KeyboardInterrupt:
+        log.error("KeyboardInterrupt: Run cancelled by user.")
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    _main()

esptool-5.0.2/espefuse/cli_util.py

@@ -0,0 +1,246 @@
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from typing import Any
+
+import rich_click as click
+from click.parser import OptionParser, ParsingState, _unpack_args
+from esptool.cli_util import Group as EsptoolGroup
+from esptool.logger import log
+
+from espefuse.efuse_interface import (
+    DEPRECATED_COMMANDS,
+    init_commands,
+    SUPPORTED_BURN_COMMANDS,
+    SUPPORTED_READ_COMMANDS,
+    SUPPORTED_COMMANDS,
+)
+
+
+click.rich_click.USE_CLICK_SHORT_HELP = True
+click.rich_click.COMMAND_GROUPS = {
+    "*": [
+        {
+            "name": "Burn commands",
+            "commands": SUPPORTED_BURN_COMMANDS,
+        },
+        {
+            "name": "Read commands",
+            "commands": SUPPORTED_READ_COMMANDS,
+        },
+    ]
+}
+
+
+class ChainParser(OptionParser):
+    """
+    This is a modified version of the OptionParser class from click.parser.
+    It allows for the processing of arguments and options in interspersed order
+    together with chaining commands.
+    """
+
+    def _process_args_for_options(self, state: ParsingState) -> None:
+        while state.rargs:
+            arg = state.rargs.pop(0)
+            arglen = len(arg)
+            # Double dashes always handled explicitly regardless of what
+            # prefixes are valid.
+            if arg == "--":
+                return
+            # if the argument is a command, stop parsing options
+            elif arg.replace("_", "-") in SUPPORTED_COMMANDS:
+                state.largs.append(arg)
+                return
+            elif arg[:1] in self._opt_prefixes and arglen > 1:
+                self._process_opts(arg, state)
+            elif self.allow_interspersed_args:
+                state.largs.append(arg)
+            else:
+                state.rargs.insert(0, arg)
+                return
+
+    def _process_args_for_args(self, state: ParsingState) -> None:
+        pargs, args = _unpack_args(
+            state.largs + state.rargs, [x.nargs for x in self._args]
+        )
+
+        # This check is required because of the way we modify nargs in ChainingCommand
+        if len(pargs) > 0:
+            for idx, arg in enumerate(self._args):
+                arg.process(pargs[idx], state)
+
+        state.largs = args
+        state.rargs = []
+
+
+class EfuseContext(click.RichContext):
+    @property
+    def show_sensitive_info(self) -> bool:
+        self.ensure_object(dict)
+        value: bool = self.obj.get("show_sensitive_info", False)
+        if not value:
+            log.print("Sensitive data will be hidden (see --show-sensitive-info)")
+        return value
+
+
+class ChainingCommand(click.RichCommand, click.Command):
+    context_class = EfuseContext
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def _is_option(self, arg: str) -> bool:
+        return arg.startswith("--") or arg.startswith("-")
+
+    def invoke(self, ctx: click.Context) -> Any:
+        log.print(f'\n=== Run "{self.name}" command ===')
+        return super().invoke(ctx)
+
+    def parse_args(self, ctx: click.Context, args: list[str]):
+        # This is a hack to set nargs of the last argument to the number of arguments
+        # that will be processed separately
+        param_changed = None
+        for idx, arg in enumerate(args):
+            # command found in args or option found after argument
+            if arg.replace("_", "-") in SUPPORTED_COMMANDS or (
+                self._is_option(arg) and idx > 0
+            ):
+                arguments_count = sum(
+                    isinstance(param, click.Argument) for param in self.params
+                )
+                for param in self.params:
+                    if param.nargs != -1:
+                        continue
+                    # set nargs of parameter to actual count of arguments and deduct
+                    # arguments_count as each argument will be processed separately,
+                    # we only care about the last one with nargs=-1
+                    # at the end we add 1 to account for the processedargument itself
+                    # e.g. if we have burn-bit BLOCK2 1 2 3, we want to set nargs to 3,
+                    # so we need to account for BLOCK2 being processed separately
+                    param.nargs = args.index(arg) - arguments_count + 1
+                    param_changed = param
+                    if (
+                        param.nargs == 0
+                        and param.required
+                        and not ctx.resilient_parsing
+                    ):
+                        raise click.UsageError(
+                            f"Command `{self.name}` requires the `{param.name}` "
+                            "argument."
+                        )
+                    break
+                break
+        ret = super().parse_args(ctx, args)
+        # restore nargs of the last argument to -1, in case it is going to be used again
+        if param_changed is not None:
+            param.nargs = -1
+        return ret
+
+    def make_parser(self, ctx: click.Context) -> OptionParser:
+        """Creates the underlying option parser for this command."""
+        parser = ChainParser(ctx)
+        parser.allow_interspersed_args = True
+        for param in self.get_params(ctx):
+            param.add_to_parser(parser, ctx)
+        return parser
+
+
+class Group(EsptoolGroup):
+    DEPRECATED_OPTIONS = {
+        "--file_name": "--file-name",
+    }
+
+    command_class = ChainingCommand
+    context_class = EfuseContext
+
+    @staticmethod
+    def _split_to_groups(args: list[str]) -> tuple[list[list[str]], list[str]]:
+        """
+        This function splits the args list into groups,
+        where each item is a cmd with all its args.
+
+        Example:
+        all_args:
+        ['burn-key-digest', 'secure_images/ecdsa256_secure_boot_signing_key_v2.pem',
+         'burn-key', 'BLOCK_KEY0', 'images/efuse/128bit_key',
+         'XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS']
+
+        used_cmds: ['burn-key-digest', 'burn-key']
+        groups:
+        [['burn-key-digest', 'secure_images/ecdsa256_secure_boot_signing_key_v2.pem'],
+         ['burn-key', 'BLOCK_KEY0', 'images/efuse/128bit_key',
+          'XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS']]
+        """
+        groups: list[list[str]] = []
+        args_group: list[str] = []
+        used_cmds: list[str] = []
+        for arg in args:
+            if arg.replace("_", "-") in SUPPORTED_COMMANDS:
+                groups.append(args_group)
+                used_cmds.append(arg)
+                args_group = [arg]
+            else:
+                args_group.append(arg)
+        groups.append(args_group)
+        return groups, used_cmds
+
+    @staticmethod
+    def repeat_read_commands(
+        used_cmds: list[str], groups: list[list[str]]
+    ) -> list[list[str]]:
+        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
+        ):
+            # append all read commands at the end of group
+            read_commands = []
+            for group in groups:
+                if group[0] in SUPPORTED_READ_COMMANDS:
+                    read_commands.append(group)
+            groups.extend(read_commands)
+        return groups
+
+    def parse_args(self, ctx: click.Context, args: list[str]):
+        ctx.ensure_object(dict)
+        ctx.obj["is_help"] = any(help_arg in args for help_arg in ctx.help_option_names)
+        idx = (
+            args.index("--chip")
+            if "--chip" in args
+            else (args.index("-c") if "-c" in args else -1)
+        )
+        ctx.obj["chip"] = args[idx + 1] if idx != -1 and idx + 1 < len(args) else "auto"
+        # override the default behavior of EsptoolGroup, because we don't need
+        # support for parameters with nargs=-1
+        args = self._replace_deprecated_args(args)
+        cmd_groups, used_cmds = self._split_to_groups(args)
+
+        # Add commands for shell completion
+        if ctx.resilient_parsing:
+            commands = init_commands(port=None, chip=ctx.obj["chip"], skip_connect=True)
+            commands.add_cli_commands(self)
+        elif len(used_cmds) == 0:
+            self.get_help(ctx)
+            ctx.exit()
+
+        cmd_groups = self.repeat_read_commands(used_cmds, cmd_groups)
+        args = [arg for group in cmd_groups for arg in group]
+
+        ctx.obj["used_cmds"] = used_cmds
+        ctx.obj["args"] = args
+        return super(click.RichGroup, self).parse_args(ctx, args)
+
+    def get_help(self, ctx: click.Context) -> str:
+        # help was called without any commands, so we need to add the commands for the
+        # default chip
+        if not (set(self.list_commands(ctx)) - set(DEPRECATED_COMMANDS)):
+            chip = ctx.obj["chip"]
+            if chip == "auto":
+                log.note(
+                    "Chip not specified, showing commands for ESP32 by default. "
+                    "Specify the --chip option to get chip-specific help."
+                )
+                chip = "esp32"
+            commands = init_commands(port=None, chip=chip, skip_connect=True)
+            commands.add_cli_commands(self)
+        return super().get_help(ctx)  # type: ignore