ESP32 Simulator
Relevant source files
The following files were used as context for generating this wiki page:
The ESP32 Simulator provides a desktop-based preview of the Muse user interface within a simulated 412 x 412 SenseCAP Watcher window. It executes production code for the UI, state management, and avatar rendering on Linux and macOS environments without requiring physical hardware or the ESP-IDF toolchain. The system utilizes SDL for display, input, and timing, while host adapters simulate embedded services like Wi-Fi, Bluetooth, and power management.
Sources: esp32/simulator/README.md:19-25, README.md:99-102
The simulator is intended for rapid UI development and automated testing. It does not emulate the ESP32-S3 CPU, camera hardware, or specific radio characteristics, meaning final firmware validation still requires testing on physical devices.
Sources: esp32/simulator/README.md:27-30
System Architecture
The simulator architecture decouples the high-level UI logic from the low-level ESP32 hardware. It maps hardware-specific services to host-side software adapters.
The diagram shows the relationship between production UI code and the simulator's host-side dependencies.
Sources: esp32/simulator/src/main.c:28-40, esp32/simulator/README.md:19-25
Key Components
| Component | Description |
|---|---|
| SDL2 | Supplies the display window, mouse-as-touch input, and system timing. |
| LVGL 9.5.0 | Handles graphics rendering using a pinned version for API compatibility. |
| sim_services.c | Implements mock versions of muse_wifi, muse_ble, and muse_settings. |
| sim_platform.c | Provides host-side abstractions for platform-specific functions. |
| Sources: esp32/simulator/README.md:19-25, esp32/simulator/src/sim_services.c:26-35, esp32/simulator/CMakeLists.txt:104-115 |
Build and Environment
The simulator requires CMake 3.24+, Ninja, and GCC or Clang. It fetches pinned dependencies (LVGL and SDL) during the build process to ensure specific private APIs are available.
Sources: esp32/simulator/README.md:33-40, esp32/simulator/CMakeLists.txt:41-45
Build Commands
cmake -S esp32/simulator -B esp32/simulator/build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build esp32/simulator/build --parallel
Sources: esp32/simulator/README.md:62-65
Scripted Scenarios and Headless Mode
The simulator supports "Scenarios," which are text files defining device states. This allows for deterministic testing and screenshot generation without a display server (headless mode).
Sources: esp32/simulator/README.md:126-140
Scenario Configuration Options
| Key | Supported Values |
|---|---|
face | boot, idle, listening, thinking, speaking, error, off, happy |
wifi | off, no_network, connecting, connected, failed, not_nearby |
ble | off, advertising, connected |
link | boot, unpaired, pairing, confirm, connecting, online, offline, error |
advance | Time in milliseconds to progress the simulation |
| Sources: esp32/simulator/README.md:154-164 |
The sequence shows how headless scenarios are processed to generate output.
Sources: esp32/simulator/src/main.c:113-118, esp32/simulator/README.md:143-150
Interactive Preview Controls
When running interactively, the simulator maps keyboard inputs to common UI transitions and device states.
Sources: esp32/simulator/README.md:92-95
| Input | Action | Source |
|---|---|---|
| F1 - F7 | Switches between boot, idle, listening, thinking, speaking, error, and off modes. | main.c:380-385 |
| H | Triggers the "Happy" idle animation. | main.c:386-389 |
| Space | Simulates Push-to-Talk (Listen while held, Think on release). | main.c:390-391 |
+ / - | Raises or lowers the simulated audio level meter. | main.c:392-397 |
[ / ] | Adjusts the simulated turn progress ring. | main.c:398-403 |
| S | Toggles sleep mode. | main.c:404-405 |
| P | Saves a screenshot named muse-simulator.ppm. | main.c:406-407 |
Simulated Services
The file sim_services.c stands in for ESP32 hardware services. It maintains local static variables for Wi-Fi status, BLE status, and brightness levels, allowing the UI to query these values as if it were running on a physical board.
Sources: esp32/simulator/src/sim_services.c:26-44
Example: Wi-Fi Mocking
static muse_wifi_status_t s_wifi = {
.state = MUSE_WIFI_CONNECTED,
.ssid = "Muse Simulator",
.ip = "192.0.2.2",
.rssi = -45,
};
void muse_wifi_status(muse_wifi_status_t *out) {
if (out) { *out = s_wifi; }
}
Sources: esp32/simulator/src/sim_services.c:30-35, esp32/simulator/src/sim_services.c:132-136
The ESP32 Simulator enables efficient UI iteration by providing a stable, cross-platform environment for testing Muse Gadget interfaces and generating visual documentation.