Skip to content
mikroverkPublic

About

Open-source ESP32 emulator. Run real firmware locally or in your browser — no hardware, no cloud, no subscription.

Resources

Code of conduct

Contributing

Security policy

Stars

1.2k stars

Watchers

6 watching

Forks

Repository files navigation

esp32sim logo: a smiling chip in an emulator window

esp32sim

esp32sim is an ESP32 emulator written in Rust. It runs real ESP32 firmware on your computer or in a browser tab, without the hardware.

It boots the chip's own mask ROM, the real second-stage bootloader and your unmodified application. It also models the board around the chip: displays, touch, LEDs, buttons, audio, camera and WiFi.

Try it in your browser, nothing to install: https://mikroverk.github.io/esp32sim/

--chip esp32 --board ai-thinker-cam --cam-image image.ppm supplies the AI-Thinker ESP32-CAM's OV2640 with a BMP/PPM still image. Capture supports raw RGB565/YUV422 into internal DRAM at a fixed approximate 10 FPS; the usual JPEG+PSRAM CameraWebServer path is unsupported. See the camera scope and example.

Supported chips

Chip CPU Status Boards
ESP32-S3 2 x Xtensa LX7 mature Atech 14-port kit, Waveshare Touch-LCD-4B, Touch-AMOLED-1.8, ESP32-S3-CAM, M5Stack StopWatch
ESP32-C3 RISC-V RV32IMC draft console only
ESP32-C6 RISC-V RV32IMAC draft Waveshare ESP32-C6-LCD-1.47 (with the 802.15.4 radio), Seeed XIAO ESP32-C6
ESP32 (classic) 2 x Xtensa LX6 early LilyGO TTGO T-Display, ESP32-2432S028 "Cheap Yellow Display", AI-Thinker ESP32-CAM (raw capture), Ulanzi TC001
ESP32-P4 (rev < 3 and rev ≥ 3) 2 x RISC-V RV32IMAFC draft Waveshare ESP32-P4-WIFI6-Touch-LCD-3.5 (rev ≥ 3); WiFi through an emulated ESP32-C6 co-processor on SDIO (ESP-Hosted)
ESP32-S31 2 x RISC-V RV32IMAFC draft Espressif ESP-Mosaico (display, touch, WiFi, audio, IMU, keys); IDF v6.1

Features

  • The full boot chain: mask ROM, bootloader, FreeRTOS, then your app. No patched firmware.
  • WiFi with the unmodified Espressif WiFi library. Firmware scans one or more virtual access points and the networks around them, joins one, gets DHCP, DNS and NTP, and can reach the real network, HTTPS included. The station's frames go to a pcap file or the page's live Network panel.
  • Board models, so firmware can draw on a display, read touch, light LEDs and play sound.
  • Speed: the S3 has a block cache and a JIT, and runs hello_world about 30 times faster than real time.
  • A WebAssembly build of the same emulator for the browser.
  • Comparisons with real chips: the S3 in JTAG lock-step, the C3 and C6 by console diff. See hardware testing.

Demos

These run on the demo site:

  • Linux 6.11 on the ESP32-S3 (svermigo/Linux-on-esp32-S3), with a login shell.
  • The Atech kit's Pocket Synth and its C64 SID jukebox (atech-firmware).
  • An LVGL touch panel at 480x480 with a SID player.
  • pocket-tank, where a small transformer model steers the fish.
  • An 802.15.4 energy scanner, and two Contiki-NG motes running RPL/IPv6, on the ESP32-C6.
  • A WiFi station on the ESP32-C6 with two access points and networks around it, its frames live in the page's Network panel.
  • The Seeed Studio XIAO ESP32-C6's user LED and BOOT button.
  • The Scintilla synth on the ESP32-P4 Touch-LCD-3.5, and the P4 reaching WiFi through an ESP32-C6 co-processor.
  • A compass on the ESP32-S31 ESP-Mosaico's round AMOLED, with touch, the keys and the motor.
  • MicroPython, and a Schematik Arduino sketch, on a classic ESP32 T-Display.

