feat(vmu-pro): Add BSP component for the 8BitMods VMU-Pro

[finger563]

Description

Adds a new board-support package, espp::VmuPro, for the 8BitMods VMU Pro — an ESP32-S3 based modern replacement for the Sega Dreamcast VMU. The BSP follows the same conventions as the other espp BSPs (singleton get(), espp::BaseComponent logging, Kconfig-tunable interrupt task) and wraps the board's on-board peripherals:

• Display: 1.5" 240x240 IPS LCD (ST7789-class) over SPI @ 80 MHz, with initialize_lcd() / initialize_display(), LVGL integration via espp::Display, LEDC-PWM backlight brightness control, rotation support, and the standard write_lcd_frame / write_lcd_lines / VRAM accessors. Uses swap_color_order = true to match the big-endian RGB565 format the official SDK exposes.
• Buttons: All 9 inputs (D-pad Up/Down/Left/Right, A, B, Mode, Power, Bottom) exposed as a Button enum through a single espp::Interrupt instance, with initialize_buttons(callback) for event-driven use and button_state(Button) for polling.
• Audio: Mono I2S speaker output (default 44.1 kHz, 16-bit, matching the official SDK's audio API) with play_audio(), runtime sample-rate get/set, amp enable/disable, and software volume/mute.
• uSD card: 4-bit SDMMC mounted at /sdcard (the SDK's mount point) via the standard SdCardConfig / initialize_sdcard() API.

A full example is included, using the per-example Gui class pattern from #663: the D-pad moves a cursor, A draws a circle at the cursor (with a synthesized beep), B clears (lower beep), Mode rotates the display, Bottom cycles backlight brightness, and Power toggles mute.

Docs are added under a new 8bitmods vendor section in the Dev Boards documentation, and the example is registered in the CI build matrix (esp32s3).

Warning

All GPIO assignments in this BSP are unverified placeholders. The VMU Pro's schematic is not public and the official vmupro-sdk is an app-level API that does not expose pin numbers. The peripheral set and behavior (display resolution/format, button list, audio model, sdcard mount point) are accurate per the official SDK, but every pin is marked // TODO: unverified in the header, with prominent warnings in the class docs, component README, example README, and the docs page. The same applies to invert_colors and the flash size/mode in the example's sdkconfig.defaults. For this reason the component is deliberately not added to upload_components.yml — it should not be published to the component registry until the pins are verified against real hardware or a schematic.

Motivation and Context

espp has BSPs for many small ESP32-S3 handheld/display boards, but nothing for the VMU Pro, which is a nice ESP32-S3 device with a display, buttons, speaker, and uSD card — a great fit for espp. This provides a starting point so that VMU Pro support only requires filling in the real pin map, rather than writing a BSP from scratch.

How has this been tested?

• Clean-built the example (idf.py build, ESP-IDF, target esp32s3) with no errors or warnings (-Werror enabled).
• Added the example to the CI build matrix in .github/workflows/build.yml so it is built automatically.
• Cross-checked the peripheral behavior (240x240 big-endian RGB565 display, 9-button set, 44.1 kHz 16-bit audio, /sdcard mount) against the official vmupro-sdk APIs.
• Not yet run on hardware — cannot be functional on-device until the placeholder GPIOs are replaced with the real pinout.

Screenshots (if appropriate, e.g. schematic, board, console logs, lab pictures):

N/A — not yet runnable on hardware due to placeholder pin assignments.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update
• Hardware (schematic, board, system design) change
• Software change

Checklist:

• My change requires a change to the documentation.
• I have added / updated the documentation related to this change via either README or WIKI

Software

• I have added tests to cover my changes.
• I have updated the .github/workflows/build.yml file to add my new test to the automated cloud build
• All new and existing tests passed.
• My code follows the code style of this project.

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

Pull request overview

Adds a new ESPP board-support package (BSP) component, espp::VmuPro, for the 8BitMods VMU Pro (ESP32-S3), including peripheral wrappers (display, buttons, audio, SDMMC), a full LVGL GUI-based example, documentation under a new 8bitmods vendor section, and CI build registration.

Changes:

• Introduces the new components/vmu-pro BSP component (headers, implementation, Kconfig, manifest) plus a GUI-driven example project.
• Extends documentation (Dev Boards vendor section + API reference integration via Doxygen input/example paths).
• Adds the example to the CI build matrix and updates the component publish workflow list.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
doc/en/dev_boards/index.rst	Adds 8BitMods vendor section to Dev Boards toctree.
doc/en/dev_boards/8bitmods/index.rst	New vendor landing page and toctree entry for VMU Pro.
doc/en/dev_boards/8bitmods/vmu_pro.rst	New VMU Pro BSP documentation page with warning + API include.
doc/en/dev_boards/8bitmods/vmu_pro_example.md	Includes the component example README into the docs.
doc/Doxyfile	Registers the new component header and example for Doxygen/Sphinx integration.
components/vmu-pro/CMakeLists.txt	Registers the BSP component for esp32s3 with required dependencies.
components/vmu-pro/Kconfig	Adds Kconfig options for the GPIO interrupt task configuration.
components/vmu-pro/README.md	New component README describing features and warning about unverified GPIOs.
components/vmu-pro/idf_component.yml	New component manifest (metadata, dependencies, targets).
components/vmu-pro/include/vmu-pro.hpp	Public BSP API: singleton, display/buttons/audio/sdcard interfaces + placeholder GPIO map.
components/vmu-pro/src/vmu-pro.cpp	Implements ctor and interrupts accessor.
components/vmu-pro/src/display.cpp	Implements LCD + LVGL display initialization, VRAM accessors, brightness, and drawing helpers.
components/vmu-pro/src/buttons.cpp	Implements interrupt-driven button initialization and polling helper.
components/vmu-pro/src/audio.cpp	Implements I2S audio init, audio task, volume/mute, and playback queueing.
components/vmu-pro/src/sdcard.cpp	Implements SDMMC FAT mount at /sdcard.
components/vmu-pro/example/CMakeLists.txt	New ESP-IDF example project setup referencing local components.
components/vmu-pro/example/sdkconfig.defaults	Example defaults (target, LVGL color settings, placeholder flash config).
components/vmu-pro/example/README.md	Example documentation + warning about placeholder pins.
components/vmu-pro/example/main/CMakeLists.txt	Registers the example main component sources/includes.
components/vmu-pro/example/main/vmu_pro_example.cpp	Example app_main wiring BSP + GUI + button actions + synthesized beeps.
components/vmu-pro/example/main/gui.hpp	GUI class interface for LVGL UI pattern used by the example.
components/vmu-pro/example/main/gui.cpp	GUI implementation (cursor, circles, rotation, brightness cycling).
.github/workflows/build.yml	Adds the VMU Pro example to CI build matrix (esp32s3).
.github/workflows/upload_components.yml	Adds components/vmu-pro to publish list (registry upload).

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

Suppressed comments (7)

.github/workflows/upload_components.yml:158

• The PR description explicitly says this BSP must not be published until the placeholder GPIO map is verified, but adding it here makes the upload workflow publish it to the component registry. Remove this entry until the hardware values are validated.

            components/vmu-pro

components/vmu-pro/src/audio.cpp:128

• play_audio() is a normal task-context API—the example invokes it from the Interrupt task—but this calls the ISR-only stream-buffer API. Use the nonblocking task-context variant here; otherwise the FreeRTOS ISR synchronization path is used from a task.

  xStreamBufferSendFromISR(audio_tx_stream, data, num_bytes, NULL);

components/vmu-pro/src/audio.cpp:70

• This callback_m_cv_notified_fn ignores the stop notification. The Task contract requires checking and clearing task_notified while holding m before doing more work; add the early stop check so task shutdown is handled correctly.

bool VmuPro::audio_task_callback(std::mutex &m, std::condition_variable &cv, bool &task_notified) {
  // Queue the next I2S out frame to write

doc/en/dev_boards/8bitmods/vmu_pro_example.md:1

• This include path is two directories short for a file under doc/en/dev_boards/8bitmods; it resolves under doc/en/components, so the example documentation cannot be included. The other vendor-board pages use four parent traversals.

```{include} ../../components/vmu-pro/example/README.md

components/vmu-pro/include/vmu-pro.hpp:451

• This configuration is indeterminate until initialize_i2s() runs, while the public audio_sample_rate() getter reads it without requiring sound initialization. Calling the getter beforehand therefore has undefined behavior; value-initialize the struct as the newer BSP audio implementations do.

  i2s_std_config_t audio_std_cfg;

components/vmu-pro/src/audio.cpp:64

• The object is marked initialized before Task::start() succeeds. A caller-provided invalid core or another start failure returns false, but the next call takes the sound_initialized_ branch and reports success even though no playback task exists. Set the flag only after a successful start and clean up the allocated I2S/stream resources on failure.

This issue also appears in the following locations of the same file:

• line 69
• line 128

  sound_initialized_ = true;

  return audio_task_->start();

components/vmu-pro/src/display.cpp:25

• Any later LCD initialization failure resets lcd_/lcd_spi_ but leaves backlight_ populated. This guard then rejects every retry as "already initialized" even though initialize_lcd() returned false. Roll back the backlight and channel configuration on every failure, or construct them only after the panel is ready.

  if (lcd_ || backlight_) {
    logger_.warn("LCD already initialized, not initializing again!");
    return false;