Show HN: WiPhone Lab – Doom on an Open ESP32 Wi-Fi Phone

An unofficial fork of the WiPhone open-source phone firmware (v0.8.30) adds a System Benchmark, test harness, and ports of Doom and Gravity Defied to the ESP32-based Wi-Fi phone, with most of the fork written by AI agents using hardware-in-the-loop testing. The fork keeps full telephony intact and runs on the ESP32-D0WDQ6-V3 with 520 KiB SRAM and 4 MiB PSRAM, achieving ~22 FPS for Gravity Defied and ~13.6 FPS for Doom at 320×240 resolution.

An unofficial fork of the WiPhone open-source phone firmware v0.8.30 that keeps the full phone working and adds a reproducible System Benchmark , an on-device test harness , and optional Doom and Gravity Defied ports. Not affiliated with or endorsed by MZJ Technology / HackEDA. The very first commit, "WiPhone 0.8.30 original firmware" , is their pristine upstream release; every commit after it is this fork's work. How this was built.Most of this fork was written by AI agents — the game ports, the shared display pipeline, the benchmark and the harness itself.The work was hardware-in-the-loop rather than code review on faith: the agents built firmware, flashed it to the phone, drove it over UART through the @WP1 harness, and read back telemetry and frame CRCs from the running device. Most of the numbers in this README were measured that way, and more than one conclusion came from watching the panel disagree with what the firmware believed it had drawn — seeDisplay clockbelow for the worst of them. WiPhone https://wiphone.io is an open-source, hackable mobile phone built around an ESP32 . It places calls over Wi‑Fi using SIP/VoIP , and the firmware is a single Arduino sketch WiPhone.ino . Target hardware / toolchain: | SoC | ESP32‑D0WDQ6‑V3, dual‑core Xtensa LX6 @ 240 MHz | | RAM | 520 KiB internal SRAM + 4 MiB PSRAM mapped, 40 MHz | | Display | ST7789 240×320 over VSPI, driven by TFT eSPI | | Audio | WM8750 codec over I²S | | Radios | Wi‑Fi SIP/VoIP , optional LoRa messaging | | Build | Arduino‑ESP32 1.0.5 pinned , ESP‑IDF 3.3.4 | Stock firmware features telephony, SIP, address book, messaging, settings, etc. are unchanged and documented in CHANGELOG.txt . Everything below sits on top of the stock 0.8.30 firmware; telephony is left fully intact. The additions are reachable from the phone's menus. A port of the classic J2ME motorcycle physics game. - Deterministic fixed‑point Q16.16 physics, level loader and renderer. - Runs at ~22 FPS a fixed 45 ms frame period using the shared raw‑VSPI async DMA display pipeline. - Includes an in‑app deterministic benchmark. A ride with the in-game FPS/LCD overlay enabled, on the device: gravity-defied-ride.mp4 A playable Doom port based on FPDoom . - Full‑screen 320×240 landscape output via the async DMA pipeline ~13.6 FPS at full quality with sound — see Performance notes . Sound: a real SFX mixer plus OPL2 music DOSBox dbopl emulator with GENMIDI instruments, MUS→MIDI conversion . SFX and music are mixed and played through the shared WM8750 codec/I²S using a snapshot/restore audio lease that restores the exact telephony audio state on exit.- The Doom zone and most engine buffers live in PSRAM to fit alongside the phone firmware without running the internal heap out of memory. Gameplay recorded off the device, with sound for the OPL music: doom-gameplay.mp4 A raw‑VSPI worker core 0 that converts indexed frames to RGB565 and streams them in ping‑pong DMA chunks, overlapping the game's next‑frame render. Used by both Gravity Defied and Doom; it leases the VSPI bus from TFT eSPI and returns it cleanly on exit. A production diagnostics app that takes a reproducible performance and correctness snapshot of the whole environment CPU on both cores; integer, fixed‑point, float and double kernels; internal RAM and PSRAM; audio codecs; renderer; completed display transfers; flash reads . Deterministic workloads are guarded by frozen CRC32 values and scored against an explicitly saved baseline, so an optimization can be told apart from a regression or a broken computation. On‑device harness TestHarness.cpp/.h , compiled only in harness builds : a line‑based @WP1 UART protocol for automated testing, driven by the Python host client tools/harness/wiphone harness.py . Reproducible builds tools/system benchmark/build.py : produces regular / harness firmware with a content‑addressed Build ID B1-<sha256 :16 and a full manifest, for provenance and stack‑trace‑able releases. WiPhone.ino, .cpp, .h Stock WiPhone firmware GUI, SIP, audio, storage… src/gravity defied/ Gravity Defied game + in-app benchmark src/doom/ Doom port; src/doom/engine/ is the FPDoom engine src/display/ Shared raw-VSPI async DMA display pipeline src/system benchmark/ System Benchmark app kernels, engine, storage, UI src/audio/, src/drivers/, Codecs G.711/G.722 , device drivers, src/TFT eSPI/, src/… vendored/adapted libraries tools/ Host-side tooling: build, harness, asset generation, screenshots, icon/font converters TestHarness.cpp/.h Harness-only UART automation @WP1 protocol CHANGELOG.txt Upstream WiPhone changelog Arduino‑ESP32 core pinned — newer cores are 1.0.5 not compatible. arduino‑cli used by the build script or the Arduino IDE. 1.5.1 - Board: ESP32 Wrover Module esp32wrover — PSRAM must be enabled. - Library: RadioHead 1.120 , LoRa in lora.cpp . TFT eSPI is vendored in src/TFT eSPI/ ; other libraries come with the ESP32 core. - For flashing: esptool.py 3.0.0 used here and a USB‑UART link to the phone CP2104 , e.g. /dev/ttyUSB0 . Board / compiler identity FQBN : esp32:esp32:esp32wrover:FlashFreq=80,FlashMode=dio,PartitionScheme=default,DebugLevel=none The project also compiles with -fsigned-char -fno-common -fwrapv -fno-strict-overflow , and Doom additionally requires the PSRAM linker script src/doom/wiphone doom psram.ld via -Wl,--wrap=esp spiram add to heapalloc plus -DWIPHONE DOOM EMBEDDED SFX . These are wired automatically by the build script below. tools/system benchmark/build.py applies the Doom PSRAM linker script, pins the toolchain, and emits a content‑addressed Build ID and a full manifest .elf / .map for later stack traces : Phone firmware only, without the game ports: python3 tools/system benchmark/build.py --output <artifact-dir --flavor regular --flavor harness also build the @WP1 UART test firmware --flavor both build regular + harness --no-distrobox run the host arduino-cli directly default runs it inside a distrobox container "wi-phone" With Doom and Gravity Defied, and with Doom's sound: python3 tools/system benchmark/build.py --output <artifact-dir --flavor regular \ --games --doom-sfx-wad /path/to/doom-with-audio.wad They are an optional proof of concept guarded by --games is required for the game ports. BUILD GAMES , so a default build contains none of their code — about 1.2 MiB smaller, 59% of the app partition against 98%. , and only works together with --doom-sfx-wad is what gives Doom sound --games . It generates the embedded SFX and OPL music tables from a WAD that still contains its audio lumps. Without it WIPHONE DOOM EMBEDDED SFX stays undefined, the sound table is empty, and the mixer task never starts — Doom then runs completely silent, with no error. It also costs about 780 KiB of flash, so a sound build sits near the app size limit seeDoom IWADbelow . Result: <artifact-dir /regular/WiPhone.ino.bin + .elf , .map , build-manifest.json and a Build ID like B1-EA6254DAB017912D . Open WiPhone.ino , select ESP32 Wrover Module , set Flash 80 MHz / DIO, default partition scheme, PSRAM enabled , then Verify/Upload. This builds the phone firmware alone. The game ports need BUILD GAMES uncomment it in config.h , and a correct Doom build additionally needs the custom linker/flags above — so use Option A when you want the games. Write the app image to app0 @ 0x10000 . The bootloader, partition table, NVS and other partitions are left untouched: esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 \ --before default reset --after hard reset write flash -z \ --flash mode dio --flash freq 80m --flash size 16MB \ 0x10000 <artifact-dir /regular/WiPhone.ino.bin The app image always ends before 0x300000 , so flashing the firmware never touches the Doom IWAD region below. That bound is enforced at build time: build.py passes upload.maximum size = 0x300000 - 0x10000 , so an app that would reach the WAD fails to link instead of silently overwriting it. A sound build currently uses about 98–99% of that budget. For licensing reasons no IWAD ships in this repository. The firmware expects a specific IWAD fixed size and SHA‑256, pinned in src/doom/DoomBuildConfig.h and reads it from flash at 0x300000 — inside the app0 region, after the app. Provide that IWAD yourself and flash it there: esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 \ write flash 0x300000 YOUR IWAD.wad Without a matching WAD the phone and Gravity Defied still work; Doom simply reports that it cannot mount the WAD. The toolchain is intentionally pinned to Arduino‑ESP32 1.0.5. Its precompiled SDK is a hard constraint for some optimizations see Performance notes . Full‑screen Doom is bound by writing the framebuffer, which lives in PSRAM clocked at 40 MHz CONFIG SPIRAM SPEED 40M in the frozen 1.0.5 SDK . The two obvious speed‑ups are both blocked by that SDK: - an internal‑SRAM framebuffer doesn't fit — Wi‑Fi's static RX buffers are never freed esp wifi deinit is commented out in Arduino‑ESP32 1.0.5 and the largest contiguous internal block stays below the ~77 KiB needed; 80 MHz PSRAM is not selectable without recompiling the SDK. Measured full‑screen FPS, full detail: | Configuration | FPS | |---|---| | Shipped: 40 MHz display clock, sound on | ~13.6 | | Same build with sound disabled | ~15.3 | The shipped default is full quality at ~13.6 FPS ; the SFX/OPL mixer task costs the difference. Both games drive the panel through the shared raw‑VSPI pipeline at 40 MHz . An earlier revision used 80 MHz, which is outside what this ST7789 tolerates here: it corrupted the panel's address state mid‑frame, producing torn and duplicated scanlines and, in the worst case, a display that stayed white while DMA still reported every transfer as completed — the engine, CRCs and telemetry all looked healthy. Both Doom and Gravity Defied were affected. Dropping to 40 MHz cleared it in both, and cost no frame rate: Gravity is bound by its fixed 45 ms frame period, and Doom measured slightly faster than it had at 80 MHz. FullScreenDmaTransfer now rejects any request above 40 MHz. The phone firmware and the optional game ports are separate bodies of code under different licenses. The games are a proof of concept: they link to the firmware's interfaces but are not part of it, and they are excluded from the build unless BUILD GAMES is defined see config.h . Phone firmware - © MZJ Technology / HackEDA, under the WiPhone Public License v1.0 WiPhone Public License v1.0.txt , also at https://wiphone.io/WiPhone Public License v1.0.txt https://wiphone.io/WiPhone Public License v1.0.txt . Stock files modified by this fork carry a notice to that effect, as clause 3.0.4 requires. src/TFT eSPI/ — TFT eSPI by Bodmer, FreeBSD licence src/TFT eSPI/license.txt . FairyMax.h — Fairy-Max by H.G. Muller, released into the public domain. src/audio/ — G.711 ITU-T reference and G.722 by Steve Underwood. Doom — src/doom/, GPL‑2.0 - Engine: id Software's , released 1997‑12‑23 and relicensed by id under the linuxdoom-1.10 GNU GPL v2 ; ZeniMax applied GPL‑2.0 to the official repository on 2024‑01‑16, which settles the older Doom Source License headers still present in the 1997 files. Pinned copy in tools/fpdoom/vendor/id-doom/ . - Port: FPDoom tools/fpdoom/vendor/fpdoom/ , released into the public domain under the Unlicense. - Music: opl.c , opl queue.c , oplplayer.c , midifile.c from Chocolate Doom © Simon Howard, GPL‑2.0; mus2mid.c and lprintf.h from PrBoom , GPL‑2.0; dbopl.c is the DOSBox OPL2/OPL3 emulator © The DOSBox Team, GPL‑2.0 or later. - No Doom game data ships here — you supply your own IWAD. Gravity Defied — src/gravity defied/, GPL‑2.0 - Port derived from by rgimad, AntonEvmenenko and Max Logaev, GPL‑2.0. gravity defied cpp https://github.com/rgimad/gravity defied cpp - The original Gravity Defied J2ME, 2004 and its name, logo, artwork and levels belong to Codebrew Software . This project is not associated with Codebrew Software, and the GPL‑2.0 above covers the port's code, not the original game's assets. Tooling tools/prboom/ is a standalone reference benchmark of Retro‑Go's PrBoom 2.5.0 GPL‑2.0 . It is not compiled into the firmware.