esp32tool 1.0.0

package/dist/lib/spiffs/spiffsPage.js

@@ -0,0 +1,260 @@
+/**
+ * SPIFFS Page Classes
+ * Based on ESP-IDF spiffsgen.py
+ */
+import { SpiffsFullError, SPIFFS_PH_FLAG_USED_FINAL_INDEX, SPIFFS_PH_FLAG_USED_FINAL, SPIFFS_TYPE_FILE, } from "./spiffsConfig";
+export class SpiffsPage {
+    constructor(bix, buildConfig) {
+        this.buildConfig = buildConfig;
+        this.bix = bix;
+    }
+    pack(format, ...values) {
+        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);
+    }
+    unpack(format, data, offset = 0) {
+        const view = new DataView(data.buffer, data.byteOffset + offset);
+        const results = [];
+        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;
+    }
+    calcSize(format) {
+        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 class SpiffsObjPageWithIdx extends SpiffsPage {
+    constructor(objId, buildConfig) {
+        super(0, buildConfig);
+        this.objId = objId;
+    }
+    getObjId() {
+        return this.objId;
+    }
+}
+export class SpiffsObjLuPage extends SpiffsPage {
+    constructor(bix, buildConfig) {
+        super(bix, buildConfig);
+        this.objIdsLimit = this.buildConfig.OBJ_LU_PAGES_OBJ_IDS_LIM;
+        this.objIds = [];
+    }
+    calcMagic(blocksLim) {
+        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) {
+        if (this.objIdsLimit <= 0) {
+            throw new SpiffsFullError();
+        }
+        const pageType = page instanceof SpiffsObjIndexPage ? "index" : "data";
+        this.objIds.push([page.getObjId(), pageType]);
+        this.objIdsLimit--;
+    }
+    toBinary() {
+        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) {
+        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 {
+    constructor(objId, spanIx, size, name, buildConfig) {
+        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) {
+        if (this.pagesLim <= 0) {
+            throw new SpiffsFullError();
+        }
+        this.pages.push(page.offset);
+        this.pagesLim--;
+    }
+    toBinary() {
+        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 {
+    constructor(offset, objId, spanIx, contents, buildConfig) {
+        super(objId, buildConfig);
+        this.offset = offset;
+        this.spanIx = spanIx;
+        this.contents = contents;
+    }
+    toBinary() {
+        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/dist/lib/spiffs/spiffsReader.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SPIFFS Reader - Parse and extract files from SPIFFS images
+ * Based on ESP-IDF spiffsgen.py extract_files() method
+ */
+import { SpiffsBuildConfig } from "./spiffsConfig";
+import type { SpiffsFile } from "./spiffs";
+export declare class SpiffsReader {
+    private buildConfig;
+    private imageData;
+    private filesMap;
+    constructor(imageData: Uint8Array, buildConfig: SpiffsBuildConfig);
+    private unpack;
+    parse(): void;
+    private parseBlock;
+    private parsePage;
+    private parseIndexPage;
+    listFiles(): SpiffsFile[];
+    readFile(path: string): Uint8Array | null;
+}

package/dist/lib/spiffs/spiffsReader.js

@@ -0,0 +1,192 @@
+/**
+ * SPIFFS Reader - Parse and extract files from SPIFFS images
+ * Based on ESP-IDF spiffsgen.py extract_files() method
+ */
+import { 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";
+export class SpiffsReader {
+    constructor(imageData, buildConfig) {
+        this.imageData = imageData;
+        this.buildConfig = buildConfig;
+        this.filesMap = new Map();
+    }
+    unpack(format, data, offset = 0) {
+        const view = new DataView(data.buffer, data.byteOffset + offset);
+        const results = [];
+        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() {
+        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);
+        }
+    }
+    parseBlock(blockData) {
+        // 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);
+        }
+    }
+    parsePage(pageData) {
+        // 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]);
+            }
+        }
+    }
+    parseIndexPage(pageData, headerSize, objId) {
+        // 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() {
+        const files = [];
+        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 = [];
+            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) {
+        const files = this.listFiles();
+        const file = files.find((f) => f.name === path || f.name === "/" + path);
+        return file ? file.data : null;
+    }
+}

package/dist/partition.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ESP32 Partition Table Parser
+ * Based on ESP-IDF partition table format
+ */
+export interface Partition {
+    name: string;
+    type: number;
+    subtype: number;
+    offset: number;
+    size: number;
+    flags: number;
+    typeName: string;
+    subtypeName: string;
+}
+/**
+ * Parse the entire partition table
+ */
+export declare function parsePartitionTable(data: Uint8Array): Partition[];
+/**
+ * Get the default partition table offset
+ */
+export declare function getPartitionTableOffset(): number;
+/**
+ * Format size in human-readable format
+ */
+export declare function formatSize(bytes: number): string;

package/dist/partition.js

@@ -0,0 +1,129 @@
+/**
+ * ESP32 Partition Table Parser
+ * Based on ESP-IDF partition table format
+ */
+// Partition types
+const PARTITION_TYPES = {
+    0x00: "app",
+    0x01: "data",
+};
+// App subtypes
+const APP_SUBTYPES = {
+    0x00: "factory",
+    0x10: "ota_0",
+    0x11: "ota_1",
+    0x12: "ota_2",
+    0x13: "ota_3",
+    0x14: "ota_4",
+    0x15: "ota_5",
+    0x16: "ota_6",
+    0x17: "ota_7",
+    0x18: "ota_8",
+    0x19: "ota_9",
+    0x1a: "ota_10",
+    0x1b: "ota_11",
+    0x1c: "ota_12",
+    0x1d: "ota_13",
+    0x1e: "ota_14",
+    0x1f: "ota_15",
+    0x20: "test",
+};
+// Data subtypes
+const DATA_SUBTYPES = {
+    0x00: "ota",
+    0x01: "phy",
+    0x02: "nvs",
+    0x03: "coredump",
+    0x04: "nvs_keys",
+    0x05: "efuse",
+    0x80: "esphttpd",
+    0x81: "fat",
+    0x82: "spiffs",
+};
+const PARTITION_TABLE_OFFSET = 0x8000; // Default partition table offset
+const PARTITION_ENTRY_SIZE = 32;
+const PARTITION_MAGIC = 0x50aa;
+/**
+ * Parse a single partition entry from binary data
+ */
+function parsePartitionEntry(data) {
+    if (data.length < PARTITION_ENTRY_SIZE) {
+        return null;
+    }
+    // Check magic bytes
+    const magic = (data[0] | (data[1] << 8)) & 0xffff;
+    if (magic !== PARTITION_MAGIC) {
+        return null;
+    }
+    const type = data[2];
+    const subtype = data[3];
+    const offset = data[4] | (data[5] << 8) | (data[6] << 16) | (data[7] << 24);
+    const size = data[8] | (data[9] << 8) | (data[10] << 16) | (data[11] << 24);
+    // Name is at offset 12, max 16 bytes, null-terminated
+    let name = "";
+    for (let i = 12; i < 28; i++) {
+        if (data[i] === 0)
+            break;
+        name += String.fromCharCode(data[i]);
+    }
+    const flags = data[28] | (data[29] << 8) | (data[30] << 16) | (data[31] << 24);
+    // Get type and subtype names
+    const typeName = PARTITION_TYPES[type] || `unknown(0x${type.toString(16)})`;
+    let subtypeName = "";
+    if (type === 0x00) {
+        subtypeName = APP_SUBTYPES[subtype] || `unknown(0x${subtype.toString(16)})`;
+    }
+    else if (type === 0x01) {
+        subtypeName =
+            DATA_SUBTYPES[subtype] || `unknown(0x${subtype.toString(16)})`;
+    }
+    else {
+        subtypeName = `0x${subtype.toString(16)}`;
+    }
+    return {
+        name,
+        type,
+        subtype,
+        offset,
+        size,
+        flags,
+        typeName,
+        subtypeName,
+    };
+}
+/**
+ * Parse the entire partition table
+ */
+export function parsePartitionTable(data) {
+    const partitions = [];
+    for (let i = 0; i < data.length; i += PARTITION_ENTRY_SIZE) {
+        const entryData = data.slice(i, i + PARTITION_ENTRY_SIZE);
+        const partition = parsePartitionEntry(entryData);
+        if (partition === null) {
+            // End of partition table or invalid entry
+            break;
+        }
+        partitions.push(partition);
+    }
+    return partitions;
+}
+/**
+ * Get the default partition table offset
+ */
+export function getPartitionTableOffset() {
+    return PARTITION_TABLE_OFFSET;
+}
+/**
+ * Format size in human-readable format
+ */
+export function formatSize(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    else if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(2)} KB`;
+    }
+    else {
+        return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+    }
+}

package/dist/struct.d.ts

@@ -0,0 +1,2 @@
+export declare const pack: (format: string, ...data: number[]) => number[];
+export declare const unpack: (format: string, bytes: number[]) => number[];