esp32tool 1.0.0

package/src/stubs/index.ts

@@ -0,0 +1,86 @@
+import {
+  ChipFamily,
+  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";
+import { toByteArray } from "../util";
+
+interface LoadedStub {
+  text: string;
+  data: string;
+  text_start: number;
+  entry: number;
+  data_start: number;
+}
+
+interface Stub {
+  text: number[];
+  data: number[];
+  text_start: number;
+  entry: number;
+  data_start: number;
+}
+
+export const getStubCode = async (
+  chipFamily: ChipFamily,
+  chipRevision?: number | null,
+): Promise<Stub | null> => {
+  let stubcode!: LoadedStub;
+
+  // Chips without stub support yet
+  if (
+    chipFamily == CHIP_FAMILY_ESP32H4 ||
+    chipFamily == CHIP_FAMILY_ESP32H21 ||
+    chipFamily == CHIP_FAMILY_ESP32S31
+  ) {
+    return null;
+  }
+
+  if (chipFamily == CHIP_FAMILY_ESP32) {
+    stubcode = await import("./esp32.json");
+  } else if (chipFamily == CHIP_FAMILY_ESP32S2) {
+    stubcode = await import("./esp32s2.json");
+  } else if (chipFamily == CHIP_FAMILY_ESP32S3) {
+    stubcode = await import("./esp32s3.json");
+  } else if (chipFamily == CHIP_FAMILY_ESP8266) {
+    stubcode = await import("./esp8266.json");
+  } else if (chipFamily == CHIP_FAMILY_ESP32C2) {
+    stubcode = await import("./esp32c2.json");
+  } else if (chipFamily == CHIP_FAMILY_ESP32C3) {
+    stubcode = await import("./esp32c3.json");
+  } else if (chipFamily == CHIP_FAMILY_ESP32C5) {
+    stubcode = await import("./esp32c5.json");
+  } else if (chipFamily == CHIP_FAMILY_ESP32C6) {
+    stubcode = await import("./esp32c6.json");
+  } else if (chipFamily == CHIP_FAMILY_ESP32C61) {
+    stubcode = await import("./esp32c61.json");
+  } else if (chipFamily == CHIP_FAMILY_ESP32H2) {
+    stubcode = await import("./esp32h2.json");
+  } else if (chipFamily == CHIP_FAMILY_ESP32P4) {
+    // ESP32-P4: Use esp32p4r3.json for Rev. 300+, esp32p4.json for older revisions
+    if (chipRevision !== null && chipRevision !== undefined && chipRevision >= 300) {
+      stubcode = await import("./esp32p4r3.json");
+    } else {
+      stubcode = await import("./esp32p4.json");
+    }
+  }
+
+  // Base64 decode the text and data
+  return {
+    ...stubcode,
+    text: toByteArray(atob(stubcode.text)),
+    data: toByteArray(atob(stubcode.data)),
+  };
+};

package/src/util.ts

@@ -0,0 +1,49 @@
+/**
+ * @name slipEncode
+ * Take an array buffer and return back a new array where
+ * 0xdb is replaced with 0xdb 0xdd and 0xc0 is replaced with 0xdb 0xdc
+ */
+export const slipEncode = (buffer: number[]): number[] => {
+  let encoded = [0xc0];
+  for (const byte of buffer) {
+    if (byte == 0xdb) {
+      encoded = encoded.concat([0xdb, 0xdd]);
+    } else if (byte == 0xc0) {
+      encoded = encoded.concat([0xdb, 0xdc]);
+    } else {
+      encoded.push(byte);
+    }
+  }
+  encoded.push(0xc0);
+  return encoded;
+};
+
+/**
+ * @name toByteArray
+ * Convert a string to a byte array
+ */
+export const toByteArray = (str: string): number[] => {
+  const byteArray: number[] = [];
+  for (let i = 0; i < str.length; i++) {
+    const charcode = str.charCodeAt(i);
+    if (charcode <= 0xff) {
+      byteArray.push(charcode);
+    }
+  }
+  return byteArray;
+};
+
+export const hexFormatter = (bytes: number[]) =>
+  "[" + bytes.map((value) => toHex(value)).join(", ") + "]";
+
+export const toHex = (value: number, size = 2) => {
+  const hex = value.toString(16).toUpperCase();
+  if (hex.startsWith("-")) {
+    return "-0x" + hex.substring(1).padStart(size, "0");
+  } else {
+    return "0x" + hex.padStart(size, "0");
+  }
+};
+
+export const sleep = (ms: number) =>
+  new Promise((resolve) => setTimeout(resolve, ms));

package/src/wasm/fatfs/index.d.ts

@@ -0,0 +1,26 @@
+import type { FileSource, BinarySource } from "../shared/types";
+export interface FatFSEntry {
+    path: string;
+    size: number;
+    type: 'file' | 'dir';
+}
+export interface FatFSOptions {
+    blockSize?: number;
+    blockCount?: number;
+    wasmURL?: string | URL;
+    formatOnInit?: boolean;
+}
+export interface FatFS {
+    format(): void;
+    list(): FatFSEntry[];
+    readFile(path: string): Uint8Array;
+    writeFile(path: string, data: FileSource): void;
+    deleteFile(path: string): void;
+    toImage(): Uint8Array;
+}
+export declare class FatFSError extends Error {
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+export declare function createFatFS(options?: FatFSOptions): Promise<FatFS>;
+export declare function createFatFSFromImage(image: BinarySource, options?: FatFSOptions): Promise<FatFS>;

package/src/wasm/fatfs/index.js

@@ -0,0 +1,343 @@
+const DEFAULT_BLOCK_SIZE = 512;
+const DEFAULT_BLOCK_COUNT = 1024;
+const INITIAL_LIST_BUFFER = 4096;
+const FATFS_ERR_NOT_ENOUGH_CORE = -17;
+export class FatFSError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "FatFSError";
+    }
+}
+export async function createFatFS(options = {}) {
+    console.info("[fatfs-wasm] createFatFS() starting", options);
+    const wasmURL = options.wasmURL ?? new URL("./fatfs.wasm", import.meta.url);
+    const exports = await instantiateFatFSModule(wasmURL);
+    const blockSize = options.blockSize ?? DEFAULT_BLOCK_SIZE;
+    const blockCount = options.blockCount ?? DEFAULT_BLOCK_COUNT;
+    const initResult = exports.fatfsjs_init(blockSize, blockCount);
+    console.info("[fatfs-wasm] fatfsjs_init returned", initResult);
+    if (initResult < 0) {
+        throw new FatFSError("Failed to initialize FatFS", initResult);
+    }
+    if (options.formatOnInit) {
+        const formatResult = exports.fatfsjs_format();
+        console.info("[fatfs-wasm] fatfsjs_format returned", formatResult);
+        if (formatResult < 0) {
+            throw new FatFSError("Failed to format FatFS volume", formatResult);
+        }
+    }
+    const client = new FatFSClient(exports);
+    console.info("[fatfs-wasm] Filesystem initialized");
+    return client;
+}
+export async function createFatFSFromImage(image, options = {}) {
+    console.info("[fatfs-wasm] createFatFSFromImage() starting");
+    const wasmURL = options.wasmURL ?? new URL("./fatfs.wasm", import.meta.url);
+    const exports = await instantiateFatFSModule(wasmURL);
+    const bytes = asBinaryUint8Array(image);
+    const blockSize = options.blockSize ?? DEFAULT_BLOCK_SIZE;
+    if (blockSize === 0) {
+        throw new Error("blockSize must be a positive integer");
+    }
+    const inferredBlocks = bytes.length / blockSize;
+    const blockCount = options.blockCount ?? inferredBlocks;
+    if (blockCount * blockSize !== bytes.length) {
+        throw new Error("Image size must equal blockSize * blockCount");
+    }
+    const ptr = exports.malloc(bytes.length || 1);
+    if (!ptr) {
+        throw new FatFSError("Failed to allocate WebAssembly memory", FATFS_ERR_NOT_ENOUGH_CORE);
+    }
+    try {
+        // Get heap AFTER malloc to avoid stale reference if memory grows
+        const heap = new Uint8Array(exports.memory.buffer);
+        heap.set(bytes, ptr);
+        const initResult = exports.fatfsjs_init_from_image(blockSize, blockCount, ptr, bytes.length);
+        if (initResult < 0) {
+            throw new FatFSError("Failed to initialize FatFS from image", initResult);
+        }
+    }
+    finally {
+        exports.free(ptr);
+    }
+    const client = new FatFSClient(exports);
+    console.info("[fatfs-wasm] Filesystem initialized from image");
+    return client;
+}
+class FatFSClient {
+    constructor(exports) {
+        this.encoder = new TextEncoder();
+        this.decoder = new TextDecoder();
+        this.listBufferSize = INITIAL_LIST_BUFFER;
+        this.exports = exports;
+        this.heapU8 = new Uint8Array(this.exports.memory.buffer);
+    }
+    format() {
+        const result = this.exports.fatfsjs_format();
+        this.assertOk(result, "format filesystem");
+    }
+    list() {
+        let capacity = this.listBufferSize;
+        while (true) {
+            const ptr = this.alloc(capacity);
+            try {
+                const used = this.exports.fatfsjs_list(ptr, capacity);
+                if (used === FATFS_ERR_NOT_ENOUGH_CORE) {
+                    this.listBufferSize = capacity * 2;
+                    capacity = this.listBufferSize;
+                    continue;
+                }
+                this.assertOk(used, "list files");
+                if (used === 0) {
+                    return [];
+                }
+                const payload = this.decoder.decode(this.heapU8.subarray(ptr, ptr + used));
+                return parseListPayload(payload);
+            }
+            finally {
+                this.exports.free(ptr);
+            }
+        }
+    }
+    readFile(path) {
+        const normalizedPath = normalizePath(path);
+        const pathPtr = this.allocString(normalizedPath);
+        try {
+            const size = this.exports.fatfsjs_file_size(pathPtr);
+            this.assertOk(size, `stat file "${normalizedPath}"`);
+            if (size === 0) {
+                return new Uint8Array();
+            }
+            const dataPtr = this.alloc(size);
+            try {
+                const read = this.exports.fatfsjs_read_file(pathPtr, dataPtr, size);
+                this.assertOk(read, `read file "${normalizedPath}"`);
+                return this.heapU8.slice(dataPtr, dataPtr + size);
+            }
+            finally {
+                this.exports.free(dataPtr);
+            }
+        }
+        finally {
+            this.exports.free(pathPtr);
+        }
+    }
+    writeFile(path, data) {
+        const normalizedPath = normalizePath(path);
+        const payload = asUint8Array(data, this.encoder);
+        const pathPtr = this.allocString(normalizedPath);
+        const dataPtr = this.alloc(payload.length);
+        try {
+            if (payload.length > 0 && dataPtr) {
+                this.heapU8.set(payload, dataPtr);
+            }
+            const result = this.exports.fatfsjs_write_file(pathPtr, payload.length > 0 ? dataPtr : 0, payload.length);
+            this.assertOk(result, `write file "${normalizedPath}"`);
+        }
+        finally {
+            if (dataPtr) {
+                this.exports.free(dataPtr);
+            }
+            this.exports.free(pathPtr);
+        }
+    }
+    deleteFile(path) {
+        const normalizedPath = normalizePath(path);
+        const pathPtr = this.allocString(normalizedPath);
+        try {
+            const result = this.exports.fatfsjs_delete_file(pathPtr);
+            this.assertOk(result, `delete file "${normalizedPath}"`);
+        }
+        finally {
+            this.exports.free(pathPtr);
+        }
+    }
+    toImage() {
+        const size = this.exports.fatfsjs_storage_size();
+        if (size === 0) {
+            return new Uint8Array();
+        }
+        const ptr = this.alloc(size);
+        try {
+            const copied = this.exports.fatfsjs_export_image(ptr, size);
+            this.assertOk(copied, "export filesystem image");
+            return this.heapU8.slice(ptr, ptr + size);
+        }
+        finally {
+            this.exports.free(ptr);
+        }
+    }
+    refreshHeap() {
+        if (this.heapU8.buffer !== this.exports.memory.buffer) {
+            this.heapU8 = new Uint8Array(this.exports.memory.buffer);
+        }
+    }
+    alloc(size) {
+        if (size <= 0) {
+            return 0;
+        }
+        const ptr = this.exports.malloc(size);
+        if (!ptr) {
+            throw new FatFSError("Failed to allocate WebAssembly memory", FATFS_ERR_NOT_ENOUGH_CORE);
+        }
+        this.refreshHeap();
+        return ptr;
+    }
+    allocString(value) {
+        const encoded = this.encoder.encode(value);
+        const ptr = this.alloc(encoded.length + 1);
+        this.heapU8.set(encoded, ptr);
+        this.heapU8[ptr + encoded.length] = 0;
+        return ptr;
+    }
+    assertOk(code, action) {
+        if (code < 0) {
+            throw new FatFSError(`Unable to ${action}`, code);
+        }
+    }
+}
+async function instantiateFatFSModule(input) {
+    const source = resolveWasmURL(input);
+    console.info("[fatfs-wasm] Fetching wasm from", source.href);
+    const wasmContext = { memory: null };
+    const imports = createDefaultImports(wasmContext);
+    let response = await fetch(source);
+    if (!response.ok) {
+        throw new Error(`Unable to fetch FatFS wasm from ${response.url}`);
+    }
+    console.info("[fatfs-wasm] Fetch complete, status", response.status);
+    if ("instantiateStreaming" in WebAssembly && typeof WebAssembly.instantiateStreaming === "function") {
+        try {
+            console.info("[fatfs-wasm] Attempting instantiateStreaming");
+            const streaming = await WebAssembly.instantiateStreaming(response, imports);
+            wasmContext.memory = getExportedMemory(streaming.instance.exports);
+            console.info("[fatfs-wasm] instantiateStreaming succeeded");
+            return streaming.instance.exports;
+        }
+        catch (error) {
+            console.warn("Unable to instantiate FatFS wasm via streaming, retrying with arrayBuffer()", error);
+            response = await fetch(source);
+            if (!response.ok) {
+                throw new Error(`Unable to fetch FatFS wasm from ${response.url}`);
+            }
+            console.info("[fatfs-wasm] Fallback fetch complete, status", response.status);
+        }
+    }
+    console.info("[fatfs-wasm] Instantiating from ArrayBuffer fallback");
+    const bytes = await response.arrayBuffer();
+    const instance = await WebAssembly.instantiate(bytes, imports);
+    wasmContext.memory = getExportedMemory(instance.instance.exports);
+    console.info("[fatfs-wasm] instantiate(bytes) succeeded");
+    return instance.instance.exports;
+}
+function parseListPayload(payload) {
+    if (!payload) {
+        return [];
+    }
+    return payload
+        .split("\n")
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const [rawPath, rawSize] = line.split("\t");
+        const path = rawPath ?? "";
+        const size = Number(rawSize ?? "0") || 0;
+        // Determine type: directories end with '/', files don't
+        const type = path.endsWith('/') ? 'dir' : 'file';
+        return {
+            path: path,
+            size: size,
+            type: type
+        };
+    });
+}
+function normalizePath(input) {
+    const value = input.trim().replace(/\\/g, "/");
+    const withoutRoot = value.replace(/^\/+/, "");
+    if (!withoutRoot) {
+        throw new Error('Path must point to a file (e.g. "docs/readme.txt")');
+    }
+    const collapsed = withoutRoot.replace(/\/{2,}/g, "/");
+    return collapsed.endsWith("/") ? collapsed.slice(0, -1) : collapsed;
+}
+function asUint8Array(source, encoder) {
+    if (typeof source === "string") {
+        return encoder.encode(source);
+    }
+    if (source instanceof Uint8Array) {
+        return source;
+    }
+    if (source instanceof ArrayBuffer) {
+        return new Uint8Array(source);
+    }
+    throw new Error("Unsupported file payload type");
+}
+function asBinaryUint8Array(source) {
+    if (source instanceof Uint8Array) {
+        return source;
+    }
+    if (source instanceof ArrayBuffer) {
+        return new Uint8Array(source);
+    }
+    throw new Error("Expected Uint8Array or ArrayBuffer for filesystem image");
+}
+function resolveWasmURL(input) {
+    if (input instanceof URL) {
+        return input;
+    }
+    const locationLike = typeof globalThis !== "undefined" && "location" in globalThis
+        ? globalThis.location
+        : undefined;
+    const baseHref = locationLike?.href;
+    try {
+        return baseHref ? new URL(input, baseHref) : new URL(input);
+    }
+    catch (error) {
+        throw new Error(`Unable to resolve wasm URL from "${input}": ${String(error)}`);
+    }
+}
+function createDefaultImports(context) {
+    const noop = () => { };
+    const ok = () => 0;
+    return {
+        env: {
+            emscripten_notify_memory_growth: noop
+        },
+        wasi_snapshot_preview1: {
+            fd_close: ok,
+            fd_seek: ok,
+            fd_write: (fd, iov, iovcnt, pnum) => handleFdWrite(context, fd, iov, iovcnt, pnum)
+        }
+    };
+}
+function handleFdWrite(context, fd, iov, iovcnt, pnum) {
+    const memory = context.memory;
+    if (!memory) {
+        return 0;
+    }
+    const view = new DataView(memory.buffer);
+    let total = 0;
+    for (let i = 0; i < iovcnt; i++) {
+        const base = iov + i * 8;
+        const ptr = view.getUint32(base, true);
+        const len = view.getUint32(base + 4, true);
+        total += len;
+        // Suppress fd_write logging in production (fd 1=stdout, 2=stderr)
+        // Uncomment for debugging:
+        // if (fd === 1 || fd === 2) {
+        //     const bytes = new Uint8Array(memory.buffer, ptr, len);
+        //     const text = new TextDecoder().decode(bytes);
+        //     console.info(`[fatfs-wasm::fd_write fd=${fd}] ${text}`);
+        // }
+    }
+    view.setUint32(pnum, total, true);
+    return 0;
+}
+function getExportedMemory(exports) {
+    for (const value of Object.values(exports)) {
+        if (value instanceof WebAssembly.Memory) {
+            return value;
+        }
+    }
+    return null;
+}

