stm32f4-emu 1.2.1 → 1.3.1

package/README.md

@@ -90,13 +90,13 @@ npm run serve                  # then open http://127.0.0.1:8123
 npm test                       # == node site/test_flow.mjs
 
 # websocket bridge: headless Node serves the emulator, browser is a thin UI
-npm run bridge -- blinky/blinky.bin --port 8234
+npm run bridge -- firmware/blinky/blinky.bin --port 8234
 # then open http://127.0.0.1:8123/console.html?bridge=ws://127.0.0.1:8234
 
 # gateway-backed run: firmware talks to a REAL network stack (gVisor)
 cd stm32-periph-wasm/pkg
-node cli.mjs ../../eth_http/eth_http.bin 10000000 \
-  --gateway --config=../../eth_http/config.yaml
+node cli.mjs ../../firmware/eth_http/eth_http.bin 10000000 \
+  --gateway --config=../../firmware/eth_http/config.yaml
 # (requires an HTTP server at 127.0.0.1:8092; see AGENTS.md §10)
 ```
 
@@ -132,6 +132,11 @@ custom SPI/I2C devices) to pins and buses with the component API —
 `ext_devices.spiDevices`/`i2cDevices` for your own bus protocol. See
 [docs/components.md](docs/components.md).
 
+For platform integration (Wokwi/OpenHW/Velxio) use the `STM32F4` facade —
+factories, GPIO/USART/SPI/I2C objects, polled event callbacks, DMA
+controller, live displays, SWD/JTAG/power/probe helpers. See
+[docs/facade.md](docs/facade.md).
+
 ## Drive it from an AI agent (MCP)
 
 `mcp/server.mjs` exposes the emulator over the Model Context Protocol —
@@ -155,7 +160,7 @@ is a thin UI. Zero impact on the existing local WASM path:
 
 ```bash
 # 1. Start the bridge in Node (serves the emulator over WS on port 8234)
-node site/ws-bridge.mjs eth_http/eth_http.bin --port 8234
+node site/ws-bridge.mjs firmware/eth_http/eth_http.bin --port 8234
 
 # 2. Open the browser console with the bridge URL param
 open "http://127.0.0.1:8123/console.html?bridge=ws://127.0.0.1:8234"
@@ -214,7 +219,7 @@ firmware .bin ──► Rust WASM CPU (Thumb-2 + NVIC/exceptions)
   (SysTick, ETH, USART, SVC/PendSV) are delivered inline with exact
   exception stacking — no native deps, no JIT, no hooks.
 - **Peripherals**: a `wasm-bindgen` crate (`stm32-periph-wasm/`); registers
-  and bit fields come from the vendor SVD (`monox/stm32f407.svd`).
+  and bit fields come from the vendor SVD (`site/vendor/stm32f407.svd`).
 - **Ethernet**: TX is captured from the DMA descriptors (OWN/FS/LS poll
   demand); RX frames are delivered head-only with FS+LS status, IPHCE/PCE
   checksum status, and PTP snapshots for event messages. The full MAC
@@ -249,13 +254,13 @@ firmware .bin ──► Rust WASM CPU (Thumb-2 + NVIC/exceptions)
 ├── index.mjs, package.json  npm package entry (stm32f4-emu)
 ├── mcp/                     MCP server (drive the emulator from an AI agent)
 ├── .github/workflows/       CI (Linux/Windows/macOS test matrix) + Pages deploy
