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).
This commit is contained in:
@@ -0,0 +1,103 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user