feat(espsecure): Unify all commands and options to use dash instead of underscore

Author: peterdragun

docs/en/espsecure/index.rst

@@ -21,13 +21,13 @@ You must install ``esptool.py`` package with the ``hsm`` extra using the command
 
 The following command should be used to get an image signed using an external HSM. ::
 
-    python espsecure.py sign_data --version 2 --hsm --hsm-config <hsm_config_file> --output <signed_image> <datafile>
+    espsecure.py sign-data --version 2 --hsm --hsm-config <hsm_config_file> --output <signed_image> <datafile>
 
 The above command first extracts the public key from the HSM, generates a signature for an image using the HSM, and then creates a signature block and appends it to the image to generate a signed image.
 
 If the public key is not stored in the external HSM, you can specify the ``--pub-key`` argument to supply the public key. ::
 
-    python espsecure.py sign_data --version 2 --hsm --hsm-config <hsm_config_file> --pub-key <public_key> --output <signed_image> <datafile>
+    espsecure.py sign-data --version 2 --hsm --hsm-config <hsm_config_file> --pub-key <public_key> --output <signed_image> <datafile>
 
 .. note::
     In case you are using ESP-IDF, then an unsigned application can be generated by disabling ``CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES`` configuration option in the project settings.
@@ -37,11 +37,11 @@ Verifying the Signed Image
 
 Once the signed image is generated, we can verify it using the following command: ::
 
-    python espsecure.py verify_signature --version 2 --hsm --hsm-config <hsm_config_file> <signed_image>
+    espsecure.py verify-signature --version 2 --hsm --hsm-config <hsm_config_file> <signed_image>
 
 If the public key is not stored in the external HSM, you can specify the ``--keyfile`` argument to supply the public key. ::
 
-    python espsecure.py verify_signature --version 2 --keyfile <public_key> <signed_image>
+    espsecure.py verify-signature --version 2 --keyfile <public_key> <signed_image>
 
 
 HSM Config File

docs/en/migration-guide.rst

@@ -1,13 +1,15 @@
 .. _migration:
 
-esptool.py ``v5`` Migration Guide
-=================================
+``v5`` Migration Guide
+======================
 
-This document describes the breaking changes made to esptool.py in the major release ``v5``. It provides guidance on adapting existing workflows and scripts to ensure compatibility when updating from ``v4.*``.
+This document describes the breaking changes made to esptool.py, espsecure.py and espefuse.py in the major release ``v5``. It provides guidance on adapting existing workflows and scripts to ensure compatibility when updating from ``v4.*``.
 
+esptool.py ``v5`` Migration Guide
+*********************************
 
 ``image-info`` Output Format Change
-***********************************
+###################################
 
 The output format of the :ref:`image-info <image-info>` command has been **updated in v5**. The original format (``--version 1``) is **deprecated** and replaced by the updated format (``--version 2``). The ``--version`` argument has been **removed entirely**, and the new format is now the default and only option.
 
@@ -23,7 +25,7 @@ The output format of the :ref:`image-info <image-info>` command has been **updat
 2. Remove any ``--version`` arguments from ``image-info`` commands.
 
 Output Logging
-**************
+##############
 
 The esptool ``v5`` release introduces a centralized logging mechanism to improve output management and allow redirection.
 
@@ -42,7 +44,7 @@ The esptool ``v5`` release introduces a centralized logging mechanism to improve
 See the :ref:`logging <logging>` section for more details on available logger methods and custom logger implementation.
 
 ``write-flash`` ``--verify`` Argument
-*************************************
+#####################################
 
 The ``--verify`` option for the :ref:`write-flash <write-flash>` command has been **deprecated in v5**. Flash verification is performed automatically after every successful write operation when technically feasible.
 
@@ -58,7 +60,7 @@ The ``--verify`` option for the :ref:`write-flash <write-flash>` command has bee
 2. Update scripts/CI pipelines to remove ``--verify`` flags.
 
 Error Output Handling
