The STM32 Bluepill Emulator is a full-system emulator for the STM32F103C8 “Blue Pill” microcontroller. It executes real, unmodified firmware — compiled Arduino sketches (STM32duino), libopencm3 and STM32Cube HAL programs — in your browser or in Node.js, without any hardware.

Instead of a simplified instruction interpreter, it runs a native Rust Cortex-M3 CPU interpreter plus a Rust peripheral emulator that implements the chip’s registers — GPIO, USART, SPI, I2C, TIM, ADC, DAC, DMA, CAN, RTC, CRC, NVIC, EXTI, FSMC and more — with realistic timing, interrupts and electrical behaviour, all in one WebAssembly module.

• Test firmware without hardware — blink, UART, SPI Flash, I2C EEPROM, OLED, touchscreen, CAN and DMA sketches run in a browser tab or from the command line.
• CI & automated testing — run firmware headlessly with assertions; the 39-check integration test completes in a couple of seconds.
• Debug visibility — --verbose mode traces every peripheral access, register read/write, interrupt delivery and DMA transfer in real time.
• Learn embedded systems — see exactly how timers, DMA and interrupts interact, instruction by instruction, with no black boxes.
• No driver headaches — no ST-Link, no serial adapters, no USB driver issues. Just open a URL.

The emulator uses a dual-engine architecture:

1. Rust CPU — a native Thumb-2 interpreter executes Cortex-M3 instructions in adaptive 20K/50K batches (20K when IRQ/DMA pending, 50K idle; batch_size overrides), with exact instruction accounting.
2. Rust Peripheral WASM — the same WebAssembly module models every chip register with cycle-accurate timing, electrical behaviour (GPIO pull-ups, open-drain, slew), interrupt priorities and DMA transfers.
3. Module Worker + OffscreenCanvas — browser emulation runs off-main-thread (site/worker.js:1, site/index.html:449); canvas is transferred via OffscreenCanvas (site/worker.js:117); frame stats ride the per-frame message (a SharedArrayBuffer channel was removed — it had no readers and its scheduler starved worker controls).

Each emulation step follows this cycle (adaptive batch):

1. Pump stdin — UART RX bytes from the host
2. Process DMA transfers queued by peripherals
3. Execute an adaptive batch in the Rust interpreter (20K busy / 50K idle)
4. Tick all peripherals by the elapsed instruction count (step_batch)
5. Deliver pending interrupts (up to 64 per batch, NVIC-priority ordered)
6. Check watchdog reset flags
7. Worker posts frame → main renders (OffscreenCanvas if transferred, site/worker.js:168); UI_THROTTLE 10 (site/index.html:441) — step 60fps, paint 6fps, never starves throughput

• Hookless instruction counting — emu_start(begin,0,0,maxBatch) stops exactly at the batch limit, removing the per-instruction callback (~20% win).
• Closed-form timer advance — CNT jumps to next event tick (124× on advance()).
• Adaptive 20K/50K batch (pkg/emulator.js:698) — 20K keeps IRQ latency ≈1.1 ms; 50K doubles idle throughput, free when idle.
• REG_POOL pooling (pkg/emulator.js:228) — batch register transport reuses 3 mallocs (384 allocs/40M → pooled).
• Worker + OffscreenCanvas (site/worker.js:1) — off-main-thread + zero-copy canvas; the loop always yields via setTimeout so stop/UART/GPIO controls stay live; browser 8.6 MIPS headed.
• UI_THROTTLE 10 (site/index.html:441) — DOM 6fps vs emulation 60fps decoupling.
• Bus binary search + Rust DMA pump — sorted-vector lookup (~99% hit) + DMA resolved entirely in Rust (flat op-plan).

• NVIC priority dispatch — pending IRQs are sorted by priority and delivered in batches of up to 64 per step. A fairness mechanism prevents a single high-rate IRQ from starving others.
• SVC (supervisor call) — dispatched inline onto the real stack. The 32-byte Cortex-M exception frame is built on the real stack; the SVCall handler vector is resolved from the vector table.
• PendSV — pended via SCB ICSR PENDSVSET, dispatched at the next batch boundary. Used for context-switch testing.
• Faults — BusFault, UsageFault and HardFault set CFSR/HFSR/BFAR registers, pends the appropriate exception, and escalates to HardFault if the fault handler is not enabled in SHCSR.
• SysTick debt drain — millis() / micros() accuracy via a debt counter: missed ticks are accumulated and delivered one-per-batch to avoid double-counting.
• Deep sleep (SLEEPDEEP) — SCB SCR bit 2 freezes all peripherals except RTC and IWDG. Timers use tick_frozen() to advance their delta base without processing state, preventing catch-up jumps on wake.

• --config=<file.yaml> — configuration file: firmware path, external devices (SPI flash, I2C EEPROM, OLED, LCD, touchscreen, FSMC), UART baud.
• --max=<N> — stop after N instructions (default: unlimited).
• --map=<file.map> — load a linker map for PC → symbol name resolution in output.
• --uart=<file> — write UART TX bytes to a file (default: stdout).
• --regs — dump R0-R15, xPSR and SP on exit.
• --verbose — trace every peripheral read/write, DMA transfer and interrupt delivery.
• --periph-plugin=<file.mjs> — load a JS peripheral plugin (default export: array of {base, size, read, write}).
• -h / --help — show usage.

