feat(espefuse): Replace execute-scripts with public API

BREAKING CHANGE:
- execute-scripts command is removed

Author: peterdragun

docs/en/espefuse/execute-scripts-cmd.rst

@@ -41,7 +41,6 @@ Supported Commands
    get-custom-mac <get-custom-mac-cmd>
    adc-info <adc-info-cmd>
    set-flash-voltage <set-flash-voltage-cmd>
-   execute-scripts <execute-scripts-cmd>
    check-error <check-error-cmd>
 
 Optional General Arguments Of Commands

docs/en/espefuse/index.rst

@@ -225,7 +225,6 @@ Choices for the ``--before`` and ``--after`` options have been renamed to use ``
 
 1. Replace all underscores in the ``--before`` and ``--after`` options with ``-`` in your scripts.
 
-
 espsecure.py ``v5`` Migration Guide
 ***********************************
 
@@ -268,9 +267,9 @@ The public API of ``espsecure.py`` has been updated to provide a more consistent
 **Migration Steps:**
 
 1. Update function calls to pass individual parameters instead of the ``args`` object. For example:
-   ``sign_data(args)`` -> ``sign_data(data=args.data, key=args.key, ...)``
-   or if you were mocking the args object, now you don't have to do that and you can pass parameters directly to the function like:
-   ``sign_data(data=data, key=key, ...)``.
+``sign_data(args)`` -> ``sign_data(data=args.data, key=args.key, ...)``
+or if you were mocking the args object, now you don't have to do that and you can pass parameters directly to the function like:
+``sign_data(data=data, key=key, ...)``.
 2. Replace the ``custom_commandline`` parameter with ``argv`` in the ``main`` function call.
 
 espefuse.py ``v5`` Migration Guide
