stm32f4-emu 0.1.0 → 1.0.0

package/README.md

@@ -1,5 +1,8 @@
-# STM32F4 Emulator
+# STM32F4 Emulator (`stm32f4-emu`)
 
+[![npm version](https://img.shields.io/npm/v/stm32f4-emu.svg)](https://www.npmjs.com/package/stm32f4-emu)
+[![npm downloads](https://img.shields.io/npm/dm/stm32f4-emu.svg)](https://www.npmjs.com/package/stm32f4-emu)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
 [![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)
 
@@ -72,6 +75,10 @@ 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
 
+# 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
+
 # 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 \
@@ -126,6 +133,29 @@ 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.
 
+## WebSocket bridge (headless Node ↔ browser UI)
+
+A binary WebSocket protocol so the browser console can drive the emulator
+running headlessly in Node — all WASM execution stays in Node, the browser
+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
+
+# 2. Open the browser console with the bridge URL param
+open "http://127.0.0.1:8123/?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://…`,
+the browser sends the firmware image over the bridge.
+
+See AGENTS.md §20 for the full binary protocol reference.
+
 ## Firmwares
 
 | Firmware | What it does | Success marker |
@@ -246,6 +276,7 @@ rebuild — delete it so the vendor assets stay tracked/committed.
 
 ## Documentation
 
+- [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
@@ -262,12 +293,9 @@ rebuild — delete it so the vendor assets stay tracked/committed.
 - [docs/progress-and-future.md](docs/progress-and-future.md) — status,
   known limitations, roadmap.
 
-## License
-
-GPL-3.0-only. See [LICENSE](LICENSE).
+## License & Credits
 
-*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.*
+- **License**: GPL-3.0-only. See [LICENSE](LICENSE).
+- **Unicorn CPU Core**: Powered by [Unicorn.js](https://github.com/AlexAltea/unicorn.js) by [Alex Altea](https://github.com/AlexAltea) (WASM/JS port of the [Unicorn Engine](https://www.unicorn-engine.org/) CPU emulator, derived from QEMU, licensed under GPLv2).
+- **Heritage**: Fork and continuation of [nviennot/stm32-emulator](https://github.com/nviennot/stm32-emulator) (native SDL 3D printer emulator by Nicolas Viennot). The headless WASM peripheral model, networking stack, browser demo, virtual components API, MCP server, and npm package are new work built on that base.
+- **DOOM**: Ported using [doomgeneric](https://github.com/ozkl/doomgeneric) by Ozkan Sezgin.

package/cli.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// stm32f4-emu — headless CLI to load and run an STM32F4 firmware image.
+//
+//   stm32f4-emu <firmware> [--inst N] [--format auto|bin|hex|elf] [--verbose]
+//                   [--lowpower]
+//
+// Loads a .bin/.elf/.hex firmware, boots it in the emulator, and streams the
+// guest UART to stdout. Peripheral register accesses are traced to stderr when
+// --verbose is given. With --lowpower, the core halts on WFI/WFE and the
+// emulator advances the virtual RTC until a wakeup source (e.g. an RTC alarm)
+// fires — so firmware that enters STOP (e.g. deep_sleep_demo.bin) runs.
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+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';
+
+const require = createRequire(import.meta.url);
+const unicornFactory = require('./site/vendor/unicorn_arm.cjs');
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const svdXml = readFileSync(resolve(__dirname, 'site/vendor/stm32f407.svd'), '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'));
+
+const USAGE = `stm32f4-emu — run an STM32F4 firmware image in the emulator
+
+Usage:
+  stm32f4-emu <firmware> [options]
+
+Arguments:
+  <firmware>            path to a firmware image (.bin, .elf, or .hex)
+
+Options:
+  -n, --inst <N>        instruction budget to run (default 20000000)
+  -f, --format <fmt>    firmware format: auto|bin|hex|elf (default auto)
+  -v, --verbose         trace peripheral register reads/writes to stderr
+  -l, --lowpower        halt on WFI/WFE and advance the virtual RTC until wakeup
+  -h, --help            show this help
+  -V, --version         show version
+
+Examples:
+  stm32f4-emu build/firmware.bin
+  stm32f4-emu app.elf --inst 5000000 --verbose
+  stm32f4-emu deep_sleep_demo.bin --lowpower
+`;
+
+function fail(msg) {
+    process.stderr.write(msg + '\n\n' + USAGE);
+    process.exit(2);
+}
+
+function detectFormat(buf, format) {
+    if (format !== 'auto') return format;
+    if (buf[0] === 0x7F && buf[1] === 0x45 && buf[2] === 0x4C && buf[3] === 0x46) return 'elf';
+    let i = 0;
+    while (i < buf.length && (buf[i] === 0x20 || buf[i] === 0x09 || buf[i] === 0x0D || buf[i] === 0x0A)) i++;
+    if (buf[i] === 0x3A) return 'hex'; // ':'
+    return 'bin';
+}
+
+async function main() {
+    const args = process.argv.slice(2);
+    let firmwarePath = null;
+    let inst = 20000000;
+    let format = 'auto';
+    let verbose = false;
+    let lowpower = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '-h' || a === '--help') { process.stdout.write(USAGE); process.exit(0); }
+        if (a === '-V' || a === '--version') { process.stdout.write(`stm32f4-emu ${pkg.version}\n`); process.exit(0); }
+        if (a === '-v' || a === '--verbose') { verbose = true; continue; }
+        if (a === '-l' || a === '--lowpower') { lowpower = true; continue; }
+        if (a === '-n' || a === '--inst') {
+            const v = args[++i];
+            inst = Number(v);
+            if (!Number.isFinite(inst) || inst <= 0) fail(`invalid --inst value: ${v}`);
+            continue;
+        }
+        if (a === '-f' || a === '--format') {
+            format = args[++i];
+            if (!['auto', 'bin', 'hex', 'elf'].includes(format)) fail(`invalid --format: ${format}`);
+            continue;
+        }
+        if (a.startsWith('-')) fail(`unknown option: ${a}`);
+        if (firmwarePath) fail('multiple firmware paths given');
+        firmwarePath = a;
+    }
+    if (!firmwarePath) fail('no firmware path given');
+
+    let raw;
+    try {
+        raw = new Uint8Array(readFileSync(firmwarePath));
+    } catch (e) {
+        fail(`cannot read firmware '${firmwarePath}': ${e.message}`);
+    }
+
+    const fmt = detectFormat(raw, format);
+    let firmware, extra_mem = [];
+    try {
+        if (fmt === 'elf') {
+            const elf = parseElf(raw);
+            if (!elf.flash) fail('ELF contains no FLASH segment (expected a segment at 0x08000000)');
+            firmware = elf.flash;
+            extra_mem = elf.extraMem || [];
+        } else if (fmt === 'hex') {
+            const hex = parseIntelHex(Buffer.from(raw).toString('latin1'));
+            if (!hex.flash) fail('Intel HEX contains no FLASH records (expected data in the 0x08000000 range)');
+            firmware = hex.flash;
+        } else {
+            firmware = raw;
+        }
+    } catch (e) {
+        fail(`failed to parse ${fmt} firmware: ${e.message}`);
+    }
+
+    let emu;
+    try {
+        emu = await createEmulator({
+            firmware, bindings, unicorn: unicornFactory, svdXml, wasmInit: wasmBytes,
+            extra_mem, verbose, lowpower,
+        });
+    } catch (e) {
+        fail(`emulator failed to load firmware: ${e.message}`);
+    }
+
+    const STEP = 100000;
+    let remaining = inst;
+    let lastInst = 0;
+    try {
+        while (remaining > 0) {
+            const take = Math.min(STEP, remaining);
+            const r = emu.step(take);
+            remaining -= (r.instCount - lastInst);
+            lastInst = r.instCount;
+            const u = emu.drainUart();
+            if (u && u.length) process.stdout.write(u.toString());
+            if (r.stopped) break;
+        }
+        const tail = emu.drainUart();
+        if (tail && tail.length) process.stdout.write(tail.toString());
+    } finally {
+        try { emu.close(); } catch {}
+    }
+}
+
+main().catch((e) => {
+    process.stderr.write(`stm32f4-emu: ${e.message}\n`);
+    process.exit(1);
+});

package/index.mjs

@@ -8,6 +8,14 @@ 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';
+
+// 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.
+STM32F4.create = (opts = {}) => STM32F4._create({
+    bindings, unicorn: unicornFactory, svdXml, wasmInit: wasmBytes, ...opts,
+});
 
 const require = createRequire(import.meta.url);
 const unicornFactory = require('./site/vendor/unicorn_arm.cjs');
@@ -36,4 +44,4 @@ export async function createSTM32F407(opts = {}) {
     return createEmulator({ ...opts, firmware: bin, bindings, unicorn: unicornFactory, svdXml, wasmInit: wasmBytes });
 }
 
-export { createEmulator, createNetSim, FIRMWARES, bindings, unicornFactory, svdXml, LED, Button, Pwm, I2cRegisterDevice, Potentiometer };
+export { createEmulator, createNetSim, FIRMWARES, bindings, unicornFactory, svdXml, LED, Button, Pwm, I2cRegisterDevice, Potentiometer, STM32F4, GPIOPin, USART, DMAStream };

package/mcp/server.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 // 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
@@ -31,6 +32,25 @@ try {
 }
 
 let session = null;      // { emu, firmware, components: Map }
+
+// ── CLI surface for the bin: stm32f4-mcp --help / --version ──
+// Printed before the stdio MCP transport starts (stdout is the JSON-RPC
+// channel once running, so we must exit before connecting).
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    process.stdout.write(
+        'stm32f4-mcp — MCP server exposing the STM32F407 emulator.\n\n' +
+        'Usage: stm32f4-mcp [--help] [--version]\n\n' +
+        'Speaks MCP over stdio (JSON-RPC). Connect it from an MCP client such\n' +
+        'as Claude Code or Claude Desktop. Optional peer deps:\n' +
+        '  npm install @modelcontextprotocol/sdk zod\n'
+    );
+    process.exit(0);
+}
+if (process.argv.includes('--version') || process.argv.includes('-V')) {
+    const ver = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    process.stdout.write(`stm32f4-mcp ${ver}\n`);
+    process.exit(0);
+}
 let componentSeq = 0;
 
 const text = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s, null, 2) }] });

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "stm32f4-emu",
-  "version": "0.1.0",
+  "version": "1.0.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"
+    "stm32f4-emu": "./cli.mjs",
+    "stm32f4-mcp": "./mcp/server.mjs",
+    "stm32f4-bridge": "./site/ws-bridge.mjs"
   },
   "exports": {
     ".": "./index.mjs",
@@ -14,12 +16,16 @@
     "./netsim": "./site/netsim.js",
     "./firmwares": "./site/firmware.js",
     "./loaders": "./site/loaders.js",
+    "./stm32f4": "./site/stm32f4.js",
     "./vendor": "./site/vendor/stm32_periph_wasm.js",
     "./vendor/unicorn": "./site/vendor/unicorn_arm.cjs",
+    "./remote": "./site/remote-emu.js",
+    "./ws-bridge": "./site/ws-bridge.mjs",
     "./site": "./site/index.html"
   },
   "files": [
     "index.mjs",
+    "cli.mjs",
     "README.md",
     "site/emulator.js",
     "site/components.js",
@@ -29,6 +35,8 @@
     "site/loaders.js",
     "site/index.html",
     "site/app.js",
+    "site/remote-emu.js",
+    "site/ws-bridge.mjs",
     "site/vendor/"
   ],
   "keywords": [
@@ -55,29 +63,52 @@
     "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": "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_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:bridge": "node site/test_ws_bridge.mjs",
+    "test:bridge:browser": "node site/test_bridge_cdp.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:can": "node site/test_candemo.mjs",
+    "test:caninject": "node site/test_can_inject.mjs",
+    "test:watchdog": "node site/test_watchdog.mjs",
+    "test:wwdg": "node site/test_wwdg.mjs",
+    "test:wwdgwin": "node site/test_wwdg_window.mjs",
+    "test:timcap": "node site/test_tim_capture.mjs",
+    "test:lowpower": "node site/test_lowpower.mjs",
+    "test:qspi": "node site/test_qspi.mjs",
+    "test:qspi:browser": "node site/test_qspi_cdp.mjs",
+    "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:mcp": "node mcp/test_mcp.mjs",
     "mcp": "node mcp/server.mjs",
+    "bridge": "node site/ws-bridge.mjs",
     "firmwares": "node tools/make_firmware.mjs",
     "serve": "python3 -m http.server 8123 --directory site",
     "prepack": "node tools/make_firmware.mjs"
   },
+  "dependencies": {
+    "ws": "^8.21.3"
+  },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.25 || ^4.0"
   },
   "peerDependenciesMeta": {
-    "@modelcontextprotocol/sdk": { "optional": true },
-    "zod": { "optional": true }
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "playwright": "^1.62.1",
     "zod": "^3.25 || ^4.0"
   }
 }