feat: Rename reset modes to use dash instead of underscore

Author: peterdragun

docs/en/espefuse/index.rst

@@ -51,7 +51,7 @@ Optional General Arguments Of Commands
 - ``--chip``, ``-c`` - Target chip type. If this argument is omitted, the tool automatically detects the chip type when connected. But if the command has a help option, the chip is not connected, and the default chip is ``esp32``, please specify the specific type of chip to get the correct help. Example of usage: ``-c esp32``, ``-c esp32c3``, ``-c esp32s2`` and others.
 - ``--baud``, ``-b`` - Serial port baud rate, the same as for esptool.
 - ``--port``, ``-p`` - Serial port device, for example: ``-p /dev/ttyUSB0`` (Linux and macOS) or ``-p COM1`` (Windows).
-- ``--before`` -  What to do before connecting to the chip: ``default_reset``, ``no_reset``, ``esp32r1``, ``no_reset_no_sync``.
+- ``--before`` -  What to do before connecting to the chip: ``default-reset``, ``no-reset``, ``esp32r1``, ``no-reset-no-sync``.
 - ``--debug``, ``-d`` - Show debugging information.
 - ``--virt`` - For host tests. The tool will work in the virtual mode (without connecting to a chip).
 - ``--path-efuse-file`` - For host tests. Use it together with ``--virt`` option. The tool will work in the virtual mode (without connecting to a chip) and save eFuse memory to a given file. If the file does not exists the tool creates it. To reset written eFuses just delete the file. Usage: ``--path-efuse-file efuse_memory.bin``.

docs/en/esptool/advanced-options.rst

@@ -3,7 +3,7 @@
 Advanced Options
 ================
 
-The following advanced global configuration options can be used for all esptool commands. They are placed before the command name on the command line. For example, the option ``--before no_reset`` has to be placed before ``flash-id``. The command should look like this: ``esptool.py --before no_reset flash-id``.
+The following advanced global configuration options can be used for all esptool commands. They are placed before the command name on the command line. For example, the option ``--before no-reset`` has to be placed before ``flash-id``. The command should look like this: ``esptool.py --before no-reset flash-id``.
 
 For basic/fundamental global configuration options, see the :ref:`options` page.
 
@@ -19,10 +19,10 @@ The ``--before`` argument allows you to specify whether the chip needs resetting
 
 .. list::
 
-    * ``--before default_reset`` is the default, which uses DTR & RTS serial control lines (see :ref:`entering-the-bootloader`) to try to reset the chip into bootloader mode.
-    * ``--before no_reset`` will skip DTR/RTS control signal assignments and just start sending a serial synchronisation command to the chip. This is useful if your chip doesn't have DTR/RTS, or for some serial interfaces (like Arduino board onboard serial) which behave differently when DTR/RTS are toggled.
-    * ``--before no_reset_no_sync`` will skip DTR/RTS control signal assignments and skip also the serial synchronization command. This is useful if your chip is already running the :ref:`stub bootloader <stub>` and you want to avoid resetting the chip and uploading the stub again.
-    :esp32c3 or esp32s3 or esp32c6 or esp32h2 or esp32p4 or esp32c5 or esp32c61: * ``--before usb_reset`` will use custom reset sequence for USB-JTAG-Serial (used for example for ESP chips connected through the USB-JTAG-Serial peripheral). Usually, this option doesn't have to be used directly. Esptool should be able to detect connection through USB-JTAG-Serial.
+    * ``--before default-reset`` is the default, which uses DTR & RTS serial control lines (see :ref:`entering-the-bootloader`) to try to reset the chip into bootloader mode.
+    * ``--before no-reset`` will skip DTR/RTS control signal assignments and just start sending a serial synchronisation command to the chip. This is useful if your chip doesn't have DTR/RTS, or for some serial interfaces (like Arduino board onboard serial) which behave differently when DTR/RTS are toggled.
+    * ``--before no-reset-no-sync`` will skip DTR/RTS control signal assignments and skip also the serial synchronization command. This is useful if your chip is already running the :ref:`stub bootloader <stub>` and you want to avoid resetting the chip and uploading the stub again.
+    :esp32c3 or esp32s3 or esp32c6 or esp32h2 or esp32p4 or esp32c5 or esp32c61: * ``--before usb-reset`` will use custom reset sequence for USB-JTAG-Serial (used for example for ESP chips connected through the USB-JTAG-Serial peripheral). Usually, this option doesn't have to be used directly. Esptool should be able to detect connection through USB-JTAG-Serial.
 
 Reset After Operation: ``--after``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -31,11 +31,11 @@ The ``--after`` argument allows you to specify whether the chip should be reset
 
 .. list::
 
