# 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
```