esp32tool 1.0.0

package/src/index.ts

@@ -0,0 +1,63 @@
+/// <reference types="@types/w3c-web-serial" />
+
+import { ESP_ROM_BAUD, Logger } from "./const";
+import { ESPLoader } from "./esp_loader";
+
+export type { Logger } from "./const";
+export { ESPLoader } from "./esp_loader";
+
+export {
+  CHIP_FAMILY_ESP32,
+  CHIP_FAMILY_ESP32S2,
+  CHIP_FAMILY_ESP32S3,
+  CHIP_FAMILY_ESP8266,
+  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,
+} from "./const";
+
+export const connect = async (logger: Logger) => {
+  // - Request a port and open a connection.
+  const port = await navigator.serial.requestPort();
+
+  await port.open({ baudRate: ESP_ROM_BAUD });
+
+  logger.log("Connected successfully.");
+
+  return new ESPLoader(port, logger);
+};
+
+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 {
+  SpiffsFS,
+  SpiffsBuildConfig,
+  SpiffsReader,
+  DEFAULT_SPIFFS_CONFIG,
+  type SpiffsFile,
+  type SpiffsBuildConfigOptions,
+} from "./lib/spiffs/index";

package/src/lib/spiffs/index.ts

@@ -0,0 +1,22 @@
+/**
+ * SPIFFS Module Entry Point
+ */
+
+export { SpiffsFS, type SpiffsFile } from "./spiffs";
+export {
+  SpiffsBuildConfig,
+  type SpiffsBuildConfigOptions,
+  SpiffsFullError,
+} from "./spiffsConfig";
+export { SpiffsReader } from "./spiffsReader";
+
+// Default ESP32 SPIFFS configuration
+export const DEFAULT_SPIFFS_CONFIG = {
+  pageSize: 256,
+  blockSize: 4096,
+  objNameLen: 32,
+  metaLen: 4,
+  useMagic: true,
+  useMagicLen: true,
+  alignedObjIxTables: false,
+};

package/src/lib/spiffs/spiffs.ts