-*********************
+#####################
 
 In ``v5``, error handling and output behavior have been improved to provide better user experience and script compatibility.
 
@@ -75,7 +77,7 @@ In ``v5``, error handling and output behavior have been improved to provide bett
 2. Ensure scripts handle non-zero exit codes correctly in the case of operations interrupted by the user.
 
 Beta Target Support Removal
-***************************
+###########################
 
 Support for the following beta targets has been **removed in v5**:
 
@@ -93,7 +95,7 @@ Support for the following beta targets has been **removed in v5**:
 Use esptool ``v4`` for legacy workflows targeting these beta chips.
 
 ``verify-flash`` ``--diff`` Argument
-*************************************
+####################################
 
 The format of the ``--diff`` option of the :ref:`verify-flash <verify-flash>` command has **changed in v5**. Previously, ``--diff=yes/no`` had to be specified to enable or disable the diff output. In the new version, the ``--diff`` option is a simple boolean switch without the need of a ``yes`` or ``no`` value.
 
@@ -102,7 +104,7 @@ The format of the ``--diff`` option of the :ref:`verify-flash <verify-flash>` co
 1. Rewrite the ``--diff=yes`` argument to a simple ``--diff`` in any existing ``verify-flash`` commands in scripts/CI pipelines. Delete ``--diff=no`` completely if detailed diff output is not required.
 
 Using esptool as a Python Module
-********************************
+################################
 
 All command functions (e.g., ``verify-flash``, ``write-flash``) have been refactored to remove their dependency on the ``args`` object from the argparse module. Instead, all arguments are now passed explicitly as individual parameters. This change, combined with enhancements to the public API, provides a cleaner, more modular interface for programmatic use of esptool in custom scripts and applications (see :ref:`scripting <scripting>`).
 
@@ -121,7 +123,7 @@ For detailed examples and API reference, see the :ref:`scripting <scripting>` se
 
 
 Flash Operations from Non-flash Related Commands
-************************************************
+################################################
 
 When esptool is used as a CLI tool, the following commands no longer automatically attach the flash by default, since flash access is not required for their core functionality:
 
@@ -145,7 +147,7 @@ The ``--spi-connection`` CLI argument has been **removed** from non-flash relate
 
 
 Shell Completion
-****************
+################
 
 The esptool ``v5`` has switched to using `Click <https://click.palletsprojects.com/>`_ for command line argument parsing, which changes how shell completion works.
 
@@ -155,7 +157,7 @@ The esptool ``v5`` has switched to using `Click <https://click.palletsprojects.c
 2. Follow the new shell completion setup instructions in the :ref:`shell-completion` section of the :ref:`installation <installation>` guide.
 
 ``merge-bin`` ``--fill-flash-size`` Argument
-********************************************
+############################################
 
 The ``--fill-flash-size`` option of the :ref:`merge-bin <merge-bin>` command has been renamed to ``--pad-to-size``. This change provides a more intuitive and descriptive name for the argument and is consistent with the naming scheme in other esptool image manipulation commands.
 
@@ -164,7 +166,7 @@ The ``--fill-flash-size`` option of the :ref:`merge-bin <merge-bin>` command has
 1. Rename the ``--fill-flash-size`` to ``--pad-to-size`` in any existing ``merge-bin`` commands in scripts/CI pipelines.
 
 ``write-flash`` ``--ignore-flash-encryption-efuse-setting`` Argument
-********************************************************************
+####################################################################
 
 The ``--ignore-flash-encryption-efuse-setting`` option of the :ref:`write-flash <write-flash>` command has been renamed to ``--ignore-flash-enc-efuse``. This change shortens the argument name to improve readability and consistency with other esptool options.
 
@@ -173,7 +175,7 @@ The ``--ignore-flash-encryption-efuse-setting`` option of the :ref:`write-flash
 1. Rename the ``--ignore-flash-encryption-efuse-setting`` to ``--ignore-flash-enc-efuse`` in any existing ``write-flash`` commands in scripts/CI pipelines.
 
 ``make_image`` Command Removal
