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).
104 lines
5.5 KiB
Markdown
104 lines
5.5 KiB
Markdown
# 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.
|