---
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`。