@@ -0,0 +1,175 @@
+/**
+ * SPIFFS Filesystem Implementation
+ * Based on ESP-IDF spiffsgen.py
+ */
+
+import { SpiffsBuildConfig, SpiffsFullError } from "./spiffsConfig";
+import { SpiffsBlock } from "./spiffsBlock";
+
+export interface SpiffsFile {
+  name: string;
+  size: number;
+  data: Uint8Array;
+}
+
+export class SpiffsFS {
+  private imgSize: number;
+  private buildConfig: SpiffsBuildConfig;
+  private blocks: SpiffsBlock[];
+  private blocksLim: number;
+  private remainingBlocks: number;
+  private curObjId: number;
+
+  constructor(imgSize: number, buildConfig: SpiffsBuildConfig) {
+    if (imgSize % buildConfig.blockSize !== 0) {
+      throw new Error("image size should be a multiple of block size");
+    }
+
+    this.imgSize = imgSize;
+    this.buildConfig = buildConfig;
+    this.blocks = [];
+    this.blocksLim = Math.floor(this.imgSize / this.buildConfig.blockSize);
+    this.remainingBlocks = this.blocksLim;
+    this.curObjId = 1; // starting object id
+  }
+
+  private createBlock(): SpiffsBlock {
+    if (this.isFull()) {
+      throw new SpiffsFullError("the image size has been exceeded");
+    }
+
+    const block = new SpiffsBlock(this.blocks.length, this.buildConfig);
+    this.blocks.push(block);
+    this.remainingBlocks--;
+    return block;
+  }
+
+  isFull(): boolean {
+    return this.remainingBlocks <= 0;
+  }
+
+  createFile(imgPath: string, contents: Uint8Array): void {
+    if (imgPath.length > this.buildConfig.objNameLen) {
+      throw new Error(`object name '${imgPath}' too long`);
+    }
+
+    const name = imgPath;
+    let offset = 0;
+
+    try {
+      const block = this.blocks[this.blocks.length - 1];
+      block.beginObj(this.curObjId, contents.length, name);
+    } catch {
+      const block = this.createBlock();
+      block.beginObj(this.curObjId, contents.length, name);
+    }
+
+    while (offset < contents.length) {
+      const chunkSize = Math.min(
+        this.buildConfig.OBJ_DATA_PAGE_CONTENT_LEN,
+        contents.length - offset,
+      );
+      const contentsChunk = contents.slice(offset, offset + chunkSize);
+
+      try {
+        const block = this.blocks[this.blocks.length - 1];
+        try {
+          block.updateObj(contentsChunk);
+        } catch (e) {
+          if (e instanceof SpiffsFullError) {
+            if (block.isFull()) {
+              throw e;
+            }
+            // Object index exhausted, write another object index page
+            block.beginObj(
+              this.curObjId,
+              contents.length,
+              name,
+              block.currentObjIndexSpanIx,
+              block.currentObjDataSpanIx,
+            );
+            continue;
+          }
+          throw e;
+        }
+      } catch (e) {
+        if (e instanceof SpiffsFullError) {
+          // All pages in block exhausted, create new block
+          const prevBlock = this.blocks[this.blocks.length - 1];
+          const block = this.createBlock();
+          block.currentObjId = prevBlock.currentObjId;
+          block.currentObjIdxPage = prevBlock.currentObjIdxPage;
+          block.currentObjDataSpanIx = prevBlock.currentObjDataSpanIx;
+          block.currentObjIndexSpanIx = prevBlock.currentObjIndexSpanIx;
+          continue;
+        }
+        throw e;
+      }
+
+      offset += chunkSize;
+    }
+
+    const block = this.blocks[this.blocks.length - 1];
+    block.endObj();
+    this.curObjId++;
+  }
+
+  toBinary(): Uint8Array {
+    const allBlocks: Uint8Array[] = [];
+
+    for (const block of this.blocks) {
+      allBlocks.push(block.toBinary(this.blocksLim));
+    }
+
+    let bix = this.blocks.length;
+    let remaining = this.remainingBlocks;
+
+    if (this.buildConfig.useMagic) {
+      // Create empty blocks with magic numbers
+      while (remaining > 0) {
+        const block = new SpiffsBlock(bix, this.buildConfig);
+        allBlocks.push(block.toBinary(this.blocksLim));
+        remaining--;
+        bix++;
+      }
+    } else {
+      // Fill remaining space with 0xFF
+      const remainingSize =
+        this.imgSize - allBlocks.length * this.buildConfig.blockSize;
+      if (remainingSize > 0) {
+        const padding = new Uint8Array(remainingSize);
+        padding.fill(0xff);
+        allBlocks.push(padding);
+      }
+    }
+
+    // Concatenate all blocks
+    const totalSize = allBlocks.reduce((sum, block) => sum + block.length, 0);
+    const img = new Uint8Array(totalSize);
+    let offset = 0;
+    for (const block of allBlocks) {
+      img.set(block, offset);
+      offset += block.length;
+    }
+
+    return img;
+  }
+
+  listFiles(): SpiffsFile[] {
+    // This would require parsing the blocks - implement in fromBinary
+    throw new Error("listFiles requires fromBinary to be called first");
+  }
+
+  readFile(): Uint8Array {
+    // This would require parsing the blocks - implement in fromBinary
+    throw new Error("readFile requires fromBinary to be called first");
+  }
+
+  deleteFile(): void {
+    // SPIFFS doesn't support in-place deletion
+    // Need to recreate filesystem without the file
+    throw new Error(
+      "deleteFile not yet implemented - requires filesystem recreation",
+    );
+  }
+}

package/src/lib/spiffs/spiffsBlock.ts

