Propagate the lessons from tron-room-demo's hardware bring-up back into
the canonical template, so demos are hardware-testable from day one:
- Contract change: the sketch renders into emuGfx::fb565 (320x240
uint16_t, RGB565 in PANEL WIRE ORDER - big-endian, the byte sequence
the ST7789 receives over SPI, the same convention TFT_eSprite's
primitives use). The host expands 565 to 8888 for SDL only. Native
little-endian writes look right in the emulator but show byte-swapped
on the panel (seen on hardware: BG 0x0002 -> green, fogged floor
0x0882 -> pink) - the new contract makes that bug impossible.
- Recommended sketch structure: examples/APP/Core.h holds all
rendering/logic device-agnostically (demoInit/demoInput/demoFrame);
the .cpp is a thin emulator shell. Bundled sample demonstrates it.
- New fw/ scaffold: standalone PlatformIO project (shared boards/lib,
T-Deck pin map) with DemoHW.ino driving the same core through a
TFT_eSprite frameBuffer() and reporting true fps + render/push split
over USB serial every 2 s. -O2 explicitly (pio default -Os skews
benchmarks).
- shim.h gains rgb565()/wire565() helpers; Makefile deps now include
the sketch's headers; --dump now also fires on safety-hatch exit (a
long --frames run was silently losing its dump before).
Verified: template builds + smoke renders correct 565 colors; DemoHW
builds clean for ESP32-S3 (328 KB flash).
Make the template foolproof to copy-and-fill for a new demo:
- examples/Conway/ replaced by a neutral examples/Demo/Demo.cpp sample
(bouncing box) documenting the full sketch contract (setup/loop,
emuGfx::fb, emuGfx::dirty, emu::keyboard)
- Makefile passes the sketch path as -DAPP_SRC; main.cpp now includes
APP_SRC instead of hardcoding Conway.cpp, window title uses APP_NAME
- Safety hatch: emulator auto-exits after 10 seconds by default so a
runaway demo can't hang and eat resources; --user-run disables the
cap, --timeout MS adjusts it (default 10000)
- README rewritten as a step-by-step recipe: replace the Demo sketch,
run 'make run'; documents all CLI flags, drops the unimplemented
--dump-interval flag
Verified: fresh copy + sketch swap builds and renders; hatch fires at
10s (and at --timeout 2000); --user-run runs until --frames cap.
Complete self-contained SDL3 emulator-only template for prototyping
sketches without hardware:
- Makefile: single-TU build (host + sketch), run/smoke/clean targets
- shim.h: minimal Arduino API shim (millis, random, String, GPIO stubs)
- src/main.cpp: SDL3 host loop presenting emuGfx::fb, CLI frame dumps
- examples/Conway: Conway.cpp sketch + .ino reference copy
- .gitignore: exclude built binaries and captured BMP frames
The Conway sketch previously started with paused=true, which prevented
render() from being called each frame, leaving the framebuffer all-black
and resulting in a black SDL3 window. Changed to paused=false so the
simulation runs immediately.