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
+38 -4
View File
@@ -29,6 +29,7 @@ struct Evt {
int x, y; // tap coords
bool fired = false;
int holdIters = 0;
bool pin = false; // trackball centre press (GPIO0 pulse) instead
};
static std::vector<Evt> g_evts;
@@ -36,13 +37,23 @@ static unsigned long g_iters = 0;
static void schedule(double at, char key) { g_evts.push_back({at, key, 0, 0}); }
static void scheduleTap(double at, int x, int y) { g_evts.push_back({at, 0, x, y}); }
static void schedulePin(double at)
{
Evt e;
e.at = at;
e.pin = true;
g_evts.push_back(e);
}
static void pumpEvents(double el)
{
for (auto &e : g_evts) {
if (!e.fired && el >= e.at) {
e.fired = true;
if (e.key) {
if (e.pin) {
emu::setPin(BOARD_BOOT_PIN, LOW); // trackball centre press
e.holdIters = 2; // released 2 iterations later
} else if (e.key) {
test::typeKey(e.key);
} else {
emu::touchDown = true;
@@ -51,7 +62,8 @@ static void pumpEvents(double el)
e.holdIters = 60; // ~80 ms press, like main.cpp
}
} else if (e.fired && e.holdIters > 0 && --e.holdIters == 0) {
emu::touchDown = false; // release -> pollTouch edge
if (e.pin) emu::setPin(BOARD_BOOT_PIN, HIGH); // click release
else emu::touchDown = false; // release -> pollTouch edge
}
}
}
@@ -158,11 +170,33 @@ TEST(e2e/corridor_assault)
EXPECT(garrisonHit || test::serialHas("[combat]"));
}
// The trackball centre click must act exactly like a screen tap. This drives
// the FULL device pipeline (attachTrackball ISR -> tbClicks latch ->
// applyTrackball release gate -> registerClick) — and it doubles as the
// regression for the I2S sound engine silently claiming GPIO0 as its MCLK
// output (a zero-initialized i2s_pin_config_t), which killed the click line
// on hardware while every emulator build looked fine. With the pin-ownership
// model in the shim, the claimed GPIO0 is a dead input here too, so this
// journey fails until the sketch stops claiming the pin.
TEST(e2e/trackball_click)
{
reboot();
EXPECT(pumpUntil(8.0, bootDone));
test::serialClear();
schedulePin(1.0); // trackball centre click
EXPECT(pumpFor(3.0));
EXPECT(test::serialHas("[click]")); // registered (beacon or blocked)
}
int main(int argc, char **argv)
{
// headless: no window needed — rendering goes into the shim framebuffer
// headless: no window needed — rendering goes into the shim framebuffer.
// AUDIO matters for parity too: without it the sketch's i2s_driver_install
// fails early and i2s_set_pin() never runs, so the shim's pin-ownership
// model (and any bug it exists to catch) would stay dormant in E2E.
::setenv("SDL_VIDEODRIVER", "dummy", 1);
if (!SDL_Init(SDL_INIT_VIDEO)) {
::setenv("SDL_AUDIODRIVER", "dummy", 1);
if (!SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO)) {
std::printf("SDL_Init failed: %s\n", SDL_GetError());
return 2;
}