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).
5.5 KiB
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_tcomment in the S3 SDK header). A zero-initialized pin config (i2s_pin_config_t pins = {};) leavesmck_io_num = 0, andi2s_set_pin()then claims GPIO0 as the I2S MCLK output. Symptom (NetDeck, fixed 261115): app boots fine, trackball roll works, butdigitalRead(GPIO0)reads 0 at idle and the click never registers — the sound engine had silently hijacked the line right afterattachTrackball(). Fix: always setpins.mck_io_num = I2S_PIN_NO_CHANGEexplicitly. - 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(), NetDeckapplyTrackball()). 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 whileisPressed()is true is the real release signal — re-armwasDownthere 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 whyTB_IMPULSE/TB_FRICTIONare split per build (#ifdef EMULATORin 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, shimdriver/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, anddispatchIsrs()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 failse2e/trackball_click; withmck_io_num = I2S_PIN_NO_CHANGEset, 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 byunit/shim_edge_survives_same_dispatch_pulse). - E2E runs with audio: the E2E binary inits
SDL_INIT_AUDIO(dummy driver). Without iti2s_driver_installfailed early andi2s_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)
cat /dev/ttyACM0or a pyserial loop reads the app's Serial output (pio device monitorrefuses a non-TTY stdin). Opening the port does not reset the board;pio run -t uploaddoes.- 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=0at idle with exactly one latched FALLING edge. - 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 tosound.begin()in one flash cycle.