-    * ``--after hard_reset`` is the default. The RTS serial control line is used to reset the chip into a normal boot sequence.
-    :esp8266: * ``--after soft_reset`` runs the user firmware, but any subsequent reset will return to the serial bootloader. This was the reset behaviour in esptool v1.x.
-    * ``--after no_reset`` leaves the chip in the serial bootloader, no reset is performed.
-    * ``--after no_reset_stub`` leaves the chip in the stub bootloader, no reset is performed.
-    :not esp8266 and not esp32 and not esp32h2 and not esp32c6: * ``--after watchdog_reset`` hard-resets the chip by triggering an internal watchdog reset. This is useful when the RTS control line is not available, especially in the USB-OTG and USB-Serial/JTAG modes. Use this if a chip is getting stuck in download mode when using the default reset method in USB-Serial/JTAG mode. Using this may cause the port to re-enumerate on Linux (e.g. ``/dev/ttyACM0`` -> ``/dev/ttyACM1``).
+    * ``--after hard-reset`` is the default. The RTS serial control line is used to reset the chip into a normal boot sequence.
+    :esp8266: * ``--after soft-reset`` runs the user firmware, but any subsequent reset will return to the serial bootloader. This was the reset behaviour in esptool v1.x.
+    * ``--after no-reset`` leaves the chip in the serial bootloader, no reset is performed.
+    * ``--after no-reset-stub`` leaves the chip in the stub bootloader, no reset is performed.
+    :not esp8266 and not esp32 and not esp32h2 and not esp32c6: * ``--after watchdog-reset`` hard-resets the chip by triggering an internal watchdog reset. This is useful when the RTS control line is not available, especially in the USB-OTG and USB-Serial/JTAG modes. Use this if a chip is getting stuck in download mode when using the default reset method in USB-Serial/JTAG mode. Using this may cause the port to re-enumerate on Linux (e.g. ``/dev/ttyACM0`` -> ``/dev/ttyACM1``).
 
 
 Connect Loop

docs/en/esptool/flashing-firmware.rst

@@ -51,9 +51,9 @@ ESP-IDF outputs the full esptool command used for flashing after the build is fi
     or
     idf.py -p PORT flash
     or
-    python -m esptool --chip {IDF_TARGET_PATH_NAME} -b 460800 --before default_reset --after hard_reset write-flash --flash-mode dio --flash-size 2MB --flash-freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin
+    python -m esptool --chip {IDF_TARGET_PATH_NAME} -b 460800 --before default-reset --after hard-reset write-flash --flash-mode dio --flash-size 2MB --flash-freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin
     or from the "esp-idf/examples/get-started/hello_world/build" directory
-    python -m esptool --chip {IDF_TARGET_PATH_NAME} -b 460800 --before default_reset --after hard_reset write-flash "@flash_args"
+    python -m esptool --chip {IDF_TARGET_PATH_NAME} -b 460800 --before default-reset --after hard-reset write-flash "@flash_args"
 
 Arduino
 ^^^^^^^
@@ -67,7 +67,7 @@ To do a verbose upload and see the exact esptool invocation, run ``pio run -v -t
 
 ::
 
