stm32f4-emu 0.1.0

package/README.md

@@ -0,0 +1,273 @@
+# STM32F4 Emulator
+
+[![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)
+
+An STM32F407 microcontroller emulator that runs real Cortex-M4 firmware. It
+combines a **Unicorn CPU core** (QEMU-derived, compiled to WASM) with a
+**Rust peripheral model** (RCC, USART, GPIO, DMA, ETH, TIM, NVIC, ...) also
+compiled to WASM — so the whole machine runs headless in **Node.js or a
+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.
+
+## Live demo
+
+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
+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
+URL field** to connect a real network stack (openhw-gw + gVisor) with a
+scripted network (netsim) as fallback, a live UART terminal (with **UART
+RX input** — type into the console and the firmware reads it; newline
+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`) is serviced by an opt-in guest-IRQ
+pump; 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`, …
+
+## DOOM (in the browser)
+
+**[`site/doom.html`](site/doom.html)** runs DOOM 1 shareware
+(doomgeneric, ported to the emulated F407) at ~25 FPS in a
+headless-Chrome-verified browser page — playable, but below DOOM's native
+35 fps: at ~918k guest instructions per rendered frame, 35 fps would need
+~32 MIPS and the Unicorn WASM core tops out near 20-24 (details and the
+measurements in AGENTS.md §16). Because the guest mixes one frame of audio
+per rendered frame, sound below 35 fps plays slightly slow and pitched-down
+rather than breaking up — the worklet rate-matches instead of inserting
+gaps, and the stats line reports it (`audio 0.72x`). The page: 320×200
+CMAP256 framebuffer,
+WASD + arrows + Ctrl/Space/Shift + F-keys, I2S audio out (mixer →
+AudioWorklet at 11025 Hz), and a realtime lock that paces the guest to
+wall time. **Save/load works**: the firmware stages savegames to an
+EXTRAM region (2 slots × 256 KB at 0xC0080000) and `doom.js` mirrors
+them to `localStorage['doom-save-N']`, so F6 (quick-save), F2 (save
+menu), F9 (quick-load, 'y' to confirm) and F3 (load menu) survive page
+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,
+  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
+  it from flash — the driver loads it into 8 MB of `extra_mem`
+  (0xB8000000).
+
+## Quickstart
+
+```bash
+# browser demo locally
+npm run serve                  # then open http://127.0.0.1:8123
+
+# node end-to-end flow test (boot -> DHCP -> TCP -> HTTP, 2 rounds)
+npm test                       # == node site/test_flow.mjs
+
+# 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
+# (requires an HTTP server at 127.0.0.1:8092; see AGENTS.md §10)
+```
+
+## Use it as a library (npm package)
+
+`npm pack` produces `stm32f4-emu` — the full emulator as a library,
+with all WASM assets, the SVD register map, and the firmware binaries
+bundled:
+
+```js
+import { createSTM32F407, createNetSim, FIRMWARES } from 'stm32f4-emu';
+
+const netsim = createNetSim();                        // canned DHCP/TCP/HTTP peer
+const emu = await createSTM32F407({
+    firmware: FIRMWARES.eth_http.bytes,               // any STM32F4 firmware blob
+    onTx: (frame) => {
+        for (const reply of netsim.onTx(frame)) emu.injectFrame(reply);
+    },
+});
+
+emu.step(100000);              // run up to 100k instructions
+const uart = emu.drainUart();  // collect UART output
+emu.injectFrame(packetBytes);  // inject an Ethernet frame
+```
+
+See `site/test_flow.mjs` and the exports in `index.mjs` for the full API
+(`decodeFirmware`, `createEmulator`, `createNetSim` re-exports).
+
+Attach virtual hardware (LEDs, buttons, PWM readers, analog sensors,
+custom SPI/I2C devices) to pins and buses with the component API —
+`emu.pin()`/`emu.watchPin()`/`emu.setAdcChannel()` plus the
+`LED`/`Button`/`Pwm`/`Potentiometer`/`I2cRegisterDevice` components, or
+`ext_devices.spiDevices`/`i2cDevices` for your own bus protocol. See
+[docs/components.md](docs/components.md).
+
+## Drive it from an AI agent (MCP)
+
+`mcp/server.mjs` exposes the emulator over the Model Context Protocol —
+boot firmware, step, read UART, poke pins, inject ADC values, and inspect
+registers as tools an MCP client (Claude Code, Claude Desktop) can call:
+
+```bash
+npm install && npm run mcp
+```
+
+The MCP SDK is an *optional peer dependency*, so installing this package
+as a library stays dependency-free; only MCP users need
+`npm i @modelcontextprotocol/sdk zod`. See [docs/mcp.md](docs/mcp.md) for
+the tool reference and client config.
+
+## Firmwares
+
+| Firmware | What it does | Success marker |
+|---|---|---|
+| `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` |
+| `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) |
+
+Plus 17 more test binaries (`crypto_test`, `hal_test`, `timer_test`,
+`periph_test`, `echo_test`, `blink_serial`, `rx_interrupt_test`,
+`spi_tft_test`, …) from the `*_test/` directories — all boot headless and
+print a banner over UART (probe: `node site/probe_firmwares.mjs`).
+
+All are bare-metal (no RTOS), built with the Arduino core's
+arm-none-eabi-gcc, and driven purely through memory-mapped registers —
+the same firmware binaries run on the emulator and on real silicon. That
+equivalence is for **logic**, not **timing**: timers/ADC/RNG/RTC/watchdogs
+are instruction-count driven rather than wall-clock driven, so firmware
+relying on real-time behavior (PWM frequency matching real hardware,
+watchdog timeouts close to spec) will diverge — see docs/progress-and-future.md#known-limitations.
+
+## Architecture
+
+```
+firmware .bin ──► Unicorn WASM CPU ──► memory hooks
+                          │
+                    periph_read/write ──► Rust peripheral model (WASM)
+                                          RCC USART GPIO DMA ETH TIM NVIC
+                          │
+                    UART out / ETH TX frames ──► driver (cli.mjs / site/emulator.js)
+                          │
+                    RX frames injected (netsim, or real gVisor gateway)
+```
+
+- **CPU**: Unicorn 2.1.4 compiled to WASM executes Thumb-2 code; every
+  read/write to a hooked MMIO range is routed into the Rust model, which
+  answers by writing the modeled register value back into guest memory.
+- **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
+  (`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
+  import-free universal factory; `site/netsim.js` is a canned network peer;
+  `site/loaders.js` parses Intel HEX / ELF32 / linker-map files. The demo
+  page's gateway mode uses the exact same protocol as the Node CLI:
+  raw Ethernet frames over a WebSocket (`/api/network-gateway`), `RESET`
+  control message on reboot.
+
+## Repository layout
+
+```
+├── site/                    Single-page console + universal emulator factory
+│   ├── index.html, app.js   Console UI (UART, presets, loaders, gateway, GPIO)
+│   ├── doom.html, doom.js   DOOM page (gameplay + save/load via localStorage)
+│   ├── emulator.js          Import-free emulator factory (Node + browser)
+│   ├── components.js        Virtual components (LED/Button/Pwm/Potentiometer/...)
+│   ├── netsim.js            Canned DHCP/TCP/HTTP network peer (fallback)
+│   ├── loaders.js           Intel HEX / ELF32 / linker-map parsers
+│   ├── test_flow.mjs        Node E2E flow test (npm test)
+│   ├── test_blinky.mjs      Node blinky GPIO test (npm test)
+│   ├── test_rx_interrupt.mjs Node UART-interrupt test (npm test)
+│   ├── test_component_*.mjs Component-API tests, one firmware each (npm test)
+│   ├── test_doom.mjs        Node DOOM boot/menu/gameplay/save test
+│   └── vendor/              Browser WASM build, SVD, Unicorn
+├── 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
+├── 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)
+├── 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)
+└── AGENTS.md                Full architecture, build steps, runbook
+```
+
+## Building from source
+
+```bash
+# Rust peripheral model (Node target; browser target goes to site/vendor/)
+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
+
+# native SDL emulator (upstream heritage, not the headless path)
+cd stm32-emulator-main && cargo build --release
+```
+
+`wasm-pack` writes `site/vendor/.gitignore` containing `*` after a browser
+rebuild — delete it so the vendor assets stay tracked/committed.
+
+## Testing
+
+- `npm test` — flow test (`site/test_flow.mjs`) + 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,
+  I2cRegisterDevice/rtc_test), exit 0 = all PASS. Each test file boots
+  exactly one firmware in its own `node` process — `createEmulator()`
+  instances aren't safe to reuse across different firmware in the same
+  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
+  (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`.
+- Soak-tested: 200M-instruction gateway runs with 1000+ consecutive TCP
+  rounds, 0 failures (details in AGENTS.md §10).
+
+## Documentation
+
+- [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
+  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.
+- [docs/components.md](docs/components.md) — attach virtual LEDs, buttons,
+  PWM/analog sensors, and custom SPI/I2C devices to pins/buses
+  (rp2040js-style component API).
+- [docs/mcp.md](docs/mcp.md) — the MCP server: drive the emulator as tools
+  from Claude Code / Claude Desktop or any MCP client.
+- [docs/benchmarks.md](docs/benchmarks.md) — throughput numbers, soak
+  results, tunables.
+- [docs/progress-and-future.md](docs/progress-and-future.md) — status,
+  known limitations, roadmap.
+
+## License
+
+GPL-3.0-only. See [LICENSE](LICENSE).
+
+*This repository is a fork/continuation of
+[nviennot/stm32-emulator](https://github.com/nviennot/stm32-emulator), which
+emulated 3D-printer firmwares (Elegoo Saturn, Anycubic Mono X) in a native
+SDL app. The WASM headless emulator, network firmwares, browser demo, and npm
+package are new work built on that base.*

package/index.mjs

@@ -0,0 +1,39 @@
+// stm32f4-emu — Node API entry.
+// Wraps the browser/Node-universal emulator.js with the bundled assets
+// (SVD, wasm bindings, Unicorn) so Node consumers get a one-call setup.
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+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';
+
+const require = createRequire(import.meta.url);
+const unicornFactory = require('./site/vendor/unicorn_arm.cjs');
+
+const svdXml = readFileSync(new URL('./site/vendor/stm32f407.svd', import.meta.url), 'utf8');
+const wasmBytes = new Uint8Array(readFileSync(new URL('./site/vendor/stm32_periph_wasm_bg.wasm', import.meta.url)));
+
+// Decode a base64-encoded firmware from FIRMWARES.
+export function decodeFirmware(key) {
+    const fw = FIRMWARES[key];
+    if (!fw) throw new Error(`unknown firmware '${key}' (have: ${Object.keys(FIRMWARES).join(', ')})`);
+    const bin = atob(fw.bytes);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+}
+
+// Convenience: create an emulator with the bundled STM32F407 assets.
+//   await createSTM32F407({ firmware })           // firmware: Uint8Array
+//   await createSTM32F407({ firmware: 'eth_http' })  // or a FIRMWARES key
+// All extra options pass through to createEmulator().
+export async function createSTM32F407(opts = {}) {
+    const { firmware } = 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, unicorn: unicornFactory, svdXml, wasmInit: wasmBytes });
+}
+
+export { createEmulator, createNetSim, FIRMWARES, bindings, unicornFactory, svdXml, LED, Button, Pwm, I2cRegisterDevice, Potentiometer };

package/mcp/server.mjs

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// MCP server exposing the STM32F407 emulator as tools an MCP client
+// (Claude Code / Claude Desktop / any MCP host) can drive: load firmware,
+// step execution, read/write UART, poke and watch GPIO pins, inject ADC
+// values, and inspect CPU registers.
+//
+// One active emulator session at a time — load_firmware/reset replaces it.
+// 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';
+
+// The MCP SDK and zod are OPTIONAL peer dependencies: the emulator library
+// itself has no runtime dependencies, and only this server needs them, so
+// they aren't forced on consumers who just want to run firmware. Loaded
+// dynamically to turn a missing install into an actionable message rather
+// than a raw ERR_MODULE_NOT_FOUND stack.
+let McpServer, StdioServerTransport, z;
+try {
+    ({ McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js'));
+    ({ StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js'));
+    ({ z } = await import('zod'));
+} catch (e) {
+    process.stderr.write(
+        'stm32f4-mcp: missing optional dependencies.\n\n' +
+        '  npm install @modelcontextprotocol/sdk zod\n\n' +
+        'They are optional peer dependencies so that using this package as an\n' +
+        'emulator library stays dependency-free. See docs/mcp.md.\n' +
+        `\nOriginal error: ${e.message}\n`);
+    process.exit(1);
+}
+
+let session = null;      // { emu, firmware, components: Map }
+let componentSeq = 0;
+
+const text = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s, null, 2) }] });
+const err = (s) => ({ content: [{ type: 'text', text: s }], isError: true });
+
+function requireSession() {
+    if (!session) throw new Error('no firmware loaded — call load_firmware first');
+    return session;
+}
+
+const server = new McpServer({ name: 'stm32f4-emu', version: '0.1.0' });
+
+server.registerTool('list_firmwares', {
+    description: 'List the firmware images bundled with the emulator that load_firmware accepts.',
+    inputSchema: {},
+}, async () => text(Object.keys(FIRMWARES)));
+
+server.registerTool('load_firmware', {
+    description: 'Boot a bundled firmware image, replacing any active session. Use list_firmwares for valid names.',
+    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)'),
+    },
+}, async ({ firmware, enable_irqs = false }) => {
+    if (!FIRMWARES[firmware]) return err(`unknown firmware '${firmware}' (have: ${Object.keys(FIRMWARES).join(', ')})`);
+    const replaced = session !== null;
+    if (session) { try { session.emu.close(); } catch {} }
+    const emu = await createSTM32F407({ firmware, enable_irqs });
+    session = { emu, firmware, components: new Map() };
+    componentSeq = 0;
+    return text({
+        loaded: firmware,
+        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.'
+            : undefined,
+    });
+});
+
+server.registerTool('step', {
+    description: 'Run the CPU for up to N instructions. Returns the program counter, total instruction count, and whether the machine stopped.',
+    inputSchema: { instructions: z.number().int().positive().default(100000) },
+}, async ({ instructions }) => {
+    const { emu } = requireSession();
+    const r = emu.step(instructions);
+    return text({ pc: '0x' + (r.pc >>> 0).toString(16), instCount: r.instCount, stopped: r.stopped });
+});
+
+server.registerTool('read_uart', {
+    description: 'Drain and return any UART output the firmware has printed since the last call.',
+    inputSchema: {},
+}, async () => text(requireSession().emu.drainUart() || '(no output)'));
+
+server.registerTool('send_uart', {
+    description: 'Send text to the firmware over UART RX (as if typed into a serial console).',
+    inputSchema: { text: z.string() },
+}, async ({ text: s }) => {
+    const { emu } = requireSession();
+    emu.sendUart([...s].map((c) => c.charCodeAt(0)));
+    return text(`sent ${s.length} byte(s)`);
+});
+
+server.registerTool('read_pin', {
+    description: 'Read a GPIO pin: the level the guest is driving out, and the input level it sees.',
+    inputSchema: {
+        port: z.string().describe('port letter, e.g. "A"'),
+        pin: z.number().int().min(0).max(15),
+    },
+}, async ({ port, pin }) => {
+    const p = requireSession().emu.pin(port, pin);
+    return text({ port, pin, output: p.read(), input: p.readInput() });
+});
+
+server.registerTool('write_pin', {
+    description: 'Drive a GPIO input level into the guest (as an external device or button would).',
+    inputSchema: {
+        port: z.string().describe('port letter, e.g. "A"'),
+        pin: z.number().int().min(0).max(15),
+        level: z.boolean(),
+    },
+}, async ({ port, pin, level }) => {
+    requireSession().emu.pin(port, pin).write(level);
+    return text(`P${port.toUpperCase()}${pin} <- ${level ? 'high' : 'low'}`);
+});
+
+server.registerTool('set_adc_channel', {
+    description: 'Force an ADC channel to a 12-bit value (0-4095), simulating an analog sensor. Omit `value` to clear the override.',
+    inputSchema: {
+        peripheral: z.string().default('ADC1'),
+        channel: z.number().int().min(0).max(18),
+        value: z.number().int().min(0).max(4095).optional(),
+    },
+}, async ({ peripheral, channel, value }) => {
+    const { emu } = requireSession();
+    if (value === undefined) {
+        emu.clearAdcChannel(peripheral, channel);
+        return text(`${peripheral} ch${channel} override cleared`);
+    }
+    emu.setAdcChannel(peripheral, channel, value);
+    return text(`${peripheral} ch${channel} <- ${value}`);
+});
+
+server.registerTool('read_registers', {
+    description: 'Read the ARM CPU registers (R0-R12, SP, LR, PC, XPSR) as hex.',
+    inputSchema: {},
+}, async () => {
+    const r = requireSession().emu.getRegisters();
+    return text(Object.fromEntries(Object.entries(r).map(([k, v]) => [k, '0x' + (v >>> 0).toString(16)])));
+});
+
+server.registerTool('read_memory', {
+    description: 'Read a 32-bit word from guest memory (flash, SRAM, or a peripheral register).',
+    inputSchema: { address: z.number().int().describe('absolute address, e.g. 0x40020014 for GPIOA_ODR') },
+}, async ({ address }) => {
+    const v = requireSession().emu.read32(address);
+    return text({ address: '0x' + (address >>> 0).toString(16), value: '0x' + (v >>> 0).toString(16), decimal: v });
+});
+
+server.registerTool('attach_component', {
+    description: 'Attach a virtual component to the running machine and return its id for read_component. Types: led (port+pin), button (port+pin), pwm (timer+channel), potentiometer (peripheral+channel).',
+    inputSchema: {
+        type: z.enum(['led', 'button', 'pwm', 'potentiometer']),
+        port: z.string().optional().describe('led/button: port letter, e.g. "A"'),
+        pin: z.number().int().min(0).max(15).optional().describe('led/button: pin number'),
+        timer: z.string().optional().describe('pwm: timer name, e.g. "TIM2"'),
+        channel: z.number().int().optional().describe('pwm: channel 1-4; potentiometer: ADC channel'),
+        peripheral: z.string().optional().describe('potentiometer: ADC peripheral, default ADC1'),
+        activeLow: z.boolean().optional(),
+    },
+}, async (a) => {
+    const { emu, components } = requireSession();
+    const id = `${a.type}${++componentSeq}`;
+    let comp;
+    switch (a.type) {
+        case 'led':
+            if (a.port === undefined || a.pin === undefined) return err('led requires port and pin');
+            comp = new LED(emu, a.port, a.pin, { activeLow: a.activeLow ?? false });
+            break;
+        case 'button':
+            if (a.port === undefined || a.pin === undefined) return err('button requires port and pin');
+            comp = new Button(emu, a.port, a.pin, { activeLow: a.activeLow ?? true });
+            break;
+        case 'pwm':
+            if (!a.timer) return err('pwm requires timer');
+            comp = new Pwm(emu, a.timer, a.channel ?? 1);
+            break;
+        case 'potentiometer':
+            if (a.channel === undefined) return err('potentiometer requires channel');
+            comp = new Potentiometer(emu, a.peripheral ?? 'ADC1', a.channel);
+            break;
+    }
+    components.set(id, { type: a.type, comp });
+    return text({ id, type: a.type });
+});
+
+server.registerTool('read_component', {
+    description: 'Read the current state of an attached component (led: on/off, pwm: freq/duty, potentiometer: value).',
+    inputSchema: { id: z.string() },
+}, async ({ id }) => {
+    const entry = requireSession().components.get(id);
+    if (!entry) return err(`no component '${id}'`);
+    const { type, comp } = entry;
+    if (type === 'led') return text({ id, type, on: comp.value });
+    if (type === 'pwm') return text({ id, type, freq: comp.freq, duty: comp.duty });
+    if (type === 'potentiometer') return text({ id, type, value: comp.value });
+    return text({ id, type, note: 'buttons are write-only; use control_component to press/release' });
+});
+
+server.registerTool('control_component', {
+    description: 'Act on an attached component: press/release a button, or set a potentiometer value.',
+    inputSchema: {
+        id: z.string(),
+        action: z.enum(['press', 'release', 'set']),
+        value: z.number().optional().describe('required for action=set on a potentiometer'),
+    },
+}, async ({ id, action, value }) => {
+    const entry = requireSession().components.get(id);
+    if (!entry) return err(`no component '${id}'`);
+    const { type, comp } = entry;
+    if (action === 'set') {
+        if (type !== 'potentiometer') return err(`'set' only applies to a potentiometer, not ${type}`);
+        if (value === undefined) return err("action 'set' requires value");
+        comp.value = value;
+        return text({ id, value: comp.value });
+    }
+    if (type !== 'button') return err(`'${action}' only applies to a button, not ${type}`);
+    action === 'press' ? comp.press() : comp.release();
+    return text({ id, action });
+});
+
+server.registerTool('reset', {
+    description: 'Close the active emulator session and clear all attached components.',
+    inputSchema: {},
+}, async () => {
+    if (!session) return text('no active session');
+    try { session.emu.close(); } catch {}
+    const was = session.firmware;
+    session = null;
+    return text(`closed session (${was})`);
+});
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "stm32f4-emu",
+  "version": "0.1.0",
+  "description": "STM32F407 emulator: Unicorn (WASM) CPU + Rust peripheral model. Runs real Cortex-M4 firmware in Node or the browser.",
+  "type": "module",
+  "main": "index.mjs",
+  "bin": {
+    "stm32f4-mcp": "./mcp/server.mjs"
+  },
+  "exports": {
+    ".": "./index.mjs",
+    "./components": "./site/components.js",
+    "./emulator": "./site/emulator.js",
+    "./netsim": "./site/netsim.js",
+    "./firmwares": "./site/firmware.js",
+    "./loaders": "./site/loaders.js",
+    "./vendor": "./site/vendor/stm32_periph_wasm.js",
+    "./vendor/unicorn": "./site/vendor/unicorn_arm.cjs",
+    "./site": "./site/index.html"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    "site/emulator.js",
+    "site/components.js",
+    "mcp/server.mjs",
+    "site/netsim.js",
+    "site/firmware.js",
+    "site/loaders.js",
+    "site/index.html",
+    "site/app.js",
+    "site/vendor/"
+  ],
+  "keywords": [
+    "stm32",
+    "stm32f407",
+    "emulator",
+    "arm",
+    "cortex-m4",
+    "unicorn",
+    "wasm",
+    "embedded",
+    "firmware"
+  ],
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danish9661/stm32F4-emulator.git"
+  },
+  "homepage": "https://danish9661.github.io/stm32F4-emulator/",
+  "bugs": {
+    "url": "https://github.com/danish9661/stm32F4-emulator/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "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",
+    "test:flow": "node site/test_flow.mjs",
+    "test:blinky": "node site/test_blinky.mjs",
+    "test:rx": "node site/test_rx_interrupt.mjs",
+    "test:multi": "node site/test_multi_instance.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:mcp": "node mcp/test_mcp.mjs",
+    "mcp": "node mcp/server.mjs",
+    "firmwares": "node tools/make_firmware.mjs",
+    "serve": "python3 -m http.server 8123 --directory site",
+    "prepack": "node tools/make_firmware.mjs"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25 || ^4.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": { "optional": true },
+    "zod": { "optional": true }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25 || ^4.0"
+  }
+}