esp32tool 1.0.0 → 1.1.0

package/README.md

@@ -1,31 +1,41 @@
 
-# ESP32Tool
 
-**ESP32Tool** is a JavaScript tool that lets you read and write data on ESP devices at lightning speed directly in your browser using WebSerial.
+# 🚀 ESP32Tool – The Ultimate ESP Filesystem Powerhouse
 
-**Features:**
-- Supports all common filesystems
-- Upload and download files easily – no complicated steps
-- Custom, high-performance flash access (up to 10x faster than esptool.py)
-- Automatic resume on read errors – no more broken flash operations
+**Flash. Manage. Dominate. All in your browser.**
 
-👉 **Try ESP32Tool in your browser:** [jason2866.github.io/esp32tool](https://jason2866.github.io/esp32tool)
+Meet **ESP32Tool** – your all-in-one, next-gen solution for ESP device management. Experience seamless firmware flashing, backup, and now, full filesystem control with just a few clicks. No drivers, no command line, no limits!
 
-👉 **Offline use:** Electron binaries are available in the [release section](https://github.com/Jason2866/esp32tool/releases).
+---
+
+✨ **What makes ESP32Tool shine?**
+
+- **Universal Filesystem Support:** Instantly detect, read, and write to LittleFS, SPIFFS, and FATFS – all major ESP filesystems, fully supported!
+- **Total File Control:** Effortlessly add or delete individual files. Upload, download, organize – your ESP, your rules.
+- **Lightning Fast:** Custom, high-performance flash access – up to 10x faster than esptool.py!
+- **Rock-Solid Reliability:** Automatic resume on read errors. No more broken operations, ever.
+- **Plug & Play:** Manage your ESP directly in the browser. No software installation needed.
+- **Offline Ready:** Prefer desktop? Grab the Electron app from our [releases](https://github.com/Jason2866/esp32tool/releases).
+
+> **Try it now:** [jason2866.github.io/esp32tool](https://jason2866.github.io/esp32tool)
 
 ---
 
-## Local Development
+## 🛠️ Developer Quickstart
 
 1. Clone this repository
 2. Install dependencies: `npm install`
-3. Start the development environment: `script/develop`
-4. Open in your browser: [http://localhost:5004/](http://localhost:5004/)
+3. Start the dev environment: `script/develop`
+4. Open [http://localhost:5004/](http://localhost:5004/) in your browser
 
 ---
 
-## Origin & Development
+## 🏆 Our Story
 
-This project was originally created by [Melissa LeBlanc-Williams](https://github.com/makermelissa). [Nabu Casa](https://www.nabucasa.com) ported the code to TypeScript and took over maintenance from Adafruit in March 2022. In July 2022, Nabu Casa stopped maintaining the project in favor of Espressif's [esptool-js](https://github.com/espressif/esptool-js). Due to instability, Adafruit updated their fork with Nabu Casa's changes in November 2022 and resumed maintenance. In December 2024, the backend was switched to Espressif's esptool-js. Since esptool.js remained buggy, this independent version was created. In December 2025, support for new MCUs, chip variants (P4 revisions), and optimized flash reading was added.
+Born from the minds of [Melissa LeBlanc-Williams](https://github.com/makermelissa), [Nabu Casa](https://www.nabucasa.com), Adafruit, and now supercharged by Jason2866, ESP32Tool has evolved into the most advanced, browser-based ESP management suite. With every update, we push the boundaries of what’s possible for your ESP devices.
+
+**Latest update:** December 2025 – Now with full LittleFS, SPIFFS, and FATFS support, plus file add/delete magic!
+
+---
 
-**Copyright:** Adafruit, Nabu Casa, and Johann Obermeier
+© Adafruit, Nabu Casa & Johann Obermeier

package/css/dark.css

@@ -154,3 +154,14 @@ input {
 .littlefs-fs-button:hover {
   background-color: #71ae1e;
 }
+
+/* ESP8266 Info Box - Dark Mode */
+.esp8266-info .info-box {
+  background-color: #2a2a2a;
+  border-color: #00a7e9;
+  color: #e0e0e0;
+}
+
+.esp8266-info .info-box strong {
+  color: #00a7e9;
+}

package/css/style.css

@@ -521,6 +521,17 @@ div.clear {
   cursor: pointer;
 }
 
+#commands .partition-table #butOpenFSManager {
+  background-color: #8ec641;
+  color: white;
+  border-color: #8ec641;
+}
+
+#commands .partition-table #butOpenFSManager:hover {
+  background-color: #71ae1e;
+  border-color: #71ae1e;
+}
+
 #commands .partition-table .progress-bar {
   width: 400px;
   margin-bottom: 10px;
@@ -561,6 +572,50 @@ div.clear {
   border-color: #00a7e9;
 }
 
+/* ESP8266 Filesystem Info Box */
+.esp8266-info {
+  width: 100%;
+  margin-top: 15px;
+}
+
+.esp8266-info .info-box {
+  background-color: #f8f9fa;
+  border: 2px solid #00a7e9;
+  border-radius: 8px;
+  padding: 15px 20px;
+  text-align: left;
+}
+
+.esp8266-info .info-box strong {
+  display: block;
+  font-size: 16px;
+  margin-bottom: 10px;
+  color: #00a7e9;
+}
+
+.esp8266-info .info-box p {
+  margin: 8px 0;
+  line-height: 1.5;
+}
+
+.esp8266-info .info-box ul {
+  margin: 10px 0;
+  padding-left: 20px;
+  list-style-type: none;
+}
+
+.esp8266-info .info-box ul li {
+  margin: 5px 0;
+  padding-left: 0;
+}
+
+.esp8266-info .info-box ul li strong {
+  display: inline;
+  font-size: 14px;
+  color: inherit;
+  margin: 0;
+}
+
 .justify {
   display: flex;
   justify-content: space-between;
@@ -868,3 +923,147 @@ div.clear {
   color: #fff;
   border-color: #71ae1e;
 }
+
+/* File Viewer Modal Styles */
+.file-viewer-content {
+  max-width: 900px;
+  width: 90vw;
+  max-height: 90vh;
+  display: flex;
+  flex-direction: column;
+  padding: 0;
+  overflow: hidden;
+  text-align: left;
+}
+
+.file-viewer-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 20px 30px;
+  border-bottom: 2px solid #e0e0e0;
+}
+
+.file-viewer-header h2 {
+  margin: 0;
+  font-size: 20px;
+  color: #333;
+}
+
+.close-button {
+  background: none;
+  border: none;
+  font-size: 28px;
+  color: #999;
+  cursor: pointer;
+  padding: 0;
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  transition: all 0.2s;
+}
+
+.close-button:hover {
+  background-color: #f0f0f0;
+  color: #333;
+}
+
+.file-viewer-info {
+  display: flex;
+  justify-content: space-between;
+  padding: 12px 30px;
+  background-color: #f8f8f8;
+  font-size: 13px;
+  color: #666;
+  border-bottom: 1px solid #e0e0e0;
+}
+
+.file-viewer-tabs {
+  display: flex;
+  padding: 0 30px;
+  background-color: #f8f8f8;
+  border-bottom: 2px solid #e0e0e0;
+}
+
+.tab-button {
+  background: none;
+  border: none;
+  padding: 12px 24px;
+  font-size: 14px;
+  font-weight: 600;
+  color: #666;
+  cursor: pointer;
+  border-bottom: 3px solid transparent;
+  transition: all 0.2s;
+  margin-bottom: -2px;
+}
+
+.tab-button:hover {
+  color: #333;
+  background-color: rgba(113, 174, 30, 0.1);
+}
+
+.tab-button.active {
+  color: #71ae1e;
+  border-bottom-color: #71ae1e;
+}
+
+.file-viewer-body {
+  flex: 1;
+  overflow: auto;
+  padding: 20px 30px;
+  background-color: #fff;
+  min-height: 300px;
+  max-height: calc(90vh - 250px);
+  text-align: left;
+}
+
+.file-viewer-body pre {
+  margin: 0;
+  font-family: "SF Mono", "Menlo", "Monaco", "Consolas", "Liberation Mono", "Courier New", monospace;
+  font-size: 13px;
+  line-height: 1.5;
+  white-space: pre;
+  overflow-x: auto;
+  color: #333;
+  tab-size: 4;
+  text-align: left;
+}
+
+.file-viewer-body .hex-view {
+  font-family: "SF Mono", "Menlo", "Monaco", "Consolas", "Liberation Mono", "Courier New", monospace;
+  font-size: 12px;
+  line-height: 1.6;
+}
+
+.hex-line {
+  display: flex;
+  margin-bottom: 2px;
+}
+
+.hex-offset {
+  color: #999;
+  margin-right: 20px;
+  min-width: 80px;
+}
+
+.hex-bytes {
+  color: #333;
+  margin-right: 20px;
+  min-width: 400px;
+}
+
+.hex-ascii {
+  color: #666;
+}
+
+.file-viewer-footer {
+  padding: 20px 30px;
+  border-top: 2px solid #e0e0e0;
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+}

package/dist/esp_loader.js

@@ -107,6 +107,9 @@ export class ESPLoader extends EventTarget {
             // Don't await this promise so it doesn't block rest of method.
             this.readLoop();
         }
+        // Drain input buffer first for CP210x compatibility on Windows
+        // This helps clear any stale data before sync
+        await this.drainInputBuffer(200);
         // Clear buffer again after starting read loop
         await this.flushSerialBuffers();
         await this.sync();
@@ -156,6 +159,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);

package/dist/index.d.ts

@@ -6,5 +6,6 @@ export { CHIP_FAMILY_ESP32, CHIP_FAMILY_ESP32S2, CHIP_FAMILY_ESP32S3, CHIP_FAMIL
 export declare const connect: (logger: Logger) => Promise<ESPLoader>;
 export { parsePartitionTable, getPartitionTableOffset, formatSize, } from "./partition";
 export type { Partition } from "./partition";
-export { FilesystemType, detectFilesystemType, detectFilesystemFromImage, getDefaultBlockSize, getBlockSizeCandidates, LITTLEFS_DEFAULT_BLOCK_SIZE, LITTLEFS_BLOCK_SIZE_CANDIDATES, FATFS_DEFAULT_BLOCK_SIZE, FATFS_BLOCK_SIZE_CANDIDATES, } from "./wasm/filesystems";
+export { FilesystemType, detectFilesystemType, detectFilesystemFromImage, getDefaultBlockSize, getBlockSizeCandidates, getESP8266FilesystemLayout, scanESP8266Filesystem, LITTLEFS_DEFAULT_BLOCK_SIZE, LITTLEFS_BLOCK_SIZE_CANDIDATES, FATFS_DEFAULT_BLOCK_SIZE, FATFS_BLOCK_SIZE_CANDIDATES, ESP8266_LITTLEFS_BLOCK_SIZE, ESP8266_LITTLEFS_BLOCK_SIZE_CANDIDATES, ESP8266_LITTLEFS_PAGE_SIZE, ESP8266_SPIFFS_PAGE_SIZE, ESP8266_SPIFFS_BLOCK_SIZE, } from "./wasm/filesystems";
+export type { ESP8266FilesystemLayout } from "./wasm/filesystems";
 export { SpiffsFS, SpiffsBuildConfig, SpiffsReader, DEFAULT_SPIFFS_CONFIG, type SpiffsFile, type SpiffsBuildConfigOptions, } from "./lib/spiffs/index";

package/dist/index.js

@@ -11,5 +11,5 @@ export const connect = async (logger) => {
     return new ESPLoader(port, logger);
 };
 export { parsePartitionTable, getPartitionTableOffset, formatSize, } from "./partition";
-export { FilesystemType, detectFilesystemType, detectFilesystemFromImage, getDefaultBlockSize, getBlockSizeCandidates, LITTLEFS_DEFAULT_BLOCK_SIZE, LITTLEFS_BLOCK_SIZE_CANDIDATES, FATFS_DEFAULT_BLOCK_SIZE, FATFS_BLOCK_SIZE_CANDIDATES, } from "./wasm/filesystems";
+export { FilesystemType, detectFilesystemType, detectFilesystemFromImage, getDefaultBlockSize, getBlockSizeCandidates, getESP8266FilesystemLayout, scanESP8266Filesystem, LITTLEFS_DEFAULT_BLOCK_SIZE, LITTLEFS_BLOCK_SIZE_CANDIDATES, FATFS_DEFAULT_BLOCK_SIZE, FATFS_BLOCK_SIZE_CANDIDATES, ESP8266_LITTLEFS_BLOCK_SIZE, ESP8266_LITTLEFS_BLOCK_SIZE_CANDIDATES, ESP8266_LITTLEFS_PAGE_SIZE, ESP8266_SPIFFS_PAGE_SIZE, ESP8266_SPIFFS_BLOCK_SIZE, } from "./wasm/filesystems";
 export { SpiffsFS, SpiffsBuildConfig, SpiffsReader, DEFAULT_SPIFFS_CONFIG, } from "./lib/spiffs/index";

package/dist/partition.d.ts

@@ -24,3 +24,11 @@ export declare function getPartitionTableOffset(): number;
  * Format size in human-readable format
  */
 export declare function formatSize(bytes: number): string;
+/**
+ * Detect filesystem type from image data
+ * Returns the detected filesystem type: 'littlefs', 'fatfs', 'spiffs', or 'unknown'
+ *
+ * This is a wrapper around detectFilesystemFromImage from filesystems.ts
+ * with fallback to partition subtype if detection fails.
+ */
+export declare function detectFilesystemType(data: Uint8Array, partitionSubtype?: number): string;

package/dist/partition.js

@@ -2,6 +2,7 @@
  * ESP32 Partition Table Parser
  * Based on ESP-IDF partition table format
  */
+import { detectFilesystemFromImage, FilesystemType } from "./wasm/filesystems";
 // Partition types
 const PARTITION_TYPES = {
     0x00: "app",
@@ -39,6 +40,7 @@ const DATA_SUBTYPES = {
     0x80: "esphttpd",
     0x81: "fat",
     0x82: "spiffs",
+    0x83: "littlefs",
 };
 const PARTITION_TABLE_OFFSET = 0x8000; // Default partition table offset
 const PARTITION_ENTRY_SIZE = 32;
@@ -127,3 +129,33 @@ export function formatSize(bytes) {
         return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
     }
 }
+/**
+ * Detect filesystem type from image data
+ * Returns the detected filesystem type: 'littlefs', 'fatfs', 'spiffs', or 'unknown'
+ *
+ * This is a wrapper around detectFilesystemFromImage from filesystems.ts
+ * with fallback to partition subtype if detection fails.
+ */
+export function detectFilesystemType(data, partitionSubtype) {
+    // Use the centralized detection function from filesystems.ts
+    const fsType = detectFilesystemFromImage(data);
+    // If detection succeeded, return the result
+    if (fsType !== FilesystemType.UNKNOWN) {
+        return fsType.toLowerCase();
+    }
+    // Fall back to partition table subtype if no clear signature found
+    if (partitionSubtype !== undefined) {
+        if (partitionSubtype === 0x81) {
+            return "fatfs";
+        }
+        else if (partitionSubtype === 0x82) {
+            // Subtype 0x82 can be either SPIFFS or LittleFS, default to SPIFFS
+            return "spiffs";
+        }
+        else if (partitionSubtype === 0x83) {
+            return "littlefs";
+        }
+    }
+    // Default to unknown
+    return "unknown";
+}

package/dist/wasm/filesystems.d.ts

@@ -3,6 +3,39 @@ export declare const LITTLEFS_DEFAULT_BLOCK_SIZE = 4096;
 export declare const LITTLEFS_BLOCK_SIZE_CANDIDATES: number[];
 export declare const FATFS_DEFAULT_BLOCK_SIZE = 4096;
 export declare const FATFS_BLOCK_SIZE_CANDIDATES: number[];
+export declare const ESP8266_LITTLEFS_BLOCK_SIZE = 8192;
+export declare const ESP8266_LITTLEFS_BLOCK_SIZE_CANDIDATES: number[];
+export declare const ESP8266_LITTLEFS_PAGE_SIZE = 256;
+export declare const ESP8266_SPIFFS_PAGE_SIZE = 256;
+export declare const ESP8266_SPIFFS_BLOCK_SIZE = 8192;
+/**
+ * ESP8266 filesystem layout information
+ */
+export interface ESP8266FilesystemLayout {
+    start: number;
+    end: number;
+    size: number;
+    page: number;
+    block: number;
+}
+/**
+ * Scan ESP8266 flash for filesystem by detecting filesystem signatures
+ * Reads actual block_count from LittleFS superblock for accurate size detection
+ *
+ * @param flashData - Flash data starting at scanOffset
+ * @param scanOffset - The offset in flash where this data starts
+ * @param flashSize - Total flash size in bytes
+ * @returns Detected filesystem layout or null
+ */
+export declare function scanESP8266Filesystem(flashData: Uint8Array, scanOffset: number, flashSize: number): ESP8266FilesystemLayout | null;
+/**
+ * Get common ESP8266 filesystem layouts as fallback
+ * Used when we can't scan the actual flash
+ *
+ * @param flashSizeMB - Flash size in megabytes
+ * @returns Array of possible filesystem layouts (most common first)
+ */
+export declare function getESP8266FilesystemLayout(flashSizeMB: number): ESP8266FilesystemLayout[];
 /**
  * Filesystem types based on partition subtype
  */
@@ -20,14 +53,17 @@ export declare enum FilesystemType {
 export declare function detectFilesystemType(partition: Partition): FilesystemType;
 /**
  * Detect filesystem type from image data
- * Reads the first 8KB to identify filesystem by magic headers and ASCII signatures
+ * Properly validates LittleFS superblock structure at correct offsets
+ *
+ * @param imageData - Binary filesystem image data
+ * @param chipName - Optional chip name for ESP8266-specific detection (e.g. "ESP8266")
  */
-export declare function detectFilesystemFromImage(imageData: Uint8Array): FilesystemType;
+export declare function detectFilesystemFromImage(imageData: Uint8Array, chipName?: string): FilesystemType;
 /**
- * Get appropriate block size for filesystem type
+ * Get appropriate block size for filesystem type and chip
  */
-export declare function getDefaultBlockSize(fsType: FilesystemType): number;
+export declare function getDefaultBlockSize(fsType: FilesystemType, chipName?: string): number;
 /**
- * Get block size candidates for filesystem type
+ * Get block size candidates for filesystem type and chip
  */
-export declare function getBlockSizeCandidates(fsType: FilesystemType): number[];
+export declare function getBlockSizeCandidates(fsType: FilesystemType, chipName?: string): number[];