feat(logging): Add collapsible output stages and ASCII progress bars

Author: radimkarnis

docs/en/esptool/configuration-file.rst

@@ -97,7 +97,7 @@ Complete list of configurable options:
 +------------------------------+-----------------------------------------------------------+----------+
 | erase_write_timeout_per_mb   | Timeout (per megabyte) for erasing and writing data       | 40 s     |
 +------------------------------+-----------------------------------------------------------+----------+
-| mem_end_rom_timeout          | Short timeout for ESP_MEM_END                             | 0.2 s    |
+| mem_end_rom_timeout          | Short timeout for MEM_END                                 | 0.2 s    |
 +------------------------------+-----------------------------------------------------------+----------+
 | serial_write_timeout         | Timeout for serial port write                             | 10 s     |
 +------------------------------+-----------------------------------------------------------+----------+

docs/en/esptool/scripting.rst

@@ -295,7 +295,7 @@ Esptool allows redirecting output by implementing a custom logger class. This ca
         log_to_file = True
         log_file = "esptool.log"
 
-        def print(self, message, *args, **kwargs):
+        def print(self, message="", *args, **kwargs):
             # Print to console
             print(f"[CustomLogger]: {message}", *args, **kwargs)
             # Optionally log to a file
@@ -312,14 +312,22 @@ Esptool allows redirecting output by implementing a custom logger class. This ca
         def error(self, message):
             self.print(message, file=sys.stderr)
 
-        def print_overwrite(self, message, last_line=False):
-            # Overwriting not needed, print normally
-            self.print(message)
-
-        def set_progress(self, percentage):
-            # Progress updates not needed, pass
+        def stage(self, finish=False):
+            # Collapsible stages not needed in this example
             pass
 
+        def progress_bar(
+            self,
+            cur_iter,
+            total_iters,
+            prefix = "",
+            suffix = "",
+            bar_length: int = 30,
+        ):
+            # Progress bars replaced with simple percentage output in this example
+            percent = f"{100 * (cur_iter / float(total_iters)):.1f}"
+            self.print(f"Finished: {percent}%")
+
     # Replace the default logger with the custom logger
     log.set_logger(CustomLogger())
 
@@ -334,11 +342,11 @@ To ensure compatibility with esptool, the custom logger should re-implement (or
 - ``note``: Logs informational messages.
 - ``warning``: Logs warning messages.
 - ``error``: Logs error messages.
-- ``print_overwrite``: Handles message overwriting (can be a simple ``print()`` if overwriting is not needed).
-- ``set_progress``: Handles percentage updates of long-running operations - ``write-flash``, ``read-flash``, and ``dump-mem`` (useful for GUI visualisation, e.g. as a progress bar).
+- ``stage``: Starts or ends a collapsible output stage.
+- ``progress_bar``: Displays a progress bar.
 
 .. autoclass:: esptool.logger.EsptoolLogger
-   :members: print, note, warning, error, print_overwrite, set_progress
+   :members: print, note, warning, error, stage, progress_bar
    :member-order: bysource
 
-These methods are essential for maintaining proper integration and behavior with esptool. Additionally, all calls to the logger should be made using ``log.print()`` (or the respective method, such as ``log.info()`` or ``log.warning()``) instead of the standard ``print()`` function to ensure the output is routed through the custom logger. This ensures consistency and allows the custom logger to handle all output appropriately. You can further customize this logger to fit your application's needs, such as integrating with GUI components or advanced logging frameworks.
+These methods are essential for maintaining proper integration and behavior with esptool. Additionally, all output printing should be made using ``log.print()`` (or the respective method, such as ``log.info()`` or ``log.warning()``) instead of the standard ``print()`` function to ensure the output is routed through the custom logger. This ensures consistency and allows the custom logger to handle all output appropriately. You can further customize this logger to fit your application's needs, such as integrating with GUI components or advanced logging frameworks.

esptool/__init__.py

@@ -278,7 +278,8 @@ def check_flash_size(esp: ESPLoader, address: int, size: int) -> None:
     cls=Group,
     no_args_is_help=True,
     context_settings=dict(help_option_names=["-h", "--help"], max_content_width=120),
-    help=f"esptool.py v{__version__} - Espressif chips ROM Bootloader Utility",
+    help=f"esptool.py v{__version__} - Espressif SoCs flashing, debugging, "
+    "and provisioning utility",
 )
 @click.option(
     "--chip",
@@ -376,6 +377,12 @@ def prepare_esp_object(ctx):
     # 1) Get the ESP object
     #######################
 
+    # Disable output stage collapsing, colors, and overwriting in trace mode
+    if ctx.obj["trace"]:
+        log._smart_features = False
+
+    log.stage()
+
     if ctx.obj["before"] != "no_reset_no_sync":
         initial_baud = min(
             ESPLoader.ESP_ROM_BAUD, ctx.obj["baud"]
@@ -430,19 +437,23 @@ def prepare_esp_object(ctx):
             f"on any of the {len(ser_list)} available serial ports."
         )
 
+    log.stage(finish=True)
+    log.print(f"Connected to {esp.CHIP_NAME} on {esp._port.port}:")
+
     # 2) Print the chip info
     ########################
 
     if esp.secure_download_mode:
         log.print(f"Chip is {esp.CHIP_NAME} in Secure Download Mode")
     else:
-        log.print(f"Chip is {esp.get_chip_description()}")
-        log.print(f"Features: {', '.join(esp.get_chip_features())}")
-        log.print(f"Crystal is {esp.get_crystal_freq()}MHz")
+        log.print(f"{'Chip type:':<20}{esp.get_chip_description()}")
+        log.print(f"{'Features:':<20}{', '.join(esp.get_chip_features())}")
+        log.print(f"{'Crystal frequency:':<20}{esp.get_crystal_freq()}MHz")
         usb_mode = esp.get_usb_mode()
         if usb_mode is not None:
-            log.print(f"USB mode: {usb_mode}")
+            log.print(f"{'USB mode:':<20}{usb_mode}")
         read_mac(esp)
+        log.print()
 
     # 3) Upload the stub flasher
     ############################
@@ -488,6 +499,7 @@ def teardown():
 
         # 8) Reset the chip
         ###################
+        log.print()
         # Handle post-operation behaviour (reset or other)
         if ctx.obj["invoked_subcommand"] == "load-ram":
             # the ESP is now running the loaded image, so let it run