-    ".../.platformio/penv/bin/python" ".../.platformio/packages/tool-esptoolpy/esptool.py" --chip {IDF_TARGET_PATH_NAME} --port "/dev/cu.usbserial001" --baud 921600 --before default_reset --after hard_reset write-flash -z --flash-mode dio --flash-freq 40m --flash-size detect {IDF_TARGET_BOOTLOADER_OFFSET} .../.platformio/packages/framework-arduinoespressif32/tools/sdk/bin/bootloader_dio_40m.bin 0x8000 .../project_folder/.pio/build/esp32doit-devkit-v1/partitions.bin 0xe000 .../.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin 0x10000 .pio/build/esp32doit-devkit-v1/firmware.bin
+    ".../.platformio/penv/bin/python" ".../.platformio/packages/tool-esptoolpy/esptool.py" --chip {IDF_TARGET_PATH_NAME} --port "/dev/cu.usbserial001" --baud 921600 --before default-reset --after hard-reset write-flash -z --flash-mode dio --flash-freq 40m --flash-size detect {IDF_TARGET_BOOTLOADER_OFFSET} .../.platformio/packages/framework-arduinoespressif32/tools/sdk/bin/bootloader_dio_40m.bin 0x8000 .../project_folder/.pio/build/esp32doit-devkit-v1/partitions.bin 0xe000 .../.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin 0x10000 .pio/build/esp32doit-devkit-v1/firmware.bin
 
 
 Flashing
@@ -77,7 +77,7 @@ If you split the output, you'll find the ``write-flash`` command with a list of
 
 Change ``PORT`` to the name of :ref:`actually used serial port <serial-port>` and run the command. A successful flash looks like this::
 
-    $ python -m esptool -p /dev/tty.usbserial-0001 -b 460800 --before default_reset --after hard_reset --chip {IDF_TARGET_PATH_NAME} write-flash --flash-mode dio --flash-size detect --flash-freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin
+    $ python -m esptool -p /dev/tty.usbserial-0001 -b 460800 --before default-reset --after hard-reset --chip {IDF_TARGET_PATH_NAME} write-flash --flash-mode dio --flash-size detect --flash-freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin
     esptool.py v4.8.1
     Serial port /dev/tty.usbserial-0001:
     Connecting.........

docs/en/esptool/scripting.rst

@@ -52,7 +52,7 @@ This example demonstrates writing two binary files using high-level commands:
         attach_flash(esp)  # Attach the flash memory chip, required for flash operations
         with open(BOOTLOADER, "rb") as bl_file, open(FIRMWARE, "rb") as fw_file:
             write_flash(esp, [(0, bl_file), (0x1000, fw_file)])  # Write the binary files
-        reset_chip(esp, "hard_reset")  # Reset the chip
+        reset_chip(esp, "hard-reset")  # Reset the chip
 
 - The ``esp`` object has to be replaced with the stub flasher object returned by ``run_stub(esp)`` when the stub flasher is activated. This step can be skipped if the stub flasher is not needed.
 - Running ``attach_flash(esp)`` is required for any flash-memory-related operations to work.
@@ -90,7 +90,7 @@ The following example demonstrates running a series of flash memory operations i
             write_flash(esp, [(0, bl_file), (0x1000, fw_file)])  # Write the binary files
             verify_flash(esp, [(0, bl_file), (0x1000, fw_file)])  # Verify the written data
         read_flash(esp, 0x0, 0x2400, "output.bin")  # Read the flash memory into a file
-        reset_chip(esp, "hard_reset")  # Reset the chip
+        reset_chip(esp, "hard-reset")  # Reset the chip
 
 - This example doesn't use ``detect_chip()``, but instantiates a ``ESP32ROM`` class directly. This is useful when you know the target chip in advance. In this scenario ``esp.connect()`` is required to establish a connection with the device.
 - Multiple operations can be chained together in a single context manager block.

docs/en/migration-guide.rst

@@ -215,6 +215,17 @@ A significant amount of changes have been made to the log styling and formatting
 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.
 
 
