tasmota-webserial-esptool 7.2.4 → 7.2.6

package/README.md

@@ -1,21 +1,40 @@
-# WebSerial ESPTool
 
-JavaScript package to install and make backups of firmwares on ESP devices via the browser using WebSerial.
+# 🚀 WebSerial ESPTool – Flash. Backup. Enjoy.
 
-WebSerial ESPTool is **not** based on esptool.js
+**The next-generation solution for ESP firmware – right in your browser!**
 
+WebSerial ESPTool brings you hassle-free firmware flashing and backup for your ESP devices, directly from your browser. No drivers, no command line, no headaches. Just plug in your ESP, open your browser, and experience seamless, lightning-fast firmware management.
 
-## Local development
+---
 
-- Clone this repository.
-- Install dependencies with `npm install`
-- Run `script/develop`
-- Open http://localhost:5004/
+✨ **Why choose WebSerial ESPTool?**
 
-## Origin
+- **Plug & Play:** Install and back up firmware straight from your browser – no software installation required!
+- **Cutting-Edge Compatibility:** Supports the latest ESP MCUs and chip variants (including P4 revisions).
+- **Blazing Fast & Reliable:** Optimized flashing and reading for maximum performance.
+- **Truly Independent:** Not a clone of esptool.js – 100% original, innovative codebase!
 
