esptool 4.8.dev3__tar.gz → 4.8.dev5__tar.gz

{esptool-4.8.dev3 → esptool-4.8.dev5}/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.dev5/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.1
+Name: esptool
+Version: 4.8.dev5
+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.dev3 → esptool-4.8.dev5}/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.dev3 → esptool-4.8.dev5}/espefuse/efuse/base_fields.py

@@ -12,6 +12,7 @@ from bitstring import BitArray, BitStream, CreationError
 import esptool
 
 from . import util
+from typing import List
 
 
 class CheckArgValue(object):
@@ -227,13 +228,14 @@ class EfuseBlockBase(EfuseProtectBase):
 
         return [self.parent.read_reg(offs) for offs in get_offsets(self)]
 
-    def read(self):
+    def read(self, print_info=True):
         words = self.get_words()
         data = BitArray()
         for word in reversed(words):
             data.append("uint:32=%d" % word)
         self.bitarray.overwrite(data, pos=0)
-        self.print_block(self.bitarray, "read_regs")
+        if print_info:
+            self.print_block(self.bitarray, "read_regs")
 
     def print_block(self, bit_string, comment, debug=False):
         if self.parent.debug or debug:
@@ -385,6 +387,18 @@ class EfuseBlockBase(EfuseProtectBase):
                     )
                     break
             if not self.fail and self.num_errors == 0:
+                self.read(print_info=False)
+                if self.wr_bitarray & self.bitarray != self.wr_bitarray:
+                    # if the required bits are not set then we need to re-burn it again.
+                    if burns < 2:
+                        print(
+                            f"\nRepeat burning BLOCK{self.id} (#{burns + 2}) because not all bits were set"
+                        )
+                        continue
+                    else:
+                        print(
+                            f"\nAfter {burns + 1} attempts, the required data was not set to BLOCK{self.id}"
+                        )
                 break
 
     def burn(self):
