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:
Dejvino
2026-11-15 10:24:30 +01:00
parent 4645c7a1c6
commit 1dcc87d8d4
12 changed files with 368 additions and 30 deletions
+22 -5
View File
@@ -1154,10 +1154,22 @@ static void pollKeyboard()
static void pollTouch()
{
if (!touchAvail) return;
// Only act on a NEW press (wasDown guards held touches). If the GT911
// keeps isPressed() true after the finger lifted (stuck IRQ observed on
// some units), getPoint() reporting zero points is the real release
// signal — re-arm so the next physical tap still registers.
static bool wasDown = false;
bool down = touch.isPressed();
if (!down) { wasDown = false; return; }
if (wasDown) return; // only act on new taps
if (wasDown) {
// After a press, attempt to detect release by reading the point.
// If getPoint() reports no active point, the IRQ may have been stuck;
// reset wasDown so the next physical tap can be registered.
int16_t x[1], y[1];
int gp = touch.getPoint(x, y, 1);
if (gp <= 0) { wasDown = false; }
return;
}
int16_t x[1], y[1];
int gp = touch.getPoint(x, y, 1);
if (gp > 0) {
@@ -1174,10 +1186,8 @@ static void pollTouch()
// ---------------------------------------------------------------------------
static void applyTrackball()
{
uint32_t e[4], clicks;
uint32_t e[4];
for (int i = 0; i < 4; i++) { e[i] = tbEdges[i]; tbEdges[i] = 0; }
clicks = tbClicks;
tbClicks = 0;
tbVelX += ((int32_t)e[0] - (int32_t)e[2]) * TB_IMPULSE;
tbVelY += ((int32_t)e[3] - (int32_t)e[1]) * TB_IMPULSE;
@@ -1200,7 +1210,14 @@ static void applyTrackball()
clampCursor();
}
if (clicks) registerClick();
// Click acts on RELEASE (like CrtTerminal): contact bounce fires several
// FALLING edges while the pin is low, so consuming only once the pin is
// back HIGH collapses the burst into one registered click — and a click
// still counts if the frame boundary lands mid-press.
if (tbClicks && digitalRead(BOARD_BOOT_PIN) == HIGH) {
tbClicks = 0;
registerClick();
}
}
// ---------------------------------------------------------------------------
+14
View File
@@ -188,3 +188,17 @@ E2E freeze-tint pixel assertions were stale since the diagonal-stripe
rework (pre-existing failures at HEAD under SDL2 too) — updated to the
committed pattern, sampled away from the freeze text. Full suite green:
14 unit + 7 integration + 3 E2E journeys, 0 failures.
### Hardware fix: trackball click dead on device (fixed this commit)
The 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, so clicks never registered on hardware (verified with
an on-device diagnostic build: `pin0=0` at idle, one latched FALLING
edge). Fix: `pins.mck_io_num = I2S_PIN_NO_CHANGE` in
`sound_engine.cpp`; the click now also registers on release with
contact-bounce collapse (the proven `CrtTerminal` pattern). The
emulator gained a GPIO-matrix pin-ownership model + edge-accurate ISR
latch so this class of bug reproduces there (`e2e/trackball_click`
fails on the old code, passes on the fix) — see [HW.md](HW.md).
+5
View File
@@ -39,6 +39,11 @@ bool SoundEngine::begin()
pins.ws_io_num = BOARD_I2S_WS;
pins.data_out_num = BOARD_I2S_DOUT;
pins.data_in_num = I2S_PIN_NO_CHANGE;
// MCLK must be explicitly disabled: `= {}` zero-initializes mck_io_num
// to 0, and i2s_set_pin() then claims GPIO0 as the MCLK output (GPIO0 is
// one of the few MCLK-capable pins) — GPIO0 is the trackball centre /
// BOOT line, so the click would go dead.
pins.mck_io_num = I2S_PIN_NO_CHANGE;
i2s_set_pin(SND_I2S_PORT, &pins);
q_ = xQueueCreate(12, sizeof(SndEvent));