esp32tool 1.0.0

package/src/lib/spiffs/spiffsPage.ts

@@ -0,0 +1,357 @@
+/**
+ * SPIFFS Page Classes
+ * Based on ESP-IDF spiffsgen.py
+ */
+
+import {
+  SpiffsBuildConfig,
+  SpiffsFullError,
+  SPIFFS_PH_FLAG_USED_FINAL_INDEX,
+  SPIFFS_PH_FLAG_USED_FINAL,
+  SPIFFS_TYPE_FILE,
+} from "./spiffsConfig";
+
+export abstract class SpiffsPage {
+  protected buildConfig: SpiffsBuildConfig;
+  protected bix: number;
+
+  constructor(bix: number, buildConfig: SpiffsBuildConfig) {
+    this.buildConfig = buildConfig;
+    this.bix = bix;
+  }
+
+  abstract toBinary(): Uint8Array;
+
+  protected pack(format: string, ...values: number[]): Uint8Array {
+    const buffer = new ArrayBuffer(this.calcSize(format));
+    const view = new DataView(buffer);
+    let offset = 0;
+
+    for (let i = 0; i < format.length; i++) {
+      const type = format[i];
+      const value = values[i];
+
+      switch (type) {
+        case "B": // unsigned char (1 byte)
+          view.setUint8(offset, value);
+          offset += 1;
+          break;
+        case "H": // unsigned short (2 bytes)
+          if (this.buildConfig.endianness === "little") {
+            view.setUint16(offset, value, true);
+          } else {
+            view.setUint16(offset, value, false);
+          }
+          offset += 2;
+          break;
+        case "I": // unsigned int (4 bytes)
+          if (this.buildConfig.endianness === "little") {
+            view.setUint32(offset, value, true);
+          } else {
+            view.setUint32(offset, value, false);
+          }
+          offset += 4;
+          break;
+      }
+    }
+
+    return new Uint8Array(buffer);
+  }
+
+  protected unpack(format: string, data: Uint8Array, offset = 0): number[] {
+    const view = new DataView(data.buffer, data.byteOffset + offset);
+    const results: number[] = [];
+    let pos = 0;
+
+    for (const type of format) {
+      switch (type) {
+        case "B":
+          results.push(view.getUint8(pos));
+          pos += 1;
+          break;
+        case "H":
+          results.push(
+            this.buildConfig.endianness === "little"
+              ? view.getUint16(pos, true)
+              : view.getUint16(pos, false),
+          );
+          pos += 2;
+          break;
+        case "I":
+          results.push(
+            this.buildConfig.endianness === "little"
+              ? view.getUint32(pos, true)
+              : view.getUint32(pos, false),
+          );
+          pos += 4;
+          break;
+      }
+    }
+
+    return results;
+  }
+
+  private calcSize(format: string): number {
+    let size = 0;
+    for (const type of format) {
+      switch (type) {
+        case "B":
+          size += 1;
+          break;
+        case "H":
+          size += 2;
+          break;
+        case "I":
+          size += 4;
+          break;
+      }
+    }
+    return size;
+  }
+}
+
+export abstract class SpiffsObjPageWithIdx extends SpiffsPage {
+  protected objId: number;
+
+  constructor(objId: number, buildConfig: SpiffsBuildConfig) {
+    super(0, buildConfig);
+    this.objId = objId;
+  }
+
+  getObjId(): number {
+    return this.objId;
+  }
+}
+
+export class SpiffsObjLuPage extends SpiffsPage {
+  private objIdsLimit: number;
+  private objIds: Array<[number, string]>; // [objId, pageType]
+
+  constructor(bix: number, buildConfig: SpiffsBuildConfig) {
+    super(bix, buildConfig);
+    this.objIdsLimit = this.buildConfig.OBJ_LU_PAGES_OBJ_IDS_LIM;
+    this.objIds = [];
+  }
+
+  private calcMagic(blocksLim: number): number {
+    let magic = 0x20140529 ^ this.buildConfig.pageSize;
+    if (this.buildConfig.useMagicLen) {
+      magic = magic ^ (blocksLim - this.bix);
+    }
+    const mask = (1 << (8 * this.buildConfig.objIdLen)) - 1;
+    return magic & mask;
+  }
+
+  registerPage(page: SpiffsObjPageWithIdx): void {
+    if (this.objIdsLimit <= 0) {
+      throw new SpiffsFullError();
+    }
+    const pageType = page instanceof SpiffsObjIndexPage ? "index" : "data";
+    this.objIds.push([page.getObjId(), pageType]);
+    this.objIdsLimit--;
+  }
+
+  toBinary(): Uint8Array {
+    const img = new Uint8Array(this.buildConfig.pageSize);
+    img.fill(0xff);
+
+    let offset = 0;
+    for (const [objId, pageType] of this.objIds) {
+      let id = objId;
+      if (pageType === "index") {
+        id ^= 1 << (this.buildConfig.objIdLen * 8 - 1);
+      }
+
+      const packed = this.pack(
+        this.buildConfig.objIdLen === 1
+          ? "B"
+          : this.buildConfig.objIdLen === 2
+            ? "H"
+            : "I",
+        id,
+      );
+      img.set(packed, offset);
+      offset += packed.length;
+    }
+
+    return img;
+  }
+
+  magicfy(blocksLim: number): void {
+    const remaining = this.objIdsLimit;
+    const emptyObjId = (1 << (this.buildConfig.objIdLen * 8)) - 1;
+
+    if (remaining >= 2) {
+      for (let i = 0; i < remaining; i++) {
+        if (i === remaining - 2) {
+          this.objIds.push([this.calcMagic(blocksLim), "data"]);
+          break;
+        } else {
+          this.objIds.push([emptyObjId, "data"]);
+        }
+        this.objIdsLimit--;
+      }
+    }
+  }
+}
+
+export class SpiffsObjIndexPage extends SpiffsObjPageWithIdx {
+  private spanIx: number;
+  private name: string;
+  private size: number;
+  private pagesLim: number;
+  private pages: number[];
+
+  constructor(
+    objId: number,
+    spanIx: number,
+    size: number,
+    name: string,
+    buildConfig: SpiffsBuildConfig,
+  ) {
+    super(objId, buildConfig);
+    this.spanIx = spanIx;
+    this.name = name;
+    this.size = size;
+
+    if (this.spanIx === 0) {
+      this.pagesLim = this.buildConfig.OBJ_INDEX_PAGES_OBJ_IDS_HEAD_LIM;
+    } else {
+      this.pagesLim = this.buildConfig.OBJ_INDEX_PAGES_OBJ_IDS_LIM;
+    }
+    this.pages = [];
+  }
+
+  registerPage(page: SpiffsObjDataPage): void {
+    if (this.pagesLim <= 0) {
+      throw new SpiffsFullError();
+    }
+    this.pages.push(page.offset);
+    this.pagesLim--;
+  }
+
+  toBinary(): Uint8Array {
+    const img = new Uint8Array(this.buildConfig.pageSize);
+    img.fill(0xff);
+
+    const objId = this.objId ^ (1 << (this.buildConfig.objIdLen * 8 - 1));
+
+    const format =
+      (this.buildConfig.objIdLen === 1
+        ? "B"
+        : this.buildConfig.objIdLen === 2
+          ? "H"
+          : "I") +
+      (this.buildConfig.spanIxLen === 1
+        ? "B"
+        : this.buildConfig.spanIxLen === 2
+          ? "H"
+          : "I") +
+      "B";
+
+    let offset = 0;
+    const header = this.pack(
+      format,
+      objId,
+      this.spanIx,
+      SPIFFS_PH_FLAG_USED_FINAL_INDEX,
+    );
+    img.set(header, offset);
+    offset += header.length;
+
+    // Add padding
+    offset += this.buildConfig.OBJ_DATA_PAGE_HEADER_LEN_ALIGNED_PAD;
+
+    // If first index page, add filename, type and size
+    if (this.spanIx === 0) {
+      const sizeType = this.pack("IB", this.size, SPIFFS_TYPE_FILE);
+      img.set(sizeType, offset);
+      offset += sizeType.length;
+
+      // Write filename with proper null-termination
+      const nameBytes = new TextEncoder().encode(this.name);
+      // Ensure we don't exceed objNameLen
+      const bytesToWrite = Math.min(
+        nameBytes.length,
+        this.buildConfig.objNameLen,
+      );
+      img.set(nameBytes.slice(0, bytesToWrite), offset);
+      // The rest is already 0xFF from img.fill(0xff), but SPIFFS expects 0x00 for unused name bytes
+      // Fill remaining name bytes with 0x00
+      for (let i = bytesToWrite; i < this.buildConfig.objNameLen; i++) {
+        img[offset + i] = 0x00;
+      }
+      offset +=
+        this.buildConfig.objNameLen +
+        this.buildConfig.metaLen +
+        this.buildConfig.OBJ_INDEX_PAGES_HEADER_LEN_ALIGNED_PAD;
+    }
+
+    // Add page indices
+    for (const page of this.pages) {
+      // Calculate page index by dividing page offset by page size
+      // pageSize is always a power of 2, so integer division is safe
+      const pageIx = Math.floor(page / this.buildConfig.pageSize);
+      const pageIxPacked = this.pack(
+        this.buildConfig.pageIxLen === 1
+          ? "B"
+          : this.buildConfig.pageIxLen === 2
+            ? "H"
+            : "I",
+        pageIx,
+      );
+      img.set(pageIxPacked, offset);
+      offset += pageIxPacked.length;
+    }
+
+    return img;
+  }
+}
+
+export class SpiffsObjDataPage extends SpiffsObjPageWithIdx {
+  offset: number;
+  private spanIx: number;
+  private contents: Uint8Array;
+
+  constructor(
+    offset: number,
+    objId: number,
+    spanIx: number,
+    contents: Uint8Array,
+    buildConfig: SpiffsBuildConfig,
+  ) {
+    super(objId, buildConfig);
+    this.offset = offset;
+    this.spanIx = spanIx;
+    this.contents = contents;
+  }
+
+  toBinary(): Uint8Array {
+    const img = new Uint8Array(this.buildConfig.pageSize);
+    img.fill(0xff);
+
+    const format =
+      (this.buildConfig.objIdLen === 1
+        ? "B"
+        : this.buildConfig.objIdLen === 2
+          ? "H"
+          : "I") +
+      (this.buildConfig.spanIxLen === 1
+        ? "B"
+        : this.buildConfig.spanIxLen === 2
+          ? "H"
+          : "I") +
+      "B";
+
+    const header = this.pack(
+      format,
+      this.objId,
+      this.spanIx,
+      SPIFFS_PH_FLAG_USED_FINAL,
+    );
+    img.set(header, 0);
+    img.set(this.contents, header.length);
+
+    return img;
+  }
+}