package/src/wasm/filesystems.ts

@@ -0,0 +1,156 @@
+import type { Partition } from "../partition";
+
+export const LITTLEFS_DEFAULT_BLOCK_SIZE = 4096;
+export const LITTLEFS_BLOCK_SIZE_CANDIDATES = [4096, 2048, 1024, 512];
+export const FATFS_DEFAULT_BLOCK_SIZE = 4096;
+export const FATFS_BLOCK_SIZE_CANDIDATES = [4096, 2048, 1024, 512];
+
+/**
+ * Filesystem types based on partition subtype
+ */
+export enum FilesystemType {
+  UNKNOWN = "unknown",
+  LITTLEFS = "littlefs",
+  FATFS = "fatfs",
+  SPIFFS = "spiffs",
+}
+
+/**
+ * Detect filesystem type from partition information
+ * Note: This only provides a hint. LittleFS is often stored in SPIFFS partitions (0x82).
+ * Use detectFilesystemFromImage() for accurate detection.
+ */
+export function detectFilesystemType(partition: Partition): FilesystemType {
+  if (partition.type !== 0x01) {
+    return FilesystemType.UNKNOWN;
+  }
+
+  switch (partition.subtype) {
+    case 0x81:
+      return FilesystemType.FATFS;
+    case 0x82:
+      return FilesystemType.UNKNOWN;
+    default:
+      return FilesystemType.UNKNOWN;
+  }
+}
+
+/**
+ * Detect filesystem type from image data
+ * Reads the first 8KB to identify filesystem by magic headers and ASCII signatures
+ */
+export function detectFilesystemFromImage(
+  imageData: Uint8Array,
+): FilesystemType {
+  if (imageData.length < 512) {
+    return FilesystemType.UNKNOWN;
+  }
+
+  const searchSize = Math.min(8192, imageData.length);
+
+  // Check for LittleFS magic numbers and ASCII signature
+  for (let offset = 0; offset < searchSize - 8; offset++) {
+    // Check for LittleFS magic: "littlefs" or "lfs\x00" or version-specific magic
+    const magic32 =
+      imageData[offset] |
+      (imageData[offset + 1] << 8) |
+      (imageData[offset + 2] << 16) |
+      (imageData[offset + 3] << 24);
+
+    // LittleFS v2.x magic: 0x32736c66 ("lfs2" in little-endian)
+    // LittleFS v1.x magic: 0x31736c66 ("lfs1" in little-endian)
+    if (magic32 === 0x32736c66 || magic32 === 0x31736c66) {
+      return FilesystemType.LITTLEFS;
+    }
+
+    // Check for ASCII "littlefs" string
+    if (offset + 8 <= searchSize) {
+      const str = String.fromCharCode(
+        imageData[offset],
+        imageData[offset + 1],
+        imageData[offset + 2],
+        imageData[offset + 3],
+        imageData[offset + 4],
+        imageData[offset + 5],
+        imageData[offset + 6],
+        imageData[offset + 7],
+      );
+      if (str === "littlefs") {
+        return FilesystemType.LITTLEFS;
+      }
+    }
+  }
+
+  // Check for FAT filesystem signatures
+  if (imageData.length >= 512) {
+    const bootSig = imageData[510] | (imageData[511] << 8);
+    if (bootSig === 0xaa55) {
+      const fat16Sig =
+        imageData.length >= 62
+          ? String.fromCharCode(
+              imageData[54],
+              imageData[55],
+              imageData[56],
+              imageData[57],
+              imageData[58],
+            )
+          : "";
+      const fat32Sig =
+        imageData.length >= 90
+          ? String.fromCharCode(
+              imageData[82],
+              imageData[83],
+              imageData[84],
+              imageData[85],
+              imageData[86],
+            )
+          : "";
+
+      if (fat16Sig.startsWith("FAT") || fat32Sig.startsWith("FAT")) {
+        return FilesystemType.FATFS;
+      }
+    }
+  }
+
+  // Check for SPIFFS magic (0x20140529)
+  if (imageData.length >= 4) {
+    const spiffsMagic =
+      imageData[0] |
+      (imageData[1] << 8) |
+      (imageData[2] << 16) |
+      (imageData[3] << 24);
+    if (spiffsMagic === 0x20140529) {
+      return FilesystemType.SPIFFS;
+    }
+  }
+
+  return FilesystemType.UNKNOWN;
+}
+
+/**
+ * Get appropriate block size for filesystem type
+ */
+export function getDefaultBlockSize(fsType: FilesystemType): number {
+  switch (fsType) {
+    case FilesystemType.FATFS:
+      return FATFS_DEFAULT_BLOCK_SIZE;
+    case FilesystemType.LITTLEFS:
+      return LITTLEFS_DEFAULT_BLOCK_SIZE;
+    default:
+      return 4096;
+  }
+}
+
+/**
+ * Get block size candidates for filesystem type
+ */
+export function getBlockSizeCandidates(fsType: FilesystemType): number[] {
+  switch (fsType) {
+    case FilesystemType.FATFS:
+      return FATFS_BLOCK_SIZE_CANDIDATES;
+    case FilesystemType.LITTLEFS:
+      return LITTLEFS_BLOCK_SIZE_CANDIDATES;
+    default:
+      return [4096, 2048, 1024, 512];
+  }
+}