@@ -307,3 +306,69 @@ The ``--port`` option is now required for all commands (except when using ``--vi
 **Migration Steps:**
 
 1. Add the ``--port`` option to all your espefuse commands.
+
+
+``execute-scripts`` Command Removal
+###################################
+
+The ``execute-scripts`` command has been **removed in v5**. This command was used to execute custom eFuses scripts. It was deprecated in favor of using ``espefuse.py`` as a Python module (see :ref:`here <espefuse-scripting>`).
+
+**Migration Steps:**
+
+1. Refactor any workflows using the deprecated ``execute-scripts`` to use the public API.
+2. Make sure to use the ``batch_mode`` argument for ``init_commands`` to avoid burning eFuses one by one.
+3. Variables ``idx`` and ``configfiles`` are no longer supported. These can be replaced with simple for loops in Python.
+
+For example, the following commands and script (using ESP32):
+
+.. code-block:: bash
+
+    > espefuse.py --port /dev/ttyUSB0 execute_scripts efuse_script.py --do-not-confirm
+
+.. code-block:: python
+
+    espefuse(esp, efuses, args, "burn_efuse JTAG_DISABLE 1 DISABLE_SDIO_HOST 1 CONSOLE_DEBUG_DISABLE 1")
+    espefuse(esp, efuses, args, "burn_key flash_encryption ../../images/efuse/256bit --no-protect-key")
+    espefuse(esp, efuses, args, "burn_key_digest ../../secure_images/rsa_secure_boot_signing_key.pem")
+    espefuse(esp, efuses, args, "burn_bit BLOCK3 64 66 69 72 78 82 83 90")
+    espefuse(esp, efuses, args, "burn_custom_mac AA:BB:CC:DD:EE:88")
+
+    efuses.burn_all()
+
+    espefuse(esp, efuses, args, "summary")
+    espefuse(esp, efuses, args, "adc_info")
+    espefuse(esp, efuses, args, "get_custom_mac")
+
+    if not efuses["BLOCK1"].is_readable() or not efuses["BLOCK1"].is_writeable():
+        raise Exception("BLOCK1 should be readable and writeable")
+
+Can be replaced with public API:
+
+.. code-block:: python
+
+    from espefuse import init_commands
+
+    with init_commands(port="/dev/ttyUSB0", batch_mode=True, do_not_confirm=True) as espefuse:
+        espefuse.burn_efuse({"JTAG_DISABLE": "1", "DISABLE_SDIO_HOST": "1", "CONSOLE_DEBUG_DISABLE": "1"})
+        with open("../../images/efuse/256bit", "rb") as f:
+            espefuse.burn_key(["flash_encryption"], [f], no_protect_key=True)
+        with open("../../secure_images/rsa_secure_boot_signing_key.pem", "rb") as f:
+            espefuse.burn_key_digest([f])
+        espefuse.burn_bit("BLOCK3", [64, 66, 69, 72, 78, 82, 83, 90])
+        espefuse.burn_custom_mac(b"\xaa\xbb\xcc\xdd\xee\x88")
+
+        espefuse.burn_all()
+
+        espefuse.summary()
+        espefuse.adc_info()
+        espefuse.get_custom_mac()
+
+        if not espefuse.efuses["BLOCK1"].is_readable() or not espefuse.efuses["BLOCK1"].is_writeable():
+            raise Exception("BLOCK1 should be readable and writeable")
+
+.. note::
+
+    Please note that the ``batch_mode`` argument for ``init_commands`` is required to avoid burning eFuses one by one. This was previously
+    the default behavior for ``execute-scripts`` command.
+
+For more details on the public API, see :ref:`espefuse-scripting`.

docs/en/migration-guide.rst

@@ -13,6 +13,7 @@
 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,
@@ -118,6 +119,10 @@ def cli(
     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(
@@ -159,7 +164,6 @@ def close_port():
     commands.efuses.postpone = postpone
     commands.add_cli_commands(cli)
 
-    used_cmds = ctx.obj["used_cmds"]
     multiple_burn_commands = (
         sum(cmd.replace("_", "-") in SUPPORTED_BURN_COMMANDS for cmd in used_cmds) > 1
     )
@@ -180,6 +184,20 @@ def process_result(result, *args, **kwargs):
             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

espefuse/__init__.py

@@ -10,6 +10,7 @@
 from esptool.logger import log
 
 from espefuse.efuse_interface import (
+    DEPRECATED_COMMANDS,
     init_commands,
     SUPPORTED_BURN_COMMANDS,
     SUPPORTED_READ_COMMANDS,
@@ -224,7 +225,7 @@ def parse_args(self, ctx: click.Context, args: list[str]):
     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 self.list_commands(ctx):
+        if not (set(self.list_commands(ctx)) - set(DEPRECATED_COMMANDS)):
             chip = ctx.obj["chip"]
             if chip == "auto":
                 log.note(

espefuse/cli_util.py

@@ -355,25 +355,6 @@ def summary_cli(format, file, efuses_to_show=[]):
             """Print human-readable summary of eFuse values."""
             self.summary(efuses_to_show, format, file)
 
-        @cli.command("execute-scripts")
-        @click.argument("scripts", nargs=-1, type=click.File("r"), required=True)
-        @click.option(
-            "--index",
-            type=int,
-            help="integer index. It allows to retrieve unique data per chip "
-            "from configfiles and then burn them (ex. CUSTOM_MAC, UNIQUE_ID).",
-        )
-        @click.option(
-            "--configfiles",
-            type=click.File("r"),
-            multiple=True,
-            help="List of configfiles with data",
-        )
-        @click.pass_context
-        def execute_scripts_cli(ctx, scripts, index, configfiles):
-            """Executes scripts to burn at one time."""
-            self.execute_scripts(scripts, ctx.obj["debug"], configfiles, index)
-
         @cli.command("check-error")
         @click.option(
             "--recovery", is_flag=True, help="Recovery of BLOCKs after encoding errors"
@@ -1151,9 +1132,6 @@ def check_error(self, recovery: bool = False, do_not_confirm: bool = False):
             raise esptool.FatalError("Error(s) were detected in eFuses")
         print("No errors detected")
 
-    def execute_scripts(self, scripts, debug, configfiles, index):
-        raise NotImplementedError("execute_scripts is not implemented")
-
     def burn_custom_mac(self, mac: str | bytes):
         """
         Burn a 48-bit Custom MAC Address.

espefuse/efuse/base_operations.py

@@ -41,7 +41,6 @@ class DefChip:
     "burn-key-digest",
     "burn-custom-mac",
     "set-flash-voltage",
-    "execute-scripts",
 ]
 
 SUPPORTED_READ_COMMANDS = [
@@ -52,7 +51,11 @@ class DefChip:
     "check-error",
 ]
 
-SUPPORTED_COMMANDS = SUPPORTED_READ_COMMANDS + SUPPORTED_BURN_COMMANDS
+DEPRECATED_COMMANDS = ["execute-scripts"]
+
+SUPPORTED_COMMANDS = (
+    SUPPORTED_READ_COMMANDS + SUPPORTED_BURN_COMMANDS + DEPRECATED_COMMANDS
+)
 
 SUPPORTED_CHIPS = {
     "esp32": DefChip(esp32_efuse, esptool.targets.ESP32ROM),