• Blue Pill board SVG — LED glow, pin-activity amber highlights, per-pin toggle counts.
• GPIO panel — live readout of all 32 pins across ports A–D with colour-coded modes (output high, output low, input).
• UART terminal — real-time serial output with a text input for RX injection.
• Showcase peripherals — live OLED/LCD canvas, 7-segment display, RGB bar, buzzer indicator, button widget with EXTI13 interrupt.
• Chip selector — switch between six chips (Blue Pill C8/CB, Maple Mini, Nucleo, F103RC, GD32, SVD-based F105 with CAN2 + OTG) at load time; the preset menu filters to the selected chip.

Beyond the built-in STM32F103C8 map, the emulator supports any STM32F1-series chip via CMSIS System View Description (SVD) files:

• Built-in map — STM32F103C8 with hardcoded register addresses, always works, no external files needed. A chip table adds C8/CB, Maple Mini, Nucleo-F103RB, F103RC and GD32F103C8/CB/RB variants (flash/RAM sizes + DBGMCU IDCODE) on the same map.
• SVD-based map — parse any STM32F1xx SVD file to generate a peripheral map at runtime. Ships with STM32F103.svd and STM32F105xx.svd (connectivity line, CAN2).
• Auto-registration — if an SVD omits ARM core peripherals (NVIC, SysTick, SCB at 0xE000Exxx), the emulator registers them automatically. This fixed millis()/PendSV silently breaking on the F105 SVD.
• Last-wins overlap — custom or SVD peripherals can shadow built-in entries, enabling per-chip overrides.

764 asserts covering every peripheral in isolation: GPIO electrical model, pin events, USART TX/RX (incl. HDSEL loopback, LIN, IrDA/smartcard registers), ADC conversion timing, RC sample-and-hold, DAC→ADC loopback, external triggers (TIM/EXTI), RCC, SysTick, all timer modes, NVIC priority dispatch, CRC, SPI (incl. TI frame format), I2C state machine (incl. slave mode, 10-bit, PEC, SMBus ALERT), RTC alarm, PWR/FLASH, CAN mailboxes + filters, DMA pump, AFIO, EXTI, BKP, DAC, TIM6, FSMC, SDIO, USB, deep-sleep gating and fault escalation, plus DMA circular mode, GPIO LCKR, AFIO SWJ pin reservation, UID, MCO/RCC clock tree, PVD levels, WKUP/standby gating, SPI NSS output, CAN silent modes, TIM dead-time, ADC discontinuous/JAUTO, SDSC cards, ITM stimulus, ESOF and the HD/CL superset (UART4/5, TIM5, ADC3, CAN2, OTG) on the builtin map.

Runs the 24-peripheral Arduino sketch (tests/arduino_periph_test/) for 100M instructions with UART input “AB”. Asserts 39/39 checks pass (GPIO, USART TX, UART loopback, RCC, FLASH, PWR, BKP, IWDG, WWDG, RTC, CRC, DAC, ADC, AFIO, EXTI, CAN, SPI flash, I2C EEPROM, OLED, touchscreen, LCD, I2C2, SPI2, USART2, SVC, PendSV, DMA, UART RX, TIM2, EXTI0, EXTI1, EXTI13, CAN RX, SysTick, TIM3 PWM, TIM4, RTC Alarm). Completes in a couple of seconds; the full 200M run takes ~3s.

24 browser checks running live firmware in Chromium via Playwright: every demo preset boots and prints (blink through dual-CAN, USB enumeration, I2C slave), every static page loads with zero console errors, and the docs viewer, nav and screenshots are asserted. Runs headlessly in CI on every push.

• cargo check — Rust compilation sanity
• tests/test_all.mjs — 764 unit asserts
• tests/canary.mjs — 39/39 firmware checks
• 200M full run — echo -n "AB" | node pkg/cli.mjs --config=... --max=200000000
• tests/test_emulator_js.mjs — browser run-loop path (createEmulator + run)
• tests/test_browser.mjs — Playwright Chromium: 200M firmware + GPIO + chip selector
• tests/test_firmware_formats.mjs — hex/map/ELF cross-format consistency
• tests/test_esm.mjs — ESM glue smoke test
• Byte-exact artifact guard — cmp between pkg/ and site/ for emulator.js, wasm glue and .wasm

• Live demo — 10 presets: blink, UART echo, TIM2 PWM fade, ADC-on-UART, SPI flash + I2C EEPROM/OLED, a 39-check peripheral test, the peripheral showcase (OLED, LCD, 7-seg, RGB, buzzer, button) and an 8-LED WS2812 strip streamed over SPI1 + DMA.
• GitHub repository — source, CLI, library API and full documentation.
• npm package — npm install stm32f1-emu