package/src/lib/spiffs/spiffsReader.ts

@@ -0,0 +1,280 @@
+/**
+ * SPIFFS Reader - Parse and extract files from SPIFFS images
+ * Based on ESP-IDF spiffsgen.py extract_files() method
+ */
+
+import {
+  SpiffsBuildConfig,
+  SPIFFS_PH_FLAG_USED_FINAL_INDEX,
+  SPIFFS_PH_FLAG_USED_FINAL,
+  SPIFFS_PH_FLAG_LEN,
+  SPIFFS_PH_IX_SIZE_LEN,
+  SPIFFS_PH_IX_OBJ_TYPE_LEN,
+} from "./spiffsConfig";
+import type { SpiffsFile } from "./spiffs";
+
+interface FileInfo {
+  name: string | null;
+  size: number;
+  dataPages: Array<[number, Uint8Array]>; // [span_ix, content]
+}
+
+export class SpiffsReader {
+  private buildConfig: SpiffsBuildConfig;
+  private imageData: Uint8Array;
+  private filesMap: Map<number, FileInfo>;
+
+  constructor(imageData: Uint8Array, buildConfig: SpiffsBuildConfig) {
+    this.imageData = imageData;
+    this.buildConfig = buildConfig;
+    this.filesMap = new Map();
+  }
+
+  private unpack(format: string, data: Uint8Array, offset = 0): number[] {
+    const view = new DataView(data.buffer, data.byteOffset + offset);
+    const results: number[] = [];
+    let pos = 0;
+
+    for (const type of format) {
+      switch (type) {
+        case "B":
+          results.push(view.getUint8(pos));
+          pos += 1;
+          break;
+        case "H":
+          results.push(
+            this.buildConfig.endianness === "little"
+              ? view.getUint16(pos, true)
+              : view.getUint16(pos, false),
+          );
+          pos += 2;
+          break;
+        case "I":
+          results.push(
+            this.buildConfig.endianness === "little"
+              ? view.getUint32(pos, true)
+              : view.getUint32(pos, false),
+          );
+          pos += 4;
+          break;
+      }
+    }
+
+    return results;
+  }
+
+  parse(): void {
+    const blocksCount = Math.floor(
+      this.imageData.length / this.buildConfig.blockSize,
+    );
+
+    for (let bix = 0; bix < blocksCount; bix++) {
+      const blockOffset = bix * this.buildConfig.blockSize;
+      const blockData = this.imageData.slice(
+        blockOffset,
+        blockOffset + this.buildConfig.blockSize,
+      );
+
+      this.parseBlock(blockData);
+    }
+  }
+
+  private parseBlock(blockData: Uint8Array): void {
+    // Parse lookup pages to find valid objects
+    for (
+      let pageIdx = 0;
+      pageIdx < this.buildConfig.OBJ_LU_PAGES_PER_BLOCK;
+      pageIdx++
+    ) {
+      const luPageOffset = pageIdx * this.buildConfig.pageSize;
+      const luPageData = blockData.slice(
+        luPageOffset,
+        luPageOffset + this.buildConfig.pageSize,
+      );
+
+      // Parse object IDs from lookup page
+      for (let i = 0; i < luPageData.length; i += this.buildConfig.objIdLen) {
+        if (i + this.buildConfig.objIdLen > luPageData.length) break;
+
+        const objIdBytes = luPageData.slice(i, i + this.buildConfig.objIdLen);
+        const [objId] = this.unpack(
+          this.buildConfig.objIdLen === 1
+            ? "B"
+            : this.buildConfig.objIdLen === 2
+              ? "H"
+              : "I",
+          objIdBytes,
+        );
+
+        // Check if it's a valid object (not erased/empty)
+        const emptyValue = (1 << (this.buildConfig.objIdLen * 8)) - 1;
+        if (objId === emptyValue) continue;
+
+        // Check if it's an index page (MSB set)
+        const isIndex =
+          (objId & (1 << (this.buildConfig.objIdLen * 8 - 1))) !== 0;
+        const realObjId = objId & ~(1 << (this.buildConfig.objIdLen * 8 - 1));
+
+        if (isIndex && !this.filesMap.has(realObjId)) {
+          this.filesMap.set(realObjId, {
+            name: null,
+            size: 0,
+            dataPages: [],
+          });
+        }
+      }
+    }
+
+    // Parse actual pages to get file metadata and content
+    for (
+      let pageIdx = this.buildConfig.OBJ_LU_PAGES_PER_BLOCK;
+      pageIdx < this.buildConfig.PAGES_PER_BLOCK;
+      pageIdx++
+    ) {
+      const pageOffset = pageIdx * this.buildConfig.pageSize;
+      const pageData = blockData.slice(
+        pageOffset,
+        pageOffset + this.buildConfig.pageSize,
+      );
+
+      this.parsePage(pageData);
+    }
+  }
+
+  private parsePage(pageData: Uint8Array): void {
+    // Parse page header
+    const headerFormat =
+      (this.buildConfig.objIdLen === 1
+        ? "B"
+        : this.buildConfig.objIdLen === 2
+          ? "H"
+          : "I") +
+      (this.buildConfig.spanIxLen === 1
+        ? "B"
+        : this.buildConfig.spanIxLen === 2
+          ? "H"
+          : "I") +
+      "B";
+
+    const headerSize =
+      this.buildConfig.objIdLen +
+      this.buildConfig.spanIxLen +
+      SPIFFS_PH_FLAG_LEN;
+
+    if (pageData.length < headerSize) return;
+
+    const [objId, spanIx, flags] = this.unpack(headerFormat, pageData);
+
+    // Check for valid page
+    const emptyId = (1 << (this.buildConfig.objIdLen * 8)) - 1;
+    if (objId === emptyId) return;
+
+    const isIndex = (objId & (1 << (this.buildConfig.objIdLen * 8 - 1))) !== 0;
+    const realObjId = objId & ~(1 << (this.buildConfig.objIdLen * 8 - 1));
+
+    if (isIndex && flags === SPIFFS_PH_FLAG_USED_FINAL_INDEX) {
+      // Index page - contains file metadata
+      if (!this.filesMap.has(realObjId)) {
+        this.filesMap.set(realObjId, {
+          name: null,
+          size: 0,
+          dataPages: [],
+        });
+      }
+
+      // Only first index page (span_ix == 0) has filename and size
+      if (spanIx === 0) {
+        this.parseIndexPage(pageData, headerSize, realObjId);
+      }
+    } else if (!isIndex && flags === SPIFFS_PH_FLAG_USED_FINAL) {
+      // Data page - contains file content
+      if (this.filesMap.has(realObjId)) {
+        const contentStart = headerSize;
+        const content = pageData.slice(
+          contentStart,
+          contentStart + this.buildConfig.OBJ_DATA_PAGE_CONTENT_LEN,
+        );
+        this.filesMap.get(realObjId)!.dataPages.push([spanIx, content]);
+      }
+    }
+  }
+
+  private parseIndexPage(
+    pageData: Uint8Array,
+    headerSize: number,
+    objId: number,
+  ): void {
+    // Skip to size and type fields
+    let offset =
+      headerSize + this.buildConfig.OBJ_DATA_PAGE_HEADER_LEN_ALIGNED_PAD;
+
+    const sizeTypeFormat = "IB";
+    const sizeTypeSize = SPIFFS_PH_IX_SIZE_LEN + SPIFFS_PH_IX_OBJ_TYPE_LEN;
+
+    if (offset + sizeTypeSize <= pageData.length) {
+      const [fileSize] = this.unpack(sizeTypeFormat, pageData, offset);
+      offset += sizeTypeSize;
+
+      // Read filename
+      const nameEnd = offset + this.buildConfig.objNameLen;
+      if (nameEnd <= pageData.length) {
+        const nameBytes = pageData.slice(offset, nameEnd);
+        // Find null terminator
+        const nullPos = nameBytes.indexOf(0);
+        const actualNameBytes =
+          nullPos !== -1 ? nameBytes.slice(0, nullPos) : nameBytes;
+        const filename = new TextDecoder().decode(actualNameBytes);
+
+        const fileInfo = this.filesMap.get(objId)!;
+        fileInfo.name = filename;
+        fileInfo.size = fileSize;
+      }
+    }
+  }
+
+  listFiles(): SpiffsFile[] {
+    const files: SpiffsFile[] = [];
+
+    for (const [, fileInfo] of this.filesMap) {
+      if (fileInfo.name === null) continue;
+
+      // Sort data pages by span index
+      fileInfo.dataPages.sort((a, b) => a[0] - b[0]);
+
+      // Reconstruct file content
+      const chunks: Uint8Array[] = [];
+      let totalWritten = 0;
+
+      for (const [, content] of fileInfo.dataPages) {
+        const remaining = fileInfo.size - totalWritten;
+        if (remaining <= 0) break;
+
+        const toWrite = Math.min(content.length, remaining);
+        chunks.push(content.slice(0, toWrite));
+        totalWritten += toWrite;
+      }
+
+      // Concatenate chunks
+      const data = new Uint8Array(totalWritten);
+      let offset = 0;
+      for (const chunk of chunks) {
+        data.set(chunk, offset);
+        offset += chunk.length;
+      }
+
+      files.push({
+        name: fileInfo.name,
+        size: fileInfo.size,
+        data,
+      });
+    }
+
+    return files;
+  }
+
+  readFile(path: string): Uint8Array | null {
+    const files = this.listFiles();
+    const file = files.find((f) => f.name === path || f.name === "/" + path);
+    return file ? file.data : null;
+  }
+}