-├── tools/make_firmware.mjs  Regenerates site/firmware.js from eth_*/.bin
+├── tools/make_firmware.mjs  Regenerates site/firmware.js from firmware/*/.bin
 ├── stm32-periph-wasm/       Rust peripheral model (WASM build + pkg/)
-├── eth_http/ eth_dhcp/ eth_test/   Sample network firmwares + configs
-├── doom/                    DOOM 1 port (doomgeneric f407 target + WAD path)
+├── firmware/eth_http/ eth_dhcp/ eth_test/   Sample network firmwares + configs
+├── firmware/doom/           DOOM 1 port (doomgeneric f407 target + WAD path)
 ├── openhw-local-gateway/    Go gateway (gVisor network stack)
 ├── scripts/verify_ethernet.sh   Regression runner for all three firmwares
-├── src/, monox/, saturn/    Native SDL emulator (upstream heritage)
+├── hardware/monox/, hardware/saturn/  Upstream printer firmwares (heritage)
 └── AGENTS.md                Full architecture, build steps, runbook
 ```
 
@@ -267,10 +272,9 @@ cd stm32-periph-wasm && wasm-pack build --release --target nodejs
 
 # firmware (bare-metal Makefiles; toolchain from the Arduino core)
 TOOLCHAIN="$HOME/.arduino15/packages/STMicroelectronics/tools/xpack-arm-none-eabi-gcc/14.2.1-1.1/bin/arm-none-eabi-" \
-  make -C eth_http          # also eth_dhcp, eth_test
+  make -C firmware/eth_http   # also eth_dhcp, eth_test (all firmware lives in firmware/)
 
-# native SDL emulator (upstream heritage, not the headless path)
-cd stm32-emulator-main && cargo build --release
+# (no native SDL emulator in this tree — the headless WASM path above is the only backend)
 ```
 
 `wasm-pack` writes `site/vendor/.gitignore` containing `*` after a browser

package/index.d.ts

@@ -18,7 +18,287 @@ export const bindings: any;
 export const unicornFactory: any;
 export const svdXml: string;
 
-// Component-attachment API (attach devices to an emulator handle).
+// STM32F4 high-level facade (see site/stm32f4.js). F1-API parity surface:
+// factories, execute/step results, GPIO/USART/SPI/I2C classes, symbol
+// helpers, and engine pass-throughs. TX is a single shared model buffer
+// (only usart1.onData/output fire); event callbacks beyond SPI/I2C taps
+// are absent by design (no core event queue on F4).
+export interface ExecuteResult { instCount: number; stopped: boolean; }
+export interface FacadeStepResult { pc: number; instCount: number; stopped: boolean; }
+export class GPIOPin {
+  constructor(mcu: STM32F4, port: string, pin: number);
+  on(event: 'change', cb: (high: boolean) => void): () => void;
+  addListener(cb: (high: boolean) => void): () => void;
+  read(): boolean;
+  readInput(): boolean;
+  setInput(high: boolean): void;
+  setInputValue(high: boolean): void;
+  detach(): void;
+}
+export class GPIO {
+  constructor(mcu: STM32F4);
+  pin(port: string | number, pin: number): GPIOPin;
+}
+export interface ChipRecord {
+  key: string;
+  svd: string;
+  flash_size: number;
+  ram_size: number;
+  maxClockMHz: number;
+  label: string;
+  idcode: number;
+  usarts: number[];
+  timers: number[];
+  can: number[];
+  dac: boolean;
+  ltdc: boolean;
+  gpioBanks: number;
+  spi: number[];
+  i2c: number[];
+  uart78: number[];
+  i2s: number[];
+  sai: number[];
+  sdio: boolean;
+  dcmi: boolean;
+  crc: boolean;
+  cryp: boolean;
+  hash: boolean;
+  rng: boolean;
+  fsmc: boolean;
+  dma2d: boolean;
+  qspi: boolean;
+}
+export declare const CHIPS: Record<string, Omit<ChipRecord, 'key'>>;
+export declare function chipInfo(key?: string): ChipRecord;
+export class USART {
+  readonly n: number;
+  onData: ((byte: number) => void) | null;
+  constructor(mcu: STM32F4, n: number);
+  send(data: string | Uint8Array | number[]): void;
+  sendData(data: string | Uint8Array | number[]): void;
+  get output(): string;
+}
+export class SPI {
+  readonly ch: number;
+  onTransfer: ((channel: string, tx: number[], rx: number[]) => void) | null;
+  constructor(mcu: STM32F4, ch: number);
+  injectMiso(bytes: Uint8Array | number[]): void;
+}
+export class I2C {
+  readonly ch: number;
+  onStart: ((addr: number, isRead: boolean) => void) | null;
+  onWrite: ((byte: number) => void) | null;
+  onRead: (() => void) | null;
+  onStop: (() => void) | null;
+  constructor(mcu: STM32F4, ch: number);
+  injectRx(bytes: Uint8Array | number[]): void;
+}
+export class DMAStream {
+  constructor(mcu: STM32F4, streamIndex: number);
+  pendingCount(): number;
+  setCompleted(success?: boolean): void;
+  tcif(): boolean;
+  htif(): boolean;
+  cr(): number;
+  ndtr(): number;
+}
+export class DMAController {
+  constructor(mcu: STM32F4, controller?: 1 | 2);
+  lisr(): number;
+  hisr(): number;
+  tcif(s: number): boolean;
+  htif(s: number): boolean;
+  cr(s: number): number;
+  ndtr(s: number): number;
+  par(s: number): number;
+  m0ar(s: number): number;
+  m1ar(s: number): number;
+  fcr(s: number): number;
+  stream(s: number): DMAStream;
+}
+export class Display {
+  constructor(mcu: STM32F4);
+  get oled(): { w: number; h: number; fb: Uint8Array; frame: number } | null;
+  get tft(): { w: number; h: number; fb: Uint8Array; frame: () => number } | null;
+  ltdc(): { w: number; h: number; pf: string; fb: Uint8Array; addr: number; pitch: number } | null;
+}
+export class STM32F4 {
+  readonly gpio: GPIO;
+  readonly usart: USART;
+  // Slots for absent-silicon USARTs are null (F401/F411: 3,4,5).
+  readonly usart1: USART; readonly usart2: USART; readonly usart3: USART | null;
+  readonly usart4: USART | null; readonly usart5: USART | null; readonly usart6: USART;
+  readonly usart7: USART | null; readonly usart8: USART | null;
+  readonly usarts: Record<number, USART>;
+  readonly spi1: SPI | null; readonly spi2: SPI; readonly spi3: SPI;
+  readonly spi4: SPI | null; readonly spi5: SPI | null; readonly spi6: SPI | null;
+  readonly spiBus: Record<number, SPI>;
+  readonly i2c1: I2C; readonly i2c2: I2C; readonly i2c3: I2C;
+  readonly i2cBus: Record<number, I2C>;
+  readonly spi: { specs: any[]; pushMiso(peripheral: string, bytes: Uint8Array | number[]): void };
+  readonly i2c: { specs: any[]; pushRx(peripheral: string, bytes: Uint8Array | number[]): void };
+  readonly dma: { stream(index: number): DMAStream; controller(ctl: 1 | 2): DMAController };
+  readonly display: Display;
+  readonly chip: ChipRecord;
+  readonly chipSvdXml: string | null;
+  // Wokwi/OpenHW/Velxio integration callbacks (polled dispatch, see site/stm32f4.js).
+  onExtiEdge: ((line: number) => void) | null;
+  onCanTx: ((can: number) => void) | null;
+  onCanRx: ((can: number, id: number, len: number, data: number[]) => void) | null;
+  onTimUpdate: ((tim: number) => void) | null;
+  onTimCapture: ((tim: number, ch: number, val: number) => void) | null;
+  onDmaTc: ((controller: number, stream: number) => void) | null;
+  onWdogReset: ((which: number) => void) | null;
+  onUsbIn: ((ep: number, data: number[]) => void) | null;
+  onUsbHsIn: ((ep: number, data: number[]) => void) | null;
+  onItmByte: ((port: number, byte: number) => void) | null;
+  onFsmcAccess: ((bank: number, off: number, write: boolean, size: number, val: number) => void) | null;
+  onAdcDone: ((adc: number, chan: number, value: number) => void) | null;
+  onDacWrite: ((chan: number, value: number) => void) | null;
+  onCrcResult: ((value: number) => void) | null;
+  onRtcAlarm: ((which: number) => void) | null;
+  onI2cAlert: ((peripheral: number, asserted: boolean) => void) | null;
+  onHostTx: ((...args: any[]) => void) | null;
+  onHostRx: ((...args: any[]) => void) | null;
+  constructor(emu: any, bindings?: any, chip?: ChipRecord, chipSvdXml?: string | null);
+  static create(opts?: any): Promise<STM32F4>;
+  static fromELF(buf: Uint8Array | ArrayBuffer, opts?: any): Promise<STM32F4>;
+  static fromBin(buf: Uint8Array | ArrayBuffer, opts?: any): Promise<STM32F4>;
+  static fromHex(text: string, opts?: any): Promise<STM32F4>;
+  loadBin(bytes: Uint8Array | ArrayBuffer, base?: number): void;
+  loadHex(text: string): void;
+  loadELF(bytes: Uint8Array | ArrayBuffer): void;
+  // Live peripheral injection (anytime unless noted).
+  setAdcChannel(peripheral: string, channel: number, value: number): void;
+  clearAdcChannel(peripheral: string, channel: number): void;
+  takeAdcDma(): number[];
+  canInject(id: number, dlc: number, data: Uint8Array | number[]): void;
+  canInjectFd(id: number, data: Uint8Array | number[], brs?: boolean): void;
+  timInjectCapture(timer: number, ch: number): void;
+  timPwmPulseUs(timer: number, ch: number, clockHz: number): number;
+  timOcMode(timer: number, ch: number): number;
+  timMoe(timer: number): boolean;
+  timEncoderStep(timer: number, ti: number, rising: boolean): void;
+  timBreakInput(timer: number, asserted: boolean): void;
+  dacTrigger(ch: number, src: number, dmaStaged?: boolean): void;
+  dacUnderrun(ch: number): boolean;
+  takeSpeakerSamples(): Float32Array;
+  usbInjectSetup(bytes: Uint8Array | number[]): boolean;
+  usbInjectOut(ep: number, bytes: Uint8Array | number[]): boolean;
+  usbTakeIn(ep: number): number[];
+  usbReset(): void;
+  usbEnumerated(): void;
+  usbHsInjectSetup(bytes: Uint8Array | number[]): boolean;
+  usbHsInjectOut(ep: number, bytes: Uint8Array | number[]): boolean;
+  usbHsTakeIn(ep: number): number[];
+  usbHsReset(): void;
+  usbHsEnumerated(): void;
+  ethInject(frame: Uint8Array | number[]): void;
+  // Fault / model-harness methods (mirror wasm exports 1:1).
+  uartSetCts(base: number, asserted: boolean): void;
+  uartFaultRx(base: number, fe: boolean, pe: boolean): void;
+  uartIdle(base: number): void;
+  uartLinBreak(base: number): void;
+  uartBreakPending(base: number): boolean;
+  uartTxLen(base: number): number;
+  uartMuted(base: number): boolean;
+  spiFaultCrc(base: number): void;
+  spiFaultModf(base: number): void;
+  spiSlaveSelect(base: number, asserted: boolean): void;
+  spiSlaveClock(base: number, mosi: number): number;
+  spiSlaveGate(base: number): boolean;
+  i2cArmArbLoss(base: number): void;
+  i2cArmSmbusAlert(base: number, addr: number): void;
+  i2cSlaveAddress(base: number, addr: number, isRead: boolean): boolean;
+  i2cSlaveWrite(base: number, byte: number): void;
+  i2cSlaveRead(base: number): number;
+  i2cSlaveStop(base: number): void;
+  i2cSlaveStatus(base: number): number;
+  sdioFaultDataCrc(): void;
+  rccInjectFailure(srcMask: number, dead: boolean): void;
+  flashRdpLevel(): number;
+  flashSetRdp(levelByte: number): void;
+  rngSeedEntropy(words: number[] | Uint32Array): void;
+  rngEntropyAvail(): number;
+  rtcTamperPin(level: boolean): void;
+  rtcTimestamp(): void;
+  setIntrPending(irq: number): void;
+  hasPendingInterrupt(): boolean;
+  // Scope probes (read-only model state).
+  adcDualLatched(): boolean;
+  ethPpsCount(): number;
+  ethPpsLevel(): boolean;
+  ethLinkUp(): boolean;
+  ethSetLink(up: boolean): void;
+  ltdcScanline(): number;
+  ltdcFrameCount(): number;
+  audioRemaining(): number;
+  audioClear(): void;
+  dcmiSync(vsync: boolean, hsync: boolean, pclkDiv: number): void;
+  qspiMmapLive(): boolean;
+  qspiMmapRead(offset: number): number;
+  sdioBusWidth(): number;
+  sdioCardBlocks(): number;
+  sdioReadBlock(block: number): number[];
+  takeItm(port: number): number[];
+  itmPending(port: number): number;
+  takeFsmc(bank: number): number[];
+  pushFsmc(bank: number, values: number[] | Uint32Array): void;
+  regfileGet(peripheral: string, offset: number): number;
+  regfileSet(peripheral: string, offset: number, value: number): void;
+  get oled(): any;
+  get tft(): any;
+  get rtc(): any;
+  get buzzer(): any;
+  get camera(): any;
+  execute(cycles?: number): ExecuteResult;
+  step(cycles?: number): FacadeStepResult;
+  uartRx(byte: number): boolean;
+  get uartOutput(): string;
+  setSymbols(mapText: string): number;
+  resolveSymbol(pc: number): string | null;
+  read32(addr: number): number;
+  write32(addr: number, val: number): void;
+  memRead32(addr: number): number;
+  memWriteBytes(addr: number, bytes: Uint8Array | number[]): void;
+  periphRead(addr: number, width?: number): number;
+  periphWrite(addr: number, width: number, value: number): void;
+  addJsPeripheral(base: number, size: number, read: (addr: number, size: number) => number, write: (addr: number, value: number, size: number) => void): boolean;
+  pwrMode(): number;
+  pwrEstimate(): number;
+  swdHalted(): boolean;
+  swdHalt(): void;
+  swdResume(): void;
+  swdStep(): number;
+  swdAddWatch(kind: number, addr: number, len: number): number;
+  swdRemoveWatch(slot: number): void;
+  swdTakeTrip(): number[];
+  swdDpRead(addr: number): number;
+  swdDpWrite(addr: number, value: number): void;
+  swdApRead(bank: number, reg: number): number;
+  swdApWrite(bank: number, reg: number, value: number): void;
+  swdRegRead(idx: number): number;
+  swdRegWrite(idx: number, value: number): void;
+  jtagReset(): void;
+  jtagIr(ir: number): void;
+  jtagIdcode(): number;
+  jtagDp(addr: number, rnw: boolean, wdata: number): number;
+  jtagAp(bank: number, reg: number, rnw: boolean, wdata: number): number;
+  dmaController(ctl?: 1 | 2): DMAController;
+  getRegisters(): any;
+  getPc(): number;
+  getSp(): number;
+  faultInfo(): any;
+  takeFault(): [number, number] | null;
+  stop(): void;
+  reset(): void;
+  close(): void;
+  resetCpu(): void;
+  setNrst(asserted: boolean): boolean;
+  isNrstAsserted(): boolean;
+  bootPreset(image: any): void;
+  ledStatus(fwName: string, boardKey: string): any;
+}
 export class LED {
   constructor(emu: any, port: string, num: number, opts?: { activeLow?: boolean });
   on(): void;
@@ -47,6 +327,7 @@ export class I2cRegisterDevice {
   constructor(emu: any, peripheral: string, opts?: any);
 }
 
+// Component-attachment API (attach devices to an emulator handle).
 // Board LED map + host reset/boot control (see site/boards.js,
 // site/emulator.js, site/stm32f4.js).
 export interface BoardLed { bank: number; pin: number; label: string; }

package/index.mjs

@@ -7,13 +7,17 @@ import { createEmulator } from './site/emulator.js';
 import { createNetSim } from './site/netsim.js';
 import { FIRMWARES } from './site/firmware.js';
 import { LED, Button, Pwm, I2cRegisterDevice, Potentiometer } from './site/components.js';
-import { STM32F4, GPIOPin, USART, DMAStream } from './site/stm32f4.js';
+import { STM32F4, GPIOPin, GPIO, USART, SPI, I2C, DMAStream, DMAController, Display, CHIPS, chipInfo } from './site/stm32f4.js';
 
 // Node consumers get a one-call setup that injects the bundled assets. The
 // `firmware` option is optional (defer to loadBin/loadHex/loadELF after
 // create), matching the rp2040js / avr8js ergonomics.
+// NOTE: svdXml is deliberately NOT injected here. STM32F4._create resolves
+// the SVD per `chip` (F401/F411/F407/F429) itself; injecting the F407 default
+// would shadow the chip map (right sizes + IDCODE, wrong registers). A caller
+// passing svdXml explicitly still wins (override path in _create).
 STM32F4.create = (opts = {}) => STM32F4._create({
-    bindings, svdXml, wasmInit: wasmBytes, ...opts,
+    bindings, wasmInit: wasmBytes, ...opts,
 });
 
 const svdXml = readFileSync(new URL('./site/vendor/stm32f407.svd', import.meta.url), 'utf8');
@@ -39,5 +43,5 @@ export async function createSTM32F407(opts = {}) {
     return createEmulator({ ...opts, firmware: bin, bindings, svdXml, wasmInit: wasmBytes });
 }
 
-export { createEmulator, createNetSim, FIRMWARES, bindings, svdXml, LED, Button, Pwm, I2cRegisterDevice, Potentiometer, STM32F4, GPIOPin, USART, DMAStream };
+export { createEmulator, createNetSim, FIRMWARES, bindings, svdXml, LED, Button, Pwm, I2cRegisterDevice, Potentiometer, STM32F4, GPIOPin, GPIO, USART, SPI, I2C, DMAStream, DMAController, Display, CHIPS, chipInfo };
 export { boardLed, BOARD_LED, BOARD_LED_ALIASES } from './site/boards.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stm32f4-emu",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "STM32F407 emulator: Rust CPU + peripheral model (WASM). Runs real Cortex-M4 firmware in Node or the browser.",
   "type": "module",
   "main": "index.mjs",
@@ -104,7 +104,7 @@
     "lint": "eslint site mcp tools index.mjs cli.mjs",
     "format": "prettier --check .",
     "format:write": "prettier --write .",
-    "build:wasm": "wasm-pack build stm32-periph-wasm --target web --out-dir ../site/vendor && rm -f site/vendor/.gitignore && cp monox/stm32f407.svd site/vendor/ 2>/dev/null || true; command -v wasm-opt >/dev/null 2>&1 && wasm-opt -O3 site/vendor/stm32_periph_wasm_bg.wasm -o site/vendor/stm32_periph_wasm_bg.wasm || echo 'wasm-opt not found, skipping'",
+    "build:wasm": "wasm-pack build stm32-periph-wasm --target web --out-dir ../site/vendor && rm -f site/vendor/.gitignore && git checkout -- site/vendor/stm32f407.svd site/vendor/stm32f401.svd site/vendor/stm32f411.svd site/vendor/stm32f429.svd 2>/dev/null || true; command -v wasm-opt >/dev/null 2>&1 && wasm-opt -O3 site/vendor/stm32_periph_wasm_bg.wasm -o site/vendor/stm32_periph_wasm_bg.wasm || echo 'wasm-opt not found, skipping'",
     "build:wasm:node": "wasm-pack build stm32-periph-wasm --target nodejs --out-dir pkg",
     "build:wasm:opt": "wasm-opt -O3 site/vendor/stm32_periph_wasm_bg.wasm -o site/vendor/stm32_periph_wasm_bg.wasm",
     "test:wasm": "node site/test_wasm_cpu.mjs && node site/test_flow_wasm.mjs && node site/test_audio_wasm.mjs && node site/test_wasm_multi.mjs && node site/test_lowpower_wasm.mjs && node site/probe_freertos.mjs && node site/test_doom_wasm.mjs"

package/site/app.js

@@ -2,8 +2,8 @@
 // Preset + custom (.bin/.hex/.elf/.map) firmware loading, Run/Stop/Reset,
 // an optional WebSocket gateway (real network stack) with a netsim fallback,
 // live UART terminal, GPIO/peripheral register readout, and packet viewer.
-import * as bindings from './vendor/stm32_periph_wasm.js?v=41';
-import { createEmulator } from './emulator.js?v=2';
+import * as bindings from './vendor/stm32_periph_wasm.js?v=43';
+import { createEmulator } from './emulator.js?v=3';
 import { createNetSim } from './netsim.js';
 import { createUsbHost } from './usbhost.js';
 import { boardsOf, boardForSelection, BOARDS, boardLed } from './boards.js?v=7';
@@ -142,6 +142,9 @@ const DEVICE_FIRMWARES = {
     buzzer_test_f401: { buzzer: { tim: 'TIM2' } },
     buzzer_test_f411: { buzzer: { tim: 'TIM2' } },
     buzzer_test_f429: { buzzer: { tim: 'TIM2' } },
+    audio_play_test_f401: { speaker: true },
+    audio_play_test_f411: { speaker: true },
+    audio_play_test_f429: { speaker: true },
     rtc_test_f401: { rtc: { i2c: 'I2C1', addr: 0x68, init: RTC_INIT } },
     rtc_test_f411: { rtc: { i2c: 'I2C1', addr: 0x68, init: RTC_INIT } },
     rtc_test_f429: { rtc: { i2c: 'I2C1', addr: 0x68, init: RTC_INIT } },
@@ -481,7 +484,7 @@ const boot = async () => {
     setStatus('booting…', 'stop');
     if (emu) { try { emu.close(); } catch (e) {} emu = null; }
     oledCacheKey = ''; tftCacheKey = ''; buzzerCacheKey = ''; rtcCacheKey = ''; ppsCacheKey = ''; TRACES.length = 0; { const cv = traceCanvas(); if (cv) cv._dma = []; } renderTraces();
-    if (audioCtx) { try { audioCtx.close(); } catch (e) {} audioCtx = null; audioQueued = 0; }
+    if (audioCtx) { try { audioCtx.close(); } catch (e) {} audioCtx = null; audioQueued = 0; audioDropped = 0; if (window.__audioCtx) delete window.__audioCtx; }
     gpioDrivenHigh.clear();
 
     const fw = image.flash;
@@ -546,19 +549,24 @@ const boot = async () => {
         // ── local mode: WASM runs in the browser (default) ──
         // Board variant per firmware preset (SVD + flash/RAM sizes), honoring
         // the board selector when the preset supports the selected board.
-        // NOTE (VENDOR_V): vendor asset versions (?v=41) must be bumped together
+        // NOTE (VENDOR_V): vendor asset versions (?v=43) must be bumped together
         // after every wasm-pack rebuild, or browsers keep the stale model.
         const { key: boardKey, board } = boardForSelection(image.name, boardSelectEl ? boardSelectEl.value : 'all');
-        const svdXml = await fetch('vendor/' + board.svd + '?v=41').then((r) => r.text());
+        const svdXml = await fetch('vendor/' + board.svd + '?v=43').then((r) => r.text());
         if (id !== session) return;
 
         netsim = gw.connected ? null : createNetSim();
         // Scripted USB host when the demo preset boots locally.
         usbhost = (!bridgeUrl && image.name.startsWith('usb_cdc_test')) ? createUsbHost(bindings) : null;
-        // Harness arms for eth_feat_test (local mode only): the guest
-        // prints markers and spins, the page arms collisions + link (same
-        // mechanism as the node matrix hooks).
-        featHooks = (!bridgeUrl && image.name.startsWith('eth_feat_test') && bindings && typeof bindings.eth_arm_collision === 'function')
+        // Harness arms for collision tests (local mode only): the guest
+        // prints COLLIDE ARM and spins, the page arms the one-shot
+        // collision + link hooks (same mechanism as the node matrix).
+        // Covers eth_feat_test AND eth_pins_test (its COL phase needs the
+        // same arm-before-TX timing; without it PINS COL FAILs while the
+        // node harness passes).
+        featHooks = (!bridgeUrl && bindings && typeof bindings.eth_arm_collision === 'function'
+            && (image.name.startsWith('eth_feat_test') || image.name.startsWith('eth_pins_test'))
+        )
             ? { collideDone: 0, linkDown: false, linkUp: false } : null;
         gw.tx = 0; gw.rx = 0;
         if (gw.connected) setGwStatus(true, gwLabel());
@@ -569,7 +577,7 @@ const boot = async () => {
             svdFile: board.svd,
             flash_size: board.flash_size,
             ram_size: board.ram_size,
-            wasmUrl: 'vendor/stm32_periph_wasm_bg.wasm?v=41',
+            wasmUrl: 'vendor/stm32_periph_wasm_bg.wasm?v=43',
             extra_mem: image.extraMem,
             uart_addr: image.uartAddr,
             enable_irqs: IRQ_FIRMWARES.has(image.name),
@@ -634,13 +642,14 @@ const loop = async (id) => {
     while (session === id) {
         if (!running) { await raf(); continue; }
         try {
-            // eth_feat_test/eth_adv run at 20k-inst steps: their wire-rate
-            // bands and race windows are calibrated for fine steps (the
-            // node matrix uses 5k-20k); 100k steps would overshoot every
-            // band (observed: eth_adv FRAG FAILs at 100k — both fragments
-            // consumed before the reassembly loop polls — while 20k passes
-            // 13/13; the node matrix runs both at 20k).
-            const fineSteps = image && (image.name.startsWith('eth_feat_test') || image.name.startsWith('eth_adv'));
+            // eth_feat_test/eth_adv/eth_pins_test run at 20k-inst steps:
+            // their wire-rate bands and race windows are calibrated for
+            // fine steps (the node matrix uses 5k-20k); 100k steps would
+            // overshoot every band (observed: eth_adv FRAG FAILs at 100k —
+            // both fragments consumed before the reassembly loop polls —
+            // while 20k passes 13/13; eth_pins_test COL needs the arm to
+            // land inside the TX window; the node matrix runs all at 20k).
+            const fineSteps = image && (image.name.startsWith('eth_feat_test') || image.name.startsWith('eth_adv') || image.name.startsWith('eth_pins_test'));
             const res = await emu.step(fineSteps ? 20000 : undefined);
             totalInst = res.instCount;
             stepsDone++;
@@ -663,7 +672,7 @@ const loop = async (id) => {
         try {
             if (!bridgeUrl && image && image.name.startsWith('dcmi_test') && bindings.dcmi_feed_frame) driveDcmi();
         } catch (e) {}
-        // Harness arms for eth_feat_test (local mode only).
+        // Harness arms for collision tests (local mode only; see boot).
         try {
             if (featHooks) {
                 const arms = uartBuf.split('COLLIDE ARM').length - 1;
@@ -1194,6 +1203,13 @@ const renderBuzzer = () => {
 
 const speakerInfo = $('speakerInfo');
 let audioCtx = null, audioNextTime = 0, audioQueued = 0;
+// Cap on scheduled-ahead audio: the guest produces faster than realtime
+// (a tone loop emits unbounded samples per second of wall time), so an
+// uncapped scheduler piles up hundreds of seconds of BufferSources —
+// audible only after a huge delay, plus unbounded graph/memory growth.
+// MAX_AHEAD keeps ~2 s scheduled; excess samples are dropped (counted).
+const AUDIO_MAX_AHEAD_S = 2.0;
+let audioDropped = 0;
 const renderSpeaker = () => {
     if (!emu || !emu.takeSpeakerSamples) { speakerInfo.textContent = 'no audio firmware'; return; }
     const samples = emu.takeSpeakerSamples();
@@ -1201,12 +1217,19 @@ const renderSpeaker = () => {
     if (!audioCtx) {
         try { audioCtx = new (window.AudioContext || window.webkitAudioContext)(); } catch (e) {}
         if (!audioCtx) { speakerInfo.textContent = 'WebAudio unavailable'; return; }
-        audioNextTime = audioCtx.currentTime + 0.05;
+        audioNextTime = Math.max(audioNextTime, audioCtx.currentTime + 0.05);
+        window.__audioCtx = audioCtx;
     }
     if (audioCtx.state === 'suspended') audioCtx.resume();
+    // Rebase late schedulers (tab was hidden / long pause): never schedule
+    // in the past, never more than MAX_AHEAD ahead of now.
+    audioNextTime = Math.max(audioNextTime, audioCtx.currentTime + 0.02);
     let off = 0;
     while (off < samples.length) {
-        const n = Math.min(4096, samples.length - off);
+        const headroom = AUDIO_MAX_AHEAD_S - (audioNextTime - audioCtx.currentTime);
+        if (headroom <= 0) { audioDropped += samples.length - off; break; }
+        const maxN = Math.floor(headroom * audioCtx.sampleRate);
+        const n = Math.min(4096, samples.length - off, Math.max(1, maxN));
         const buf = audioCtx.createBuffer(1, n, audioCtx.sampleRate);
         const ch = buf.getChannelData(0);
         for (let i = 0; i < n; i++) ch[i] = samples[off + i];
@@ -1218,7 +1241,10 @@ const renderSpeaker = () => {
         off += n;
         audioQueued += n;
     }
-    speakerInfo.textContent = `I2S capture playing — ${(audioQueued / audioCtx.sampleRate).toFixed(1)} s queued`;
+    window.__audioQueued = audioQueued;
+    window.__audioDropped = audioDropped;
+    const ahead = Math.max(0, audioNextTime - audioCtx.currentTime);
+    speakerInfo.textContent = `I2S capture playing — ${(audioQueued / audioCtx.sampleRate).toFixed(1)} s queued (${ahead.toFixed(1)} s ahead${audioDropped ? `, ${audioDropped} dropped` : ''})`;
 };
 
 let rtcCacheKey = '';

package/site/console.html

@@ -957,7 +957,7 @@ canvas {
     · <a href="about.html">About</a>
  </footer>
 
-<script type="module" src="app.js?v=50"></script>
+<script type="module" src="app.js?v=52"></script>
 <script>
 // Custom firmware dropdown (replaces native <select>)
 (() => {

package/site/emulator.js

@@ -461,6 +461,10 @@ export async function createEmulator(opts) {
                 hint = String(opts.chipHint || opts.svdFile || '');
                 hint = hint.split('/').pop().split('.').slice(0, -1).join('.') || hint;
             } catch {}
+            // compat[0] may carry no SVD filename (older callers pass none):
+            // default to the F407 identity rather than an empty hint that
+            // leaves IDCODE at its reset value (comprehensive_test pins 0x413).
+            if (!hint) hint = 'stm32f407';
             init_svd_chip(svdXml, hint);
         } else init_svd(svdXml);
     }