stm32f4-emu 1.2.1 → 1.4.0

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/cli.mjs

@@ -15,9 +15,11 @@ import { dirname, resolve } from 'node:path';
 import * as bindings from './site/vendor/stm32_periph_wasm.js';
 import { createEmulator } from './site/emulator.js';
 import { parseIntelHex, parseElf } from './site/loaders.js';
+import { CHIPS, chipInfo } from './site/stm32f4.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const svdXml = readFileSync(resolve(__dirname, 'site/vendor/stm32f407.svd'), 'utf8');
+const svdCache = {};
+const svdFor = (f) => svdCache[f] || (svdCache[f] = readFileSync(resolve(__dirname, 'site/vendor/' + f), 'utf8'));
 const wasmBytes = new Uint8Array(readFileSync(resolve(__dirname, 'site/vendor/stm32_periph_wasm_bg.wasm')));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf8'));
 
@@ -32,6 +34,7 @@ Arguments:
 Options:
   -n, --inst <N>        instruction budget to run (default 20000000)
   -f, --format <fmt>    firmware format: auto|bin|hex|elf (default auto)
+  -c, --chip <chip>     chip: stm32f401|stm32f411|stm32f407|stm32f407ve|stm32f429 (default stm32f407)
   -v, --verbose         trace guest PCs to stderr (capped per step)
   -l, --lowpower        halt on WFI/WFE and advance the virtual RTC until wakeup
   -h, --help            show this help
