esp32tool 1.3.1 → 1.3.2

package/dist/esp_loader.d.ts

@@ -394,6 +394,14 @@ export declare class ESPLoader extends EventTarget {
      * @returns true if reset was performed, false if not needed
      */
     resetToFirmware(): Promise<boolean>;
+    /**
+     * @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 detectUsbConnectionType;
     /**
      * @name enterConsoleMode
      * Prepare device for console mode by resetting to firmware
@@ -419,6 +427,29 @@ export declare class ESPLoader extends EventTarget {
      * This is needed after Improv or other operations that leave ESP in firmware mode
      */
     reconnectToBootloader(): Promise<void>;
+    /**
+     * @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
+     */
+    exitConsoleMode(): Promise<boolean>;
+    /**
+     * @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;
+    /**
+     * @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.
+     */
+    resetInConsoleMode(): Promise<void>;
     /**
      * @name drainInputBuffer
      * Actively drain the input buffer by reading data for a specified time.

package/dist/esp_loader.js

@@ -346,27 +346,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"}`);
         }
         catch (err) {
@@ -445,7 +425,6 @@ export class ESPLoader extends EventTarget {
         this.chipFamily = chip.family;
         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";
             }
@@ -456,7 +435,6 @@ export class ESPLoader extends EventTarget {
         }
         else if (this.chipFamily === CHIP_FAMILY_ESP32C3) {
             this.chipRevision = await this.getChipRevision();
-            this.logger.debug(`ESP32-C3 revision: ${this.chipRevision}`);
         }
         this.logger.debug(`Detected chip via magic value: ${toHex(chipMagicValue >>> 0, 8)} (${this.chipName})`);
     }
@@ -551,10 +529,7 @@ export class ESPLoader extends EventTarget {
             }
         }
         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
@@ -1164,7 +1139,9 @@ export class ESPLoader extends EventTarget {
             }
             catch (error) {
                 lastError = error;
-                this.logger.debug(`${strategy.name} reset failed: ${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;
                 // Wait a bit for in-flight operations to abort
@@ -1305,7 +1282,6 @@ export class ESPLoader extends EventTarget {
         const hi = (word5 >> 23) & 0x07;
         // 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;
     }
     /**
@@ -2009,8 +1985,8 @@ export class ESPLoader extends EventTarget {
             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
@@ -2601,7 +2577,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;
         }
         // Wait for pending writes to complete
@@ -2609,7 +2585,7 @@ export class ESPLoader extends EventTarget {
             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
         if (this._writer) {
@@ -2618,7 +2594,7 @@ export class ESPLoader extends EventTarget {
                 this._writer.releaseLock();
             }
             catch (err) {
-                this.logger.debug(`Writer close/release error: ${err}`);
+                //        this.logger.debug(`Writer close/release error: ${err}`);
             }
             this._writer = undefined;
         }
@@ -2631,7 +2607,7 @@ export class ESPLoader extends EventTarget {
                 writer.releaseLock();
             }
             catch (err) {
-                this.logger.debug(`Direct writer close error: ${err}`);
+                //        this.logger.debug(`Direct writer close error: ${err}`);
             }
         }
         await new Promise((resolve) => {
@@ -2653,7 +2629,7 @@ export class ESPLoader extends EventTarget {
                 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);
@@ -2690,7 +2666,7 @@ export class ESPLoader extends EventTarget {
             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
         if (this._writer) {
@@ -2737,6 +2713,39 @@ export class ESPLoader extends EventTarget {
     async resetToFirmware() {
         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
+     */
+    async detectUsbConnectionType() {
+        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
@@ -2746,8 +2755,21 @@ export class ESPLoader extends EventTarget {
     async enterConsoleMode() {
         // 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;
+        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
             const wasReset = await this._resetToFirmwareIfNeeded();
@@ -2790,7 +2812,7 @@ export class ESPLoader extends EventTarget {
                     this.chipFamily === CHIP_FAMILY_ESP32S3
                     ? "USB-JTAG/Serial or USB-OTG"
                     : "USB-JTAG/Serial";
-                this.logger.log(`Resetting ${this.chipFamily} (${resetMethod}) to boot into firmware...`);
+                this.logger.log(`Resetting ${this.chipName || "device"} (${resetMethod}) to boot into firmware...`);
                 // Set console mode flag before reset to prevent subsequent hardReset calls
                 this._consoleMode = true;
                 // For S2/S3: Clear force download boot mask before WDT reset
@@ -3053,6 +3075,98 @@ export class ESPLoader extends EventTarget {
             throw err;
         }
     }
+    /**
+     * @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() {
+        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() {
+        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() {
+        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.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/dist/index.d.ts

@@ -7,6 +7,7 @@ export declare const connect: (logger: Logger) => Promise<ESPLoader>;
 export declare const connectWithPort: (port: SerialPort, logger: Logger) => Promise<ESPLoader>;
 export { parsePartitionTable, getPartitionTableOffset, formatSize, } from "./partition";
 export type { Partition } from "./partition";
+export { toHex, sleep, hexFormatter, formatMacAddr } from "./util";
 export { FilesystemType, detectFilesystemType, detectFilesystemFromImage, getDefaultBlockSize, getBlockSizeCandidates, getESP8266FilesystemLayout, scanESP8266Filesystem, LITTLEFS_DEFAULT_BLOCK_SIZE, LITTLEFS_BLOCK_SIZE_CANDIDATES, FATFS_DEFAULT_BLOCK_SIZE, FATFS_BLOCK_SIZE_CANDIDATES, ESP8266_LITTLEFS_BLOCK_SIZE, ESP8266_LITTLEFS_BLOCK_SIZE_CANDIDATES, ESP8266_LITTLEFS_PAGE_SIZE, ESP8266_SPIFFS_PAGE_SIZE, ESP8266_SPIFFS_BLOCK_SIZE, } from "./wasm/filesystems";
 export type { ESP8266FilesystemLayout } from "./wasm/filesystems";
 export { SpiffsFS, SpiffsBuildConfig, SpiffsReader, DEFAULT_SPIFFS_CONFIG, type SpiffsFile, type SpiffsBuildConfigOptions, } from "./lib/spiffs/index";

package/dist/index.js

@@ -44,5 +44,7 @@ export const connectWithPort = async (port, logger) => {
     return new ESPLoader(port, logger);
 };
 export { parsePartitionTable, getPartitionTableOffset, formatSize, } from "./partition";
+// Export utility functions for use in UI code
+export { toHex, sleep, hexFormatter, formatMacAddr } from "./util";
 export { FilesystemType, detectFilesystemType, detectFilesystemFromImage, getDefaultBlockSize, getBlockSizeCandidates, getESP8266FilesystemLayout, scanESP8266Filesystem, LITTLEFS_DEFAULT_BLOCK_SIZE, LITTLEFS_BLOCK_SIZE_CANDIDATES, FATFS_DEFAULT_BLOCK_SIZE, FATFS_BLOCK_SIZE_CANDIDATES, ESP8266_LITTLEFS_BLOCK_SIZE, ESP8266_LITTLEFS_BLOCK_SIZE_CANDIDATES, ESP8266_LITTLEFS_PAGE_SIZE, ESP8266_SPIFFS_PAGE_SIZE, ESP8266_SPIFFS_BLOCK_SIZE, } from "./wasm/filesystems";
 export { SpiffsFS, SpiffsBuildConfig, SpiffsReader, DEFAULT_SPIFFS_CONFIG, } from "./lib/spiffs/index";

package/dist/util.d.ts

@@ -11,4 +11,8 @@ export declare const slipEncode: (buffer: number[]) => number[];
 export declare const toByteArray: (str: string) => number[];
 export declare const hexFormatter: (bytes: number[]) => string;
 export declare const toHex: (value: number, size?: number) => string;
+/**
+ * Format MAC address array to string (e.g., [0xAA, 0xBB, 0xCC] -> "AA:BB:CC:DD:EE:FF")
+ */
+export declare const formatMacAddr: (macAddr: number[]) => string;
 export declare const sleep: (ms: number) => Promise<unknown>;

package/dist/util.js

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