-******************************
+##############################
 
 The ``make_image`` command for the ESP8266 has been **removed in v5**. This command has been deprecated in favor of using **objcopy** (or other tools) to generate ELF images and then using ``elf2image`` to create the final ``.bin`` file.
 
@@ -182,7 +184,7 @@ The ``make_image`` command for the ESP8266 has been **removed in v5**. This comm
 1. Replace any ``make_image`` workflows with the recommended way of assembling firmware images using **objcopy** and ``elf2image``.
 
 Using Binary from GitHub Releases on Linux
-******************************************
+##########################################
 
 The ``esptool.py`` binary from GitHub Releases on Linux is now using Ubuntu 22.04 as the base image. That means the image is using ``glibc`` 2.35, which is not fully compatible with the ``glibc`` 2.28 from Ubuntu 20.04 (the base image for ``v4.*``).
 
@@ -191,7 +193,7 @@ The ``esptool.py`` binary from GitHub Releases on Linux is now using Ubuntu 22.0
 1. Update your operating system to a newer version which bundles ``glibc`` 2.35 or later
 
 Command and Option Renaming
-***************************
+###########################
 
 All the commands and options have been renamed to use ``-`` instead of ``_`` as a separator (e.g., ``write_flash`` -> ``write-flash``).
 
@@ -204,10 +206,58 @@ This change affects most of the commands and the following options: ``--flash_si
 1. Replace all underscores in command and option names with ``-`` in your scripts and CI pipelines.
 
 Log Format Changes
-******************
+##################
 
 A significant amount of changes have been made to the log styling and formatting in ``v5``. Some of the messages, warnings, and errors are now formatted differently or reworded to provide more context and improve readability. Exhaustive list of changed messages won't be provided.
 
 **Migration Steps:**
 
 1. Make sure to adjust any of your scripts, asserts, CI workflows, or others to accommodate the new/changed format of messages. If you are parsing the log output (not recommended), consider importing esptool as a module and using the public API (see :ref:`here <scripting>`) to get the information you need.
+
+
+espsecure.py ``v5`` Migration Guide
+***********************************
+
+Command and Option Renaming
+###########################
+
+All the commands and options have been renamed to use ``-`` instead of ``_`` as a separator (e.g., ``sign_data`` -> ``sign-data``).
+
+Old command and option names are **deprecated**, meaning they will work for now with a warning, but will be removed in the next major release.
+
+This change affects most of the commands and the following options: ``--aes_xts``, ``--flash_crypt_conf``, ``--append_signatures``.
+
+**Migration Steps:**
+
+1. Replace all underscores in command and option names with ``-`` in your scripts and CI pipelines.
+
+Public API Changes
+##################
+
+The public API of ``espsecure.py`` has been updated to provide a more consistent and user-friendly interface for programmatic use in custom scripts and applications.
+
+**Key Changes:**
+
+- All functions now accept individual parameters instead of relying on the ``args`` object from the argparse module. Affected functions are:
+    - ``digest_secure_bootloader``
+    - ``generate_signing_key``
+    - ``digest_secure_bootloader``
+    - ``generate_signing_key``
+    - ``sign_data`` including ``sign_secure_boot_v1`` and ``sign_secure_boot_v2``
+    - ``verify_signature`` including ``verify_signature_v1`` and ``verify_signature_v2``
+    - ``extract_public_key``
+    - ``signature_info_v2``
+    - ``digest_sbv2_public_key`` and ``digest_rsa_public_key``
+    - ``digest_private_key``
+    - ``generate_flash_encryption_key``
+    - ``decrypt_flash_data``
+    - ``encrypt_flash_data``
+- The ``main`` function parameter ``custom_commandline`` has been renamed to ``argv`` to unify the naming convention with esptool.
+
+**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, ...)``.
+2. Replace the ``custom_commandline`` parameter with ``argv`` in the ``main`` function call.