@@ -62,6 +65,7 @@ async function main() {
     let firmwarePath = null;
     let inst = 20000000;
     let format = 'auto';
+    let chipKey = 'stm32f407';
     let verbose = false;
     let lowpower = false;
     for (let i = 0; i < args.length; i++) {
@@ -81,6 +85,11 @@ async function main() {
             if (!['auto', 'bin', 'hex', 'elf'].includes(format)) fail(`invalid --format: ${format}`);
             continue;
         }
+        if (a === '-c' || a === '--chip') {
+            chipKey = String(args[++i] || '').toLowerCase();
+            if (!CHIPS[chipKey]) fail(`invalid --chip: ${args[i]} (have: ${Object.keys(CHIPS).join(', ')})`);
+            continue;
+        }
         if (a.startsWith('-')) fail(`unknown option: ${a}`);
         if (firmwarePath) fail('multiple firmware paths given');
         firmwarePath = a;
@@ -115,8 +124,13 @@ async function main() {
 
     let emu;
     try {
+        const chip = chipInfo(chipKey);
         emu = await createEmulator({
-            firmware, bindings, svdXml, wasmInit: wasmBytes,
+            firmware, bindings,
+            svdXml: svdFor(chip.svd), svdFile: chip.svd,
+            wasmInit: wasmBytes,
+            flash_size: chip.flash_size, ram_size: chip.ram_size,
+            chipHint: chip.svd.replace(/\.svd$/, ''),
             extra_mem, lowpower,
         });
     } catch (e) {

package/index.d.ts

@@ -15,10 +15,343 @@ export function createNetSim(opts?: any): any;
 
 export const FIRMWARES: Record<string, { bytes: string; [key: string]: unknown }>;
 export const bindings: any;
-export const unicornFactory: any;
 export const svdXml: string;
+// Removed: unicornFactory (Unicorn backend deleted — Rust CPU is sole backend).
 
-// 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;
+  // Peripheral-domain helpers (ETH status, DMA2D jobs, NAND, trace/FPU).
+  ethMacAddr(): bigint;
+  ethTxDeferred(): boolean;
+  ethCollisionArmed(): boolean;
+  ethArmCollision(): void;
+  ethPauseTx(): number;
+  ethBackoffSlots(attempt: number, seed: number): number;
+  dma2dTakeJob(): number[];
+  dma2dJobDone(): void;
+  dma2dFifoThreshold(dma: string, stream: number): number;
+  dmaStreamCt(dma: string, stream: number): boolean;
+  dmaStreamFeif(dma: string, stream: number): boolean;
+  fsmcBindNand(bank: number, size: number): void;
+  fsmcNandErase(bank: number, offset: number, len: number): void;
+  traceStart(): void;
+  traceStop(): void;
+  takeTrace(): number[];
+  getFpuState(): any;
+  setSreg(i: number, v: number): void;
+  setFpscr(v: number): void;
+  wdogRequested(): boolean;
+  wdogClearFlags(): void;
+  wdogIwdgFlag(): boolean;
+  wdogWwdgFlag(): boolean;
+  flashProgramming(): boolean;
+  // Protocol helpers (USB status/VBUS, UART LIN/SMARTCARD/IrDA, CAN error/FD).
+  usbInStatus(ep: number): number;
+  usbOutStatus(ep: number): number;
+  usbHsInStatus(ep: number): number;
+  usbHsOutStatus(ep: number): number;
+  usbSetVbus(present: boolean): void;
+  usbHsSetVbus(present: boolean): void;
+  usbFrame(): number;
+  usbHsFrame(): number;
+  usbUlpiRate(): number;
+  usbHsUlpiRate(): number;
+  usbDmaProgress(ep: number): any;
+  uartBreakTx(base: number): void;
+  uartIrdaRx(base: number, byte: number, lowPower?: boolean): void;
+  uartIrdaTxClass(base: number): number;
+  uartSmartcardNack(base: number): void;
+  uartSmartcardRetries(base: number): number;
+  canNoteError(base: number, lec: number, recover?: boolean): void;
+  canFdLen(base: number, fifo: number, slot: number): number;
+  canFdByte(base: number, fifo: number, slot: number, idx: number): number;
+  canFdCost(base: number, fd: boolean, brs: boolean, payloadBytes: number): bigint;
+  i2cPec(base: number): number;
+  spiFlashDebug(peripheral: string): number[];
+  sdioCardIrq(set: boolean): void;
+  rtcTamper(): void;
+  audioLoadWav(bytes: Uint8Array | number[]): void;
+  ltdcClutEntry(layer: number, idx: number): number;
+  ltdcLutPixel(layer: number, pf: number, byte: number): number;
+  // 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;
@@ -46,7 +379,59 @@ export class Potentiometer {
 export class I2cRegisterDevice {
   constructor(emu: any, peripheral: string, opts?: any);
 }
+// Hardware-substitute components (close the documented model gaps — pure
+// JS on existing wasm exports, see site/components.js).
+export class CameraSensor {
+  constructor(emu: any, opts?: { width?: number; height?: number; scene?: string; noise?: number });
+  pixels(): Uint8Array;
+  capture(): boolean;
+  frame: number;
+}
+export class DacLoad {
+  constructor(emu: any, opts?: { channel?: number; vref?: number; bits?: number });
+  write(code: number): number;
+  get code(): number;
+  get voltage(): number;
+  get underrun(): boolean;
+}
+export class RngNoise {
+  constructor(emu: any, opts?: { source?: string; seed?: number });
+  seed(words?: number): number;
+  get avail(): number;
+}
+export class I2cPeer {
+  constructor(emu: any, opts?: { base?: number });
+  loseNextArbitration(): void;
+  alert(addr: number): void;
+}
+export class UsbLink {
+  constructor(emu: any, opts?: { hs?: boolean });
+  plug(): void;
+  unplug(): void;
+  get frame(): number;
+  get ulpiRate(): number;
+}
+export class UlpiMeter {
+  constructor(emu: any, opts?: { hs?: boolean });
+  get rateMbps(): number;
+  budgetBytes(usec: number): number;
+}
+export class UartBaud {
+  constructor(emu: any, opts?: { base?: number; clockHz?: number });
+  get brr(): number;
+  get over8(): number;
+  get baud(): number;
+  get txLen(): number;
+}
+export class NandEcc {
+  constructor();
+  enable(): void;
+  disable(): void;
+  write(word16: number): number;
+  get eccr(): number;
+}
 
+// 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

@@ -6,14 +6,18 @@ import * as bindings from './site/vendor/stm32_periph_wasm.js';
 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 { LED, Button, Pwm, Servo, I2cRegisterDevice, Potentiometer, CameraSensor, DacLoad, RngNoise, I2cPeer, UsbLink, UlpiMeter, UartBaud, NandEcc } from './site/components.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');
@@ -28,16 +32,28 @@ export function decodeFirmware(key) {
     return Uint8Array.from(bin, c => c.charCodeAt(0));
 }
 
-// Convenience: create an emulator with the bundled STM32F407 assets.
+// Convenience: create an emulator with the bundled assets.
 //   await createSTM32F407({ firmware })           // firmware: Uint8Array
 //   await createSTM32F407({ firmware: 'eth_http' })  // or a FIRMWARES key
+//   await createSTM32F407({ firmware, chip: 'stm32f401' })  // other chips
+// `chip` resolves SVD + flash/RAM + IDCODE from the facade CHIPS table
+// (default stm32f407); explicit svdXml/flash_size/ram_size opts override it.
 // All extra options pass through to createEmulator().
 export async function createSTM32F407(opts = {}) {
-    const { firmware } = opts;
+    const { firmware, chip = 'stm32f407' } = opts;
     const bin = typeof firmware === 'string' ? decodeFirmware(firmware) : firmware;
     if (!bin) throw new Error('createSTM32F407 requires `firmware` (Uint8Array or a FIRMWARES key)');
-    return createEmulator({ ...opts, firmware: bin, bindings, svdXml, wasmInit: wasmBytes });
+    const info = chipInfo(chip);
+    const cSvd = (opts.svdXml !== undefined) ? opts.svdXml
+        : readFileSync(new URL(`./site/vendor/${info.svd}`, import.meta.url), 'utf8');
+    return createEmulator({
+        ...opts, firmware: bin, bindings, wasmInit: wasmBytes,
+        svdXml: cSvd, svdFile: info.svd,
+        flash_size: opts.flash_size ?? info.flash_size,
+        ram_size: opts.ram_size ?? info.ram_size,
+        chipHint: info.svd.replace(/\.svd$/, ''),
+    });
 }
 
-export { createEmulator, createNetSim, FIRMWARES, bindings, svdXml, LED, Button, Pwm, I2cRegisterDevice, Potentiometer, STM32F4, GPIOPin, USART, DMAStream };
+export { createEmulator, createNetSim, FIRMWARES, bindings, svdXml, LED, Button, Pwm, Servo, I2cRegisterDevice, Potentiometer, CameraSensor, DacLoad, RngNoise, I2cPeer, UsbLink, UlpiMeter, UartBaud, NandEcc, STM32F4, GPIOPin, GPIO, USART, SPI, I2C, DMAStream, DMAController, Display, CHIPS, chipInfo };
 export { boardLed, BOARD_LED, BOARD_LED_ALIASES } from './site/boards.js';

package/mcp/server.mjs

@@ -9,7 +9,7 @@ import { readFileSync } from 'node:fs';
 // Sequential instances are supported (see docs/components.md), but there is
 // exactly one active system per process and creating a new one detaches the
 // old, so we close the previous instance before creating the next.
-import { createSTM32F407, FIRMWARES, LED, Button, Pwm, Potentiometer } from '../index.mjs';
+import { createSTM32F407, FIRMWARES, LED, Button, Pwm, Potentiometer, CHIPS } from '../index.mjs';
 
 // The MCP SDK and zod are OPTIONAL peer dependencies: the emulator library
 // itself has no runtime dependencies, and only this server needs them, so
@@ -73,16 +73,19 @@ server.registerTool('load_firmware', {
     inputSchema: {
         firmware: z.string().describe('a firmware key from list_firmwares, e.g. "blinky"'),
         enable_irqs: z.boolean().optional().describe('run guest IRQ handlers between batches (needed for interrupt-driven firmware; must stay off for the ETH demos)'),
+        chip: z.string().optional().describe(`chip variant: ${Object.keys(CHIPS).join('|')} (default stm32f407)`),
     },
-}, async ({ firmware, enable_irqs = false }) => {
+}, async ({ firmware, enable_irqs = false, chip = 'stm32f407' }) => {
     if (!FIRMWARES[firmware]) return err(`unknown firmware '${firmware}' (have: ${Object.keys(FIRMWARES).join(', ')})`);
+    if (!CHIPS[chip]) return err(`unknown chip '${chip}' (have: ${Object.keys(CHIPS).join(', ')})`);
     const replaced = session !== null;
     if (session) { try { session.emu.close(); } catch {} }
-    const emu = await createSTM32F407({ firmware, enable_irqs });
+    const emu = await createSTM32F407({ firmware, enable_irqs, chip });
     session = { emu, firmware, components: new Map() };
     componentSeq = 0;
     return text({
         loaded: firmware,
+        chip,
         enable_irqs,
         note: replaced
             ? 'Replaced a previous session. Peripheral state is process-global in the wasm model, so switching firmware in one process can misbehave (see docs/components.md) — restart this server for a fully clean boot.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stm32f4-emu",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "STM32F407 emulator: Rust CPU + peripheral model (WASM). Runs real Cortex-M4 firmware in Node or the browser.",
   "type": "module",
   "main": "index.mjs",
@@ -93,7 +93,7 @@
     "test:browser": "node site/test_browser.mjs",
     "test:edge": "node site/test_edge_cases.mjs",
     "test:fsmc": "node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/test_fsmc_dcmi.mjs",
-    "test:components": "node site/test_component_led.mjs && node site/test_component_button.mjs && node site/test_component_pwm.mjs && node site/test_component_i2cregfile.mjs && node site/test_component_adc.mjs",
+    "test:components": "node site/test_component_led.mjs && node site/test_component_button.mjs && node site/test_component_pwm.mjs && node site/test_component_i2cregfile.mjs && node site/test_component_adc.mjs && node site/test_components_subs.mjs",
     "test:mcp": "node mcp/test_mcp.mjs",
     "mcp": "node mcp/server.mjs",
     "bridge": "node site/ws-bridge.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"