esp32tool 1.3.1 → 1.3.2

package/src/esp_loader.ts

@@ -522,28 +522,7 @@ export class ESPLoader extends EventTarget {
     // Detect if device is using USB-JTAG/Serial or USB-OTG (not external serial chip)
     // This is needed to determine the correct reset strategy for console mode
     try {
-      if (
-        this.chipFamily === CHIP_FAMILY_ESP32S2 ||
-        this.chipFamily === CHIP_FAMILY_ESP32S3
-      ) {
-        const isUsingUsbOtg = await this.usingUsbOtg();
-        const isUsingUsbJtagSerial = await this.usingUsbJtagSerial();
-        this._isUsbJtagOrOtg = isUsingUsbOtg || isUsingUsbJtagSerial;
-      } else if (
-        this.chipFamily === CHIP_FAMILY_ESP32C3 ||
-        this.chipFamily === CHIP_FAMILY_ESP32C5 ||
-        this.chipFamily === CHIP_FAMILY_ESP32C6
-      ) {
-        const isUsingUsbJtagSerial = await this.usingUsbJtagSerial();
-        this._isUsbJtagOrOtg = isUsingUsbJtagSerial;
-      } else if (this.chipFamily === CHIP_FAMILY_ESP32P4) {
-        const isUsingUsbOtg = await this.usingUsbOtg();
-        const isUsingUsbJtagSerial = await this.usingUsbJtagSerial();
-        this._isUsbJtagOrOtg = isUsingUsbOtg || isUsingUsbJtagSerial;
-      } else {
-        // Other chips don't have USB-JTAG/OTG
-        this._isUsbJtagOrOtg = false;
-      }
+      this._isUsbJtagOrOtg = await this.detectUsbConnectionType();
       this.logger.debug(
         `USB connection type: ${this._isUsbJtagOrOtg ? "USB-JTAG/OTG" : "External Serial Chip"}`,
       );
@@ -647,7 +626,6 @@ export class ESPLoader extends EventTarget {
 
     if (this.chipFamily === CHIP_FAMILY_ESP32P4) {
       this.chipRevision = await this.getChipRevision();
-      this.logger.debug(`ESP32-P4 revision: ${this.chipRevision}`);
 
       if (this.chipRevision >= 300) {
         this.chipVariant = "rev300";
@@ -657,7 +635,6 @@ export class ESPLoader extends EventTarget {
       this.logger.debug(`ESP32-P4 variant: ${this.chipVariant}`);
     } else if (this.chipFamily === CHIP_FAMILY_ESP32C3) {
       this.chipRevision = await this.getChipRevision();
-      this.logger.debug(`ESP32-C3 revision: ${this.chipRevision}`);
     }
 
     this.logger.debug(
@@ -787,10 +764,7 @@ export class ESPLoader extends EventTarget {
         this._totalBytesRead += value.length;
       }
     } catch {
-      // Don't log error if this is an expected disconnect during console mode transition
-      if (!this._consoleMode) {
-        this.logger.error("Read loop got disconnected");
-      }
+      //      this.logger.error("Read loop got disconnected");
     } finally {
       // Always reset reconfiguring flag when read loop ends
       // This prevents "Cannot write during port reconfiguration" errors
@@ -1485,9 +1459,9 @@ export class ESPLoader extends EventTarget {
         }
       } catch (error) {
         lastError = error as Error;
-        this.logger.debug(
-          `${strategy.name} reset failed: ${(error as Error).message}`,
-        );
+        //        this.logger.debug(
+        //          `${strategy.name} reset failed: ${(error as Error).message}`,
+        //        );
 
         // Set abandon flag to stop any in-flight operations
         this._abandonCurrentOperation = true;
@@ -1641,8 +1615,6 @@ export class ESPLoader extends EventTarget {
     // Combine: upper 3 bits from word5, lower 3 bits from word3
     const revision = (hi << 3) | low;
 
-    this.logger.debug(`ESP32-C3 revision: ${revision}`);
-
     return revision;
   }
 
@@ -2454,8 +2426,8 @@ export class ESPLoader extends EventTarget {
       // Restart Readloop
       this.readLoop();
     } catch (e) {
-      this.logger.error(`Reconfigure port error: ${e}`);
-      throw new Error(`Unable to change the baud rate to ${baud}: ${e}`);
+      //      this.logger.error(`Reconfigure port error: ${e}`);
+      //      throw new Error(`Unable to change the baud rate to ${baud}: ${e}`);
     } finally {
       // Always reset flag, even on error or early return
       this._isReconfiguring = false;
@@ -3228,7 +3200,7 @@ export class ESPLoader extends EventTarget {
       return;
     }
     if (!this.port.writable) {
-      this.logger.debug("Port already closed, skipping disconnect");
+      //      this.logger.debug("Port already closed, skipping disconnect");
       return;
     }
 
@@ -3236,7 +3208,7 @@ export class ESPLoader extends EventTarget {
     try {
       await this._writeChain;
     } catch (err) {
-      this.logger.debug(`Pending write error during disconnect: ${err}`);
+      //      this.logger.debug(`Pending write error during disconnect: ${err}`);
     }
 
     // Release persistent writer before closing
@@ -3245,7 +3217,7 @@ export class ESPLoader extends EventTarget {
         await this._writer.close();
         this._writer.releaseLock();
       } catch (err) {
-        this.logger.debug(`Writer close/release error: ${err}`);
+        //        this.logger.debug(`Writer close/release error: ${err}`);
       }
       this._writer = undefined;
     } else {
@@ -3256,7 +3228,7 @@ export class ESPLoader extends EventTarget {
         await writer.close();
         writer.releaseLock();
       } catch (err) {
-        this.logger.debug(`Direct writer close error: ${err}`);
+        //        this.logger.debug(`Direct writer close error: ${err}`);
       }
     }
 
@@ -3285,7 +3257,7 @@ export class ESPLoader extends EventTarget {
       try {
         this._reader.cancel();
       } catch (err) {
-        this.logger.debug(`Reader cancel error: ${err}`);
+        //        this.logger.debug(`Reader cancel error: ${err}`);
         // Reader already released, resolve immediately
         clearTimeout(timeout);
         resolve(undefined);
@@ -3325,7 +3297,7 @@ export class ESPLoader extends EventTarget {
     try {
       await this._writeChain;
     } catch (err) {
-      this.logger.debug(`Pending write error during release: ${err}`);
+      //      this.logger.debug(`Pending write error during release: ${err}`);
     }
 
     // Release writer
@@ -3372,6 +3344,42 @@ export class ESPLoader extends EventTarget {
     return await this._resetToFirmwareIfNeeded();
   }
 
+  /**
+   * @name detectUsbConnectionType
+   * Detect if device is using USB-JTAG/Serial or USB-OTG (not external serial chip)
+   * This helper extracts the detection logic from initialize() for reuse
+   * @returns true if USB-JTAG or USB-OTG, false if external serial chip
+   * @throws Error if detection fails and chipFamily is not set
+   */
+  private async detectUsbConnectionType(): Promise<boolean> {
+    if (!this.chipFamily) {
+      throw new Error("Cannot detect USB connection type: chipFamily not set");
+    }
+
+    if (
+      this.chipFamily === CHIP_FAMILY_ESP32S2 ||
+      this.chipFamily === CHIP_FAMILY_ESP32S3
+    ) {
+      const isUsingUsbOtg = await this.usingUsbOtg();
+      const isUsingUsbJtagSerial = await this.usingUsbJtagSerial();
+      return isUsingUsbOtg || isUsingUsbJtagSerial;
+    } else if (
+      this.chipFamily === CHIP_FAMILY_ESP32C3 ||
+      this.chipFamily === CHIP_FAMILY_ESP32C5 ||
+      this.chipFamily === CHIP_FAMILY_ESP32C6
+    ) {
+      const isUsingUsbJtagSerial = await this.usingUsbJtagSerial();
+      return isUsingUsbJtagSerial;
+    } else if (this.chipFamily === CHIP_FAMILY_ESP32P4) {
+      const isUsingUsbOtg = await this.usingUsbOtg();
+      const isUsingUsbJtagSerial = await this.usingUsbJtagSerial();
+      return isUsingUsbOtg || isUsingUsbJtagSerial;
+    } else {
+      // Other chips don't have USB-JTAG/OTG
+      return false;
+    }
+  }
+
   /**
    * @name enterConsoleMode
    * Prepare device for console mode by resetting to firmware
@@ -3382,8 +3390,26 @@ export class ESPLoader extends EventTarget {
     // Set console mode flag
     this._consoleMode = true;
 
-    // Check device type
-    const isUsbJtag = this.isUsbJtagOrOtg === true;
+    // Re-detect USB connection type to ensure we have a definitive value
+    // This handles cases where isUsbJtagOrOtg might be undefined
+    let isUsbJtag: boolean;
+    try {
+      isUsbJtag = await this.detectUsbConnectionType();
+      this.logger.debug(
+        `USB connection type detected: ${isUsbJtag ? "USB-JTAG/OTG" : "External Serial Chip"}`,
+      );
+    } catch (err) {
+      // If detection fails, fall back to cached value or fail-fast
+      if (this.isUsbJtagOrOtg === undefined) {
+        throw new Error(
+          `Cannot enter console mode: USB connection type unknown and detection failed: ${err}`,
+        );
+      }
+      this.logger.debug(
+        `USB detection failed, using cached value: ${this.isUsbJtagOrOtg}`,
+      );
+      isUsbJtag = this.isUsbJtagOrOtg;
+    }
 
     if (isUsbJtag) {
       // USB-JTAG/OTG devices: Use watchdog reset which closes port
@@ -3431,7 +3457,7 @@ export class ESPLoader extends EventTarget {
             : "USB-JTAG/Serial";
 
         this.logger.log(
-          `Resetting ${this.chipFamily} (${resetMethod}) to boot into firmware...`,
+          `Resetting ${this.chipName || "device"} (${resetMethod}) to boot into firmware...`,
         );
 
         // Set console mode flag before reset to prevent subsequent hardReset calls
@@ -3748,6 +3774,115 @@ export class ESPLoader extends EventTarget {
     }
   }
 
+  /**
+   * @name exitConsoleMode
+   * Exit console mode and return to bootloader
+   * For ESP32-S2, uses reconnectToBootloader which will trigger port change
+   * @returns true if manual reconnection is needed (ESP32-S2), false otherwise
+   */
+  async exitConsoleMode(): Promise<boolean> {
+    if (this._parent) {
+      return await this._parent.exitConsoleMode();
+    }
+
+    // Clear console mode flag
+    this._consoleMode = false;
+
+    // Check if this is ESP32-S2 with USB-JTAG/OTG
+    const isESP32S2 = this.chipFamily === CHIP_FAMILY_ESP32S2;
+
+    // For ESP32-S2: if _isUsbJtagOrOtg is undefined, try to detect it
+    // If detection fails or is undefined, assume USB-JTAG/OTG (conservative/safe path)
+    let isUsbJtagOrOtg = this._isUsbJtagOrOtg;
+    if (isESP32S2 && isUsbJtagOrOtg === undefined) {
+      try {
+        isUsbJtagOrOtg = await this.detectUsbConnectionType();
+      } catch (err) {
+        this.logger.debug(
+          `USB detection failed, assuming USB-JTAG/OTG for ESP32-S2: ${err}`,
+        );
+        isUsbJtagOrOtg = true; // Conservative fallback for ESP32-S2
+      }
+    }
+
+    if (isESP32S2 && isUsbJtagOrOtg) {
+      // ESP32-S2 USB: Use reconnectToBootloader which handles the mode switch
+      // This will close the port and the device will reboot to bootloader
+      this.logger.log("ESP32-S2 USB detected - reconnecting to bootloader");
+
+      try {
+        await this.reconnectToBootloader();
+      } catch (err) {
+        this.logger.debug(`Reconnect error (expected for ESP32-S2): ${err}`);
+      }
+
+      // For ESP32-S2, port will change, so return true to indicate manual reconnection needed
+      return true;
+    }
+
+    // For other devices, use standard reconnectToBootloader
+    await this.reconnectToBootloader();
+    return false; // No manual reconnection needed
+  }
+
+  /**
+   * @name isConsoleResetSupported
+   * Check if console reset is supported for this device
+   * ESP32-S2 USB-JTAG/CDC does not support reset in console mode
+   * because any reset causes USB port to be lost (hardware limitation)
+   */
+  isConsoleResetSupported(): boolean {
+    if (this._parent) {
+      return this._parent.isConsoleResetSupported();
+    }
+
+    // For ESP32-S2: if _isUsbJtagOrOtg is undefined, assume USB-JTAG/OTG (conservative)
+    // This means console reset is NOT supported (safer default)
+    const isS2UsbJtag =
+      this.chipFamily === CHIP_FAMILY_ESP32S2 &&
+      (this._isUsbJtagOrOtg === true || this._isUsbJtagOrOtg === undefined);
+    return !isS2UsbJtag; // Not supported for ESP32-S2 USB-JTAG/CDC
+  }
+
+  /**
+   * @name resetInConsoleMode
+   * Reset device while in console mode (firmware mode)
+   *
+   * NOTE: For ESP32-S2 USB-JTAG/CDC, ANY reset (hardware or software) causes
+   * the USB port to be lost because the device switches USB modes during reset.
+   * This is a hardware limitation - use isConsoleResetSupported() to check first.
+   */
+  async resetInConsoleMode(): Promise<void> {
+    if (this._parent) {
+      return await this._parent.resetInConsoleMode();
+    }
+
+    if (!this.isConsoleResetSupported()) {
+      this.logger.debug(
+        "Console reset not supported for ESP32-S2 USB-JTAG/CDC",
+      );
+      return; // Do nothing
+    }
+
+    // For other devices: Use standard firmware reset
+    const isWebUSB = (this.port as any).isWebUSB === true;
+
+    try {
+      this.logger.debug("Resetting device in console mode");
+
+      if (isWebUSB) {
+        await this.hardResetToFirmwareWebUSB();
+      } else {
+        await this.hardResetToFirmware();
+      }
+
+      this.logger.debug("Device reset complete");
+    } catch (err) {
+      this.logger.error(`Reset failed: ${err}`);
+      throw err;
+    }
+  }
+
   /**
    * @name drainInputBuffer
    * Actively drain the input buffer by reading data for a specified time.

package/src/index.ts

@@ -107,6 +107,9 @@ export {
 } from "./partition";
 export type { Partition } from "./partition";
 
+// Export utility functions for use in UI code
+export { toHex, sleep, hexFormatter, formatMacAddr } from "./util";
+
 export {
   FilesystemType,
   detectFilesystemType,

package/src/util.ts

@@ -45,5 +45,14 @@ export const toHex = (value: number, size = 2) => {
   }
 };
 
+/**
+ * Format MAC address array to string (e.g., [0xAA, 0xBB, 0xCC] -> "AA:BB:CC:DD:EE:FF")
+ */
+export const formatMacAddr = (macAddr: number[]): string => {
+  return macAddr
+    .map((value) => value.toString(16).toUpperCase().padStart(2, "0"))
+    .join(":");
+};
+
 export const sleep = (ms: number) =>
   new Promise((resolve) => setTimeout(resolve, ms));

package/script/build

@@ -1,12 +0,0 @@
-# Stop on errors
-set -e
-
-cd "$(dirname "$0")/.."
-
-rm -rf dist
-rm -rf js/modules
-mkdir js/modules
-NODE_ENV=production npm exec -- tsc
-NODE_ENV=production npm exec -- rollup -c
-cp dist/web/*.js js/modules/
-mv js/modules/index.js js/modules/esptool.js

package/script/develop

@@ -1,17 +0,0 @@
-# Stop on errors
-set -e
-
-cd "$(dirname "$0")/.."
-
-rm -rf dist
-
-# Quit all background tasks when script exits
-trap "kill 0" EXIT
-
-# Run tsc once as rollup expects those files
-npm exec -- tsc || true
-
-npm exec -- serve -p 5004 &
-npm exec -- tsc --watch &
-npm exec -- rollup -c --watch &
-wait