You can also load your own firmware for any of the chips.

Quick start

No Rust needed: the releases carry prebuilt binaries for macOS and Linux, and docs/quick-start.md takes your own build from the tarball to a run in three steps. From a checkout:

cargo build --release
tools/fetch-demo-assets.sh --no-linux       # downloads the mask ROMs, which are not in the repo

FW=web/wasm/fw/public                       # demo firmware included in the repo
./target/release/esp32sim --boot rom --rom web/wasm/fw/esp32s3_rev0_rom.elf \
    --bootloader $FW/atech-bootloader.bin --ptable $FW/atech-ptable.bin --app $FW/atech-firmware.bin \
    --script $FW/atech-script1.txt --wav out.wav --tft-png tft.png --max-seconds 5

This boots the Atech synth firmware, plays a short script, and saves the audio to out.wav and the display to tft.png. Use esp32sim-c3, esp32sim-c6, esp32sim-p4, esp32sim-s31 or --chip esp32 for the other chips.

Getting started covers the rest: your own ESP-IDF builds, each chip, WiFi, scripts, the browser build and debugging.

Documentation

  • Quick start: install the release, fetch the mask ROM, run your own build, read the result
  • Getting started: running firmware on each chip, WiFi, scripts, the browser build
  • CLI reference: every flag, environment variable and output file
  • Boards: what each board models, and how to add one
  • Architecture: how the emulator is put together
  • Peripherals: which hardware blocks are modelled, and how completely
  • Hardware testing: how the emulator is compared with real chips
  • All documents: chip notes, design decisions and plans

Contributing

Bug fixes, peripherals, boards and new chips are welcome. CONTRIBUTING.md lists what a pull request needs; these are the same checks CI runs. Security problems go through SECURITY.md, not the public issue tracker.

Credits and license

esp32sim is released under the MIT License.

Authors: Joakim Eriksson, RISE (@joakimeriksson), Alice (@aliceisjustplaying) and Mattia Fiumara, Schematik (@mfiumara), together with other contributors.

The emulator was written from the ESP-IDF register headers, the Xtensa core configuration that ships with ESP-IDF, the RISC-V specification, the chips' technical reference manuals and observed firmware behaviour. QEMU was consulted only to confirm instruction semantics; no code was copied.

esp32sim is unofficial and not affiliated with Espressif Systems.

Third-party code, data and demo files keep their own licenses:

  • pocket-tank (mediacutlet/pocket-tank, MIT). Its bootloader, partition table and app are in web/wasm/fw/public/ with pocket-tank-LICENSE.txt; its model is downloaded.
  • MicroPython (micropython.org, MIT): the official ESP32_GENERIC v1.29.0 image used by the T-Display demo, downloaded by tools/fetch-micropython.sh and not in the repo. The demo's app and filesystem are in examples/ttgo-tdisplay, with Russ Hughes's st7789py driver and fonts (MIT); the notice is in web/wasm/fw/public/tdisplay-NOTICE.txt.
  • Mask ROM ELFs (espressif/esp-rom-elfs, Apache-2.0), downloaded, not in the repo.
  • xterm.js (xtermjs/xterm.js, MIT), downloaded, not in the repo.
  • The Linux image (svermigo/Linux-on-esp32-S3, GPL-3.0), downloaded, not in the repo.
  • ESP-IDF ADC calibration data (Espressif, Apache-2.0): the curve-fitting coefficients and S3 ADC1 calibration from #165, in esp-periph/src/sar_adc.rs; see esp-periph/LICENSE-ADC.

About

Open-source ESP32 emulator. Run real firmware locally or in your browser — no hardware, no cloud, no subscription.

Resources

Code of conduct

Contributing

Security policy

Stars

1.2k stars

Watchers

6 watching

Forks

Releases

Packages

Used by

Contributors

Languages