@@ -441,8 +455,8 @@ class EspEfusesBase(object):
     """
 
     _esp = None
-    blocks = []
-    efuses = []
+    blocks: List[EfuseBlockBase] = []
+    efuses: List = []
     coding_scheme = None
     force_write_always = None
     batch_mode_cnt = 0
@@ -635,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):

{esptool-4.8.dev3 → esptool-4.8.dev5}/espefuse/efuse/base_operations.py

@@ -5,6 +5,7 @@
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 import argparse
+import os
 import json
 import sys
 
@@ -65,16 +66,20 @@ def add_common_commands(subparsers, efuses):
     )
     burn.add_argument(
         "name_value_pairs",
-        help="Name of efuse register and New value pairs to burn",
+        help="Name of efuse field and new value pairs to burn. EFUSE_NAME: "
+        "[{}].".format(", ".join([e.name for e in efuses.efuses])),
         action=ActionEfuseValuePair,
         nargs="+",
-        metavar="[EFUSE_NAME VALUE] [{} VALUE".format(
-            " VALUE] [".join([e.name for e in efuses.efuses])
-        ),
+        metavar="[EFUSE_NAME VALUE]",
         efuse_choices=[e.name for e in efuses.efuses]
         + [name for e in efuses.efuses for name in e.alt_names if name != ""],
         efuses=efuses,
     )
+    burn.add_argument(
+        "--force",
+        help="Suppress an error to burn eFuses",
+        action="store_true",
+    )
 
     read_protect_efuse = subparsers.add_parser(
         "read_protect_efuse",
@@ -169,12 +174,22 @@ def add_common_commands(subparsers, efuses):
         help="Display information about ADC calibration data stored in efuse.",
     )
 
-    dump_cmd = subparsers.add_parser("dump", help="Dump raw hex values of all efuses")
+    dump_cmd = subparsers.add_parser("dump", help="Dump raw hex values of all eFuses")
+    dump_cmd.add_argument(
+        "--format",
+        help="Select the dump format: "
+        "default - usual console eFuse dump; "
+        "joint - all eFuse blocks are stored in one file; "
+        "split - each eFuse block is placed into its own file. The tool will create multiple files based on "
+        "the given --file_name (/path/blk.bin): blk0.bin, blk1.bin ... blkN.bin. Use the burn_block_data cmd "
+        "to write it back to another chip.",
+        choices=["default", "split", "joint"],
+        default="default",
+    )
     dump_cmd.add_argument(
         "--file_name",
-        help="Saves dump for each block into separate file. Provide the common "
-        "path name /path/blk.bin, it will create: blk0.bin, blk1.bin ... blkN.bin. "
-        "Use burn_block_data to write it back to another chip.",
+        help="The path to the file in which to save the dump, if not specified, output to the console.",
+        default=sys.stdout,
     )
 
     summary_cmd = subparsers.add_parser(
@@ -183,7 +198,7 @@ def add_common_commands(subparsers, efuses):
     summary_cmd.add_argument(
         "--format",
         help="Select the summary format",
-        choices=["summary", "json"],
+        choices=["summary", "json", "value_only"],
         default="summary",
     )
     summary_cmd.add_argument(
@@ -192,6 +207,11 @@ def add_common_commands(subparsers, efuses):
         type=argparse.FileType("w"),
         default=sys.stdout,
     )
+    summary_cmd.add_argument(
+        "efuses_to_show",
+        help="The efuses to show. If not provided, all efuses will be shown.",
+        nargs="*",
+    )
 
     execute_scripts = subparsers.add_parser(
         "execute_scripts", help="Executes scripts to burn at one time."
@@ -246,14 +266,21 @@ def add_show_sensitive_info_option(p):
 
 
 def summary(esp, efuses, args):
-    """Print a human-readable summary of efuse contents"""
+    """Print a human-readable or json summary of efuse contents"""
     ROW_FORMAT = "%-50s %-50s%s = %s %s %s"
-    human_output = args.format == "summary"
+    human_output = args.format in ["summary", "value_only"]
+    value_only = args.format == "value_only"
+    if value_only and len(args.efuses_to_show) != 1:
+        raise esptool.FatalError(
+            "The 'value_only' format can be used exactly for one efuse."
+        )
+    do_filtering = bool(args.efuses_to_show)
     json_efuse = {}
+    summary_efuse = []
     if args.file != sys.stdout:
         print("Saving efuse values to " + args.file.name)
-    if human_output:
-        print(
+    if human_output and not value_only:
+        summary_efuse.append(
             ROW_FORMAT.replace("-50", "-12")
             % (
                 "EFUSE_NAME (Block)",
@@ -262,13 +289,12 @@ def summary(esp, efuses, args):
                 "[Meaningful Value]",
                 "[Readable/Writeable]",
                 "(Hex Value)",
-            ),
-            file=args.file,
+            )
         )
-        print("-" * 88, file=args.file)
+        summary_efuse.append("-" * 88)
     for category in sorted(set(e.category for e in efuses), key=lambda c: c.title()):
-        if human_output:
-            print("%s fuses:" % category.title(), file=args.file)
+        if human_output and not value_only:
+            summary_efuse.append(f"{category.title()} fuses:")
         for e in (e for e in efuses if e.category == category):
             if e.efuse_type.startswith("bytes"):
                 raw = ""
@@ -297,8 +323,12 @@ def summary(esp, efuses, args):
                     value = "".join(v)
                 else:
                     value = value.replace("0", "?")
-            if human_output:
-                print(
+            if (
+                human_output
+                and (not do_filtering or e.name in args.efuses_to_show)
+                and not value_only
+            ):
+                summary_efuse.append(
                     ROW_FORMAT
                     % (
                         e.get_info(),
@@ -307,18 +337,20 @@ def summary(esp, efuses, args):
                         value,
                         perms,
                         raw,
-                    ),
-                    file=args.file,
+                    )
                 )
                 desc_len = len(e.description[50:])
                 if desc_len:
                     desc_len += 50
                     for i in range(50, desc_len, 50):
-                        print(
-                            "%-50s %-50s" % ("", e.description[i : (50 + i)]),
-                            file=args.file,
+                        summary_efuse.append(
+                            f"{'':<50} {e.description[i : (50 + i)]:<50}"
                         )
-            if args.format == "json":
+            elif human_output and value_only and e.name in args.efuses_to_show:
+                summary_efuse.append(f"{value}")
+            elif args.format == "json" and (
+                not do_filtering or e.name in args.efuses_to_show
+            ):
                 json_efuse[e.name] = {
                     "name": e.name,
                     "value": base_value if readable else value,
@@ -332,42 +364,74 @@ def summary(esp, efuses, args):
                     "efuse_type": e.efuse_type,
                     "bit_len": e.bit_len,
                 }
-        if human_output:
-            print("", file=args.file)
-    if human_output:
-        print(efuses.summary(), file=args.file)
+        if human_output and not value_only:
+            # Remove empty category if efuses are filtered and there are none to show
+            if do_filtering and summary_efuse[-1] == f"{category.title()} fuses:":
+                summary_efuse.pop()
+            else:
+                summary_efuse.append("")
+    if human_output and not value_only:
+        summary_efuse.append(efuses.summary())
         warnings = efuses.get_coding_scheme_warnings()
         if warnings:
-            print(
-                "WARNING: Coding scheme has encoding bit error warnings", file=args.file
+            summary_efuse.append(
+                "WARNING: Coding scheme has encoding bit error warnings"
             )
+    if human_output:
+        for line in summary_efuse:
+            print(line, file=args.file)
         if args.file != sys.stdout:
             args.file.close()
             print("Done")
-    if args.format == "json":
+    elif args.format == "json":
         json.dump(json_efuse, args.file, sort_keys=True, indent=4)
         print("")
 
 
 def dump(esp, efuses, args):
     """Dump raw efuse data registers"""
-    # Using --debug option allows to print dump.
-    # Nothing to do here. The log will be printed
-    # during EspEfuses.__init__() in self.read_blocks()
-    if args.file_name:
-        # save dump to the file
+    dump_file = args.file_name
+    to_console = args.file_name == sys.stdout
+
+    def output_block_to_file(block, f, to_console):
+        block_dump = BitStream(block.get_bitstring())
+        block_dump.byteswap()
+        if to_console:
+            f.write(block_dump.hex + "\n")
+        else:
+            block_dump.tofile(f)
+
+    if args.format == "default":
+        if to_console:
+            # for "espefuse.py dump" cmd
+            for block in efuses.blocks:
+                block.print_block(block.get_bitstring(), "dump", debug=True)
+            return
+        else:
+            # for back compatibility to support "espefuse.py dump --file_name dump.bin"
+            args.format = "split"
+
+    if args.format == "split":
+        # each efuse block is placed into its own file
         for block in efuses.blocks:
-            file_dump_name = args.file_name
-            place_for_index = file_dump_name.find(".bin")
-            file_dump_name = (
-                file_dump_name[:place_for_index]
-                + str(block.id)
-                + file_dump_name[place_for_index:]
-            )
-            print(file_dump_name)
-            with open(file_dump_name, "wb") as f:
-                block.get_bitstring().byteswap()
-                block.get_bitstring().tofile(f)
+            if not to_console:
+                file_dump_name = args.file_name
+                fname, fextension = os.path.splitext(file_dump_name)
+                file_dump_name = f"{fname}{block.id}{fextension}"
+                print(f"Dump efuse block{block.id} -> {file_dump_name}")
+                dump_file = open(file_dump_name, "wb")
+            output_block_to_file(block, dump_file, to_console)
+            if not to_console:
+                dump_file.close()
+    elif args.format == "joint":
+        # all efuse blocks are stored in one file
+        if not to_console:
+            print(f"Dump efuse blocks -> {args.file_name}")
+            dump_file = open(args.file_name, "wb")
+        for block in efuses.blocks:
+            output_block_to_file(block, dump_file, to_console)
+        if not to_console:
+            dump_file.close()
 
 
 def burn_efuse(esp, efuses, args):
@@ -457,6 +521,14 @@ def burn_efuse(esp, efuses, args):
         )
         print("                        espefuse/esptool will not work.")
 
+    if efuses.is_efuses_incompatible_for_burn():
+        if args.force:
+            print("Ignore incompatible eFuse settings.")
+        else:
+            raise esptool.FatalError(
+                "Incompatible eFuse settings detected, abort. (use --force flag to skip it)."
+            )
+
     if not efuses.burn_all(check_batch_mode=True):
         return