Files
lilygo-t-deck/HW.md
T
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

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.