Files
Dejvino 1dcc87d8d4 Fix trackball click: I2S MCLK was claiming GPIO0; emulator pin-ownership parity
Root cause (on device): sound_engine zero-initialized i2s_pin_config_t,
leaving mck_io_num == 0. i2s_set_pin() then claimed GPIO0 — an
MCLK-capable pin on the S3 and the trackball centre / BOOT line — as
its MCLK output. Verified on device with a diagnostic build: pin0 read
LOW at idle, exactly one latched FALLING edge, clicks never registered.

- sound_engine: set pins.mck_io_num = I2S_PIN_NO_CHANGE explicitly.
- NetDeck: register the trackball click on release with contact-bounce
  collapse (the proven CrtTerminal pattern); pollTouch re-arms when
  isPressed() stays true but getPoint() reports no points (stuck GT911
  IRQ on some units).
- Emulator parity (so this class of bug dies before flashing):
  GPIO-matrix pin-ownership model in the shim — i2s_set_pin() claims
  its pins, claimed pins are dead inputs (digitalRead LOW, no edges,
  loud WARNING on claim/ISR collisions); host pin writes go through
  emu::setPin/togglePin with an edge-accurate ISR latch (a full
  press+release pulse between dispatches no longer gets swallowed);
  E2E inits SDL_INIT_AUDIO so the I2S path actually runs there.
  Regression coverage: e2e/trackball_click (fails on the old engine),
  unit/shim_claimed_pin_is_dead_input,
  unit/shim_edge_survives_same_dispatch_pulse.
- Makefile: firmware step follows the sketch move (root platformio.ini,
  src_dir = src/netdeck).
- HW.md: new notes file for emulator-vs-hardware quirks and the
  on-device debugging recipe.

On-device verified: clicks register in both views (beacon drops, node
routing). Fast layer 23 unit + 7 integration green. Note: e2e
boot_and_controls + network_journey failures are pre-existing at HEAD
(reproduced on a clean stash before this change).
2026-11-15 10:24:30 +01:00

5.5 KiB

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.