Repository navigation
Releases
v2.0.0 — Flash Once. Run Anywhere. 2× Faster Than wasm3 on ESP32 🚀
Flash your firmware once. Change what it does by dropping in a file.
A zero-dependency, C99 WebAssembly runtime built for microcontrollers that never ran an OS.
⚡ Headline Benchmarks: 2.0× Faster Than wasm3
Tested head-to-head on real ESP32 hardware (160 MHz) across 43 compute, memory, and control-flow kernels with bit-identical checksums:
| Runtime | Slowdown vs. Native | Head-to-Head |
|---|---|---|
| Eccles WASM v2.0.0 | 10.4× | 🏆 2.0× faster overall (wins 43/43 kernels) |
wasm3 |
20.5× | Baseline |
Powered by computed-goto dispatch, fused superinstructions, and an IRAM-resident interpreter loop.
🔥 What’s New in v2.0.0
- 🔒 Deny-by-Default Hardware Sandboxing: Modules start with zero hardware access. Grant GPIO, I2C, SPI, UART, ADC, PWM, or threads bit-by-bit—and lock modules down to specific pins or bus addresses.
- 🧩 Multi-Instance Isolation & Spawner: Run multiple independent WASM instances side by side, or spawn parallel worker threads (
wasi-threads+atomics) across dual-core MCUs like the ESP32. - 🌊 256-Byte Streaming Loader: Stream
.wasmmodules directly from flash, SD cards, LittleFS, FatFs, or custom storage (eccles_wasm_set_fs) without ever loading the full binary into RAM. - ⏱️ Deterministic Fuel & Watchdog Safety: Enforce per-call instruction budgets (
eccles_wasm_set_fuel) and automatic yield intervals so buggy or untrusted modules never hang your firmware. - 🌍 Six Ready-to-Use Backends: Out-of-the-box support for ESP-IDF, Arduino, Raspberry Pi Pico (RP2040), STM32 HAL, Zephyr / nRF, and a Desktop Simulator, plus guest SDKs for C, C++, and
no_stdRust (embedded-hal1.0).
✅ Battle-Tested on Real Silicon
- 4,186 / 4,186 hardware conformance checks passing in 80 seconds on an ESP32 (0 failures across traps, fuzzing, atomics, privilege enforcement, and multi-core threads).
- Zero mismatches across 17,465 differential fuzz calls against Node.js V8, plus clean runs under ASan, UBSan, and ThreadSanitizer.
🚀 Get Started in 30 Seconds
#include "eccles_wasm.h"
#include "blink_wasm.h"
void app_main(void) {
eccles_wasm_init();
eccles_wasm_set_hal_privilege(ECCLES_WASM_ALLOW_PIN_ALL | ECCLES_WASM_ALLOW_SAFE);
if (eccles_wasm_load_buffer(blink_wasm, blink_wasm_len) != ECCLES_WASM_SUCCESSFUL) return;
eccles_wasm_run("setup");
for (;;) eccles_wasm_run("loop");
}📖 Full Documentation: Dive into the new 37-page Wiki (wiki/ or ECCLES_WASM_WIKI.txt) covering memory sizing, custom host functions, and platform bring-up guides.
💖 Support Independent Embedded Tooling
Eccles WASM is built independently with zero corporate backing, MIT-licensed, and free forever. If it saves you a firmware reflash:
- ⭐ Star the repository to help other embedded engineers find it
- 💖 Sponsor on GitHub or Support via Paystack
Full Changelog: v1.1.0...v2.0.0
v1.1.0 — Write Once, Run on Any Microcontroller (4× Faster, Multi-VM & Guest SDKs)
Write Once, Run on Any Microcontroller
Eccles WASM v1.1.0 turns your microcontroller into a fast, multi-instance WebAssembly host. Flash your firmware once, then deploy or update behavior on the fly by dropping in a .wasm file—from an SD card, LittleFS/SPIFFS, flash array, or OTA stream—without touching the host firmware.
Now battle-tested end-to-end on Arduino and ESP32, v1.1.0 delivers up to 4× faster execution, independent parallel VMs, modern WebAssembly proposals, and first-class C, C++, and Rust guest SDKs.
What's New in v1.1.0
- Up to 4× Faster Interpreter (Computed Goto + Superinstruction Fusion):
- Automatically enables computed-goto dispatch on GCC and Clang (with a portable
switchfallback). - Peephole translator fuses common compiled-code sequences into single handlers (
local.get+ ALU/compare, compare-and-branchBLC/BLL, local-base memory loadsOP_LLD32, and direct local storesFLLS/FLCS). - Measured up to 4.0× faster on ALU and memory sieve benchmarks and 2.6× faster on call-heavy recursion.
- Automatically enables computed-goto dispatch on GCC and Clang (with a portable
- Multi-Instance Parallel VMs (
eccles_wasm_vm_create):- Carve completely isolated VM instances out of any arena buffer—zero shared interpreter state.
- Run multiple
.wasmmodules simultaneously across RTOS tasks or CPU cores using optionalECCLES_WASM_HW_LOCK()/ECCLES_WASM_HW_UNLOCK()hooks.
- First-Class Guest SDKs (
sdk/c&sdk/rust):- C & C++ (
eccles_wasm_runtime.h): Zero-dependency headers with optional#define EW_ARDUINO_COMPAT(pinMode,digitalWrite,analogRead,delay,millis) andew::Pin,ew::I2c, andew::SpiC++ wrappers. - Rust (
sdk/rust):no_stdcrate implementingembedded-hal1.0 traits so existing sensor and display driver crates run unmodified inside the sandbox.
- C & C++ (
- Modern WebAssembly Proposals:
- Added Tail Calls (
return_call,return_call_indirect), Reference Types & Multiple Tables (funcref,externref,table.get/set/init/copy/grow/size/fill), Extended-Const expressions, and Imported Memory, Tables & Globals (eccles_wasm_vm_set_global).
- Added Tail Calls (
- Hardened Verification Suite:
- Added ThreadSanitizer (
make tsan) multi-instance concurrency tests and Chaos Fuzzing (make chaos) on type-confused modules under ASan + UBSan alongside Node/V8 differential fuzzing.
- Added ThreadSanitizer (
Quick Start
Host Firmware (C99)
#include "eccles_wasm.h"
void app_main(void) {
eccles_wasm_load("/spiffs/app.wasm"); // streamed in 256-byte chunks
eccles_wasm_set_fuel(2000000); // runaway guests trap safely
eccles_wasm_run("setup");
for (;;) eccles_wasm_run("loop");
}Guest Application (sdk/c or sdk/rust)
#include "eccles_wasm_runtime.h"
EW_EXPORT("setup") void setup(void) { ew_pin_mode(2, EW_OUTPUT); }
EW_EXPORT("loop") void loop(void) { ew_toggle(2); ew_sleep(500); }- Getting Started Guide:
docs/GETTING_STARTED.md - Guest Runtime API:
docs/RUNTIME_API.md - Architecture & Design:
docs/DESIGN.md - Full Changelog:
CHANGELOG.md
Full Changelog: v1.0.0...v1.1.0
v1.0.0 — Write Once, Run on Any Microcontroller: Portable C99 WebAssembly Runtime
Write Once, Run on Any Microcontroller
ECCLES WASM is a portable, zero-heap C99 WebAssembly interpreter built specifically for resource-constrained microcontrollers. Compile your application logic to .wasm once—from C, Rust, or AssemblyScript—and execute the exact same binary across ESP32, STM32, RP2040, Zephyr, Arduino, or a desktop Host Simulator.
Why ECCLES WASM?
- True Hardware Portability: Guest modules import a unified hardware API (
enable,disable,pwm,adc,uart_*,i2c_*,spi_*,irq_*,sleep). Every call returnsSUCCESSFUL,FAILED, orUNSUPPORTED, allowing a single.wasmbinary to dynamically probe and adapt to whatever chip it lands on. - Streaming Load & Translation: Function bodies are structurally validated and translated on the fly through a tiny chunk buffer (
ECCLES_WASM_CHUNK_SIZE, default 256 bytes). The raw.wasmfile is never buffered in RAM—stream directly from SPIFFS, LittleFS, FatFs, SD cards, UART, or OTA packets. - Zero-Heap Single-Arena Memory Model: Runs cleanly in ~24 KB+ of RAM using one static array (or a single caller-supplied buffer). Linear memory caps (
ECCLES_WASM_MEM_LIMIT_BYTES) let standard 64 KiB-page.wasmbinaries execute safely on smaller MCUs. - Deterministic Safety & Watchdog Protection: Built-in instruction fuel budgets (
eccles_wasm_set_fuel) and periodic yield hooks (ECCLES_WASM_YIELD_INTERVAL) prevent runaway guest loops from locking up the CPU or starving RTOS tasks. - Drop-In Integration: Just two files (
eccles_wasm.handeccles_wasm.c) with zero external dependencies beyond a standard C99 compiler.
Built-In Platform Backends
| Backend | GPIO | ADC | PWM | Time / Sleep | Reset | RNG | IRQ | UART / I2C / SPI | Log |
|---|---|---|---|---|---|---|---|---|---|
| ESP-IDF (ESP32) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | stdout |
| Raspberry Pi Pico | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | stdout |
| Arduino | Yes | Yes | Yes | Yes | ESP/ARM | ESP32 | — | C++ Glue | C++ Glue |
| STM32 HAL | Yes | — | — | Yes | Yes | — | — | CubeMX | — |
| Zephyr RTOS | Yes | — | — | Yes | Yes | Yes | — | — | printk |
| Host PC Simulator | Sim | Sim | Sim | Yes | Sim | Yes | Sim | Sim | stdout |
(Need custom silicon? Override any subset of operations at runtime via eccles_wasm_hal_override().)
Quick Start
Host Firmware (C99)
#include "eccles_wasm.h"
void app_main(void) {
eccles_wasm_set_fuel(500000); // Prevent infinite guest loops
eccles_wasm_load("/spiffs/blink.wasm"); // Streamed in 256-byte chunks
eccles_wasm_run("main"); // Execute exported entry point
}Portable Guest Application (clang --target=wasm32 -nostdlib)
#define ECCLES_IMPORT(n) __attribute__((import_module("env"), import_name(n)))
ECCLES_IMPORT("enable") int enable(int pin);
ECCLES_IMPORT("disable") int disable(int pin);
ECCLES_IMPORT("sleep") int sleep(int ms);
__attribute__((export_name("main")))
void main_(void) {
for (;;) {
enable(2);
sleep(500);
disable(2);
sleep(500);
}
}What's Included in v1.0.0
- Core Runtime: Streaming loader, structural validator, 16-bit bytecode translator, and interpreter supporting WebAssembly 1.0 + sign-extension ops, non-trapping float conversions, bulk memory (
memory.copy/memory.fill), and multi-value blocks. - WASI-Lite Support: Built-in
fd_write,proc_exit,clock_time_get,random_get,args_*, andsched_yieldso standardprintf()-style C and Rust guests run out of the box. - Ready-to-Build Manifests: Includes support for CMake, ESP-IDF Component Registry (
idf_component.yml), PlatformIO (library.json), and Arduino Library Manager (library.properties). - Test Suite & Differential Fuzzer: Host test harness with SDK mocks and differential fuzzing against reference WebAssembly execution.
Full Changelog: https://github.com/Igwe-Starking/eccles-wasm/commits/v1.0.0