README.md

metadata

title: ESP32 Emulator (VGA32 / FabGL / FreeDOS)
emoji: 🔌
colorFrom: blue
colorTo: green
sdk: static
pinned: false
license: gpl-3.0
short_description: Browser ESP32 emulator - Arduino bins, VGA, PS/2, FreeDOS

ESP32 模擬器 (ESP32 emulator, runs entirely in the browser)

可載入 Arduino-ESP32 / ESP-IDF 編譯出來的二進位檔（完整 flash 映像，或單獨的 bootloader / partitions / app .bin）， 用真實 ESP32 ROM 開機（ROM → 第二階段 bootloader → app），並模擬 LilyGO TTGO VGA32 的周邊電路：

週邊	模擬方式
CPU	Xtensa LX6 雙核（視窗暫存器、loop、MAC16、FPU、32 位元乘除、S32C1I、XEA2 例外/中斷），WebAssembly 核心（C 編譯）＋ JS 參考核心
開機	原廠 ESP32 ROM（Espressif QEMU 發行版附的 esp32-v3-rom*.bin），SPI flash / PSRAM 晶片模型、cache MMU、eFuse、SHA、RTC、TIMG、FRC…
VGA	I2S1 LCD 模式 + DMA 描述子鏈 → 依 VGA32 電阻網路（R=22,21 G=19,18 B=5,4 HS=23 VS=15）重建 hsync/vsync 與像素，顯示在 canvas
PS/2 鍵盤/滑鼠	GPIO 33/32、26/27 開集極匯流排 + FabGL 使用的 ULP 協處理器（含 RTC_IO），完整 PS/2 位元協定（可虛擬點擊/實體鍵盤）
UART0	序列埠終端機（可輸入）
GPIO	40 腳狀態、板子示意圖

內建範例（皆為真實 Arduino-ESP32 2.0.17 編譯的二進位）：

1. FreeDOS 1.4（預設）— FabGL 的 8086 PC 模擬器跑在被模擬的 ESP32 上開機，VGA 輸出、PS/2 鍵盤輸入。
2. FabGL VGA 示範 — 16 色 640×480 VGA + 色塊動畫，PS/2 鍵盤輸入即時回顯（可用虛擬鍵盤）。
3. 序列埠回音 + LED — Serial、millis()、digitalWrite(2)，GPIO 面板可看到腳位閃爍。
4. Hello（Serial）。

使用

1. 開啟頁面自動載入 FreeDOS 範例；畫面點一下即可用實體鍵盤，或用下方虛擬鍵盤（Shift/Ctrl/Alt 為鎖定鍵）。
2. 「載入二進位…」：選擇 .bin（可多個）。位址自動猜測 (bootloader 0x1000、partitions 0x8000、boot_app0 0xE000、app 0x10000、整份 flash 0x0)，可手動修改；只給 app 會自動補上預設開機檔。
3. 「全速」不與實際時間同步；「下載 flash」可取回含寫入結果的 flash。

速度

虛擬 ESP32 為 2×240 MHz，瀏覽器以直譯方式執行，視裝置約為真機的 25–100%（狀態列顯示）。FreeDOS 約需 1–2 分鐘到提示字元，可按 Enter 略過開機選單。

目錄

• index.html / app.js / js/*.js — 模擬器（soc.js 週邊、xtensa.js JS 核心、cpu_wasm.js+wasm/xtensa.c WASM 核心、i2s.js VGA、ps2.js / ulp.js 鍵盤）
• assets.js — gzip+base64 內嵌的 ROM、WASM、範例韌體（Space 的二進位檔會被 CDN 重新導向而無 CORS，所以內嵌）
• firmware/dosvga32/ — 範例韌體原始碼（FabGL PCEmulator 改寫，磁碟映像放在 flash 分區 dosdisk）
• tools/ — 建置/除錯腳本（build_assets.py、run.mjs、vga.mjs …）

授權

模擬器程式 GPL-3.0-or-later（範例韌體包含 FabGL，GPL-3）。ESP32 ROM 映像取自 Espressif QEMU 發行版；FreeDOS 為 GPL。

開發 / 部署

見 docs/DEVELOPING.md。部署：export HF_TOKEN=hf_...; scripts/deploy.sh（Token 只用環境變數）。整個專案的壓縮原始碼包在 Space 的 downloads/esp32emu-source.tar.gz。