Tactility GameBoy firmware export notes — 2026-07-17

Context: GameBoy side-loaded ELF prototype on ESP32-S3 color board 192.168.68.129 / ES3C28P, Tactility 0.8.0-dev, firmware built with ESP-IDF 5.3.2.

What happened

The GameBoy app package built locally against the newer cached SDK, but the board firmware rejected startup with the generic dialog:

Application failed to start: missing symbol

USB serial revealed exact missing symbols/runtime behavior.

Confirmed runtime findings

Initial app install/run failed because app was not installed after an interrupted reinstall:

Loader: App not found: one.tactility.gameboy

After reinstall, the loader failed on:

ELF: Can't find symbol esp_log
ElfApp: Application failed to load: missing symbol

Earlier local/source verifier was misleading because it checked the local/generated firmware source exports, not the actual firmware currently running on the board.

Temporary app-side workaround applied

To make the app launch on current board firmware:

Removed/avoided LVGL canvas APIs from the GameBoy app:
- lv_canvas_create
- lv_canvas_set_buffer
- lv_obj_invalidate
- display sizing helpers used only for scaling
Disabled ESP_LOGI/W/E macros in the app source so the side-loaded ELF does not require:
- esp_log
- esp_log_timestamp
Rebuilt and uploaded the patched ELF directly via /fs/upload because /app/install rebooted/crashed mid-install and left stale ELF content.

Result: GameBoy now launches to the ROM browser screen, but the emulator display is intentionally disabled and shows a placeholder until firmware exports canvas APIs.

Firmware exports needed later for full GameBoy display

Add/export these symbols in the firmware’s side-loaded ELF resolver/export table (likely TactilityC/Source/tt_init.cpp or module export path) and rebuild/flash the board firmware:

esp_log
esp_log_timestamp
lv_canvas_create
lv_canvas_set_buffer
lv_obj_invalidate
lv_display_get_horizontal_resolution
lv_display_get_vertical_resolution

Optional if restoring scaled/pretty display:

lv_obj_set_style_transform_scale_x
lv_obj_set_style_transform_scale_y
lv_obj_set_style_layout

Install/debug lessons

/app/run returning HTTP 200 only means the run request was accepted; it does not prove ELF relocation/start succeeded.
Always use USB serial logs while debugging side-loaded ELF startup.
Always verify installed ELF hash by downloading it back:

curl 'http://192.168.68.129/fs/download?path=/sdcard/tactility/app/one.tactility.gameboy/elf/esp32s3.elf' -o /tmp/installed_gameboy.elf
sha256sum /tmp/installed_gameboy.elf Apps/GameBoy/build/cmake-build-esp32s3/GameBoy.app.elf

If /app/install times out or the board reboots, it may leave stale ELF content. Direct upload of ELF and manifest worked:

POST /fs/upload?path=/sdcard/tactility/app/one.tactility.gameboy/elf/esp32s3.elf
POST /fs/upload?path=/sdcard/tactility/app/one.tactility.gameboy/manifest.properties

3.0 KiB Raw Blame History Unescape Escape