[Strycher]

Closes #289.

What changed and why

On 2026-09-08 the touch controller, then the IMU breakout, went silent on the I2C bus for hours. Every reader retried its device on every loop pass, each failure costing two error lines to serial and SD, so the loop fell from 44 Hz to 12-25 Hz and the logs filled with a million identical ESP_ERR_INVALID_STATE (NACK) lines. Nothing recovered without a reboot, and the boot log could not say why the last run ended.

New unit src/i2c_health.{h,cpp}, and a serviceX() in each I2C unit called from loop():

• Health check is a chip-ID register read compared to the expected value, on Wire directly: LSM6DSOX 0x0F=0x6C, LIS3MDL 0x0F=0x3D, FT6336U 0xA8=0x11, BME688 0xD0=0x61. An address probe was the first design and the bench disproved it: the LIS3MDL ACKed its address on every scan while failing every data byte. SHT41 and MAX17048 have no ID register; their own read/isDeviceReady() results feed the same counters.
• Drop after 5 consecutive failures or 8 of the last 16 checks. Dropping clears the unit's available flag, which gates its reads in loop(), and logs once.
• Re-probe every 10 s: check, on failure a bus recovery (nine SCL clocks with SDA released, START+STOP, Wire.end()/begin()), check again at the recorded address and at the chip's alternate address (0x6A/0x6B, 0x1C/0x1E, 0x77/0x76). When it answers, the unit's normal init runs.
• Init read-back: initIMU() clears both flags first and reads a configuration register back on each chip; a chip that ACKs WHO_AM_I but NACKs its configuration writes (the 17:38 boot did exactly that and the library said OK) is refused.
• Flap back-off: a device that drops again within 30 s of returning waits 10, 20, 40 ... 320 s; 30 s of good checks clears it.
• Boot log prints the reset reason (panic, watchdog, brownout, power-on).
• Cadences: IMU every 200 ms, touch 1 s, gauge 2 s, SHT41 on its read, BME688 on the 3 s BSEC cadence.

Docs: bench STEMMA chain order and the 4517 board facts in HARDWARE.md; the redirected-output flash hang in DIAGNOSTICS.md; the scan now names 0x29 as the TSL2591.

What the hardware said

Flashed to the UM bench board at commit 8c96702 and run for 100+ minutes:

• The fault is the LIS3MDL's floating address-select input on the 4517 board. On the old firmware it looked like a dead bus. On this firmware the log names it: 53 drops, most returns at the other address (answers at 0x1E now, not 0x1C), some at the same one, a re-drop within a second of each re-init. The 8 of 16 rule fired on the intermittent phases. Hardware fix: bridge the ADM jumper (owner).
• Loop 44-53 Hz throughout. About 100 error lines an hour against 80,000 before.
• The first live bus recovery exposed a digitalWrite()-before-pinMode() ordering; fixed in this branch (4a9c9aa).
• Touch wake, GPS, SHT41, BME688, gauge all normal for the whole run.

Builds: um_feathers3 RAM 22.7% Flash 27.6%; feather_s3 RAM 31.6% Flash 64.7%.

Gemini gate (four passes, $0.10)

Fixed: BME688 status narrowed to BME68X_E_COM_FAIL; the 8-of-16 window (an intermittent chip kept resetting a consecutive counter); init read-back for a chip that NACKs its configuration; the failure window cleared only by a successful init, not by the re-probe; LIS3MDL read-back on the operation mode rather than the data-rate bits; back-off decays with good behaviour.

Rejected with evidence: "begin() leaks the old I2C device" (all five libraries delete before new); "Wire re-entrancy between endTransmission(false) and requestFrom" (straight-line code, one task); "a long SD write makes the next probe time out" (the Wire timeout is per transaction); "bus recovery aborts an OLED transaction" and "web task reads flags mid-init" (single loop task, synchronous WebServer); "the LIS3MDL ignores the 155 Hz data rate in medium mode" (the library sets ultra-high mode itself; the read-back now checks the operation mode anyway).

Accepted as designed: a noisy SHT41 can be dropped for 10 s after 8 bad reads in a third of a second; re-init of one IMU chip re-inits both (one breakout); no hot-plug of a device absent at boot (never existed).

Verification still owed

Owner flashes the branch tip and confirms on hardware. The board currently runs 8c96702; the three commits after it (recovery pin order, back-off, back-off decay) are built but not yet flashed.

🤖 Generated with Claude Code

[Strycher]

Agent: EmberDelta (session f0e32f9f)