stm32f4-emu 1.1.1 → 1.3.1

package/README.md

@@ -6,6 +6,14 @@
 [![CI](https://github.com/danish9661/stm32F4-emulator/actions/workflows/ci.yml/badge.svg)](https://github.com/danish9661/stm32F4-emulator/actions/workflows/ci.yml)
 [![Pages](https://github.com/danish9661/stm32F4-emulator/actions/workflows/pages.yml/badge.svg)](https://github.com/danish9661/stm32F4-emulator/actions/workflows/pages.yml)
 
+> **Status: emulation complete.** All 41 peripheral modules are Detailed
+> (0 Partial), all five board maps verify green (37/37/72/73/59 presets),
+> and the Ethernet descriptor layer (EDFE, TCH/TER + RCH/RER walks, RDES4,
+> backoff probe) plus the Wireshark-validated pcap capture (`a1b2c3d4`,
+> tcpdump-verified DHCP→TCP→HTTP) are in. What remains is product work,
+> not emulation: npm publish, https gateway endpoint, VS Code packaging
+> (see [docs/progress-and-future.md](docs/progress-and-future.md)).
+
 An STM32F407 microcontroller emulator that runs real Cortex-M4 firmware. It
 combines a **Rust CPU core** (a WASM-native Thumb-2 interpreter with exact
 Cortex-M exception entry/return, including the VFPv4-SP FPU) with a
@@ -15,7 +23,12 @@ browser tab**, with no SDL, no native deps, no hardware.
 
 It ships three real networking firmwares (`eth_http`, `eth_dhcp`, `eth_test`)
 that do DHCP + TCP + HTTP against a simulated (or a real gVisor-backed)
-network, a browser demo, and a publishable npm package.
+network, a 66-marker Ethernet feature matrix (`eth_feat_test`: PHY/MDIO,
+checksum offload, hash/perfect/SA/DA filtering, VLAN, PTP, WOL, wire
+pacing, deferral/collisions, pause frames, MMC, RBUS — see
+[NETWORKING.md](NETWORKING.md)) plus real LwIP 2.2.1 (`lwip_demo`) and
+MII/RMII pin mirrors (`eth_pins_test`), a browser demo, and a publishable
+npm package.
 
 ## Live demo
 
@@ -24,7 +37,7 @@ The browser demo deploys to GitHub Pages:
 **https://danish9661.github.io/stm32F4-emulator/**
 
 A single console page that starts **idle** — nothing runs until you pick a
-firmware: a preset dropdown with 31 bundled binaries (network demos, a
+firmware: a preset dropdown with 223 bundled binaries (network demos, a
 bare-metal LED blinker, peripheral/crypto/UART/SPI test binaries), custom
 firmware upload (`.bin`, Intel `.hex`, `.elf` — with loadable RAM segments
 and symbols — plus `.map` for a symbol table), Run/Stop/Reset, a **gateway
@@ -35,7 +48,7 @@ characters excluded per HTML spec, see AGENTS.md §11), GPIO pin readout
 for banks A–E, and key peripheral registers. Interrupt-driven firmware
 (`rx_interrupt_test`, `rx_crypto_test`) gets inline guest-IRQ delivery;
 polling firmware (the ETH demos) never uses it. For automation, a
-preset can auto-boot via the URL: `?fw=eth_http`, `?fw=blinky`, `?fw=crypto_test`, …
+preset can auto-boot via the URL: `console.html?fw=eth_http`, `console.html?fw=blinky`, `console.html?fw=crypto_test`, …
 
 ## DOOM (in the browser)
 
@@ -60,7 +73,7 @@ reloads.
 - Controls: move W/S/A/D + arrows · strafe Shift · fire Ctrl · use
   Space · menu Enter/Esc · save F2/F6 · load F3/F9 · F1/F10/F11/F12.
 - Boot → menu → gameplay verified end-to-end by
-  `node site/test_doom.mjs` (boot markers, menu navigation to E1M1,
+  `node site/test_doom_wasm.mjs` (boot markers, menu navigation to E1M1,
   palette + framebuffer, W-move + turn, audio, **save → `SAVE ok slot=0`
   → load handshake**).
 - `site/doom1.wad` is the 4.2 MB shareware WAD; the firmware never reads
@@ -77,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
-# then open http://127.0.0.1:8123?bridge=ws://127.0.0.1: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)
 ```
 
@@ -119,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 —
@@ -142,17 +160,17 @@ 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/?bridge=ws://127.0.0.1:8234"
+open "http://127.0.0.1:8123/console.html?bridge=ws://127.0.0.1:8234"
 ```
 
 The `RemoteEmu` adapter (`site/remote-emu.js`) is a drop-in replacement
 for the local `emu` object — same `step()`/`drainUart()`/`read32()` API,
 all proxied over binary WebSocket. Device stubs (OLED/TFT/etc.) run in
 Node and are not visible to browser JS. Without `?fw=`, the page boots
-whatever firmware the bridge was started with; with `?fw=blinky&bridge=ws://…`,
+whatever firmware the bridge was started with; with `console.html?fw=blinky&bridge=ws://…`,
 the browser sends the firmware image over the bridge.
 
 See AGENTS.md §20 for the full binary protocol reference.
@@ -164,8 +182,11 @@ See AGENTS.md §20 for the full binary protocol reference.
 | `eth_http/` | DHCP + TCP client + HTTP GET + prints the response | `TCP connected`, `=== HTTP <len>b ===` |
 | `eth_dhcp/` | Loops DHCP Discover/Offer/Request/Ack | `DHCP SUCCESS` |
 | `eth_test/` | Raw ETH TX/RX self-test | `ETH Test: done` |
+| `eth_feat_test/` | 66-marker Ethernet feature matrix (netsim, F407 + F429) | `FEAT Test: done` (all 66 markers, `FAIL`/`TIMEOUT` anti-markers) |
+| `lwip_demo/` | Real LwIP 2.2.1 (DHCP→DNS→TCP echo→TCP server→UDP echo) | `LWIP DEMO DONE` |
+| `eth_pins_test/` | MII/RMII pin-level mirrors (TX_EN/CRS_DV/RXD/COL/MDIO/MDC) | `PINS ALL PASS` |
 | `blinky/` | **No ethernet** — LED blinker on GPIOA PA5 + UART tick counter | `tick N LED=ON/OFF` |
-| `doom/` | **DOOM 1 shareware** (doomgeneric F407 port, browser page `site/doom.html`) | `node site/test_doom.mjs` (boot + menu + gameplay + save/load) |
+| `doom/` | **DOOM 1 shareware** (doomgeneric F407 port, browser page `site/doom.html`) | `node site/test_doom_wasm.mjs` (boot + menu + gameplay + save/load) |
 
 Plus 17 more test binaries (`crypto_test`, `hal_test`, `timer_test`,
 `periph_test`, `echo_test`, `blink_serial`, `rx_interrupt_test`,
@@ -198,10 +219,13 @@ 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`).
-- **Ethernet**: TX is captured from the DMA descriptors; RX frames are
-  injected into the RX ring and the firmware's `eth_irq_flag` (SRAM) drives
-  polling — no interrupts required. Optionally, a Go gateway
+  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
+  register map is cross-checked against CMSIS `stm32f407xx.h` (DMASR/
+  DMAIER/MACFFR/MACPMTCTL positions — see [NETWORKING.md](NETWORKING.md)
+  §6 for the audit). Optionally, a Go gateway
   (`openhw-local-gateway/`) with a gVisor network stack makes the firmware
   talk to a real network: `node cli.mjs <fw.bin> <inst> --gateway`.
 - **Browser build** (`site/`): same modules as ESM; `site/emulator.js` is an
@@ -230,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
 ```
 
@@ -248,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
@@ -259,7 +282,10 @@ rebuild — delete it so the vendor assets stay tracked/committed.
 
 ## Testing
 
-- `npm test` — flow test (`site/test_flow.mjs`) + blinky test
+- `npm test` — flow test (`site/test_flow.mjs`) + Ethernet mock harnesses
+  (`site/test_eth_mock_model.mjs`: 18 checks, fake bindings + real driver;
+  `site/test_eth_mock_consumer.mjs`: 44 checks, fake firmware + real model)
+  + blinky test
   (`site/test_blinky.mjs`) + interrupt-UART test (`site/test_rx_interrupt.mjs`)
   + component-API tests (`site/test_component_{led,button,pwm,i2cregfile}.mjs`,
   each against real firmware — LED/blinky, Button/exti_test, Pwm/buzzer_test,
@@ -269,7 +295,7 @@ rebuild — delete it so the vendor assets stay tracked/committed.
   process (see docs/components.md). The same suite runs in CI on
   `ubuntu-latest`/`windows-latest`/`macos-latest`
   ([.github/workflows/ci.yml](.github/workflows/ci.yml)) on every push.
-- `node site/test_doom.mjs` — DOOM boot → menu → E1M1 gameplay + save/load
+- `node site/test_doom_wasm.mjs` — DOOM boot → menu → E1M1 gameplay + save/load
   (see the DOOM section above).
 - `scripts/verify_ethernet.sh [max_inst]` — runs all three firmwares through
   the gateway, asserts the success markers and 0 `TCP fail`.
@@ -281,7 +307,7 @@ rebuild — delete it so the vendor assets stay tracked/committed.
 - [site/about.html](site/about.html) — in-repo About page: what it is, architecture, featured firmwares, and how to use it (CLI / browser / Node API / MCP).
 - [docs/architecture.md](docs/architecture.md) — how the emulator is put
   together (CPU, peripheral model, drivers, ETH flow, interrupts).
-- [docs/peripherals.md](docs/peripherals.md) — all 33 peripherals and the
+- [docs/peripherals.md](docs/peripherals.md) — all 41 peripherals and the
   level each is implemented to, plus external devices and known gaps.
 - [docs/usage.md](docs/usage.md) — CLI, browser, and npm-library usage,
   config files, env vars, building.

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;
@@ -46,3 +326,11 @@ export class Potentiometer {
 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; }
+export declare const BOARD_LED: Record<string, BoardLed>;
+export declare const BOARD_LED_ALIASES: Record<string, BoardLed>;
+export declare function boardLed(fwName: string, boardKey: string): BoardLed;

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,4 +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/mcp/server.mjs

@@ -252,4 +252,27 @@ server.registerTool('reset', {
     return text(`closed session (${was})`);
 });
 
+server.registerTool('reset_cpu', {
+    description: 'Host reset button: CPU back to the vector-table SP/PC, peripherals keep state (like a real NRST pulse without the hold). Prefer over load_firmware when re-running the same image.',
+    inputSchema: {},
+}, async () => {
+    const { emu } = requireSession();
+    if (typeof emu.resetCpu === 'function') emu.resetCpu();
+    else emu.reset();
+    return text('cpu reset to vector table');
+});
+
+server.registerTool('set_nrst', {
+    description: 'Hold (assert=true) or release the NRST line. While held, step() only advances the model clock — the CPU executes nothing, like real hardware in reset. Query with level omitted.',
+    inputSchema: { level: z.boolean().optional().describe('true = assert (hold in reset), false = release; omit to query') },
+}, async ({ level }) => {
+    const { emu } = requireSession();
+    if (level === undefined) {
+        const s = typeof emu.isNrstAsserted === 'function' ? emu.isNrstAsserted() : false;
+        return text({ asserted: !!s });
+    }
+    const s = typeof emu.setNrst === 'function' ? emu.setNrst(level) : false;
+    return text({ asserted: !!s });
+});
+
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stm32f4-emu",
-  "version": "1.1.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",
@@ -31,6 +31,7 @@
     "site/emulator.js",
     "site/emulator.d.ts",
     "site/stm32f4.js",
+    "site/boards.js",
     "site/components.js",
     "site/netsim.js",
     "site/firmware.js",
@@ -39,6 +40,7 @@
     "site/ws-bridge.mjs",
     "site/app.js",
     "site/index.html",
+    "site/console.html",
     "site/vendor/",
     "mcp/server.mjs",
     "tools/make_firmware.mjs"
@@ -66,8 +68,8 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_blinky.mjs && node site/test_rx_interrupt.mjs && 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_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs && node site/test_fpu.mjs && node site/test_fpu_irq.mjs && node site/test_mpu.mjs && node site/test_usb.mjs && node site/test_qspi_cdp.mjs && node site/test_browser.mjs",
-    "test:unit": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_blinky.mjs && node site/test_rx_interrupt.mjs && 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_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs",
+    "test": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_eth_mock_model.mjs && node site/test_eth_mock_consumer.mjs && node site/test_periph_mock_consumer.mjs && node site/test_blinky.mjs && node site/test_blinky_f401.mjs && node site/test_blinky_f411.mjs && node site/test_blinky_f407g.mjs && node site/test_blinky_nucleo_f401.mjs && node site/test_blinky_nucleo_f411.mjs && node site/test_blinky_f429.mjs && node site/test_blinky_f407ve.mjs && node site/test_rx_interrupt.mjs && 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_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs && node site/test_fpu.mjs && node site/test_fpu_irq.mjs && node site/test_mpu.mjs && node site/test_usb.mjs && node site/test_arduino_boards.mjs && node site/test_exti.mjs && node site/test_flash.mjs && node site/test_spi_flash.mjs && node site/test_board_matrix.mjs && node site/test_qspi_cdp.mjs && node site/test_browser.mjs",
+    "test:unit": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_blinky.mjs && node site/test_blinky_f401.mjs && node site/test_blinky_f411.mjs && node site/test_blinky_f407g.mjs && node site/test_blinky_nucleo_f401.mjs && node site/test_blinky_nucleo_f411.mjs && node site/test_blinky_f429.mjs && node site/test_blinky_f407ve.mjs && node site/test_rx_interrupt.mjs && 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_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs",
     "test:bridge": "node site/test_ws_bridge.mjs",
     "test:bridge:browser": "node site/test_bridge_cdp.mjs",
     "test:flow": "node site/test_flow.mjs",
@@ -81,7 +83,9 @@
     "test:wwdgwin": "node site/test_wwdg_window.mjs",
     "test:timcap": "node site/test_tim_capture.mjs",
     "test:lowpower": "node site/test_lowpower.mjs",
+    "test:standby": "node site/test_standby.mjs",
     "test:qspi": "node site/test_qspi.mjs",
+    "test:eth:mock": "node site/test_eth_mock_model.mjs && node site/test_eth_mock_consumer.mjs && node site/test_periph_mock_consumer.mjs",
     "test:fpu": "node site/test_fpu.mjs",
     "test:fpuirq": "node site/test_fpu_irq.mjs",
     "test:mpu": "node site/test_mpu.mjs",
@@ -100,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"