@@ -0,0 +1,204 @@
+/**
+ * SPIFFS Block Class
+ * Based on ESP-IDF spiffsgen.py
+ */
+
+import { SpiffsBuildConfig, SpiffsFullError } from "./spiffsConfig";
+import {
+  SpiffsPage,
+  SpiffsObjLuPage,
+  SpiffsObjIndexPage,
+  SpiffsObjDataPage,
+  SpiffsObjPageWithIdx,
+} from "./spiffsPage";
+
+export class SpiffsBlock {
+  private buildConfig: SpiffsBuildConfig;
+  private offset: number;
+  private remainingPages: number;
+  private pages: SpiffsPage[];
+  private bix: number;
+  private luPages: SpiffsObjLuPage[];
+  private luPageIter: Iterator<SpiffsObjLuPage>;
+  private luPage: SpiffsObjLuPage | null;
+
+  private curObjIndexSpanIx: number;
+  private curObjDataSpanIx: number;
+  private curObjId: number;
+  private curObjIdxPage: SpiffsObjIndexPage | null;
+
+  constructor(bix: number, buildConfig: SpiffsBuildConfig) {
+    this.buildConfig = buildConfig;
+    this.offset = bix * this.buildConfig.blockSize;
+    this.remainingPages = this.buildConfig.OBJ_USABLE_PAGES_PER_BLOCK;
+    this.pages = [];
+    this.bix = bix;
+
+    this.luPages = [];
+    for (let i = 0; i < this.buildConfig.OBJ_LU_PAGES_PER_BLOCK; i++) {
+      const page = new SpiffsObjLuPage(this.bix, this.buildConfig);
+      this.luPages.push(page);
+    }
+    this.pages.push(...this.luPages);
+
+    this.luPageIter = this.luPages[Symbol.iterator]();
+    this.luPage = this.luPageIter.next().value || null;
+
+    this.curObjIndexSpanIx = 0;
+    this.curObjDataSpanIx = 0;
+    this.curObjId = 0;
+    this.curObjIdxPage = null;
+  }
+
+  private reset(): void {
+    this.curObjIndexSpanIx = 0;
+    this.curObjDataSpanIx = 0;
+    this.curObjId = 0;
+    this.curObjIdxPage = null;
+  }
+
+  private registerPage(page: SpiffsObjPageWithIdx): void {
+    if (page instanceof SpiffsObjDataPage) {
+      if (!this.curObjIdxPage) {
+        throw new Error("No current object index page");
+      }
+      this.curObjIdxPage.registerPage(page);
+    }
+
+    try {
+      if (!this.luPage) {
+        throw new SpiffsFullError();
+      }
+      this.luPage.registerPage(page);
+    } catch (e) {
+      if (e instanceof SpiffsFullError) {
+        const next = this.luPageIter.next();
+        if (next.done) {
+          throw new Error(
+            "Invalid attempt to add page to a block when there is no more space in lookup",
+          );
+        }
+        this.luPage = next.value;
+        this.luPage.registerPage(page);
+      } else {
+        throw e;
+      }
+    }
+
+    this.pages.push(page);
+  }
+
+  beginObj(
+    objId: number,
+    size: number,
+    name: string,
+    objIndexSpanIx = 0,
+    objDataSpanIx = 0,
+  ): void {
+    if (this.remainingPages <= 0) {
+      throw new SpiffsFullError();
+    }
+
+    this.reset();
+    this.curObjId = objId;
+    this.curObjIndexSpanIx = objIndexSpanIx;
+    this.curObjDataSpanIx = objDataSpanIx;
+
+    const page = new SpiffsObjIndexPage(
+      objId,
+      this.curObjIndexSpanIx,
+      size,
+      name,
+      this.buildConfig,
+    );
+    this.registerPage(page);
+    this.curObjIdxPage = page;
+    this.remainingPages--;
+    this.curObjIndexSpanIx++;
+  }
+
+  updateObj(contents: Uint8Array): void {
+    if (this.remainingPages <= 0) {
+      throw new SpiffsFullError();
+    }
+
+    const page = new SpiffsObjDataPage(
+      this.offset + this.pages.length * this.buildConfig.pageSize,
+      this.curObjId,
+      this.curObjDataSpanIx,
+      contents,
+      this.buildConfig,
+    );
+    this.registerPage(page);
+    this.curObjDataSpanIx++;
+    this.remainingPages--;
+  }
+
+  endObj(): void {
+    this.reset();
+  }
+
+  isFull(): boolean {
+    return this.remainingPages <= 0;
+  }
+
+  toBinary(blocksLim: number): Uint8Array {
+    const img = new Uint8Array(this.buildConfig.blockSize);
+    img.fill(0xff);
+
+    let offset = 0;
+    if (this.buildConfig.useMagic) {
+      for (let idx = 0; idx < this.pages.length; idx++) {
+        const page = this.pages[idx];
+        if (idx === this.buildConfig.OBJ_LU_PAGES_PER_BLOCK - 1) {
+          if (page instanceof SpiffsObjLuPage) {
+            page.magicfy(blocksLim);
+          }
+        }
+        const pageBinary = page.toBinary();
+        img.set(pageBinary, offset);
+        offset += pageBinary.length;
+      }
+    } else {
+      for (const page of this.pages) {
+        const pageBinary = page.toBinary();
+        img.set(pageBinary, offset);
+        offset += pageBinary.length;
+      }
+    }
+
+    return img;
+  }
+
+  get currentObjIndexSpanIx(): number {
+    return this.curObjIndexSpanIx;
+  }
+
+  get currentObjDataSpanIx(): number {
+    return this.curObjDataSpanIx;
+  }
+
+  get currentObjId(): number {
+    return this.curObjId;
+  }
+
+  get currentObjIdxPage(): SpiffsObjIndexPage | null {
+    return this.curObjIdxPage;
+  }
+
+  set currentObjId(value: number) {
+    this.curObjId = value;
+  }
+
+  set currentObjIdxPage(value: SpiffsObjIndexPage | null) {
+    this.curObjIdxPage = value;
+  }
+
+  set currentObjDataSpanIx(value: number) {
+    this.curObjDataSpanIx = value;
+  }
+
+  set currentObjIndexSpanIx(value: number) {
+    this.curObjIndexSpanIx = value;
+  }
+}