-This project was originally written by [Melissa LeBlanc-Williams](https://github.com/makermelissa). [Nabu Casa](https://www.nabucasa.com) ported the code over to TypeScript and in March 2022 took over maintenance from Adafruit. In July 2022, the Nabucasa stopped maintaining the project in favor of an official, but very early release of Espressif's [esptool-js](https://github.com/espressif/esptool-js/). Due to the instability of the tool, Adafruit updated their fork with Nabucasa's changes in November 2022 and took over maintenance once again. In December 2024, the tool was once again updated to use Espressif's esptool-js as the backend.
-Since Adafruit is slow in adding new MCUs (support for C2, C6 and H2 is from this fork) and uses now esptool.js which is still buggy, i decided to maintain my own version and do not provide PRs upstream anymore.
-In 12/2025 support for new MCUs and chip variant support for the different P4 revisions and flash read was added.
+> **Did you know?**
+> - The [ESP32 Swiss Army Knife](https://github.com/Jason2866/esp32tool) is based on this project and available [online](https://jason2866.github.io/esp32tool/).
+> - [ESPConnect](https://github.com/thelastoutpostworkshop/ESPConnect) also uses WebSerial ESPTool under the hood.
 
-Copyright: Adafruit, Nabu Casa and Johann Obermeier
+---
+
+## 🛠️ Quick Start for Developers
+
+1. Clone this repository
+2. Install dependencies: `npm install`
+3. Start the dev environment: `script/develop`
+4. Open [http://localhost:5004/](http://localhost:5004/) in your browser
+
+---
+
+## 🏆 The Story
+
+Originally created by [Melissa LeBlanc-Williams](https://github.com/makermelissa), further developed by [Nabu Casa](https://www.nabucasa.com) and Adafruit, and now with new features.
+
+**Latest update:** December 2025 – now with support for new MCUs, chip variants (P4), and ultra-fast flash reading!
+
+---
+
+© Adafruit, Nabu Casa & Johann Obermeier

package/css/style.css

@@ -275,7 +275,7 @@ div.clear {
 .onoffswitch {
   display: inline-block;
   position: relative;
-  width: 50px;
+  width: 70px;
   margin-right: 5px;
   -webkit-user-select: none;
   -moz-user-select: none;

package/dist/esp_loader.d.ts

@@ -93,6 +93,22 @@ export declare class ESPLoader extends EventTarget {
     checksum(data: number[], state?: number): number;
     setBaudrate(baud: number): Promise<void>;
     reconfigurePort(baud: number): Promise<void>;
+    /**
+     * @name connectWithResetStrategies
+     * Try different reset strategies to enter bootloader mode
+     * Similar to esptool.py's connect() method with multiple reset strategies
+     */
+    connectWithResetStrategies(): Promise<void>;
+    /**
+     * @name hardResetUSBJTAGSerial
+     * USB-JTAG/Serial reset sequence for ESP32-C3, ESP32-S3, ESP32-C6, etc.
+     */
+    hardResetUSBJTAGSerial(): Promise<void>;
+    /**
+     * @name hardResetClassic
+     * Classic reset sequence for USB-to-Serial bridge chips (CH340, CP2102, etc.)
+     */
+    hardResetClassic(): Promise<void>;
     /**
      * @name sync
      * Put into ROM bootload mode & attempt to synchronize with the
@@ -189,13 +205,13 @@ export declare class ESPLoader extends EventTarget {
      *
      * @param bufferingTime - Time in milliseconds to wait for the buffer to fill
      */
-    private drainInputBuffer;
+    drainInputBuffer(bufferingTime?: number): Promise<void>;
     /**
      * @name flushSerialBuffers
      * Flush any pending data in the TX and RX serial port buffers
      * This clears both the application RX buffer and waits for hardware buffers to drain
      */
-    private flushSerialBuffers;
+    flushSerialBuffers(): Promise<void>;
     /**
      * @name readFlash
      * Read flash memory from the chip (only works with stub loader)

package/dist/esp_loader.js

@@ -86,7 +86,6 @@ export class ESPLoader extends EventTarget {
         };
     }
     async initialize() {
-        await this.hardReset(true);
         if (!this._parent) {
             this.__inputBuffer = [];
             this.__totalBytesRead = 0;
@@ -107,9 +106,8 @@ export class ESPLoader extends EventTarget {
             // Don't await this promise so it doesn't block rest of method.
             this.readLoop();
         }
-        // Clear buffer again after starting read loop
-        await this.flushSerialBuffers();
-        await this.sync();
+        // Try to connect with different reset strategies
+        await this.connectWithResetStrategies();
         // Detect chip type
         await this.detectChip();
         // Read the OTP data for this chip and store into this.efuses array
@@ -156,6 +154,9 @@ export class ESPLoader extends EventTarget {
         catch (error) {
             // GET_SECURITY_INFO not supported, fall back to magic value detection
             this.logger.debug(`GET_SECURITY_INFO failed, using magic value detection: ${error}`);
+            // Drain input buffer for CP210x compatibility on Windows
+            // This ensures all error responses are cleared before continuing
+            await this.drainInputBuffer(200);
             // Clear input buffer and re-sync to recover from failed command
             this._inputBuffer.length = 0;
             await sleep(SYNC_TIMEOUT);
@@ -298,35 +299,12 @@ export class ESPLoader extends EventTarget {
         if (bootloader) {
             // enter flash mode
             if (this.port.getInfo().usbProductId === USB_JTAG_SERIAL_PID) {
-                // esp32c3 esp32s3 etc. build-in USB serial.
-                // when connect to computer direct via usb, using following signals
-                // to enter flash mode automatically.
-                await this.setDTR(false);
-                await this.setRTS(false);
-                await this.sleep(100);
-                await this.setDTR(true);
-                await this.setRTS(false);
-                await this.sleep(100);
-                await this.setRTS(true);
-                await this.setDTR(false);
-                await this.setRTS(true);
-                await this.sleep(100);
-                await this.setDTR(false);
-                await this.setRTS(false);
-                this.logger.log("USB MCU reset.");
+                await this.hardResetUSBJTAGSerial();
+                this.logger.log("USB-JTAG/Serial reset.");
             }
             else {
-                // otherwise, esp chip should be connected to computer via usb-serial
-                // bridge chip like ch340,CP2102 etc.
-                // use normal way to enter flash mode.
-                await this.setDTR(false);
-                await this.setRTS(true);
-                await this.sleep(100);
-                await this.setDTR(true);
-                await this.setRTS(false);
-                await this.sleep(50);
-                await this.setDTR(false);
-                this.logger.log("DTR/RTS USB serial chip reset.");
+                await this.hardResetClassic();
+                this.logger.log("Classic reset.");
             }
         }
         else {
@@ -670,6 +648,108 @@ export class ESPLoader extends EventTarget {
             throw new Error(`Unable to change the baud rate to ${baud}: ${e}`);
         }
     }
+    /**
+     * @name connectWithResetStrategies
+     * Try different reset strategies to enter bootloader mode
+     * Similar to esptool.py's connect() method with multiple reset strategies
+     */
+    async connectWithResetStrategies() {
+        var _a, _b;
+        const portInfo = this.port.getInfo();
+        const isUSBJTAGSerial = portInfo.usbProductId === USB_JTAG_SERIAL_PID;
+        const isEspressifUSB = portInfo.usbVendorId === 0x303a;
+        this.logger.log(`Detected USB: VID=0x${((_a = portInfo.usbVendorId) === null || _a === void 0 ? void 0 : _a.toString(16)) || "unknown"}, PID=0x${((_b = portInfo.usbProductId) === null || _b === void 0 ? void 0 : _b.toString(16)) || "unknown"}`);
+        // Define reset strategies to try in order
+        const resetStrategies = [];
+        // Strategy 1: USB-JTAG/Serial reset (for ESP32-C3, C6, S3, etc.)
+        // Try this first if we detect Espressif USB VID or the specific PID
+        if (isUSBJTAGSerial || isEspressifUSB) {
+            resetStrategies.push({
+                name: "USB-JTAG/Serial",
+                fn: async () => await this.hardResetUSBJTAGSerial(),
+            });
+        }
+        // Strategy 2: Classic reset (for USB-to-Serial bridges)
+        resetStrategies.push({
+            name: "Classic",
+            fn: async () => await this.hardResetClassic(),
+        });
+        // Strategy 3: If USB-JTAG/Serial was not tried yet, try it as fallback
+        if (!isUSBJTAGSerial && !isEspressifUSB) {
+            resetStrategies.push({
+                name: "USB-JTAG/Serial (fallback)",
+                fn: async () => await this.hardResetUSBJTAGSerial(),
+            });
+        }
+        let lastError = null;
+        // Try each reset strategy
+        for (const strategy of resetStrategies) {
+            try {
+                this.logger.log(`Trying ${strategy.name} reset...`);
+                // Check if port is still open, if not, skip this strategy
+                if (!this.connected || !this.port.writable) {
+                    this.logger.log(`Port disconnected, skipping ${strategy.name} reset`);
+                    continue;
+                }
+                await strategy.fn();
+                // Try to sync after reset
+                await this.sync();
+                // If we get here, sync succeeded
+                this.logger.log(`Connected successfully with ${strategy.name} reset.`);
+                return;
+            }
+            catch (error) {
+                lastError = error;
+                this.logger.log(`${strategy.name} reset failed: ${error.message}`);
+                // If port got disconnected, we can't try more strategies
+                if (!this.connected || !this.port.writable) {
+                    this.logger.log(`Port disconnected during reset attempt`);
+                    break;
+                }
+                // Clear buffers before trying next strategy
+                this._inputBuffer.length = 0;
+                await this.drainInputBuffer(200);
+                await this.flushSerialBuffers();
+            }
+        }
+        // All strategies failed
+        throw new Error(`Couldn't sync to ESP. Try resetting manually. Last error: ${lastError === null || lastError === void 0 ? void 0 : lastError.message}`);
+    }
+    /**
+     * @name hardResetUSBJTAGSerial
+     * USB-JTAG/Serial reset sequence for ESP32-C3, ESP32-S3, ESP32-C6, etc.
+     */
+    async hardResetUSBJTAGSerial() {
+        await this.setRTS(false);
+        await this.setDTR(false); // Idle
+        await this.sleep(100);
+        await this.setDTR(true); // Set IO0
+        await this.setRTS(false);
+        await this.sleep(100);
+        await this.setRTS(true); // Reset. Calls inverted to go through (1,1) instead of (0,0)
+        await this.setDTR(false);
+        await this.setRTS(true); // RTS set as Windows only propagates DTR on RTS setting
+        await this.sleep(100);
+        await this.setDTR(false);
+        await this.setRTS(false); // Chip out of reset
+        // Wait for chip to boot into bootloader
+        await this.sleep(200);
+    }
+    /**
+     * @name hardResetClassic
+     * Classic reset sequence for USB-to-Serial bridge chips (CH340, CP2102, etc.)
+     */
+    async hardResetClassic() {
+        await this.setDTR(false); // IO0=HIGH
+        await this.setRTS(true); // EN=LOW, chip in reset
+        await this.sleep(100);
+        await this.setDTR(true); // IO0=LOW
+        await this.setRTS(false); // EN=HIGH, chip out of reset
+        await this.sleep(50);
+        await this.setDTR(false); // IO0=HIGH, done
+        // Wait for chip to boot into bootloader
+        await this.sleep(200);
+    }
     /**
      * @name sync
      * Put into ROM bootload mode & attempt to synchronize with the
@@ -1328,9 +1408,10 @@ export class ESPLoader extends EventTarget {
             const chunkSize = Math.min(CHUNK_SIZE, remainingSize);
             let chunkSuccess = false;
             let retryCount = 0;
-            const MAX_RETRIES = 3;
+            const MAX_RETRIES = 5;
             // 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)}`);
                     // Send read flash command for this chunk
@@ -1339,7 +1420,6 @@ export class ESPLoader extends EventTarget {
                     if (res != 0) {
                         throw new Error("Failed to read memory: " + res);
                     }
-                    let resp = new Uint8Array(0);
                     while (resp.length < chunkSize) {
                         // Read a SLIP packet
                         let packet;
@@ -1349,6 +1429,20 @@ export class ESPLoader extends EventTarget {
                         catch (err) {
                             if (err instanceof SlipReadError) {
                                 this.logger.debug(`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}`);
+                                    }
+                                }
+                                // Drain input buffer for CP210x compatibility on Windows
+                                // This clears any stale data that may be causing the error
+                                await this.drainInputBuffer(300);
                                 // If we've read all the data we need, break
                                 if (resp.length >= chunkSize) {
                                     break;
@@ -1378,17 +1472,20 @@ export class ESPLoader extends EventTarget {
                 }
                 catch (err) {
                     retryCount++;
-                    // Check if it's a timeout error
-                    if (err instanceof SlipReadError &&
-                        err.message.includes("Timed out")) {
+                    // Check if it's a timeout error or SLIP error
+                    if (err instanceof SlipReadError) {
                         if (retryCount <= MAX_RETRIES) {
-                            this.logger.log(`⚠️  Timeout error at 0x${currentAddr.toString(16)}. Reconnecting and retrying (attempt ${retryCount}/${MAX_RETRIES})...`);
+                            this.logger.log(`⚠️  ${err.message} at 0x${currentAddr.toString(16)}. Draining buffer and retrying (attempt ${retryCount}/${MAX_RETRIES})...`);
                             try {
-                                await this.reconnect();
-                                // Continue to retry the same chunk
+                                await this.drainInputBuffer(300);
+                                // Clear application buffer
+                                await this.flushSerialBuffers();
+                                // Wait before retry to let hardware settle
+                                await sleep(SYNC_TIMEOUT);
+                                // Continue to retry the same chunk (will send new read command)
                             }
-                            catch (reconnectErr) {
-                                throw new Error(`Reconnect failed: ${reconnectErr}`);
+                            catch (drainErr) {
+                                this.logger.debug(`Buffer drain error: ${drainErr}`);
                             }
                         }
                         else {
@@ -1396,7 +1493,7 @@ export class ESPLoader extends EventTarget {
                         }
                     }
                     else {
-                        // Non-timeout error, don't retry
+                        // Non-SLIP error, don't retry
                         throw err;
                     }
                 }