esp32tool 1.1.9 → 1.3.0

package/js/script.js

@@ -1,3 +1,13 @@
+// Import WebUSB serial support for Android compatibility
+import { WebUSBSerial, requestSerialPort } from './webusb-serial.js';
+import { ESP32ToolConsole } from './console.js';
+
+// Make requestSerialPort available globally for esptool.js
+// Use defensive assignment to avoid accidental overwrites
+if (!globalThis.requestSerialPort) {
+  globalThis.requestSerialPort = requestSerialPort;
+}
+
 let espStub;
 let esp32s2ReconnectInProgress = false;
 let currentLittleFS = null;
@@ -8,6 +18,13 @@ let currentFilesystemType = null; // 'littlefs', 'fatfs', or 'spiffs'
 let littlefsModulePromise = null; // Cache for LittleFS WASM module
 let lastReadFlashData = null; // Store last read flash data for ESP8266
 let currentChipName = null; // Store chip name globally
+let isConnected = false; // Track connection state
+let consoleInstance = null; // ESP32ToolConsole instance
+let baudRateBeforeConsole = null; // Store baudrate before opening console
+let espLoaderBeforeConsole = null; // Store original ESPLoader before console
+let chipFamilyBeforeConsole = null; // Store chipFamily before opening console
+let consoleResetHandler = null;
+let consoleCloseHandler = null;
 
 /**
  * Get display name for current filesystem type
@@ -34,7 +51,7 @@ function clearAllCachedData() {
         currentLittleFS.destroy();
       }
     } catch (e) {
-      console.error('Error destroying filesystem:', e);
+      debugMsg('Error destroying filesystem: ' + e);
     }
   }
   
@@ -86,6 +103,55 @@ function clearAllCachedData() {
 }
 
 const baudRates = [2000000, 1500000, 921600, 500000, 460800, 230400, 153600, 128000, 115200];
+
+// Advanced read flash parameters
+// chunkSize: Amount of data to request from ESP in one command (in KB)
+const chunkSizes = [
+  { label: "4 KB", value: 0x1000 },
+  { label: "8 KB", value: 0x2000 },
+  { label: "16 KB (WebUSB)", value: 0x4000 },
+  { label: "64 KB", value: 0x10000 },
+  { label: "128 KB", value: 0x20000 },
+  { label: "256 KB (Desktop)", value: 0x40000 }
+];
+
+// blockSize: Size of each data block sent by ESP (in bytes)
+const blockSizes = [
+  { label: "31 B (Android)", value: 31 },
+  { label: "62 B", value: 62 },
+  { label: "124 B", value: 124 },
+  { label: "248 B (CDC)", value: 248 },
+  { label: "256 B", value: 256 },
+  { label: "496 B", value: 496 },
+  { label: "512 B", value: 512 },
+  { label: "992 B", value: 992 },
+  { label: "1024 B", value: 1024 },
+  { label: "1984 B", value: 1984 },
+  { label: "2024 B", value: 2024 },
+  { label: "3968 B (Desktop)", value: 3968 },
+  { label: "4096 B (Maximum)", value: 4096 }
+];
+
+// maxInFlight: Maximum unacknowledged bytes (in bytes)
+const maxInFlights = [
+  { label: "31 B (Android)", value: 31 },
+  { label: "62 B", value: 62 },
+  { label: "124 B", value: 124 },
+  { label: "248 B (Android CDC)", value: 248 },
+  { label: "512 B", value: 512 },
+  { label: "992 B", value: 992 },
+  { label: "1024 B", value: 1024 },
+  { label: "1984 B", value: 1984 },
+  { label: "2024 B", value: 2024 },
+  { label: "3968 B", value: 3968 },
+  { label: "4096 B", value: 4096 },
+  { label: "7936 B", value: 7936 },
+  { label: "8192 B", value: 8192 },
+  { label: "15872 B", value: 15872 },
+  { label: "31744 B", value: 31744 },
+  { label: "63488 B", value: 63488 }
+];
+
 const bufferSize = 512;
 const colors = ["#00a7e9", "#f89521", "#be1e2d"];
 const measurementPeriodId = "0001";
@@ -96,7 +162,13 @@ const isElectron = window.electronAPI && window.electronAPI.isElectron;
 const maxLogLength = 100;
 const log = document.getElementById("log");
 const butConnect = document.getElementById("butConnect");
-const baudRate = document.getElementById("baudRate");
+const baudRateSelect = document.getElementById("baudRate");
+const advancedMode = document.getElementById("advanced");
+const advancedRow = document.querySelector(".advanced-row");
+const main = document.querySelector(".main");
+const chunkSizeSelect = document.getElementById("chunkSize");
+const blockSizeSelect = document.getElementById("blockSize");
+const maxInFlightSelect = document.getElementById("maxInFlight");
 const butClear = document.getElementById("butClear");
 const butErase = document.getElementById("butErase");
 const butProgram = document.getElementById("butProgram");
@@ -125,6 +197,8 @@ const littlefsFileInput = document.getElementById("littlefsFileInput");
 const butLittlefsUpload = document.getElementById("butLittlefsUpload");
 const butLittlefsMkdir = document.getElementById("butLittlefsMkdir");
 const autoscroll = document.getElementById("autoscroll");
+const consoleSwitch = document.getElementById("console");
+const consoleContainer = document.getElementById("console-container");
 const lightSS = document.getElementById("light");
 const darkSS = document.getElementById("dark");
 const darkMode = document.getElementById("darkmode");
@@ -150,7 +224,7 @@ let currentViewedFileData = null;
 document.addEventListener("DOMContentLoaded", () => {
   butConnect.addEventListener("click", () => {
     clickConnect().catch(async (e) => {
-      console.error(e);
+      debugMsg('Connection error: ' + e);
       errorMsg(e.message || e);
       if (espStub) {
         await espStub.disconnect();
@@ -190,7 +264,12 @@ document.addEventListener("DOMContentLoaded", () => {
   updateUploadRowsVisibility();
   
   autoscroll.addEventListener("click", clickAutoscroll);
-  baudRate.addEventListener("change", changeBaudRate);
+  consoleSwitch.addEventListener("click", clickConsole);
+  baudRateSelect.addEventListener("change", changeBaudRate);
+  advancedMode.addEventListener("change", clickAdvancedMode);
+  chunkSizeSelect.addEventListener("change", changeAdvancedParam);
+  blockSizeSelect.addEventListener("change", changeAdvancedParam);
+  maxInFlightSelect.addEventListener("change", changeAdvancedParam);
   darkMode.addEventListener("click", clickDarkMode);
   debugMode.addEventListener("click", clickDebugMode);
   showLog.addEventListener("click", clickShowLog);
@@ -198,10 +277,11 @@ document.addEventListener("DOMContentLoaded", () => {
     console.log("Got an uncaught error: ", event.error);
   });
   
-  // Header auto-hide functionality
+  // Header auto-hide functionality - DISABLED
   const header = document.querySelector(".header");
   const main = document.querySelector(".main");
   
+  /* DISABLED: Auto-hide header
   // Show header on mouse enter at top of page
   main.addEventListener("mousemove", (e) => {
     if (e.clientY < 5 && header.classList.contains("header-hidden")) {
@@ -227,13 +307,16 @@ document.addEventListener("DOMContentLoaded", () => {
       }, 1000);
     }
   });
+  */
   