package/src/lib/spiffs/spiffsConfig.ts

@@ -0,0 +1,140 @@
+/**
+ * SPIFFS Build Configuration
+ * Based on ESP-IDF spiffsgen.py
+ */
+
+export const SPIFFS_PH_FLAG_USED_FINAL_INDEX = 0xf8;
+export const SPIFFS_PH_FLAG_USED_FINAL = 0xfc;
+export const SPIFFS_PH_FLAG_LEN = 1;
+export const SPIFFS_PH_IX_SIZE_LEN = 4;
+export const SPIFFS_PH_IX_OBJ_TYPE_LEN = 1;
+export const SPIFFS_TYPE_FILE = 1;
+
+// Based on typedefs under spiffs_config.h
+export const SPIFFS_OBJ_ID_LEN = 2; // spiffs_obj_id
+export const SPIFFS_SPAN_IX_LEN = 2; // spiffs_span_ix
+export const SPIFFS_PAGE_IX_LEN = 2; // spiffs_page_ix
+export const SPIFFS_BLOCK_IX_LEN = 2; // spiffs_block_ix
+
+export interface SpiffsBuildConfigOptions {
+  pageSize: number;
+  blockSize: number;
+  objNameLen?: number;
+  metaLen?: number;
+  pageIxLen?: number;
+  blockIxLen?: number;
+  objIdLen?: number;
+  spanIxLen?: number;
+  packed?: boolean;
+  aligned?: boolean;
+  endianness?: "little" | "big";
+  useMagic?: boolean;
+  useMagicLen?: boolean;
+  alignedObjIxTables?: boolean;
+}
+
+export class SpiffsBuildConfig {
+  pageSize: number;
+  blockSize: number;
+  objIdLen: number;
+  spanIxLen: number;
+  packed: boolean;
+  aligned: boolean;
+  objNameLen: number;
+  metaLen: number;
+  pageIxLen: number;
+  blockIxLen: number;
+  endianness: "little" | "big";
+  useMagic: boolean;
+  useMagicLen: boolean;
+  alignedObjIxTables: boolean;
+
+  PAGES_PER_BLOCK: number;
+  OBJ_LU_PAGES_PER_BLOCK: number;
+  OBJ_USABLE_PAGES_PER_BLOCK: number;
+  OBJ_LU_PAGES_OBJ_IDS_LIM: number;
+  OBJ_DATA_PAGE_HEADER_LEN: number;
+  OBJ_DATA_PAGE_HEADER_LEN_ALIGNED: number;
+  OBJ_DATA_PAGE_HEADER_LEN_ALIGNED_PAD: number;
+  OBJ_DATA_PAGE_CONTENT_LEN: number;
+  OBJ_INDEX_PAGES_HEADER_LEN: number;
+  OBJ_INDEX_PAGES_HEADER_LEN_ALIGNED: number;
+  OBJ_INDEX_PAGES_HEADER_LEN_ALIGNED_PAD: number;
+  OBJ_INDEX_PAGES_OBJ_IDS_HEAD_LIM: number;
+  OBJ_INDEX_PAGES_OBJ_IDS_LIM: number;
+
+  constructor(options: SpiffsBuildConfigOptions) {
+    if (options.blockSize % options.pageSize !== 0) {
+      throw new Error("block size should be a multiple of page size");
+    }
+
+    this.pageSize = options.pageSize;
+    this.blockSize = options.blockSize;
+    this.objIdLen = options.objIdLen ?? SPIFFS_OBJ_ID_LEN;
+    this.spanIxLen = options.spanIxLen ?? SPIFFS_SPAN_IX_LEN;
+    this.packed = options.packed ?? true;
+    this.aligned = options.aligned ?? true;
+    this.objNameLen = options.objNameLen ?? 32;
+    this.metaLen = options.metaLen ?? 4;
+    this.pageIxLen = options.pageIxLen ?? SPIFFS_PAGE_IX_LEN;
+    this.blockIxLen = options.blockIxLen ?? SPIFFS_BLOCK_IX_LEN;
+    this.endianness = options.endianness ?? "little";
+    this.useMagic = options.useMagic ?? true;
+    this.useMagicLen = options.useMagicLen ?? true;
+    this.alignedObjIxTables = options.alignedObjIxTables ?? false;
+
+    this.PAGES_PER_BLOCK = Math.floor(this.blockSize / this.pageSize);
+    this.OBJ_LU_PAGES_PER_BLOCK = Math.ceil(
+      ((this.blockSize / this.pageSize) * this.objIdLen) / this.pageSize,
+    );
+    this.OBJ_USABLE_PAGES_PER_BLOCK =
+      this.PAGES_PER_BLOCK - this.OBJ_LU_PAGES_PER_BLOCK;
+    this.OBJ_LU_PAGES_OBJ_IDS_LIM = Math.floor(this.pageSize / this.objIdLen);
+
+    this.OBJ_DATA_PAGE_HEADER_LEN =
+      this.objIdLen + this.spanIxLen + SPIFFS_PH_FLAG_LEN;
+    const pad =
+      4 -
+      (this.OBJ_DATA_PAGE_HEADER_LEN % 4 === 0
+        ? 4
+        : this.OBJ_DATA_PAGE_HEADER_LEN % 4);
+    this.OBJ_DATA_PAGE_HEADER_LEN_ALIGNED = this.OBJ_DATA_PAGE_HEADER_LEN + pad;
+    this.OBJ_DATA_PAGE_HEADER_LEN_ALIGNED_PAD = pad;
+    this.OBJ_DATA_PAGE_CONTENT_LEN =
+      this.pageSize - this.OBJ_DATA_PAGE_HEADER_LEN;
+
+    this.OBJ_INDEX_PAGES_HEADER_LEN =
+      this.OBJ_DATA_PAGE_HEADER_LEN_ALIGNED +
+      SPIFFS_PH_IX_SIZE_LEN +
+      SPIFFS_PH_IX_OBJ_TYPE_LEN +
+      this.objNameLen +
+      this.metaLen;
+
+    if (this.alignedObjIxTables) {
+      this.OBJ_INDEX_PAGES_HEADER_LEN_ALIGNED =
+        (this.OBJ_INDEX_PAGES_HEADER_LEN + SPIFFS_PAGE_IX_LEN - 1) &
+        ~(SPIFFS_PAGE_IX_LEN - 1);
+      this.OBJ_INDEX_PAGES_HEADER_LEN_ALIGNED_PAD =
+        this.OBJ_INDEX_PAGES_HEADER_LEN_ALIGNED -
+        this.OBJ_INDEX_PAGES_HEADER_LEN;
+    } else {
+      this.OBJ_INDEX_PAGES_HEADER_LEN_ALIGNED = this.OBJ_INDEX_PAGES_HEADER_LEN;
+      this.OBJ_INDEX_PAGES_HEADER_LEN_ALIGNED_PAD = 0;
+    }
+
+    this.OBJ_INDEX_PAGES_OBJ_IDS_HEAD_LIM = Math.floor(
+      (this.pageSize - this.OBJ_INDEX_PAGES_HEADER_LEN_ALIGNED) /
+        this.blockIxLen,
+    );
+    this.OBJ_INDEX_PAGES_OBJ_IDS_LIM = Math.floor(
+      (this.pageSize - this.OBJ_DATA_PAGE_HEADER_LEN_ALIGNED) / this.blockIxLen,
+    );
+  }
+}
+
+export class SpiffsFullError extends Error {
+  constructor(message = "SPIFFS is full") {
+    super(message);
+    this.name = "SpiffsFullError";
+  }
+}