Run ESP8266 firmware on your PC without a board. The emulator boots an unmodified
firmware.bin, shows its serial output, and lets you press its buttons and watch
its pins change. It can also record repeatable test reports.
The GUI running examples/hello: a live drawing of the module with every pin, a faceplate for the button, relay and LED, and the serial console.
Use it to:
- find out why firmware crashes or keeps resetting, without flashing a board;
- test buttons, relays and LEDs with exact, repeatable timing;
- check that firmware still behaves the same after a change;
- rehearse Arduino OTA updates.
Know its limits:
- ESP8266 only, not ESP32. Developed around Arduino core 3.1.2 and the NONOS SDK. Other firmware may call ROM functions that are not implemented yet.
- No radio. Wi-Fi scans find nothing. Instead, an experimental virtual network gives Arduino 3.1.2 firmware Wi-Fi that reaches only your own computer, so you can test MQTT and OTA against local services.
- Idealized timing. It counts one instruction per cycle and treats flash writes as instant. It is a functional debugger, not a cycle-accurate or electrical model.
- Bring your own firmware. No firmware, SDK or ROM dump is included. A small example sketch is.
You need Linux, macOS, or Windows 10/11 with WSL running Ubuntu. No Python packages, Node.js or frontend build are needed.
-
Windows: first run
wsl --install -d Ubuntuin an administrator PowerShell, then open the Ubuntu app and continue as on Linux. -
Linux or Ubuntu:
sudo apt update sudo apt install -y build-essential python3 git libslirp-dev libglib2.0-dev pkg-config
-
macOS: install Apple's command line tools, which bring clang, make, git and Python 3. For the network, also install Homebrew's libslirp:
xcode-select --install brew install libslirp pkg-config
The libslirp packages are optional; they give dropped firmware its virtual network.
git clone https://github.com/digitake/esp8266-emulator.git- Windows: double-click
emulator.cmdin the cloned folder. - macOS: double-click
emulator.commandin the cloned folder. - Linux or the Ubuntu shell: run
bash run-gui.shin the cloned folder.
The first start builds the emulator, which takes a minute. Then the GUI is at http://127.0.0.1:8266/, and on Windows and macOS your browser opens it. Ctrl+C or closing the window stops it.
On Windows, to start it from any folder by typing esp8266emu, run
.\emulator.cmd -Install once in PowerShell.
Drag firmware.bin and firmware.elf onto the page; PlatformIO writes both to
.pio/build/<env>/. The chip boots at once. The .elf lets the GUI show when
setup() and loop() start, and for an Arduino 3.1.2 image it switches on the
network. Every host name the firmware looks up then leads to your own computer.
Firmware that keeps its Wi-Fi or broker settings in flash boots already set up
when you drop a saved .flash file with the other two
(boot with saved settings).
No firmware yet? Build the example with
PlatformIO Core
and drop the two files from examples/hello/.pio/build/esp12e/:
pio run -d examples/helloThings to try with it:
- Click the GPIO0 pad. The console prints
button pressed, and GPIO5 goes HIGH. - Type
hiinto the box under the console. The firmware answersyou typed: hi. - Press Reset, then Power cycle, and watch the Boot card's reset history.
Start with .\emulator.cmd -ProfileFile examples\gpio-profile.json (or
./emulator.command --profile-file examples/gpio-profile.json on macOS, or
bash run-gui.sh --profile-file examples/gpio-profile.json) to also see the
example's button, relay and LED on a faceplate.
| Part | What it gives you |
|---|---|
| Header | Image name and hash, emulated time, speed (1×, ¼× or max), MIPS, boot count, current stage |
| Board | ESP-12F drawing with each pin's live level and mode. Click a pad to drive it LOW, HIGH or release it. |
| Boot | ROM → eboot → app → SDK → setup() → loop() timeline, and the reason for every reset |
| Signals | Logic-analyzer trace of recent pin changes |
| Network | Soft AP and station state, as reported by the firmware; on the virtual network, its IP, packet counts and a link to its web server |
| Serial console | UART output with credentials masked; send text to the firmware |
The Reset, Power cycle and Erase flash buttons act like the real
thing. Flash contents the firmware saves, such as settings, survive restarts;
Download flash keeps them in a .flash file to drop again later.
See Use the GUI for every control.
| I want to… | Start with | Read more |
|---|---|---|
| Run in a terminal or CI | build/esp8266emu --flash fw.bin --speed 0 --max-seconds 10 --no-stdin --quiet |
Run headless |
| Press buttons at exact times | A scenario file: 1000 in 0 0 drives GPIO0 LOW at 1 s |
Scenario scripts |
| Find why a boot fails | The Boot card, the emulator log toggle, --strict |
Debug a boot |
| Prove nothing changed | scripts/evidence.py, then scripts/regression.py |
Reports and regression |
| Test an OTA update | scripts/ota_rehearsal.py with your own images, offline |
OTA tests |
| Give firmware a network | Install libslirp and drop the .bin with its .elf; headless: build/esp8266emu-net --net-profile … |
The network in the GUI |
| Emulate an ESP8285 or a given flash size | --chip esp8285 or --flash-size 0x200000 |
Chip and flash |
flowchart LR
image["firmware.bin + .elf"] --> emu
subgraph emu ["build/esp8266emu"]
cpu["LX106 CPU interpreter"] --> rom["ROM services written in C"]
cpu --> io["GPIO, UART, timers, flash, watchdog"]
end
emu -->|"JSON events (stdout)"| server["gui/server.py"]
server -->|"commands (stdin)"| emu
server -->|"live events, 127.0.0.1 only"| page["browser: gui/index.html"]
page -->|"clicks and uploads"| server
The firmware runs instruction by instruction, exactly as it was built. The emulator stands in for the chip's mask ROM and its peripherals; it never patches the image. The GUI server only listens on 127.0.0.1 and refuses other host names. Architecture has the details.
| Folder | Contents |
|---|---|
emulator.cmd, emulator.command, run-gui.sh |
One-command launchers for Windows, macOS and Linux |
src/ |
The emulator in C: CPU, ROM services, peripherals, networking adapter |
gui/ |
Local web server (Python standard library) and the single-page GUI |
scripts/ |
Reports, regression, OTA, profiling and symbol tools |
tests/ |
C and Python tests run by make check |
examples/ |
The hello sketch, a GPIO profile and a regression manifest |
scenarios/ |
A sample timed-input script |
docs/ |
Manual, scope, architecture, testing and networking notes |
- User manual: start here. Install, GUI, headless runs, debugging, troubleshooting and a glossary.
- Current scope: what is implemented and what is not.
- Testing: regression fixtures, OTA tests and performance.
- Virtual networking: the experimental network adapter.
- Architecture: how the emulator works inside, and its event protocol.
- Board comparison: comparing against a physical board.
- Fleet plan: proposal for ten devices at once with a 3D view.
Bug reports and fixes are welcome. Run make check before you send a change,
and see CONTRIBUTING.md for what a good report includes.
Keep firmware, flash files and credentials out of issues and commits.
MIT. Firmware, SDKs and toolchains you use with the emulator keep their own licenses. See NOTICE.md for reference material.