+Reset Mode Renaming
+###################
+
+Choices for the ``--before`` and ``--after`` options have been renamed to use ``-`` instead of ``_`` as a separator (e.g., ``default_reset`` -> ``default-reset``).
+
+
+**Migration Steps:**
+
+1. Replace all underscores in the ``--before`` and ``--after`` options with ``-`` in your scripts.
+
+
 espsecure.py ``v5`` Migration Guide
 ***********************************
 
@@ -261,3 +272,15 @@ The public API of ``espsecure.py`` has been updated to provide a more consistent
    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
+***********************************
+
+Reset Mode Renaming
+###################
+
+Choices for the ``--before`` option have been renamed to use ``-`` instead of ``_`` as a separator (e.g., ``default_reset`` -> ``default-reset``).
+
+**Migration Steps:**
+
+1. Replace all underscores in the ``--before`` option with ``-`` in your scripts.

espefuse/__init__.py

@@ -197,8 +197,8 @@ def main(custom_commandline=None, esp=None):
     init_parser.add_argument(
         "--before",
         help="What to do before connecting to the chip",
-        choices=["default_reset", "usb_reset", "no_reset", "no_reset_no_sync"],
-        default="default_reset",
+        choices=["default-reset", "usb-reset", "no-reset", "no-reset-no-sync"],
+        default="default-reset",
     )
 
     init_parser.add_argument(

esptool/__init__.py

@@ -95,6 +95,7 @@
     AnyIntType,
     OptionEatAll,
     MutuallyExclusiveOption,
+    ResetModeType,
     SpiConnectionType,
     AutoHex2BinType,
     AddrFilenamePairType,
@@ -312,17 +313,17 @@ def check_flash_size(esp: ESPLoader, address: int, size: int) -> None:
 )
 @click.option(
     "--before",
-    type=click.Choice(["default_reset", "usb_reset", "no_reset", "no_reset_no_sync"]),
-    default=os.environ.get("ESPTOOL_BEFORE", "default_reset"),
+    type=ResetModeType(["default-reset", "usb-reset", "no-reset", "no-reset-no-sync"]),
+    default=os.environ.get("ESPTOOL_BEFORE", "default-reset"),
     help="Which reset to perform before connecting to the chip.",
 )
 @click.option(
     "--after",
     "-a",
-    type=click.Choice(
-        ["hard_reset", "soft_reset", "no_reset", "no_reset_stub", "watchdog_reset"]
+    type=ResetModeType(
+        ["hard-reset", "soft-reset", "no-reset", "no-reset-stub", "watchdog-reset"]
     ),
-    default=os.environ.get("ESPTOOL_AFTER", "hard_reset"),
+    default=os.environ.get("ESPTOOL_AFTER", "hard-reset"),
     help="Which reset to perform after operation is finished.",
 )
 @click.option(
@@ -384,7 +385,7 @@ def prepare_esp_object(ctx):
 
     log.stage()
 
-    if ctx.obj["before"] != "no_reset_no_sync":
+    if ctx.obj["before"] != "no-reset-no-sync":
         initial_baud = min(
             ESPLoader.ESP_ROM_BAUD, ctx.obj["baud"]
         )  # don't sync faster than the default baud rate
@@ -1047,7 +1048,7 @@ def connect_loop(
     chip: str,
     max_retries: int,
     trace: bool = False,
-    before: str = "default_reset",
+    before: str = "default-reset",
 ):
     chip_class = CHIP_DEFS[chip]
     esp = None
@@ -1095,7 +1096,7 @@ def get_default_connected_device(
     initial_baud: int,
     chip: str = "auto",
     trace: bool = False,
-    before: str = "default_reset",
+    before: str = "default-reset",
 ):
     _esp = None
     for each_port in reversed(serial_list):

esptool/cli_util.py

@@ -24,6 +24,23 @@ def convert(
         return super().convert(value, param, ctx)
 
 
+class ResetModeType(click.Choice):
+    """Custom type to accept reset mode names with underscores as separators
+    for compatibility with v4"""
+
+    def convert(self, value: str, param: click.Parameter, ctx: click.Context) -> Any:
+        if "_" in value:
+            new_value = value.replace("_", "-")
+            if new_value not in self.choices:
+                raise click.BadParameter(f"{value} is not a valid reset mode.")
+            log.warning(
+                f"Deprecated: Choice '{value}' for option '--{param.name}' is "
+                f"deprecated. Use '{new_value}' instead."
+            )
+            return new_value
+        return super().convert(value, param, ctx)
+
+
 class AnyIntType(click.ParamType):
     """Custom type to parse any integer value - decimal, hex, octal, or binary"""
 

esptool/cmds.py

@@ -87,7 +87,7 @@
 def detect_chip(
     port: str = ESPLoader.DEFAULT_PORT,
     baud: int = ESPLoader.ESP_ROM_BAUD,
-    connect_mode: str = "default_reset",
+    connect_mode: str = "default-reset",
     trace_enabled: bool = False,
     connect_attempts: int = DEFAULT_CONNECT_ATTEMPTS,
 ) -> ESPLoader:
@@ -99,8 +99,8 @@ def detect_chip(
         port: The serial port to use for communication.
         baud: The baud rate for serial communication.
         connect_mode: The chip reset method to perform when connecting to the ESP device
-            (``"default_reset"``, ``"usb_reset"``,
-            ``"no_reset"``, ``"no_reset_no_sync"``)
+            (``"default-reset"``, ``"usb-reset"``,
+            ``"no-reset"``, ``"no-reset-no-sync"``)
         trace_enabled: Enables or disables tracing for debugging purposes.
         connect_attempts: Number of connection attempts before failing.
 
@@ -1558,30 +1558,30 @@ def get_security_flag_status(flag_name, flags_value):
         log.print("USB Access: Disabled")
 
 
-def reset_chip(esp: ESPLoader, reset_mode: str = "hard_reset") -> None:
+def reset_chip(esp: ESPLoader, reset_mode: str = "hard-reset") -> None:
     """
     Reset the ESP device.
 
     Args:
         esp: Initiated esp object connected to a real device.
         reset_mode: Reset mode to use (
-            ``"hard_reset"``: perform a hard reset using the RTS control line,
-            ``"soft_reset"``: perform a soft reset,
-            ``"no_reset"``: stay in bootloader,
-            ``"no_reset_stub"``: stay in flasher stub,
-            ``"watchdog_reset"``: perform a hard reset utilizing a software watchdog.
+            ``"hard-reset"``: perform a hard reset using the RTS control line,
+            ``"soft-reset"``: perform a soft reset,
+            ``"no-reset"``: stay in bootloader,
+            ``"no-reset-stub"``: stay in flasher stub,
+            ``"watchdog-reset"``: perform a hard reset utilizing a software watchdog.
             )
 
     """
-    if reset_mode == "hard_reset":
+    if reset_mode == "hard-reset":
         esp.hard_reset()
-    elif reset_mode == "soft_reset":
+    elif reset_mode == "soft-reset":
         log.print("Soft resetting...")
         # flash_finish will trigger a soft reset
         esp.soft_reset(False)
-    elif reset_mode == "no_reset_stub":
+    elif reset_mode == "no-reset-stub":
         log.print("Staying in flasher stub.")
-    elif reset_mode == "watchdog_reset":
+    elif reset_mode == "watchdog-reset":
         if esp.secure_download_mode:
             log.warning(
                 "Watchdog hard reset is not supported in Secure Download Mode, "
@@ -1590,7 +1590,7 @@ def reset_chip(esp: ESPLoader, reset_mode: str = "hard_reset") -> None:
             esp.hard_reset()
         else:
             esp.watchdog_reset()
-    elif reset_mode == "no_reset":
+    elif reset_mode == "no-reset":
         log.print("Staying in bootloader.")
         if esp.IS_STUB:
             esp.soft_reset(True)  # Exit the stub flasher back to ROM loader