# T-Deck hardware notes — emulator vs device quirks Lessons from debugging on the physical T-Deck that the SDL3 emulator cannot reproduce (or reproduces differently). Read this before blaming app logic for input/sound problems that "work in the emulator". ## GPIO0 is shared: trackball centre = BOOT — and MCLK-capable - The trackball centre click is wired to **GPIO 0** (`BOARD_BOOT_PIN`), the same pin as the BOOT strap button. It idles HIGH (pull-up), press pulls it LOW. LilyGO docs: while the ES7210 microphone is active, GPIO0 is unavailable (NetDeck only drives the speaker via I2S TX, so this does not apply). - **GPIO0 is one of the few MCLK-capable pins** (GPIO0/1/3, see the `i2s_pin_config_t` comment in the S3 SDK header). A zero-initialized pin config (`i2s_pin_config_t pins = {};`) leaves `mck_io_num = 0`, and `i2s_set_pin()` then claims GPIO0 as the I2S MCLK output. Symptom (NetDeck, fixed 261115): app boots fine, trackball roll works, but `digitalRead(GPIO0)` reads **0 at idle** and the click never registers — the sound engine had silently hijacked the line right after `attachTrackball()`. Fix: always set `pins.mck_io_num = I2S_PIN_NO_CHANGE` explicitly. - Meta-lesson: the emulator's `i2s_set_pin()` shim is a no-op, so pin conflicts like this are **invisible in every emulator test layer**. Any peripheral that reconfigures pins (I2S, SD, radio, touch) needs an on-device sanity check of the pins it does not own. ## Button/click conventions proven on device - **Trackball click acts on RELEASE**: contact bounce fires several FALLING edges while the pin is low; latch the count in the ISR and consume it only once `digitalRead()` is back HIGH — that collapses the burst into one action and survives a press spanning a frame boundary (`CrtTerminal.pollClick()`, NetDeck `applyTrackball()`). Acting directly on the first FALLING edge double-fires. - **Touch acts on PRESS**: `pollTouch()` moves the cursor to the tap and registers the click immediately. - The GT911 can keep `isPressed()` true after the finger lifts (stuck IRQ line on some units). `getPoint()` returning 0 points while `isPressed()` is true is the real release signal — re-arm `wasDown` there or all later taps are swallowed. ## Trackball roll: device vs emulator edge rates - Device: real quadrature pins (`G02=2 right, G01=3 up, G04=1 down, G03=15 left`) at raw pulse rates. Emulator: arrow keys toggle one pin every 3rd loop iteration, mouse wheel queues ~6-edge bursts — far slower. This is why `TB_IMPULSE`/`TB_FRICTION` are split per build (`#ifdef EMULATOR` in the sketch). Tune feel on hardware only. ## Emulator input shim gaps (known, accepted) - Touch shim: left mouse button = single-finger tap at fixed coords; no multi-touch, no stuck-IRQ behavior, so the GT911 quirk above can only be validated on device. - The emulated MCLK line idles LOW and does not toggle during actual playback (a real MCLK square wave would make digitalRead sample quasi-random values). Only the idle signature is emulated. - Clicks accumulated during the 1.4 s boot grace are discarded (`resetTrackball()` at boot end) — intentional on both targets. ## Emulator parity features (added after the GPIO0 incident) - **Pin ownership / GPIO-matrix model** (`emu_input.h`, `Arduino.h`, shim `driver/i2s.h`): `i2s_set_pin()` now *claims* every configured pin, exactly like the real driver. A claimed pin is a driven output: `digitalRead()` sees the driven level (idle LOW), `emu::setPin()` writes from the outside world are ignored, and `dispatchIsrs()` never edges it. Claiming a pin that already has an attached ISR — the exact signature of the sound-engine/GPIO0 hijack — prints a loud `[emu] WARNING: ... on hardware that input just died`. With the bug present the emulator now *kills the click* and fails `e2e/trackball_click`; with `mck_io_num = I2S_PIN_NO_CHANGE` set, silence and a passing journey. - **Edge-accurate ISR latch**: host pin writes go through `emu::setPin()`/`togglePin()`, which record every transition; `dispatchIsrs()` drains them first. A press+release pulse fully contained between two dispatches now registers (previously the level-diff sweep silently swallowed it — covered by `unit/shim_edge_survives_same_dispatch_pulse`). - **E2E runs with audio**: the E2E binary inits `SDL_INIT_AUDIO` (dummy driver). Without it `i2s_driver_install` failed early and `i2s_set_pin()` never ran, leaving the whole pin-ownership class of bugs dormant in E2E. Rule: if a shim driver can fail early, the E2E host must init enough SDL for it to take the same code path as on the device. - Regression journeys/tests: `e2e/trackball_click` (full device pipeline: ISR latch -> release gate -> registerClick), `unit/shim_claimed_pin_is_dead_input`, `unit/shim_edge_survives_same_dispatch_pulse`. ## On-device debugging recipe (that worked here) 1. `cat /dev/ttyACM0` or a pyserial loop reads the app's Serial output (`pio device monitor` refuses a non-TTY stdin). Opening the port does not reset the board; `pio run -t upload` does. 2. Add a low-rate health line (e.g. 4 Hz) printing the suspect pin level, ISR edge counter, and pending counts — it instantly showed `pin0=0` at idle with exactly one latched FALLING edge. 3. Bracket init stages with `digitalRead()` prints (pre-tft / after touch / after trackball / after sound) to bisect *which* init call steals the pin — this pinned the drop to `sound.begin()` in one flash cycle.