tasmota-webserial-esptool 9.1.8 → 9.2.0

package/src/esp_loader.ts

@@ -101,8 +101,7 @@ export class ESPLoader extends EventTarget {
   private __isReconfiguring: boolean = false;
   private __abandonCurrentOperation: boolean = false;
 
-  // Adaptive speed adjustment for flash read operations - DISABLED
-  // Using fixed conservative values that work reliably
+  // Adaptive speed adjustment for flash read operations
   private __adaptiveBlockMultiplier: number = 1;
   private __adaptiveMaxInFlightMultiplier: number = 1;
   private __consecutiveSuccessfulChunks: number = 0;
@@ -118,6 +117,7 @@ export class ESPLoader extends EventTarget {
   }
 
   // Chip properties with parent delegation
+  // chipFamily accessed before initialization as designed
   get chipFamily(): ChipFamily {
     return this._parent ? this._parent.chipFamily : this.__chipFamily!;
   }
@@ -167,7 +167,13 @@ export class ESPLoader extends EventTarget {
   }
 
   private get _inputBuffer(): number[] {
-    return this._parent ? this._parent._inputBuffer : this.__inputBuffer!;
+    if (this._parent) {
+      return this._parent._inputBuffer;
+    }
+    if (this.__inputBuffer === undefined) {
+      throw new Error("_inputBuffer accessed before initialization");
+    }
+    return this.__inputBuffer;
   }
 
   private get _inputBufferReadIndex(): number {
@@ -715,6 +721,15 @@ export class ESPLoader extends EventTarget {
     await this.port.setSignals({ dataTerminalReady: state });
   }
 
+  async setDTRandRTS(dtr: boolean, rts: boolean) {
+    this.state_DTR = dtr;
+    this.state_RTS = rts;
+    await this.port.setSignals({
+      dataTerminalReady: dtr,
+      requestToSend: rts,
+    });
+  }
+
   /**
    * @name hardResetUSBJTAGSerial
    * USB-JTAG/Serial reset for Web Serial (Desktop)
@@ -741,7 +756,7 @@ export class ESPLoader extends EventTarget {
 
   /**
    * @name hardResetClassic
-   * Classic reset for Web Serial (Desktop)
+   * Classic reset for Web Serial (Desktop) DTR = IO0, RTS = EN
    */
   async hardResetClassic() {
     await this.setDTR(false); // IO0=HIGH
@@ -755,6 +770,23 @@ export class ESPLoader extends EventTarget {
     await this.sleep(200);
   }
 
+  /**
+   * @name hardResetUnixTight
+   * Unix Tight reset for Web Serial (Desktop) - sets DTR and RTS simultaneously
+   */
+  async hardResetUnixTight() {
+    await this.setDTRandRTS(true, true);
+    await this.setDTRandRTS(false, false);
+    await this.setDTRandRTS(false, true); // IO0=HIGH & EN=LOW, chip in reset
+    await this.sleep(100);
+    await this.setDTRandRTS(true, false); // IO0=LOW & EN=HIGH, chip out of reset
+    await this.sleep(50);
+    await this.setDTRandRTS(false, false); // IO0=HIGH, done
+    await this.setDTR(false); // Needed in some environments to ensure IO0=HIGH
+
+    await this.sleep(200);
+  }
+
   // ============================================================================
   // WebUSB (Android) - DTR/RTS Signal Handling & Reset Strategies
   // ============================================================================
@@ -971,10 +1003,12 @@ export class ESPLoader extends EventTarget {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const self = this;
 
+    // Detect if this is a USB-Serial chip (needs different sync approach)
+    const isUSBSerialChip = !isUSBJTAGSerial && !isEspressifUSB;
+
     // WebUSB (Android) uses different reset methods than Web Serial (Desktop)
     if (this.isWebUSB()) {
       // For USB-Serial chips (CP2102, CH340, etc.), try inverted strategies first
-      const isUSBSerialChip = !isUSBJTAGSerial && !isEspressifUSB;
 
       // Detect specific chip types once
       const isCP2102 = portInfo.usbVendorId === 0x10c4;
@@ -993,7 +1027,7 @@ export class ESPLoader extends EventTarget {
           // Strategy 1: USB-JTAG/Serial (works in CDC mode on Desktop)
           resetStrategies.push({
             name: "USB-JTAG/Serial (WebUSB) - ESP32-S2",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetUSBJTAGSerialWebUSB();
             },
           });
@@ -1001,7 +1035,7 @@ export class ESPLoader extends EventTarget {
           // Strategy 2: USB-JTAG/Serial Inverted DTR (works in JTAG mode)
           resetStrategies.push({
             name: "USB-JTAG/Serial Inverted DTR (WebUSB) - ESP32-S2",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetUSBJTAGSerialInvertedDTRWebUSB();
             },
           });
@@ -1009,7 +1043,7 @@ export class ESPLoader extends EventTarget {
           // Strategy 3: UnixTight (CDC fallback)
           resetStrategies.push({
             name: "UnixTight (WebUSB) - ESP32-S2 CDC",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetUnixTightWebUSB();
             },
           });
@@ -1017,7 +1051,7 @@ export class ESPLoader extends EventTarget {
           // Strategy 4: Classic reset (CDC fallback)
           resetStrategies.push({
             name: "Classic (WebUSB) - ESP32-S2 CDC",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetClassicWebUSB();
             },
           });
@@ -1025,19 +1059,19 @@ export class ESPLoader extends EventTarget {
           // Other USB-JTAG chips: Try Inverted DTR first - works best for ESP32-H2 and other JTAG chips
           resetStrategies.push({
             name: "USB-JTAG/Serial Inverted DTR (WebUSB)",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetUSBJTAGSerialInvertedDTRWebUSB();
             },
           });
           resetStrategies.push({
             name: "USB-JTAG/Serial (WebUSB)",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetUSBJTAGSerialWebUSB();
             },
           });
           resetStrategies.push({
             name: "Inverted DTR Classic (WebUSB)",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetInvertedDTRWebUSB();
             },
           });
@@ -1050,31 +1084,31 @@ export class ESPLoader extends EventTarget {
           // CH340/CH343: UnixTight works best (like CP2102)
           resetStrategies.push({
             name: "UnixTight (WebUSB) - CH34x",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetUnixTightWebUSB();
             },
           });
           resetStrategies.push({
             name: "Classic (WebUSB) - CH34x",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetClassicWebUSB();
             },
           });
           resetStrategies.push({
             name: "Inverted Both (WebUSB) - CH34x",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetInvertedWebUSB();
             },
           });
           resetStrategies.push({
             name: "Inverted RTS (WebUSB) - CH34x",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetInvertedRTSWebUSB();
             },
           });
           resetStrategies.push({
             name: "Inverted DTR (WebUSB) - CH34x",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetInvertedDTRWebUSB();
             },
           });
