basic1/EMULATOR_PLAN.md

Plan: Computer Emulator Board Option

Add an SFML-based computer emulator as a new board configuration to enable developing and testing the bare-metal application on a desktop computer. This creates a "virtual board" that emulates the display hardware using SFML graphics, following the existing display driver architecture.

Steps

1. Create display/low_level_display_sfml.cpp and display/low_level_display_sfml.h - Implement LowLevelDisplaySFML class inheriting from LowLevelDisplay, with init() creating an SFML window, draw_buffer() converting the 1-bit buffer to RGBA pixels (similar to lines 105-112 in the example), and refresh() updating the SFML texture and handling window events.

2. Create board_configs/board_emulator.h - Define BOARD_NAME as "Computer Emulator (SFML)", set DISPLAY_WIDTH/DISPLAY_HEIGHT (400x300 or configurable), define DISPLAY_TYPE_EMULATOR_VAL constant, set DISPLAY_TYPE_SELECTED to emulator type, set TOUCH_TYPE_SELECTED to TOUCH_TYPE_NONE_VAL initially, and stub out all hardware pin defines (DISPLAY_SPI_PORT, GPIO pins) as unused/invalid values.

3. Update display/low_level_display_factory.cpp - Add DISPLAY_TYPE_EMULATOR to the DisplayType enum, add new case in LowLevelDisplay::create() switch statement to return new LowLevelDisplaySFML(width, height) when emulator type is selected, bypassing pin configuration struct since no hardware GPIO is needed.

4. Modify CMakeLists.txt - Add conditional compilation: detect if BOARD_EMULATOR is defined, if so, find and link SFML libraries (sfml-graphics, sfml-window, sfml-system), add display/low_level_display_sfml.cpp to sources, exclude Pico SDK hardware dependencies (multicore, GPIO, SPI), and compile for native host architecture instead of ARM.

5. Update board_config.h - Add // #define BOARD_EMULATOR to the board selection list with descriptive comment explaining it's for desktop testing, ensure conditional include adds #elif defined(BOARD_EMULATOR) case that includes board_configs/board_emulator.h.

6. Create build_emulator.sh - Script to temporarily enable BOARD_EMULATOR define in board_config.h, configure CMake for host architecture (remove -DPICO_BOARD= flags), build in build_emulator/ directory, and produce a native executable basic1_emulator instead of .uf2 file.

Further Considerations

1. Hardware abstraction for Pico SDK functions - The code uses multicore_launch_core1(), gpio_init(), spi_init(), etc. Should we create stub implementations for the emulator, conditionally compile out hardware-specific code with #ifndef BOARD_EMULATOR, or refactor hardware initialization into a separate HAL layer? Recommend Option A: stub implementations that no-op for simplicity.

2. Touch/mouse input support - Extend later by creating display/low_level_touch_sfml.cpp that inherits from LowLevelTouch, capture sf::Event::MouseButtonPressed events in refresh(), translate mouse coordinates to touch coordinates, and update TOUCH_TYPE_SELECTED in board_configs/board_emulator.h to use the SFML touch driver.

3. Keyboard input for hardware buttons - The example shows console keyboard input (lines 56-89). Should we map specific keys (arrow keys, space, enter) to emulate the hardware buttons like BUTTON_KEY0_PIN found on the e-ink board, or implement a command-line interface like the example? Recommend Option A: map keys to button events for consistency with hardware boards.