tasmota-webserial-esptool 7.2.6 → 7.3.1

package/src/esp_loader.ts

@@ -85,6 +85,8 @@ export class ESPLoader extends EventTarget {
   private _reader?: ReadableStreamDefaultReader<Uint8Array>;
   private _isESP32S2NativeUSB: boolean = false;
   private _initializationSucceeded: boolean = false;
+  private __commandLock: Promise<[number, number[]]> = Promise.resolve([0, []]);
+  private _isReconfiguring: boolean = false;
 
   constructor(
     public port: SerialPort,
@@ -112,6 +114,18 @@ export class ESPLoader extends EventTarget {
     }
   }
 
+  private get _commandLock(): Promise<[number, number[]]> {
+    return this._parent ? this._parent._commandLock : this.__commandLock;
+  }
+
+  private set _commandLock(value: Promise<[number, number[]]>) {
+    if (this._parent) {
+      this._parent._commandLock = value;
+    } else {
+      this.__commandLock = value;
+    }
+  }
+
   private detectUSBSerialChip(
     vendorId: number,
     productId: number,
@@ -549,6 +563,9 @@ export class ESPLoader extends EventTarget {
    * Send a command packet, check that the command succeeded and
    * return a tuple with the value and data.
    * See the ESP Serial Protocol for more details on what value/data are
+   *
+   * Commands are serialized to prevent concurrent execution which can cause
+   * WritableStream lock contention on CP210x adapters under Windows
    */
   async checkCommand(
     opcode: number,
@@ -556,69 +573,77 @@ export class ESPLoader extends EventTarget {
     checksum = 0,
     timeout = DEFAULT_TIMEOUT,
   ): Promise<[number, number[]]> {
-    timeout = Math.min(timeout, MAX_TIMEOUT);
-    await this.sendCommand(opcode, buffer, checksum);
-    const [value, responseData] = await this.getResponse(opcode, timeout);
-
-    if (responseData === null) {
-      throw new Error("Didn't get enough status bytes");
-    }
-
-    let data = responseData;
-    let statusLen = 0;
+    // Serialize command execution to prevent lock contention
+    const executeCommand = async (): Promise<[number, number[]]> => {
+      timeout = Math.min(timeout, MAX_TIMEOUT);
+      await this.sendCommand(opcode, buffer, checksum);
+      const [value, responseData] = await this.getResponse(opcode, timeout);
+
+      if (responseData === null) {
+        throw new Error("Didn't get enough status bytes");
+      }
 
-    if (this.IS_STUB || this.chipFamily == CHIP_FAMILY_ESP8266) {
-      statusLen = 2;
-    } else if (
-      [
-        CHIP_FAMILY_ESP32,
-        CHIP_FAMILY_ESP32S2,
-        CHIP_FAMILY_ESP32S3,
-        CHIP_FAMILY_ESP32C2,
-        CHIP_FAMILY_ESP32C3,
-        CHIP_FAMILY_ESP32C5,
-        CHIP_FAMILY_ESP32C6,
-        CHIP_FAMILY_ESP32C61,
-        CHIP_FAMILY_ESP32H2,
-        CHIP_FAMILY_ESP32H4,
-        CHIP_FAMILY_ESP32H21,
-        CHIP_FAMILY_ESP32P4,
-        CHIP_FAMILY_ESP32S31,
-      ].includes(this.chipFamily)
-    ) {
-      statusLen = 4;
-    } else {
-      // When chipFamily is not yet set (e.g., during GET_SECURITY_INFO in detectChip),
-      // assume modern chips use 4-byte status
-      if (opcode === ESP_GET_SECURITY_INFO) {
+      let data = responseData;
+      let statusLen = 0;
+
+      if (this.IS_STUB || this.chipFamily == CHIP_FAMILY_ESP8266) {
+        statusLen = 2;
+      } else if (
+        [
+          CHIP_FAMILY_ESP32,
+          CHIP_FAMILY_ESP32S2,
+          CHIP_FAMILY_ESP32S3,
+          CHIP_FAMILY_ESP32C2,
+          CHIP_FAMILY_ESP32C3,
+          CHIP_FAMILY_ESP32C5,
+          CHIP_FAMILY_ESP32C6,
+          CHIP_FAMILY_ESP32C61,
+          CHIP_FAMILY_ESP32H2,
+          CHIP_FAMILY_ESP32H4,
+          CHIP_FAMILY_ESP32H21,
+          CHIP_FAMILY_ESP32P4,
+          CHIP_FAMILY_ESP32S31,
+        ].includes(this.chipFamily)
+      ) {
         statusLen = 4;
-      } else if ([2, 4].includes(data.length)) {
-        statusLen = data.length;
+      } else {
+        // When chipFamily is not yet set (e.g., during GET_SECURITY_INFO in detectChip),
+        // assume modern chips use 4-byte status
+        if (opcode === ESP_GET_SECURITY_INFO) {
+          statusLen = 4;
+        } else if ([2, 4].includes(data.length)) {
+          statusLen = data.length;
+        }
       }
-    }
 
-    if (data.length < statusLen) {
-      throw new Error("Didn't get enough status bytes");
-    }
-    const status = data.slice(-statusLen, data.length);
-    data = data.slice(0, -statusLen);
-    if (this.debug) {
-      this.logger.debug("status", status);
-      this.logger.debug("value", value);
-      this.logger.debug("data", data);
-    }
-    if (status[0] == 1) {
-      if (status[1] == ROM_INVALID_RECV_MSG) {
-        // Unsupported command can result in more than one error response
-        // Use drainInputBuffer for CP210x compatibility on Windows
-        await this.drainInputBuffer(200);
-        throw new Error("Invalid (unsupported) command " + toHex(opcode));
-      } else {
-        throw new Error("Command failure error code " + toHex(status[1]));
+      if (data.length < statusLen) {
+        throw new Error("Didn't get enough status bytes");
+      }
+      const status = data.slice(-statusLen, data.length);
+      data = data.slice(0, -statusLen);
+      if (this.debug) {
+        this.logger.debug("status", status);
+        this.logger.debug("value", value);
+        this.logger.debug("data", data);
+      }
+      if (status[0] == 1) {
+        if (status[1] == ROM_INVALID_RECV_MSG) {
+          // Unsupported command can result in more than one error response
+          // Use drainInputBuffer for CP210x compatibility on Windows
+          await this.drainInputBuffer(200);
+          throw new Error("Invalid (unsupported) command " + toHex(opcode));
+        } else {
+          throw new Error("Command failure error code " + toHex(status[1]));
+        }
       }
-    }
 
-    return [value, data];
+      return [value, data];
+    };
+
+    // Chain command execution through the lock
+    // Use both .then() handlers to ensure lock continues even on error
+    this._commandLock = this._commandLock.then(executeCommand, executeCommand);
+    return this._commandLock;
   }
 
   /**
@@ -649,37 +674,34 @@ export class ESPLoader extends EventTarget {
   async readPacket(timeout: number): Promise<number[]> {
     let partialPacket: number[] | null = null;
     let inEscape = false;
-    let readBytes: number[] = [];
+
+    const startTime = Date.now();
+
     while (true) {
-      const stamp = Date.now();
-      readBytes = [];
-      while (Date.now() - stamp < timeout) {
-        if (this._inputBuffer.length > 0) {
-          readBytes.push(this._inputBuffer.shift()!);
-          break;
-        } else {
-          // Reduced sleep time for faster response during high-speed transfers
-          await sleep(1);
-        }
-      }
-      if (readBytes.length == 0) {
+      // Check timeout
+      if (Date.now() - startTime > timeout) {
         const waitingFor = partialPacket === null ? "header" : "content";
         throw new SlipReadError("Timed out waiting for packet " + waitingFor);
       }
-      if (this.debug)
-        this.logger.debug(
-          "Read " + readBytes.length + " bytes: " + hexFormatter(readBytes),
-        );
-      for (const b of readBytes) {
+
+      // If no data available, wait a bit
+      if (this._inputBuffer.length === 0) {
+        await sleep(1);
+        continue;
+      }
+
+      // Process all available bytes without going back to outer loop
+      // This is critical for handling high-speed burst transfers
+      while (this._inputBuffer.length > 0) {
+        const b = this._inputBuffer.shift()!;
+
         if (partialPacket === null) {
           // waiting for packet header
           if (b == 0xc0) {
             partialPacket = [];
           } else {
             if (this.debug) {
-              this.logger.debug(
-                "Read invalid data: " + hexFormatter(readBytes),
-              );
+              this.logger.debug("Read invalid data: " + toHex(b));
               this.logger.debug(
                 "Remaining data in serial buffer: " +
                   hexFormatter(this._inputBuffer),
@@ -698,9 +720,7 @@ export class ESPLoader extends EventTarget {
             partialPacket.push(0xdb);
           } else {
             if (this.debug) {
-              this.logger.debug(
-                "Read invalid data: " + hexFormatter(readBytes),
-              );
+              this.logger.debug("Read invalid data: " + toHex(b));
               this.logger.debug(
                 "Remaining data in serial buffer: " +
                   hexFormatter(this._inputBuffer),
@@ -726,7 +746,6 @@ export class ESPLoader extends EventTarget {
         }
       }
     }
-    throw new SlipReadError("Invalid state");
   }
 
   /**
@@ -825,6 +844,25 @@ export class ESPLoader extends EventTarget {
 
   async reconfigurePort(baud: number) {
     try {
+      this._isReconfiguring = true;
+
+      // Wait for pending writes to complete
+      try {
+        await this._writeChain;
+      } catch (err) {
+        this.logger.debug(`Pending write error during reconfigure: ${err}`);
+      }
+
+      // Release persistent writer before closing
+      if (this._writer) {
+        try {
+          this._writer.releaseLock();
+        } catch (err) {
+          this.logger.debug(`Writer release error during reconfigure: ${err}`);
+        }
+        this._writer = undefined;
+      }
+
       // SerialPort does not allow to be reconfigured while open so we close and re-open
       // reader.cancel() causes the Promise returned by the read() operation running on
       // the readLoop to return immediately with { value: undefined, done: true } and thus
@@ -843,6 +881,8 @@ export class ESPLoader extends EventTarget {
     } catch (e) {
       this.logger.error(`Reconfigure port error: ${e}`);
       throw new Error(`Unable to change the baud rate to ${baud}: ${e}`);
+    } finally {
+      this._isReconfiguring = false;
     }
   }
 
@@ -1589,18 +1629,98 @@ export class ESPLoader extends EventTarget {
     return espStubLoader;
   }
 
+  __writer?: WritableStreamDefaultWriter<Uint8Array>;
+  __writeChain: Promise<void> = Promise.resolve();
+
+  private get _writer(): WritableStreamDefaultWriter<Uint8Array> | undefined {
+    return this._parent ? this._parent._writer : this.__writer;
+  }
+
+  private set _writer(
+    value: WritableStreamDefaultWriter<Uint8Array> | undefined,
+  ) {
+    if (this._parent) {
+      this._parent._writer = value;
+    } else {
+      this.__writer = value;
+    }
+  }
+
+  private get _writeChain(): Promise<void> {
+    return this._parent ? this._parent._writeChain : this.__writeChain;
+  }
+
+  private set _writeChain(value: Promise<void>) {
+    if (this._parent) {
+      this._parent._writeChain = value;
+    } else {
+      this.__writeChain = value;
+    }
+  }
+
   async writeToStream(data: number[]) {
     if (!this.port.writable) {
       this.logger.debug("Port writable stream not available, skipping write");
       return;
     }
-    const writer = this.port.writable.getWriter();
-    await writer.write(new Uint8Array(data));
-    try {
-      writer.releaseLock();
-    } catch (err) {
-      this.logger.error(`Ignoring release lock error: ${err}`);
+
+    if (this._isReconfiguring) {
+      throw new Error("Cannot write during port reconfiguration");
     }
+
+    // Queue writes to prevent lock contention (critical for CP2102 on Windows)
+    this._writeChain = this._writeChain
+      .then(
+        async () => {
+          // Check if port is still writable before attempting write
+          if (!this.port.writable) {
+            throw new Error("Port became unavailable during write");
+          }
+
+          // Get or create persistent writer
+          if (!this._writer) {
+            try {
+              this._writer = this.port.writable.getWriter();
+            } catch (err) {
+              this.logger.error(`Failed to get writer: ${err}`);
+              throw err;
+            }
+          }
+
+          // Perform the write
+          await this._writer.write(new Uint8Array(data));
+        },
+        async () => {
+          // Previous write failed, but still attempt this write
+          if (!this.port.writable) {
+            throw new Error("Port became unavailable during write");
+          }
+
+          // Writer was likely cleaned up by previous error, create new one
+          if (!this._writer) {
+            this._writer = this.port.writable.getWriter();
+          }
+
+          await this._writer.write(new Uint8Array(data));
+        },
+      )
+      .catch((err) => {
+        this.logger.error(`Write error: ${err}`);
+        // Ensure writer is cleaned up on any error
+        if (this._writer) {
+          try {
+            this._writer.releaseLock();
+          } catch (e) {
+            // Ignore release errors
+          }
+          this._writer = undefined;
+        }
+        // Re-throw to propagate error
+        throw err;
+      });
+
+    // Always await the write chain to ensure errors are caught
+    await this._writeChain;
   }
 
   async disconnect() {
@@ -1612,15 +1732,49 @@ export class ESPLoader extends EventTarget {
       this.logger.debug("Port already closed, skipping disconnect");
       return;
     }
-    await this.port.writable.getWriter().close();
-    await new Promise((resolve) => {
-      if (!this._reader) {
-        resolve(undefined);
+
+    try {
+      this._isReconfiguring = true;
+
+      // Wait for pending writes to complete
+      try {
+        await this._writeChain;
+      } catch (err) {
+        this.logger.debug(`Pending write error during disconnect: ${err}`);
       }
-      this.addEventListener("disconnect", resolve, { once: true });
-      this._reader!.cancel();
-    });
-    this.connected = false;
+
+      // Release persistent writer before closing
+      if (this._writer) {
+        try {
+          await this._writer.close();
+          this._writer.releaseLock();
+        } catch (err) {
+          this.logger.debug(`Writer close/release error: ${err}`);
+        }
+        this._writer = undefined;
+      } else {
+        // No persistent writer exists, close stream directly
+        // This path is taken when no writes have been queued
+        try {
+          const writer = this.port.writable.getWriter();
+          await writer.close();
+          writer.releaseLock();
+        } catch (err) {
+          this.logger.debug(`Direct writer close error: ${err}`);
+        }
+      }
+
+      await new Promise((resolve) => {
+        if (!this._reader) {
+          resolve(undefined);
+        }
+        this.addEventListener("disconnect", resolve, { once: true });
+        this._reader!.cancel();
+      });
+      this.connected = false;
+    } finally {
+      this._isReconfiguring = false;
+    }
   }
 
   /**
@@ -1633,99 +1787,122 @@ export class ESPLoader extends EventTarget {
       return;
     }
 
-    this.logger.log("Reconnecting serial port...");
+    try {
+      this._isReconfiguring = true;
+
+      this.logger.log("Reconnecting serial port...");
 
-    this.connected = false;
-    this.__inputBuffer = [];
+      this.connected = false;
+      this.__inputBuffer = [];
 
-    // Cancel reader
-    if (this._reader) {
+      // Wait for pending writes to complete
       try {
-        await this._reader.cancel();
+        await this._writeChain;
       } catch (err) {
-        this.logger.debug(`Reader cancel error: ${err}`);
+        this.logger.debug(`Pending write error during reconnect: ${err}`);
       }
-      this._reader = undefined;
-    }
-
-    // Close port
-    try {
-      await this.port.close();
-      this.logger.log("Port closed");
-    } catch (err) {
-      this.logger.debug(`Port close error: ${err}`);
-    }
 
-    // Open the port
-    this.logger.debug("Opening port...");
-    try {
-      await this.port.open({ baudRate: ESP_ROM_BAUD });
-      this.connected = true;
-    } catch (err) {
-      throw new Error(`Failed to open port: ${err}`);
-    }
+      // Release persistent writer
+      if (this._writer) {
+        try {
+          this._writer.releaseLock();
+        } catch (err) {
+          this.logger.debug(`Writer release error during reconnect: ${err}`);
+        }
+        this._writer = undefined;
+      }
 
-    // Verify port streams are available
-    if (!this.port.readable || !this.port.writable) {
-      throw new Error(
-        `Port streams not available after open (readable: ${!!this.port.readable}, writable: ${!!this.port.writable})`,
-      );
-    }
+      // Cancel reader
+      if (this._reader) {
+        try {
+          await this._reader.cancel();
+        } catch (err) {
+          this.logger.debug(`Reader cancel error: ${err}`);
+        }
+        this._reader = undefined;
+      }
 
-    // Save chip info and flash size (no need to detect again)
-    const savedChipFamily = this.chipFamily;
-    const savedChipName = this.chipName;
-    const savedChipRevision = this.chipRevision;
-    const savedChipVariant = this.chipVariant;
-    const savedFlashSize = this.flashSize;
+      // Close port
+      try {
+        await this.port.close();
+        this.logger.log("Port closed");
+      } catch (err) {
+        this.logger.debug(`Port close error: ${err}`);
+      }
 
-    // Reinitialize
-    await this.hardReset(true);
+      // Open the port
+      this.logger.debug("Opening port...");
+      try {
+        await this.port.open({ baudRate: ESP_ROM_BAUD });
+        this.connected = true;
+      } catch (err) {
+        throw new Error(`Failed to open port: ${err}`);
+      }
 
-    if (!this._parent) {
-      this.__inputBuffer = [];
-      this.__totalBytesRead = 0;
-      this.readLoop();
-    }
+      // Verify port streams are available
+      if (!this.port.readable || !this.port.writable) {
+        throw new Error(
+          `Port streams not available after open (readable: ${!!this.port.readable}, writable: ${!!this.port.writable})`,
+        );
+      }
 
-    await this.flushSerialBuffers();
-    await this.sync();
+      // Save chip info and flash size (no need to detect again)
+      const savedChipFamily = this.chipFamily;
+      const savedChipName = this.chipName;
+      const savedChipRevision = this.chipRevision;
+      const savedChipVariant = this.chipVariant;
+      const savedFlashSize = this.flashSize;
 
-    // Restore chip info
-    this.chipFamily = savedChipFamily;
-    this.chipName = savedChipName;
-    this.chipRevision = savedChipRevision;
-    this.chipVariant = savedChipVariant;
-    this.flashSize = savedFlashSize;
+      // Reinitialize
+      await this.hardReset(true);
 
-    this.logger.debug(`Reconnect complete (chip: ${this.chipName})`);
+      if (!this._parent) {
+        this.__inputBuffer = [];
+        this.__totalBytesRead = 0;
+        this.readLoop();
+      }
 
-    // Verify port is ready
-    if (!this.port.writable || !this.port.readable) {
-      throw new Error("Port not ready after reconnect");
-    }
+      await this.flushSerialBuffers();
+      await this.sync();
 
-    // Load stub
-    const stubLoader = await this.runStub(true);
-    this.logger.debug("Stub loaded");
+      // Restore chip info
+      this.chipFamily = savedChipFamily;
+      this.chipName = savedChipName;
+      this.chipRevision = savedChipRevision;
+      this.chipVariant = savedChipVariant;
+      this.flashSize = savedFlashSize;
 
-    // Restore baudrate if it was changed
-    if (this._currentBaudRate !== ESP_ROM_BAUD) {
-      await stubLoader.setBaudrate(this._currentBaudRate);
+      this.logger.debug(`Reconnect complete (chip: ${this.chipName})`);
 
-      // Verify port is still ready after baudrate change
+      // Verify port is ready
       if (!this.port.writable || !this.port.readable) {
-        throw new Error(
-          `Port not ready after baudrate change (readable: ${!!this.port.readable}, writable: ${!!this.port.writable})`,
-        );
+        throw new Error("Port not ready after reconnect");
       }
-    }
 
-    // Copy stub state to this instance if we're a stub loader
-    if (this.IS_STUB) {
-      Object.assign(this, stubLoader);
+      // Load stub
+      const stubLoader = await this.runStub(true);
+      this.logger.debug("Stub loaded");
+
+      // Restore baudrate if it was changed
+      if (this._currentBaudRate !== ESP_ROM_BAUD) {
+        await stubLoader.setBaudrate(this._currentBaudRate);
+
+        // Verify port is still ready after baudrate change
+        if (!this.port.writable || !this.port.readable) {
+          throw new Error(
+            `Port not ready after baudrate change (readable: ${!!this.port.readable}, writable: ${!!this.port.writable})`,
+          );
+        }
+      }
+
+      // Copy stub state to this instance if we're a stub loader
+      if (this.IS_STUB) {
+        Object.assign(this, stubLoader);
+      }
+      this.logger.debug("Reconnection successful");
+    } finally {
+      this._isReconfiguring = false;
     }
-    this.logger.debug("Reconnection successful");
   }
 
   /**
@@ -1837,18 +2014,22 @@ export class ESPLoader extends EventTarget {
       const chunkSize = Math.min(CHUNK_SIZE, remainingSize);
       let chunkSuccess = false;
       let retryCount = 0;
-      const MAX_RETRIES = 5;
+      const MAX_RETRIES = 15;
 
       // Retry loop for this chunk
       while (!chunkSuccess && retryCount <= MAX_RETRIES) {
         let resp = new Uint8Array(0);
 
         try {
-          this.logger.debug(
-            `Reading chunk at 0x${currentAddr.toString(16)}, size: 0x${chunkSize.toString(16)}`,
-          );
+          // Only log on first attempt or retries
+          if (retryCount === 0) {
+            this.logger.debug(
+              `Reading chunk at 0x${currentAddr.toString(16)}, size: 0x${chunkSize.toString(16)}`,
+            );
+          }
 
           // Send read flash command for this chunk
+          // This must be inside the retry loop so we send a fresh command after errors
           const pkt = pack("<IIII", currentAddr, chunkSize, 0x1000, 1024);
           const [res] = await this.checkCommand(ESP_READ_FLASH, pkt);
 
@@ -1867,20 +2048,22 @@ export class ESPLoader extends EventTarget {
                   `SLIP read error at ${resp.length} bytes: ${err.message}`,
                 );
 
-                // Send final ACK for any data we did receive before the error
-                if (resp.length > 0) {
-                  try {
-                    const ackData = pack("<I", resp.length);
-                    const slipEncodedAck = slipEncode(ackData);
-                    await this.writeToStream(slipEncodedAck);
-                  } catch (ackErr) {
-                    this.logger.debug(`ACK send error: ${ackErr}`);
-                  }
+                // Send empty SLIP frame to abort the stub's read operation
+                // 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
+                  await this.writeToStream(abortFrame);
+                  this.logger.debug(`Sent abort frame to stub`);
+
+                  // Give stub time to process abort
+                  await sleep(50);
+                } catch (abortErr) {
+                  this.logger.debug(`Abort frame error: ${abortErr}`);
                 }
 
-                // Drain input buffer for CP210x compatibility on Windows
-                // This clears any stale data that may be causing the error
-                await this.drainInputBuffer(300);
+                // Drain input buffer to clear any stale data
+                await this.drainInputBuffer(200);
 
                 // If we've read all the data we need, break
                 if (resp.length >= chunkSize) {
@@ -1920,11 +2103,11 @@ export class ESPLoader extends EventTarget {
           if (err instanceof SlipReadError) {
             if (retryCount <= MAX_RETRIES) {
               this.logger.log(
-                `⚠️  ${err.message} at 0x${currentAddr.toString(16)}. Draining buffer and retrying (attempt ${retryCount}/${MAX_RETRIES})...`,
+                `${err.message} at 0x${currentAddr.toString(16)}. Draining buffer and retrying (attempt ${retryCount}/${MAX_RETRIES})...`,
               );
 
               try {
-                await this.drainInputBuffer(300);
+                await this.drainInputBuffer(200);
 
                 // Clear application buffer
                 await this.flushSerialBuffers();
@@ -1932,7 +2115,7 @@ export class ESPLoader extends EventTarget {
                 // Wait before retry to let hardware settle
                 await sleep(SYNC_TIMEOUT);
 
-                // Continue to retry the same chunk (will send new read command)
+                // Continue to retry the same chunk (will send NEW read command)
               } catch (drainErr) {
                 this.logger.debug(`Buffer drain error: ${drainErr}`);
               }