@@ -1084,35 +1118,35 @@ export class ESPLoader extends EventTarget {
 
           resetStrategies.push({
             name: "UnixTight (WebUSB) - CP2102",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetUnixTightWebUSB();
             },
           });
 
           resetStrategies.push({
             name: "Classic (WebUSB) - CP2102",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetClassicWebUSB();
             },
           });
 
           resetStrategies.push({
             name: "Inverted Both (WebUSB) - CP2102",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetInvertedWebUSB();
             },
           });
 
           resetStrategies.push({
             name: "Inverted RTS (WebUSB) - CP2102",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetInvertedRTSWebUSB();
             },
           });
 
           resetStrategies.push({
             name: "Inverted DTR (WebUSB) - CP2102",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetInvertedDTRWebUSB();
             },
           });
@@ -1120,7 +1154,7 @@ export class ESPLoader extends EventTarget {
           // For other USB-Serial chips, try UnixTight first, then multiple strategies
           resetStrategies.push({
             name: "UnixTight (WebUSB)",
-            fn: async function () {
+            fn: async () => {
               return await self.hardResetUnixTightWebUSB();
             },
           });
@@ -1198,7 +1232,6 @@ export class ESPLoader extends EventTarget {
         }
       }
     } else {
-      // Web Serial (Desktop) strategies
       // Strategy: USB-JTAG/Serial reset
       if (isUSBJTAGSerial || isEspressifUSB) {
         resetStrategies.push({
@@ -1209,11 +1242,11 @@ export class ESPLoader extends EventTarget {
         });
       }
 
-      // Strategy: Classic reset
+      // Strategy: UnixTight reset
       resetStrategies.push({
-        name: "Classic",
+        name: "UnixTight",
         fn: async function () {
-          return await self.hardResetClassic();
+          return await self.hardResetUnixTight();
         },
       });
 
@@ -1244,17 +1277,44 @@ export class ESPLoader extends EventTarget {
 
         await strategy.fn();
 
-        // Try to sync after reset with internally time-bounded sync (3 seconds per strategy)
-        const syncSuccess = await this.syncWithTimeout(3000);
+        // Try to sync after reset
+        // USB-Serial / native USB chips needs different sync approaches
 
-        if (syncSuccess) {
-          // Sync succeeded
-          this.logger.log(
-            `Connected successfully with ${strategy.name} reset.`,
-          );
-          return;
+        if (isUSBSerialChip) {
+          // USB-Serial chips: Use timeout strategy (2 seconds)
+          //          this.logger.log(`USB-Serial chip detected, using sync with timeout.`);
+          const syncSuccess = await this.syncWithTimeout(2000);
+
+          if (syncSuccess) {
+            // Sync succeeded
+            this.logger.log(
+              `Connected USB Serial successfully with ${strategy.name} reset.`,
+            );
+            return;
+          } else {
+            throw new Error("Sync timeout or abandoned");
+          }
         } else {
-          throw new Error("Sync timeout or abandoned");
+          // Native USB chips
+          // Note: We use Promise.race with sync() directly instead of syncWithTimeout()
+          // because syncWithTimeout causes CDC/JTAG devices to hang for unknown reasons.
+          // The abandon flag in readPacket() prevents overlapping I/O.
+          //          this.logger.log(`Native USB chip detected, using CDC/JTAG sync.`);
+          const syncPromise = this.sync();
+          const timeoutPromise = new Promise<void>((_, reject) =>
+            setTimeout(() => reject(new Error("Sync timeout")), 1000),
+          );
+
+          try {
+            await Promise.race([syncPromise, timeoutPromise]);
+            // Sync succeeded
+            this.logger.log(
+              `Connected CDC/JTAG successfully with ${strategy.name} reset.`,
+            );
+            return;
+          } catch (error) {
+            throw new Error("Sync timeout or abandoned");
+          }
         }
       } catch (error) {
         lastError = error as Error;
@@ -1309,9 +1369,9 @@ export class ESPLoader extends EventTarget {
       // just reset (no bootloader mode)
       if (this.isWebUSB()) {
         // WebUSB: Use longer delays for better compatibility
-        await this.setRTS(true); // EN->LOW
+        await this.setRTSWebUSB(true); // EN->LOW
         await this.sleep(200);
-        await this.setRTS(false);
+        await this.setRTSWebUSB(false);
         await this.sleep(200);
         this.logger.log("Hard reset (WebUSB).");
       } else {
@@ -1560,7 +1620,6 @@ export class ESPLoader extends EventTarget {
               "Timed out waiting for packet " + waitingFor,
             );
           }
-
           const b = this._readByte()!;
 
           if (partialPacket === null) {
@@ -2676,7 +2735,21 @@ export class ESPLoader extends EventTarget {
         resolve(undefined);
         return;
       }
-      this.addEventListener("disconnect", resolve, { once: true });
+
+      // Set a timeout to prevent hanging (important for node-usb)
+      const timeout = setTimeout(() => {
+        this.logger.debug("Disconnect timeout - forcing resolution");
+        resolve(undefined);
+      }, 1000);
+
+      this.addEventListener(
+        "disconnect",
+        () => {
+          clearTimeout(timeout);
+          resolve(undefined);
+        },
+        { once: true },
+      );
 
       // Only cancel if reader is still active
       try {
@@ -2684,10 +2757,19 @@ export class ESPLoader extends EventTarget {
       } catch (err) {
         this.logger.debug(`Reader cancel error: ${err}`);
         // Reader already released, resolve immediately
+        clearTimeout(timeout);
         resolve(undefined);
       }
     });
     this.connected = false;
+
+    // Close the port (important for node-usb adapter)
+    try {
+      await this.port.close();
+      this.logger.debug("Port closed successfully");
+    } catch (err) {
+      this.logger.debug(`Port close error: ${err}`);
+    }
   }
 
   /**
@@ -3357,6 +3439,12 @@ class EspStubLoader extends ESPLoader {
     if (size > maxValue) {
       throw new Error(`Size ${size} exceeds maximum value ${maxValue}`);
     }
+    // Check for wrap-around
+    if (offset + size > maxValue) {
+      throw new Error(
+        `Region end (offset + size = ${offset + size}) exceeds maximum addressable range ${maxValue}`,
+      );
+    }
 
     const timeout = timeoutPerMb(ERASE_REGION_TIMEOUT_PER_MB, size);
     const buffer = pack("<II", offset, size);

package/src/index.ts

@@ -21,39 +21,68 @@ export {
   CHIP_FAMILY_ESP32H21,
   CHIP_FAMILY_ESP32P4,
   CHIP_FAMILY_ESP32S31,
+  // Command constants
+  ESP_FLASH_BEGIN,
+  ESP_FLASH_DATA,
+  ESP_FLASH_END,
+  ESP_MEM_BEGIN,
+  ESP_MEM_END,
+  ESP_MEM_DATA,
+  ESP_SYNC,
+  ESP_WRITE_REG,
+  ESP_READ_REG,
+  ESP_ERASE_FLASH,
+  ESP_ERASE_REGION,
+  ESP_READ_FLASH,
+  ESP_SPI_SET_PARAMS,
+  ESP_SPI_ATTACH,
+  ESP_CHANGE_BAUDRATE,
+  ESP_SPI_FLASH_MD5,
+  ESP_GET_SECURITY_INFO,
+  ESP_CHECKSUM_MAGIC,
+  ESP_FLASH_DEFL_BEGIN,
+  ESP_FLASH_DEFL_DATA,
+  ESP_FLASH_DEFL_END,
+  ROM_INVALID_RECV_MSG,
+  // Block size constants
+  USB_RAM_BLOCK,
+  ESP_RAM_BLOCK,
+  // Timeout constants
+  DEFAULT_TIMEOUT,
+  CHIP_ERASE_TIMEOUT,
+  MAX_TIMEOUT,
+  SYNC_TIMEOUT,
+  ERASE_REGION_TIMEOUT_PER_MB,
+  MEM_END_ROM_TIMEOUT,
+  FLASH_READ_TIMEOUT,
 } from "./const";
 
 export const connect = async (logger: Logger) => {
+  // - Request a port and open a connection.
+  // Try to use requestSerialPort if available (supports WebUSB for Android)
   let port: SerialPort;
-
-  // Check if a custom requestSerialPort function is available (e.g., from WebUSB wrapper)
   const customRequestPort = (
     globalThis as { requestSerialPort?: () => Promise<SerialPort> }
   ).requestSerialPort;
-
   if (typeof customRequestPort === "function") {
-    // Use custom port request function (handles Android/WebUSB automatically)
-    logger.log("Using custom port request function");
     port = await customRequestPort();
   } else {
-    // Fallback to standard Web Serial API
+    // Check if Web Serial API is available
     if (!navigator.serial) {
       throw new Error(
         "Web Serial API is not supported in this browser. " +
-          "Please use Chrome 89+, Edge 89+, or Opera on desktop, or Chrome 61+ on Android with USB OTG. " +
+          "Please use Chrome, Edge, or Opera on desktop, or Chrome on Android. " +
           "Note: The page must be served over HTTPS or localhost.",
       );
     }
     port = await navigator.serial.requestPort();
   }
 
-  // Only open if not already open (WebUSB may return an opened port)
+  // Only open if not already open (requestSerialPort may return an opened port)
   if (!port.readable || !port.writable) {
     await port.open({ baudRate: ESP_ROM_BAUD });
   }
 
-  logger.log("Connected successfully.");
-
   return new ESPLoader(port, logger);
 };
 
@@ -63,12 +92,10 @@ export const connectWithPort = async (port: SerialPort, logger: Logger) => {
     throw new Error("Port is required");
   }
 
-  // Only open if not already open
+  // Check if port is already open, if not open it
   if (!port.readable || !port.writable) {
     await port.open({ baudRate: ESP_ROM_BAUD });
   }
 
-  logger.log("Connected successfully.");
-
   return new ESPLoader(port, logger);
 };