-  if ("serial" in navigator) {
+  // Check for Web Serial or WebUSB support
+  if ("serial" in navigator || "usb" in navigator) {
     const notSupported = document.getElementById("notSupported");
     notSupported.classList.add("hidden");
   }
 
   initBaudRate();
+  initAdvancedParams();
   loadAllSettings();
   updateTheme();
   logMsg("ESP32Tool loaded.");
@@ -244,10 +327,42 @@ function initBaudRate() {
     var option = document.createElement("option");
     option.text = rate + " Baud";
     option.value = rate;
-    baudRate.add(option);
+    baudRateSelect.add(option);
   }
 }
 
+function initAdvancedParams() {
+  // Initialize chunkSize dropdown
+  for (let item of chunkSizes) {
+    const option = document.createElement("option");
+    option.text = item.label;
+    option.value = item.value;
+    chunkSizeSelect.add(option);
+  }
+  // Set default: 16 KB for WebUSB, 256 KB for Desktop
+  chunkSizeSelect.value = 0x4000; // 16 KB default
+
+  // Initialize blockSize dropdown
+  for (let item of blockSizes) {
+    const option = document.createElement("option");
+    option.text = item.label;
+    option.value = item.value;
+    blockSizeSelect.add(option);
+  }
+  // Set default: 4095 B for Desktop
+  blockSizeSelect.value = 4095;
+
+  // Initialize maxInFlight dropdown
+  for (let item of maxInFlights) {
+    const option = document.createElement("option");
+    option.text = item.label;
+    option.value = item.value;
+    maxInFlightSelect.add(option);
+  }
+  // Set default: 8190 B for Desktop
+  maxInFlightSelect.value = 8190;
+}
+
 function logMsg(text) {
   log.innerHTML += text + "<br>";
 
@@ -266,31 +381,8 @@ function debugMsg(...args) {
   if (!debugMode.checked) {
     return;
   }
-  
-  function getStackTrace() {
-    let stack = new Error().stack;
-    //console.log(stack);
-    stack = stack.split("\n").map((v) => v.trim());
-    stack.shift();
-    stack.shift();
 
-    let trace = [];
-    for (let line of stack) {
-      line = line.replace("at ", "");
-      trace.push({
-        func: line.substr(0, line.indexOf("(") - 1),
-        pos: line.substring(line.indexOf(".js:") + 4, line.lastIndexOf(":")),
-      });
-    }
-
-    return trace;
-  }
-
-  let stack = getStackTrace();
-  stack.shift();
-  let top = stack.shift();
-  let prefix =
-    '<span class="debug-function">[' + top.func + ":" + top.pos + "]</span> ";
+  let prefix = "";
   for (let arg of args) {
     if (arg === undefined) {
       logMsg(prefix + "undefined");
@@ -355,19 +447,60 @@ function formatMacAddr(macAddr) {
     .join(":");
 }
 
+function toHex(value) {
+  return "0x" + value.toString(16).padStart(2, "0");
+}
+
+/**
+ * Parse flash size string (e.g., "256KB", "4MB") to bytes
+ * @param {string} sizeStr - Flash size string with unit (KB or MB)
+ * @returns {number} Size in bytes
+ */
+function parseFlashSize(sizeStr) {
+  if (!sizeStr || typeof sizeStr !== 'string') {
+    return 0;
+  }
+  
+  // Extract number and unit
+  const match = sizeStr.match(/^(\d+)(KB|MB)$/i);
+  if (!match) {
+    // If no unit, assume it's already in MB (legacy behavior)
+    const num = parseInt(sizeStr);
+    return isNaN(num) ? 0 : num * 1024 * 1024;
+  }
+  
+  const value = parseInt(match[1]);
+  const unit = match[2].toUpperCase();
+  
+  if (unit === 'KB') {
+    return value * 1024; // KB to bytes
+  } else if (unit === 'MB') {
+    return value * 1024 * 1024; // MB to bytes
+  }
+  
+  return 0;
+}
+
 /**
  * @name clickConnect
  * Click handler for the connect/disconnect button.
  */
 async function clickConnect() {
+  console.log('[clickConnect] Function called');
+  
   if (espStub) {
+    console.log('[clickConnect] Already connected, disconnecting...');
     // Remove disconnect event listener to prevent it from firing during manual disconnect
     if (espStub.handleDisconnect) {
       espStub.removeEventListener("disconnect", espStub.handleDisconnect);
     }
     
     await espStub.disconnect();
-    await espStub.port.close();
+    try {
+      await espStub.port?.close?.();
+    } catch (e) {
+      // ignore double-close
+    }
     toggleUIConnected(false);
     espStub = undefined;
     
@@ -377,13 +510,45 @@ async function clickConnect() {
     return;
   }
 
+  console.log('[clickConnect] Getting esploaderMod...');
   const esploaderMod = await window.esptoolPackage;
 
-  let esploader = await esploaderMod.connect({
-    log: (...args) => logMsg(...args),
-    debug: (...args) => debugMsg(...args),
-    error: (...args) => errorMsg(...args),
-  });
+  // Platform detection: Android always uses WebUSB, Desktop uses Web Serial
+  const userAgent = navigator.userAgent || '';
+  const isAndroid = /Android/i.test(userAgent);
+  
+  // Only log platform details to UI in debug mode (avoid fingerprinting surface)
+  if (debugMode.checked) {
+    const platformMsg = `Platform: ${isAndroid ? 'Android' : 'Desktop'} (UA: ${userAgent.substring(0, 50)}...)`;
+    logMsg(platformMsg);
+  }
+  logMsg(`Using: ${isAndroid ? 'WebUSB' : 'Web Serial'}`);
+  
+  let esploader;
+  
+  if (isAndroid) {
+    // Android: Use WebUSB directly
+    console.log('[Connect] Using WebUSB for Android');
+    try {
+      const port = await WebUSBSerial.requestPort((...args) => logMsg(...args));
+      esploader = await esploaderMod.connectWithPort(port, {
+        log: (...args) => logMsg(...args),
+        debug: (...args) => debugMsg(...args),
+        error: (...args) => errorMsg(...args),
+      });
+    } catch (err) {
+      logMsg(`WebUSB connection failed: ${err.message || err}`);
+      throw err;
+    }
+  } else {
+    // Desktop: Use Web Serial (standard esptool connect)
+    console.log('[Connect] Using Web Serial for Desktop');
+    esploader = await esploaderMod.connect({
+      log: (...args) => logMsg(...args),
+      debug: (...args) => debugMsg(...args),
+      error: (...args) => errorMsg(...args),
+    });
+  }
   
   // Store port info for ESP32-S2 detection
   let portInfo = esploader.port?.getInfo ? esploader.port.getInfo() : {};
@@ -404,119 +569,73 @@ async function clickConnect() {
       espStub = undefined;
       
       try {
+        // Close the port first
         await esploader.port.close();
         
-        if (esploader.port.forget) {
+        // For Android WebUSB: ESP32-S2 automatic reconnection doesn't work
+        // Show message and let user reconnect manually with BOOT button
+        if (isAndroid) {
+          logMsg("ESP32-S2 has switched to CDC mode");
+          logMsg("Please press and HOLD the BOOT button on your ESP32-S2, then click Connect");
+          esp32s2ReconnectInProgress = false;
+          return;
+        }
+        // For Desktop Web Serial: Use the modal dialog approach
+        if (!isAndroid && esploader.port.forget) {
           await esploader.port.forget();
         }
       } catch (disconnectErr) {
         // Ignore disconnect errors
+        debugMsg("Error during disconnect: " + disconnectErr);
       }
       
-      // Show modal dialog
-      const modal = document.getElementById("esp32s2Modal");
-      const reconnectBtn = document.getElementById("butReconnectS2");
-      
-      modal.classList.remove("hidden");
-      
-      // Handle reconnect button click
-      const handleReconnect = async () => {
-        modal.classList.add("hidden");
-        reconnectBtn.removeEventListener("click", handleReconnect);
+      // Show modal dialog ONLY for Desktop
+      if (!isAndroid) {
+        const modal = document.getElementById("esp32s2Modal");
+        const reconnectBtn = document.getElementById("butReconnectS2");
         
-        // Trigger port selection
-        try {
-          await clickConnect();
-          // Reset flag on successful connection
-          esp32s2ReconnectInProgress = false;
-        } catch (err) {
-          errorMsg("Failed to reconnect: " + err);
-          // Reset flag on error so user can try again
-          esp32s2ReconnectInProgress = false;
-        }
-      };
-      
-      reconnectBtn.addEventListener("click", handleReconnect);
+        modal.classList.remove("hidden");
+        
+        // Handle reconnect button click
+        const handleReconnect = async () => {
+          modal.classList.add("hidden");
+          reconnectBtn.removeEventListener("click", handleReconnect);
+          
+          logMsg("Requesting new device selection...");
+          
+          // Trigger port selection
+          try {
+            await clickConnect();
+            // Reset flag on successful connection
+            esp32s2ReconnectInProgress = false;
+          } catch (err) {
+            errorMsg("Failed to reconnect: " + err);
+            // Reset flag on error so user can try again
+            esp32s2ReconnectInProgress = false;
+          }
+        };
+        
+        reconnectBtn.addEventListener("click", handleReconnect);
+      }
     });
   }
   
   try {
     await esploader.initialize();
   } catch (err) {
-    // Check if this is an ESP32-S2 that needs reconnection
-    if (isESP32S2 && isElectron && !esp32s2ReconnectInProgress) {
-      esp32s2ReconnectInProgress = true;
-      logMsg("ESP32-S2 Native USB detected - automatic reconnection...");
-      toggleUIConnected(false);
-      
-      try {
-        await esploader.port.close();
-      } catch (e) {
-        console.debug("Port close error:", e);
-      }
-      
-      // Wait for new port to appear
-      logMsg("Waiting for ESP32-S2 CDC port...");
-      
-      const waitForNewPort = new Promise((resolve) => {
-        const checkInterval = setInterval(() => {
-          if (navigator.serial && navigator.serial.getPorts) {
-            navigator.serial.getPorts().then(ports => {
-              if (ports.length > 0) {
-                clearInterval(checkInterval);
-                resolve(ports[0]);
-              }
-            });
-          }
-        }, 50);
-        
-        // Timeout after 500 ms
-        setTimeout(() => {
-          clearInterval(checkInterval);
-          resolve(null);
-        }, 500);
-      });
-      
-      const newPort = await waitForNewPort;
-      
-      if (!newPort) {
-        esp32s2ReconnectInProgress = false;
-        throw new Error("ESP32-S2 CDC port did not appear in time");
-      }
-      
-      // Additional small delay to ensure port is ready
-      await new Promise(resolve => setTimeout(resolve, 100));
-      
-      // Open the new port and create ESPLoader directly
-      await newPort.open({ baudRate: 115200 });
-      logMsg("Connected successfully.");
-      
-      esploader = new esploaderMod.ESPLoader(newPort, {
-        log: (...args) => logMsg(...args),
-        debug: (...args) => debugMsg(...args),
-        error: (...args) => errorMsg(...args),
-      });
-      
-      // Initialize the new connection
-      await esploader.initialize();
-      
-      esp32s2ReconnectInProgress = false;
-      logMsg("ESP32-S2 reconnection successful!");
-    } else {
-      // If ESP32-S2 reconnect is in progress (browser modal), suppress the error
-      if (esp32s2ReconnectInProgress) {
-        logMsg("Initialization interrupted for ESP32-S2 reconnection.");
-        return;
-      }
-      
-      // Not ESP32-S2 or reconnect already attempted
-      try {
-        await esploader.disconnect();
-      } catch (disconnectErr) {
-        // Ignore disconnect errors
-      }
-      throw err;
+    // If ESP32-S2 reconnect is in progress (handled by event listener), suppress the error
+    if (esp32s2ReconnectInProgress) {
+      logMsg("Initialization interrupted for ESP32-S2 reconnection.");
+      return;
+    }
+    
+    // Not ESP32-S2 or other error
+    try {
+      await esploader.disconnect();
+    } catch (disconnectErr) {
+      // Ignore disconnect errors
     }
+    throw err;
   }
 
   logMsg("Connected to " + esploader.chipName);
@@ -526,9 +645,16 @@ async function clickConnect() {
   currentChipName = esploader.chipName;
 
   espStub = await esploader.runStub();
+  
   toggleUIConnected(true);
   toggleUIToolbar(true);
   
+  // Auto-initialize console if it was enabled before
+  if (consoleSwitch.checked) {
+    logMsg("Auto-initializing console from saved settings...");
+    await clickConsole();
+  }
+  
   // Check if ESP8266 and show filesystem button
   const isESP8266 = currentChipName && currentChipName.toUpperCase().includes("ESP8266");
   if (isESP8266) {
@@ -549,13 +675,13 @@ async function clickConnect() {
   
   // Set detected flash size in the read size field
   if (espStub.flashSize) {
-    const flashSizeBytes = parseInt(espStub.flashSize) * 1024 * 1024; // Convert MB to bytes
+    const flashSizeBytes = parseFlashSize(espStub.flashSize);
     readSize.value = "0x" + flashSizeBytes.toString(16);
   }
   
   // Set the selected baud rate
-  let baud = parseInt(baudRate.value);
-  if (baudRates.includes(baud)) {
+  let baud = parseInt(baudRateSelect.value);
+  if (baudRates.includes(baud) && esploader.chipName !== "ESP8266") {
     await espStub.setBaudrate(baud);
   }
   
@@ -573,9 +699,14 @@ async function clickConnect() {
  * Change handler for the Baud Rate selector.
  */
 async function changeBaudRate() {
-  saveSetting("baudrate", baudRate.value);
+  saveSetting("baudrate", baudRateSelect.value);
   if (espStub) {
-    let baud = parseInt(baudRate.value);
+    // Skip for ESP8266 as it only supports 115200 baud in stub mode
+    if (espStub.chipName === "ESP8266") {
+      logMsg("ESP8266 stub only supports 115200 baud");
+      return;
+    }
+    let baud = parseInt(baudRateSelect.value);
     if (baudRates.includes(baud)) {
       await espStub.setBaudrate(baud);
     }
@@ -617,6 +748,364 @@ async function clickShowLog() {
   updateLogVisibility();
 }
 
+/**
+ * @name initConsoleUI
+ * Initialize console UI, event handlers, and start console instance
+ * Extracted helper to avoid duplication across different console init flows
+ */
+async function initConsoleUI() {
+  // Wait for port to be ready
+  await sleep(200);
+  
+  // Show console container and hide commands
+  consoleContainer.classList.remove("hidden");
+  const commands = document.getElementById("commands");
+  if (commands) commands.classList.add("hidden");
+  
+  // Initialize console
+  consoleInstance = new ESP32ToolConsole(espStub.port, consoleContainer, true);
+  await consoleInstance.init();
+  
+  // Listen for console reset events
+  if (consoleResetHandler) {
+    consoleContainer.removeEventListener('console-reset', consoleResetHandler);
+  }
+  consoleResetHandler = async () => {
+    if (espStub && typeof espStub.hardReset === 'function') {
+      try {
+        debugMsg("Resetting device from console...");
+        await espStub.hardReset();
+        debugMsg("Device reset successful");
+      } catch (err) {
+        errorMsg("Failed to reset device: " + err.message);
+      }
+    }
+  };
+  consoleContainer.addEventListener('console-reset', consoleResetHandler);
+  
+  // Listen for console close events
+  if (consoleCloseHandler) {
+    consoleContainer.removeEventListener('console-close', consoleCloseHandler);
+  }
+  consoleCloseHandler = async () => {
+    if (!consoleSwitch.checked) return;
+    debugMsg("Closing console...");
+    consoleSwitch.checked = false;
+    saveSetting("console", false);
+    await closeConsole();
+  };
+  consoleContainer.addEventListener('console-close', consoleCloseHandler);
+  
+  logMsg("Console initialized");
+}
+
+/**
+ * @name clickConsole
+ * Change handler for the Console checkbox.
+ */
+async function clickConsole() {
+  const shouldEnable = consoleSwitch.checked;
+  
+  if (shouldEnable) {
+    // After WDT reset, everything is gone - start fresh with port selection
+    if (isConnected && espStub && !espStub.connected) {
+      // Port was closed after WDT reset - select new port
+      try {
+        logMsg("Please select the serial port for console mode...");
+        const newPort = await navigator.serial.requestPort();
+        
+        // Open the new port at 115200 for console
+        await newPort.open({ baudRate: 115200 });
+        
+        // Update espStub to use the new port
+        espStub.port = newPort;
+        espStub.connected = true;
+        if (espStub._parent) {
+          espStub._parent.port = newPort;
+        }
+        if (espLoaderBeforeConsole) {
+          espLoaderBeforeConsole.port = newPort;
+        }
+        
+        logMsg("Port opened for console at 115200 baud");
+      } catch (openErr) {
+        errorMsg(`Failed to open port for console: ${openErr.message}`);
+        consoleSwitch.checked = false;
+        saveSetting("console", false);
+        return;
+      }
+    }
+    
+    // Initialize console if connected and not already created
+    if (isConnected && espStub && espStub.port && !consoleInstance) {
+      try {
+        // CRITICAL: Save current state BEFORE changing anything
+        // If espStub has a parent, we need to get the baudrate from the parent!
+        // The stub child can not be used for restoring the stub. the parent must be used!
+        const loaderToSave = espStub._parent || espStub;
+        const currentBaudrate = loaderToSave.currentBaudRate;
+        const currentChipFamily = espStub.chipFamily;
+        const currentIsStub = espStub.IS_STUB;
+
+        // CRITICAL: Save the PARENT loader (not the stub child!)
+        espLoaderBeforeConsole = loaderToSave;
+        baudRateBeforeConsole = currentBaudrate;
+        chipFamilyBeforeConsole = currentChipFamily;
+
+        // Console ALWAYS runs at 115200 baud (firmware default)
+        // Always set baudrate to 115200 before opening console
+        try {
+          await espStub.setBaudrate(115200);
+          debugMsg("Baudrate set to 115200 for console");
+        } catch (baudErr) {
+          logMsg(`Failed to set baudrate to 115200: ${baudErr.message}`);
+        }
+        
+        // Enter console mode - handles both USB-JTAG and serial chip devices
+        try {
+          const portWasClosed = await espStub.enterConsoleMode();
+          
+          if (portWasClosed) {
+            // USB-JTAG/OTG device: Port was closed after WDT reset
+            debugMsg("Device reset to firmware mode (port closed)");
+            
+            // Wait a bit for device to boot
+            await sleep(500);
+            
+            // Check if this is ESP32-S2 (needs port forget and modal) or ESP32-S3 (direct requestPort)
+            const isS2 = chipFamilyBeforeConsole === 0x3252; // CHIP_FAMILY_ESP32S2 = 0x3252
+            
+            if (isS2) {
+              // ESP32-S2: Forget old port and show modal for port selection
+              if (espStub.port && espStub.port.forget) {
+                try {
+                  await espStub.port.forget();
+                  logMsg("Forgot old port");
+                } catch (forgetErr) {
+                  logMsg(`Port forget error (ignored): ${forgetErr.message}`);
+                }
+              }
+              
+              // Wait a bit for browser to process
+              await sleep(100);
+              
+              // Show modal for port selection (requires user gesture)
+              const modal = document.getElementById("esp32s2Modal");
+              const reconnectBtn = document.getElementById("butReconnectS2");
+              
+              // Update modal text for console mode
+              const modalTitle = modal.querySelector("h2");
+              const modalText = modal.querySelector("p");
+              if (modalTitle) modalTitle.textContent = "Device has been reset to firmware mode";
+              if (modalText) modalText.textContent = "Please click the button below to select the serial port for console.";
+              
+              modal.classList.remove("hidden");
+              
+              // Handle reconnect button click
+              const handleReconnect = async () => {
+                modal.classList.add("hidden");
+                reconnectBtn.removeEventListener("click", handleReconnect);
+                
+                try {
+                  // Request the NEW port (user gesture from button click)
+                  debugMsg("Please select the serial port for console mode...");
+                  const newPort = await navigator.serial.requestPort();
+                  
+                  // Open the NEW port at 115200 for console
+                  await newPort.open({ baudRate: 115200 });
+                  espStub.port = newPort;
+                  espStub.connected = true;
+                  
+                  // Keep parent/loader in sync (used by closeConsole)
+                  if (espStub._parent) {
+                    espStub._parent.port = newPort;
+                  }
+                  if (espLoaderBeforeConsole) {
+                    espLoaderBeforeConsole.port = newPort;
+                  }
+                  
+                  debugMsg("Port opened for console at 115200 baud");
+                  
+                  // Device is already in firmware mode, port is open at 115200
+                  // Initialize console directly
+                  consoleSwitch.checked = true;
+                  saveSetting("console", true);
+                  
+                  // Initialize console UI and handlers
+                  await initConsoleUI();
+                } catch (err) {
+                  errorMsg(`Failed to open port for console: ${err.message}`);
+                  consoleSwitch.checked = false;
+                  saveSetting("console", false);
+                }
+              };
+              
+              reconnectBtn.addEventListener("click", handleReconnect);
+            } else {
+              // ESP32-S3/C3/C5/C6/H2/P4: Direct requestPort (no modal, no forget)
+              try {
+                // Request port selection from user (direct, like console branch)
+                debugMsg("Please select the serial port again for console mode...");
+                const newPort = await navigator.serial.requestPort();
+                
+                // Open the new port at 115200 for console
+                await newPort.open({ baudRate: 115200 });
+                espStub.port = newPort;
+                espStub.connected = true;
+                
+                // Keep parent/loader in sync (used by closeConsole)
+                if (espStub._parent) {
+                  espStub._parent.port = newPort;
+                }
+                if (espLoaderBeforeConsole) {
+                  espLoaderBeforeConsole.port = newPort;
+                }
+                
+                debugMsg("Port opened for console at 115200 baud");
+                
+                // Device is already in firmware mode, port is open at 115200
+                // Initialize console directly
+                consoleSwitch.checked = true;
+                saveSetting("console", true);
+                
+                // Initialize console UI and handlers
+                await initConsoleUI();
+              } catch (err) {
+                errorMsg(`Failed to open port for console: ${err.message}`);
+                consoleSwitch.checked = false;
+                saveSetting("console", false);
+              }
+            }
+            
+            return;
+          } else {
+            // Serial chip device: Port stays open
+            debugMsg("Device reset to firmware mode");
+          }
+        } catch (err) {
+          errorMsg(`Failed to enter console mode: ${err.message}`);
+          consoleSwitch.checked = false;
+          saveSetting("console", false);
+          return;
+        }
+        
+        // Wait for:
+        // - Firmware to start after reset
+        // - Port to be ready for new reader
+        await sleep(200);
+        
+        // Initialize console UI and handlers
+        await initConsoleUI();
+        
+        saveSetting("console", true);
+      } catch (err) {
+        errorMsg("Failed to initialize console: " + err.message);
+        consoleSwitch.checked = false;
+        saveSetting("console", false);
+        await closeConsole();
+      }
+    } else if (!isConnected) {
+      // Not connected - just show message
+      consoleSwitch.checked = false;
+      saveSetting("console", false);
+      errorMsg("Please connect to device first");
+    }
+  } else {
+    await closeConsole();
+    saveSetting("console", false);
+  }
+}
+
+/**
+ * @name closeConsole
+ * Close console and restore device to bootloader state
+ */
+async function closeConsole() {
+  // Hide console and show commands again
+  consoleContainer.classList.add("hidden");
+  const commands = document.getElementById("commands");
+  if (commands) commands.classList.remove("hidden");
+  
+  if (consoleInstance) {
+    try {
+      await consoleInstance.disconnect();
+    } catch (err) {
+      debugMsg("Error disconnecting console: " + err);
+    }
+    consoleInstance = null;
+  }
+  
+  // Restore original state (bootloader + stub + baudrate)
+  if (espLoaderBeforeConsole && Number.isFinite(baudRateBeforeConsole)) {
+    // Check if this is a USB-JTAG/OTG device
+    const isUsbJtag = espLoaderBeforeConsole._isUsbJtagOrOtg === true;
+    
+    try {
+      if (isUsbJtag) {
+        // USB-JTAG/OTG devices: Port was lost, need to request new port
+        debugMsg("Please select the serial port again to reconnect...");
+        
+        try {
+          // Request port selection from user
+          const newPort = await navigator.serial.requestPort();
+          
+          // Update the loader to use the new port
+          espLoaderBeforeConsole.port = newPort;
+          
+          debugMsg("Port selected, reconnecting to bootloader...");
+        } catch (portErr) {
+          errorMsg(`Failed to select port: ${portErr.message}`);
+          // Reset connection state to allow fresh connect
+          espStub = undefined;
+          toggleUIConnected(false);
+          espLoaderBeforeConsole = null;
+          baudRateBeforeConsole = null;
+          chipFamilyBeforeConsole = null;
+          return;
+        }
+      }
+      
+      // Use reconnectToBootloader() - it handles everything:
+      // - Releases locks
+      // - Resets to bootloader
+      // - Reopens port at 115200
+      // - Syncs with bootloader using correct reset strategy
+      // NOTE: Call on original loader (before console), not on stub
+      await espLoaderBeforeConsole.reconnectToBootloader();
+      
+      // Now espLoaderBeforeConsole is in bootloader state (IS_STUB = false)
+      // Reload stub using the reconnected bootloader
+      const newStub = await espLoaderBeforeConsole.runStub();
+      espStub = newStub;
+
+      // Restore original baudrate
+      if (baudRateBeforeConsole !== 115200) {
+        await espStub.setBaudrate(baudRateBeforeConsole);
+      }
+
+      espLoaderBeforeConsole = null;
+      baudRateBeforeConsole = null;
+      chipFamilyBeforeConsole = null;
+    } catch (err) {
+      errorMsg("Failed to restore state after console: " + err.message);
+      // Attempt to disconnect cleanly to allow reconnection
+      try {
+        if (espLoaderBeforeConsole?.port) {
+          await espLoaderBeforeConsole.port.close();
+        }
+      } catch (closeErr) {
+        debugMsg("Failed to close port: " + closeErr);
+      }
+      // Reset connection state to allow fresh connect
+      espStub = undefined;
+      toggleUIConnected(false);
+      espLoaderBeforeConsole = null;
+      baudRateBeforeConsole = null;
+      chipFamilyBeforeConsole = null;
+    }
+  }
+}
+
 /**
  * @name updateLogVisibility
  * Update log and log controls visibility
@@ -637,6 +1126,39 @@ function updateLogVisibility() {
   }
 }
 
+/**
+ * @name clickAdvancedMode
+ * Change handler for the Advanced Mode checkbox.
+ */
+async function clickAdvancedMode() {
+  saveSetting("advanced", advancedMode.checked);
+  updateAdvancedVisibility();
+}
+
+/**
+ * @name changeAdvancedParam
+ * Change handler for advanced parameter dropdowns.
+ */
+async function changeAdvancedParam() {
+  saveSetting("chunkSize", parseInt(chunkSizeSelect.value));
+  saveSetting("blockSize", parseInt(blockSizeSelect.value));
+  saveSetting("maxInFlight", parseInt(maxInFlightSelect.value));
+}
+
+/**
+ * @name updateAdvancedVisibility
+ * Update advanced controls visibility
+ */
+function updateAdvancedVisibility() {
+  if (advancedMode.checked) {
+    advancedRow.style.display = "flex";
+    main.classList.add("advanced-active");
+  } else {
+    advancedRow.style.display = "none";
+    main.classList.remove("advanced-active");
+  }
+}
+
 /**
  * @name clickDetectFS
  * Detect ESP8266 filesystem and open manager directly
@@ -651,8 +1173,8 @@ async function clickDetectFS() {
     butDetectFS.disabled = true;
     logMsg('Detecting ESP8266 filesystem...');
     
-    const flashSizeMB = parseInt(espStub.flashSize);
-    const flashSizeBytes = flashSizeMB * 1024 * 1024;
+    const flashSizeBytes = parseFlashSize(espStub.flashSize);
+    const flashSizeMB = flashSizeBytes / (1024 * 1024);
     const esptoolMod = await window.esptoolPackage;
     
     // Scan flash for filesystem signatures - optimized based on flash size
@@ -848,7 +1370,7 @@ async function clickDetectFS() {
     
   } catch (e) {
     errorMsg(`Failed to detect/open filesystem: ${e.message || e}`);
-    console.error(e);
+    debugMsg('Filesystem detection error details: ' + e);
   } finally {
     // Hide progress bar
     readProgress.classList.add('hidden');
@@ -870,7 +1392,7 @@ async function clickErase() {
   }
   
   if (confirmed) {
-    baudRate.disabled = true;
+    baudRateSelect.disabled = true;
     butErase.disabled = true;
     butProgram.disabled = true;
     try {
@@ -882,7 +1404,7 @@ async function clickErase() {
       errorMsg(e);
     } finally {
       butErase.disabled = false;
-      baudRate.disabled = false;
+      baudRateSelect.disabled = false;
       butProgram.disabled = getValidFiles().length == 0;
     }
   }
@@ -909,7 +1431,7 @@ async function clickProgram() {
     });
   };
 
-  baudRate.disabled = true;
+  baudRateSelect.disabled = true;
   butErase.disabled = true;
   butProgram.disabled = true;
   for (let i = 0; i < firmware.length; i++) {
@@ -943,7 +1465,7 @@ async function clickProgram() {
     progress[i].querySelector("div").style.width = "0";
   }
   butErase.disabled = false;
-  baudRate.disabled = false;
+  baudRateSelect.disabled = false;
   butProgram.disabled = getValidFiles().length == 0;
   logMsg("To run the new firmware, please reset your device.");
 }
@@ -1032,7 +1554,7 @@ async function clickReadFlash() {
 
   const defaultFilename = `flash_0x${offset.toString(16)}_0x${size.toString(16)}.bin`;
 
-  baudRate.disabled = true;
+  baudRateSelect.disabled = true;
   butErase.disabled = true;
   butProgram.disabled = true;
   butReadFlash.disabled = true;
@@ -1043,13 +1565,42 @@ async function clickReadFlash() {
   try {
     const progressBar = readProgress.querySelector("div");
 
+    // Prepare options object if advanced mode is enabled
+    // Option validation helpers
+    const validateOption = (name, value) => {
+      if (value === undefined) return undefined;
+      if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`Invalid ${name}: ${value}`);
+      }
+      return value;
+    };
+
+    let options = undefined;
+    let chunkSizeOpt, blockSizeOpt, maxInFlightOpt;
+    if (advancedMode.checked) {
+      chunkSizeOpt = validateOption("chunkSize", parseInt(chunkSizeSelect.value));
+      blockSizeOpt = validateOption("blockSize", parseInt(blockSizeSelect.value));
+      maxInFlightOpt = validateOption("maxInFlight", parseInt(maxInFlightSelect.value));
+      if ((blockSizeOpt ?? maxInFlightOpt) &&
+          (blockSizeOpt === undefined || maxInFlightOpt === undefined)) {
+        throw new Error("blockSize and maxInFlight must be provided together");
+      }
+      options = {
+        chunkSize: chunkSizeOpt,
+        blockSize: blockSizeOpt,
+        maxInFlight: maxInFlightOpt
+      };
+      logMsg(`Advanced mode: chunkSize=0x${options.chunkSize?.toString(16)}, blockSize=${options.blockSize}, maxInFlight=${options.maxInFlight}`);
+    }
+
     const data = await espStub.readFlash(
       offset,
       size,
       (packet, progress, totalSize) => {
         progressBar.style.width =
           Math.floor((progress / totalSize) * 100) + "%";
-      }
+      },
+      options
     );
 
     logMsg(`Successfully read ${data.length} bytes from flash`);
@@ -1062,8 +1613,6 @@ async function clickReadFlash() {
     const esptoolMod = await window.esptoolPackage;
     const fsType = esptoolMod.detectFilesystemFromImage(data, chipName);
     
-    logMsg(`Filesystem detection: ${fsType} (chipName: ${chipName})`);
-    
     if (fsType !== 'unknown') {
       logMsg(`Detected ${fsType} filesystem in read data`);
       
@@ -1090,7 +1639,7 @@ async function clickReadFlash() {
     readProgress.classList.add("hidden");
     readProgress.querySelector("div").style.width = "0";
     butErase.disabled = false;
-    baudRate.disabled = false;
+    baudRateSelect.disabled = false;
     butProgram.disabled = getValidFiles().length == 0;
     butReadFlash.disabled = false;
     readOffset.disabled = false;
@@ -1403,16 +1952,37 @@ function toggleUIConnected(connected) {
   
   if (connected) {
     lbl = "Disconnect";
-    // Auto-hide header after connection
+    isConnected = true;
+    
+    /* DISABLED: Auto-hide header after connection
     setTimeout(() => {
       header.classList.add("header-hidden");
       main.classList.add("no-header-padding");
     }, 2000); // Hide after 2 seconds
+    */
   } else {
+    isConnected = false;
     toggleUIToolbar(false);
-    // Show header when disconnected
+    
+    // Cleanup console if it was running
+    if (consoleInstance) {
+      consoleInstance.disconnect().catch(err => {
+        debugMsg("Error disconnecting console: " + err);
+      });
+      consoleInstance = null;
+    }
+    
+    // Hide console container, show commands, and uncheck switch
+    consoleContainer.classList.add("hidden");
+    const commands = document.getElementById("commands");
+    if (commands) commands.classList.remove("hidden");
+    consoleSwitch.checked = false;
+    saveSetting("console", false);
+    
+    /* DISABLED: Show header when disconnected
     header.classList.remove("header-hidden");
     main.classList.remove("no-header-padding");
+    */
   }
   butConnect.textContent = lbl;
 }
@@ -1420,13 +1990,26 @@ function toggleUIConnected(connected) {
 function loadAllSettings() {
   // Load all saved settings or defaults
   autoscroll.checked = loadSetting("autoscroll", true);
-  baudRate.value = loadSetting("baudrate", 2000000);
+  baudRateSelect.value = loadSetting("baudrate", 2000000);
   darkMode.checked = loadSetting("darkmode", false);
-  debugMode.checked = loadSetting("debugmode", true);
+  debugMode.checked = loadSetting("debugmode", false);
   showLog.checked = loadSetting("showlog", false);
+  consoleSwitch.checked = loadSetting("console", false);
+  advancedMode.checked = loadSetting("advanced", false);
+  
+  // Load advanced parameters
+  chunkSizeSelect.value = loadSetting("chunkSize", 0x4000); // 16 KB default
+  blockSizeSelect.value = loadSetting("blockSize", 4095); // 4095 B default
+  maxInFlightSelect.value = loadSetting("maxInFlight", 8190); // 8190 B default
   
   // Apply show log setting
   updateLogVisibility();
+  
+  // Don't show console container here - it will be initialized after connect
+  // if consoleSwitch.checked is true
+  
+  // Apply advanced mode visibility
+  updateAdvancedVisibility();
 }
 
 function loadSetting(setting, defaultValue) {
@@ -1586,15 +2169,14 @@ async function detectFilesystemType(offset, size) {
  */
 async function loadLittlefsModule() {
   if (!littlefsModulePromise) {
-    // Use absolute path from root for better compatibility with GitHub Pages
-    const basePath = window.location.pathname.endsWith('/') 
-      ? window.location.pathname 
-      : window.location.pathname.substring(0, window.location.pathname.lastIndexOf('/') + 1);
+    // Derive base path from current document URL (works for all hosting layouts)
+    const basePath = new URL(".", window.location.href).pathname;
     const modulePath = `${basePath}src/wasm/littlefs/index.js`;
     
     littlefsModulePromise = import(modulePath)
       .catch(error => {
-        console.error('Failed to load LittleFS module from:', modulePath, error);
+        errorMsg('Failed to load LittleFS module from: ' + modulePath);
+        debugMsg('LittleFS module load error: ' + error);
         littlefsModulePromise = null; // Reset on error so it can be retried
         throw error;
       });
@@ -1612,7 +2194,7 @@ function resetLittleFSState() {
       // Don't call destroy() - it can cause crashes
       // Just let garbage collection handle it
     } catch (e) {
-      console.error('Error cleaning up LittleFS:', e);
+      debugMsg('Error cleaning up LittleFS: ' + e);
     }
   }
   
@@ -1632,7 +2214,7 @@ function resetLittleFSState() {
       littlefsFileList.innerHTML = '';
     }
   } catch (e) {
-    console.error('Error resetting LittleFS UI:', e);
+    debugMsg('Error resetting LittleFS UI: ' + e);
   }
 }
 
@@ -1671,9 +2253,7 @@ async function openLittleFS(partition) {
     logMsg('Mounting LittleFS filesystem...');
     
     // Import constants from esptool module
-    const basePath = window.location.pathname.endsWith('/') 
-      ? window.location.pathname 
-      : window.location.pathname.substring(0, window.location.pathname.lastIndexOf('/') + 1);
+    const basePath = new URL(".", window.location.href).pathname;
     const esptoolModulePath = `${basePath}js/modules/esptool.js`;
     const { 
       LITTLEFS_BLOCK_SIZE_CANDIDATES,
@@ -1820,9 +2400,7 @@ async function openFatFS(partition) {
     }
     
     // Load FatFS module
-    const basePath = window.location.pathname.endsWith('/') 
-      ? window.location.pathname 
-      : window.location.pathname.substring(0, window.location.pathname.lastIndexOf('/') + 1);
+    const basePath = new URL(".", window.location.href).pathname;
     const modulePath = `${basePath}src/wasm/fatfs/index.js`;
     const module = await import(modulePath);
     const { createFatFSFromImage, createFatFS } = module;
@@ -1903,7 +2481,7 @@ async function openFatFS(partition) {
     logMsg('FatFS filesystem opened successfully');
   } catch (e) {
     errorMsg(`Failed to open FatFS: ${e.message || e}`);
-    console.error('FatFS open error:', e);
+    debugMsg('FatFS open error details: ' + e);
     resetLittleFSState();
   }
 }
@@ -1944,9 +2522,7 @@ async function openSPIFFS(partition) {
     logMsg(`Partition size: ${formatSize(partition.size)} (${partition.size} bytes)`);
     
     // Import SPIFFS module
-    const basePath = window.location.pathname.endsWith('/') 
-      ? window.location.pathname 
-      : window.location.pathname.substring(0, window.location.pathname.lastIndexOf('/') + 1);
+    const basePath = new URL(".", window.location.href).pathname;
     const modulePath = `${basePath}js/modules/esptool.js`;
 
     const { 
@@ -2163,10 +2739,9 @@ async function openSPIFFS(partition) {
     refreshLittleFS();
     
     logMsg('SPIFFS filesystem opened successfully');
-    logMsg('Note: SPIFFS is a flat filesystem - directories are not supported.');
   } catch (e) {
     errorMsg(`Failed to open SPIFFS: ${e.message || e}`);
-    console.error('SPIFFS open error:', e);
+    debugMsg('SPIFFS open error details: ' + e);
     resetLittleFSState();
   }
 }
@@ -2505,7 +3080,7 @@ function clickLittlefsClose() {
         currentLittleFS.destroy();
       }
     } catch (e) {
-      console.error(`Error destroying ${fsName}:`, e);
+      debugMsg(`Error destroying ${fsName}: ` + e);
     }
     currentLittleFS = null;
   }