daily auto-sync 2026-07-17

2026-07-17 23:00:01 -04:00
parent 36860c2bc5
commit 8eeabfb5d4
2 changed files with 423 additions and 0 deletions
@@ -0,0 +1,86 @@
+# 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:
+
+```text
+Application failed to start: missing symbol
+```
+
+USB serial revealed exact missing symbols/runtime behavior.
+
+## Confirmed runtime findings
+
+1. Initial app install/run failed because app was not installed after an interrupted reinstall:
+
+```text
+Loader: App not found: one.tactility.gameboy
+```
+
+2. After reinstall, the loader failed on:
+
+```text
+ELF: Can't find symbol esp_log
+ElfApp: Application failed to load: missing symbol
+```
+
+3. 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:
+
+```text
+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:
+
+```text
+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:
+
+```bash
+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:
+
+```bash
+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
+```