Simulator
Relevant source files
The following files were used as context for generating this wiki page:
The Simulator is a dedicated development and testing environment for FlxOS that allows developers to run the operating system on a desktop environment rather than physical ESP32 hardware. It leverages the Simple DirectMedia Layer (SDL2) to provide hardware-independent graphics and input handling, enabling faster iteration cycles and debugging of the core logic and UI components.
The simulator environment is built using C++17 and integrates the same LVGL graphics library used on the target hardware, ensuring high fidelity between simulated and actual device behavior. It supports core FlxOS features including window management, application logic, and the command-line interface (CLI) for system debugging.
Sources: simulator/CMakeLists.txt:4, simulator/main_sim.cpp:13, ROADMAP.md:144
Architecture and Integration
The Simulator acts as a bridge between the platform-independent FlxOS core and a desktop operating system. It substitutes the ESP32-specific Hardware Abstraction Layer (HAL) with an SDL2-based implementation.
System Components
| Component | Description |
|---|---|
| SDL2 HAL | Manages window creation, display flushing, and input event polling on the host OS. |
| LVGL Integration | Renders the FlxOS UI into an SDL texture using a defined resolution (e.g., 320x240). |
| Mocks | Provides simulated versions of ESP-IDF components such as FreeRTOS and the System Logger. |
| CLI Service | Optional module for interacting with the system via a virtual console. |
Sources: simulator/CMakeLists.txt:20-28, simulator/main_sim.cpp:19-24, main/core/services/cli/CliService.cpp:468
Initialization Flow
The simulator setup process initializes the graphics engine, creates a virtual display, and enters a main execution loop that processes both system timers and window events.
The diagram above illustrates the sequential setup from main_sim.cpp where the environment is prepared before entering the task handling loop.
Sources: simulator/main_sim.cpp:15-40
Configuration and Build System
The Simulator is managed via a separate CMake project that handles dependencies differently than the standard ESP-IDF build process.
Build Requirements
The simulator requires specific host-side tools and libraries:
- CMake 3.16+: Project configuration.
- C++17: Required language standard.
- SDL2: Mandatory library for windowing and graphics.
- ccache: Optional support for faster recompilation.
Sources: simulator/CMakeLists.txt:1-12
Compilation Definitions
When building the simulator, several flags and definitions are applied to modify the behavior of the core components:
| Definition | Purpose |
|---|---|
FLXOS_SIMULATOR | Used in source code to conditionally compile simulator-specific logic or mocks. |
LV_CONF_INCLUDE_SIMPLE | Simplifies the LVGL configuration header inclusion logic. |
LV_CONF_BUILD_DISABLE_EXAMPLES | Reduces build time by excluding unnecessary LVGL example code. |
Sources: simulator/CMakeLists.txt:14-16, simulator/main_sim.cpp:42
Hardware Abstraction and Mocking
To run without an ESP32, the simulator provides mocks for various system-level services. This allows the high-level logic in main/core to remain unchanged.
Display HAL
The Simulator defines a HAL::flush_cb which maps the LVGL draw buffer to the SDL window. It initializes a virtual display with a default resolution of 320x240 pixels and uses a partial rendering mode to optimize performance.
Sources: simulator/main_sim.cpp:19-25
Service Mocks
The build system includes mock implementations for core ESP-IDF functionality:
- FreeRTOS Mock: Simulates tasks and queues (located in
mocks/freertos). - Logger Mock: Redirects system logs to the standard console output (
mocks/Logger_mock.cpp). - CLI Mock/Integration: The CLI service can be enabled or disabled via configuration, allowing command-line interaction with the simulated system.
Sources: simulator/CMakeLists.txt:20-25, main/core/services/cli/CliService.cpp:468
Usage in Development Lifecycle
The Simulator is identified in the project roadmap as a key tool for improving development efficiency.
The sequence diagram shows how the simulator sits between the developer and the core logic, providing immediate visual feedback without flashing hardware.
Sources: ROADMAP.md:144, README.md:104
Conclusion
The FlxOS Simulator provides a vital environment for high-level software development by abstracting away ESP32 hardware. By using SDL2 and a suite of mocks, it ensures that the majority of FlxOS logic—including the UI, application management, and CLI—can be verified on a standard desktop computer, significantly reducing the complexity of the development workflow.