tasmota-webserial-esptool 9.2.9 → 9.2.11

package/src/esp_loader.ts

@@ -141,9 +141,13 @@ export class ESPLoader extends EventTarget {
   __inputBuffer?: number[];
   __inputBufferReadIndex?: number;
   __totalBytesRead?: number;
-  private __currentBaudRate: number = ESP_ROM_BAUD;
+  public currentBaudRate: number = ESP_ROM_BAUD;
   private _maxUSBSerialBaudrate?: number;
   public __reader?: ReadableStreamDefaultReader<Uint8Array>;
+  private SLIP_END = 0xc0;
+  private SLIP_ESC = 0xdb;
+  private SLIP_ESC_END = 0xdc;
+  private SLIP_ESC_ESC = 0xdd;
   private _isESP32S2NativeUSB: boolean = false;
   private _initializationSucceeded: boolean = false;
   private __commandLock: Promise<[number, number[]]> = Promise.resolve([0, []]);
@@ -757,17 +761,14 @@ export class ESPLoader extends EventTarget {
 
         // Always read from browser's serial buffer immediately
         // to prevent browser buffer overflow. Don't apply back-pressure here.
-        const chunk = Array.from(value);
+        const chunk = Array.from(value as Uint8Array);
         Array.prototype.push.apply(this._inputBuffer, chunk);
 
         // Track total bytes read from serial port
         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
@@ -1462,9 +1463,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;
@@ -2129,47 +2130,47 @@ export class ESPLoader extends EventTarget {
               "Timed out waiting for packet " + waitingFor,
             );
           }
-          const b = this._readByte()!;
+          const byte = this._readByte()!;
 
           if (partialPacket === null) {
             // waiting for packet header
-            if (b == 0xc0) {
+            if (byte == this.SLIP_END) {
               partialPacket = [];
             } else {
               if (this.debug) {
-                this.logger.debug("Read invalid data: " + toHex(b));
+                this.logger.debug("Read invalid data: " + toHex(byte));
                 this.logger.debug(
                   "Remaining data in serial buffer: " +
                     hexFormatter(this._inputBuffer),
                 );
               }
               throw new SlipReadError(
-                "Invalid head of packet (" + toHex(b) + ")",
+                "Invalid head of packet (" + toHex(byte) + ")",
               );
             }
           } else if (inEscape) {
             // part-way through escape sequence
             inEscape = false;
-            if (b == 0xdc) {
-              partialPacket.push(0xc0);
-            } else if (b == 0xdd) {
-              partialPacket.push(0xdb);
+            if (byte == this.SLIP_ESC_END) {
+              partialPacket.push(this.SLIP_END);
+            } else if (byte == this.SLIP_ESC_ESC) {
+              partialPacket.push(this.SLIP_ESC);
             } else {
               if (this.debug) {
-                this.logger.debug("Read invalid data: " + toHex(b));
+                this.logger.debug("Read invalid data: " + toHex(byte));
                 this.logger.debug(
                   "Remaining data in serial buffer: " +
                     hexFormatter(this._inputBuffer),
                 );
               }
               throw new SlipReadError(
-                "Invalid SLIP escape (0xdb, " + toHex(b) + ")",
+                "Invalid SLIP escape (0xdb, " + toHex(byte) + ")",
               );
             }
-          } else if (b == 0xdb) {
+          } else if (byte == this.SLIP_ESC) {
             // start of escape sequence
             inEscape = true;
-          } else if (b == 0xc0) {
+          } else if (byte == this.SLIP_END) {
             // end of packet
             if (this.debug)
               this.logger.debug(
@@ -2180,7 +2181,7 @@ export class ESPLoader extends EventTarget {
             return partialPacket;
           } else {
             // normal byte in packet
-            partialPacket.push(b);
+            partialPacket.push(byte);
           }
         }
       }
@@ -2214,46 +2215,46 @@ export class ESPLoader extends EventTarget {
           this.logger.debug(
             "Read " + readBytes.length + " bytes: " + hexFormatter(readBytes),
           );
-        for (const b of readBytes) {
+        for (const byte of readBytes) {
           if (partialPacket === null) {
             // waiting for packet header
-            if (b == 0xc0) {
+            if (byte == this.SLIP_END) {
               partialPacket = [];
             } else {
               if (this.debug) {
-                this.logger.debug("Read invalid data: " + toHex(b));
+                this.logger.debug("Read invalid data: " + toHex(byte));
                 this.logger.debug(
                   "Remaining data in serial buffer: " +
                     hexFormatter(this._inputBuffer),
                 );
               }
               throw new SlipReadError(
-                "Invalid head of packet (" + toHex(b) + ")",
+                "Invalid head of packet (" + toHex(byte) + ")",
               );
             }
           } else if (inEscape) {
             // part-way through escape sequence
             inEscape = false;
-            if (b == 0xdc) {
-              partialPacket.push(0xc0);
-            } else if (b == 0xdd) {
-              partialPacket.push(0xdb);
+            if (byte == this.SLIP_ESC_END) {
+              partialPacket.push(this.SLIP_END);
+            } else if (byte == this.SLIP_ESC_ESC) {
+              partialPacket.push(this.SLIP_ESC);
             } else {
               if (this.debug) {
-                this.logger.debug("Read invalid data: " + toHex(b));
+                this.logger.debug("Read invalid data: " + toHex(byte));
                 this.logger.debug(
                   "Remaining data in serial buffer: " +
                     hexFormatter(this._inputBuffer),
                 );
               }
               throw new SlipReadError(
-                "Invalid SLIP escape (0xdb, " + toHex(b) + ")",
+                "Invalid SLIP escape (0xdb, " + toHex(byte) + ")",
               );
             }
-          } else if (b == 0xdb) {
+          } else if (byte == this.SLIP_ESC) {
             // start of escape sequence
             inEscape = true;
-          } else if (b == 0xc0) {
+          } else if (byte == this.SLIP_END) {
             // end of packet
             if (this.debug)
               this.logger.debug(
@@ -2264,7 +2265,7 @@ export class ESPLoader extends EventTarget {
             return partialPacket;
           } else {
             // normal byte in packet
-            partialPacket.push(b);
+            partialPacket.push(byte);
           }
         }
       }
@@ -2341,9 +2342,9 @@ export class ESPLoader extends EventTarget {
 
     // Track current baudrate for reconnect
     if (this._parent) {
-      this._parent._currentBaudRate = baud;
+      this._parent.currentBaudRate = baud;
     } else {
-      this._currentBaudRate = baud;
+      this.currentBaudRate = baud;
     }
 
     // Warn if baudrate exceeds USB-Serial chip capability
@@ -2429,8 +2430,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;
@@ -3138,20 +3139,6 @@ export class ESPLoader extends EventTarget {
     }
   }
 
-  private get _currentBaudRate(): number {
-    return this._parent
-      ? this._parent._currentBaudRate
-      : this.__currentBaudRate;
-  }
-
-  private set _currentBaudRate(value: number) {
-    if (this._parent) {
-      this._parent._currentBaudRate = value;
-    } else {
-      this.__currentBaudRate = value;
-    }
-  }
-
   async writeToStream(data: number[]) {
     if (!this.port.writable) {
       this.logger.debug("Port writable stream not available, skipping write");
@@ -3231,7 +3218,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;
     }
 
@@ -3239,7 +3226,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
@@ -3248,7 +3235,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 {
@@ -3259,7 +3246,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}`);
       }
     }
 
@@ -3288,7 +3275,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);
@@ -3328,7 +3315,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
@@ -3378,37 +3365,46 @@ export class ESPLoader extends EventTarget {
   /**
    * @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
+   * Uses USB PID (Product ID) for reliable detection
    * @returns true if USB-JTAG or USB-OTG, false if external serial chip
-   * @throws Error if detection fails and chipFamily is not set
+   * @throws Error if 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
+    // Use PID-based detection (most reliable method)
+    const portInfo = this.port.getInfo();
+    const pid = portInfo.usbProductId;
+    const vid = portInfo.usbVendorId;
+
+    this.logger.debug(
+      `USB detection: VID=0x${vid?.toString(16)}, PID=0x${pid?.toString(16)}`,
+    );
+
+    // Check if this is an Espressif device
+    const isEspressif = vid === 0x303a;
+
+    if (!isEspressif) {
+      this.logger.debug("Not Espressif VID - external serial chip");
       return false;
     }
+
+    // ESP32-S2/S3/C3/C6/H2 USB-JTAG/OTG PIDs
+    // 0x1001 = ESP32-S3 USB-JTAG
+    // 0x0002 = ESP32-S2 USB-JTAG
+    // 0x1000 = ESP32-C3 USB-JTAG
+    // 0x4008 = ESP32-C6 USB-JTAG
+    // 0x4009 = ESP32-H2 USB-JTAG
+    const usbJtagPids = [0x1001, 0x0002, 0x1000, 0x4008, 0x4009];
+    const isUsbJtag = usbJtagPids.includes(pid || 0);
+
+    this.logger.debug(
+      `USB-JTAG/OTG detection: ${isUsbJtag ? "YES" : "NO"} (PID=0x${pid?.toString(16)})`,
+    );
+
+    return isUsbJtag;
   }
 
   /**
@@ -3442,6 +3438,8 @@ export class ESPLoader extends EventTarget {
       isUsbJtag = this.isUsbJtagOrOtg;
     }
 
+    // Release reader/writer so console can create new ones
+    // This is needed for Desktop (Web Serial) to unlock streams
     if (isUsbJtag) {
       // USB-JTAG/OTG devices: Use watchdog reset which closes port
       const wasReset = await this._resetToFirmwareIfNeeded();
@@ -3463,6 +3461,18 @@ export class ESPLoader extends EventTarget {
         this.logger.debug(`Could not reset device: ${err}`);
       }
 
+      // For WebUSB (Android), recreate streams after hardware reset
+      if (this.isWebUSB()) {
+        try {
+          // Use the public recreateStreams() method to safely recreate streams
+          // without closing the port (important after hardware reset)
+          await (this.port as any).recreateStreams();
+          this.logger.debug("WebUSB streams recreated for console mode");
+        } catch (err) {
+          this.logger.debug(`Failed to recreate WebUSB streams: ${err}`);
+        }
+      }
+
       return false; // Port stays open
     }
   }
@@ -3488,7 +3498,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
@@ -3567,7 +3577,7 @@ export class ESPLoader extends EventTarget {
 
     try {
       this.logger.log("Reconnecting serial port...");
-      const savedBaudRate = this._currentBaudRate;
+      const savedBaudRate = this.currentBaudRate;
 
       this.connected = false;
       this.__inputBuffer = [];
@@ -3616,7 +3626,7 @@ export class ESPLoader extends EventTarget {
       try {
         await this.port.open({ baudRate: ESP_ROM_BAUD });
         this.connected = true;
-        this._currentBaudRate = ESP_ROM_BAUD;
+        this.currentBaudRate = ESP_ROM_BAUD;
       } catch (err) {
         throw new Error(`Failed to open port: ${err}`);
       }
@@ -3758,7 +3768,7 @@ export class ESPLoader extends EventTarget {
       try {
         await this.port.open({ baudRate: ESP_ROM_BAUD });
         this.connected = true;
-        this._currentBaudRate = ESP_ROM_BAUD;
+        this.currentBaudRate = ESP_ROM_BAUD;
       } catch (err) {
         throw new Error(`Failed to open port: ${err}`);
       }
@@ -3805,6 +3815,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.
@@ -3820,7 +3939,7 @@ export class ESPLoader extends EventTarget {
     await sleep(bufferingTime);
 
     // Unsupported command response is sent 8 times and has
-    // 14 bytes length including delimiter 0xC0 bytes.
+    // 14 bytes length including delimiter SLIP_END (0xC0) bytes.
     // At least part of it is read as a command response,
     // but to be safe, read it all.
     const bytesToDrain = 14 * 8;
@@ -4040,7 +4159,7 @@ export class ESPLoader extends EventTarget {
                 // The stub expects 4 bytes (ACK), if we send less it will break out
                 try {
                   // Send SLIP frame with no data (just delimiters)
-                  const abortFrame = [0xc0, 0xc0]; // Empty SLIP frame
+                  const abortFrame = [this.SLIP_END, this.SLIP_END]; // Empty SLIP frame
                   await this.writeToStream(abortFrame);
                   this.logger.debug(`Sent abort frame to stub`);
 

package/src/index.ts

@@ -99,3 +99,6 @@ export const connectWithPort = async (port: SerialPort, logger: Logger) => {
 
   return new ESPLoader(port, logger);
 };
+
+// Export utility functions for use in UI code
+export { toHex, sleep, hexFormatter, formatMacAddr } from "./util";

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));