feat: esp-idf flasher_args.json support

esp-idf projects can now specify `builder/flasher_args.json` as the firmware, to automatically load firmwares compiled by `idf.py build`. e.g.

```toml
[wokwi]
version = 1
firmware = 'build/flasher_args.json'
elf = 'build/example_app.elf'
```

Author: urish

src/esp32.ts

@@ -0,0 +1,28 @@
+export interface IESP32FlasherJSON {
+  write_flash_args: string[];
+  flash_settings: FlashSettings;
+  flash_files: Record<string, string>;
+  bootloader: IFlashFile;
+  app: IFlashFile;
+  'partition-table': IFlashFile;
+  extra_esptool_args: ExtraEsptoolArgs;
+}
+
+export interface IFlashFile {
+  offset: string;
+  file: string;
+  encrypted: string;
+}
+
+export interface ExtraEsptoolArgs {
+  after: string;
+  before: string;
+  stub: boolean;
+  chip: string;
+}
+
+export interface FlashSettings {
+  flash_mode: string;
+  flash_size: string;
+  flash_freq: string;
+}

src/main.ts

@@ -16,6 +16,7 @@ import { DelayCommand } from './scenario/DelayCommand.js';
 import { ExpectPinCommand } from './scenario/ExpectPinCommand.js';
 import { SetControlCommand } from './scenario/SetControlCommand.js';
 import { WaitSerialCommand } from './scenario/WaitSerialCommand.js';
+import { uploadFirmware } from './uploadFirmware.js';
 
 const millis = 1_000_000;
 
@@ -169,9 +170,7 @@ async function main() {
   try {
     await client.connected;
     await client.fileUpload('diagram.json', diagram);
-    const extension = firmwarePath.split('.').pop();
-    const firmwareName = `firmware.${extension}`;
-    await client.fileUpload(firmwareName, readFileSync(firmwarePath));
+    const firmwareName = await uploadFirmware(client, firmwarePath);
     await client.fileUpload('firmware.elf', readFileSync(elfPath));
 
     for (const chip of chips) {

src/uploadFirmware.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from 'fs';
+import { basename, resolve, dirname } from 'path';
+import { type APIClient } from './APIClient.js';
+import { type IESP32FlasherJSON } from './esp32.js';
+
+interface IFirmwarePiece {
+  offset: number;
+  data: ArrayBuffer;
+}
+
+const MAX_FIRMWARE_SIZE = 4 * 1024 * 1024;
+
+export async function uploadESP32Firmware(client: APIClient, firmwarePath: string) {
+  const flasherArgs = JSON.parse(readFileSync(firmwarePath, 'utf-8')) as IESP32FlasherJSON;
+  if (!('flash_files' in flasherArgs)) {
+    throw new Error('flash_files is not defined in flasher_args.json');
+  }
+
+  const firmwareParts: IFirmwarePiece[] = [];
+  let firmwareSize = 0;
+  for (const [offset, file] of Object.entries(flasherArgs.flash_files)) {
+    const offsetNum = parseInt(offset, 16);
+    if (isNaN(offsetNum)) {
+      throw new Error(`Invalid offset in flasher_args.json flash_files: ${offset}`);
+    }
+
+    const data = readFileSync(resolve(dirname(firmwarePath), file));
+    firmwareParts.push({ offset: offsetNum, data });
+    firmwareSize = Math.max(firmwareSize, offsetNum + data.byteLength);
+  }
+
+  if (firmwareSize > MAX_FIRMWARE_SIZE) {
+    throw new Error(
+      `Firmware size (${firmwareSize} bytes) exceeds the maximum supported size (${MAX_FIRMWARE_SIZE} bytes)`,
+    );
+  }
+
+  const firmwareData = new Uint8Array(firmwareSize);
+  for (const { offset, data } of firmwareParts) {
+    firmwareData.set(new Uint8Array(data), offset);
+  }
+  await client.fileUpload('firmware.bin', firmwareData);
+
+  return 'firmware.bin';
+}
+
+export async function uploadFirmware(client: APIClient, firmwarePath: string) {
+  if (basename(firmwarePath) === 'flasher_args.json') {
+    return await uploadESP32Firmware(client, firmwarePath);
+  }
+
+  const extension = firmwarePath.split('.').pop();
+  const firmwareName = `firmware.${extension}`;
+  await client.fileUpload(firmwareName, readFileSync(firmwarePath));
+  return firmwareName;
+}