Add OLED and button diagnostics

docs/electrical_tests.md

@@ -1,8 +1,112 @@
 # Electrical tests
 
-These procedures verify the MAX3243 breakout, UART1 data path, hardware flow control, and session broker. They are manual tests: the firmware never starts one automatically.
+These procedures verify the Phase 7A OLED and buttons, MAX3243 breakout, UART1 data path, hardware flow control, and session broker. They are manual tests: the firmware never starts one automatically.
 
-> **Safety:** With power removed, install only the wiring required by the selected test. DE-9 pins 3 (`TX`), 4 (`DTR`), and 7 (`RTS`) are driven outputs. Never connect one of these outputs to another driven output. Keep temporary Dupont wiring short and secure.
+> **Safety:** With power removed, install only the wiring required by the selected test. DE-9 pins 3 (`TX`), 4 (`DTR`), and 7 (`RTS`) are driven outputs. Never connect one of these outputs to another driven output. Keep temporary Dupont wiring short and secure. Power the OLED only from 3.3 V because module-mounted I²C pull-ups may connect SDA and SCL to the OLED `VCC` rail.
+
+## Phase 7A OLED and button bring-up
+
+Use the exact OLED and button connections in [Hardware wiring](wiring.md). Display diagnostics initially operate I²C at 100 kHz and probe the standard 7-bit `0x3c` and `0x3d` addresses. The connected test module acknowledges at `0x3c`, whose 8-bit write/read forms are `0x78` and `0x79`. A missing or unresponsive display is nonfatal: diagnostics should report it without disrupting UART0 or the serial services.
+
+### 1. Power-off wiring checks
+
+Disconnect both USB connectors and every other power source before checking or changing wiring.
+
+1. Confirm OLED `VCC` goes only to `3V3`, OLED `GND` goes to `GND`, SDA goes to GPIO11, and SCL goes to GPIO12.
+2. Check for an unintended short between `3V3` and `GND`, and verify ground continuity between the OLED and ESP32 board.
+3. Determine whether the OLED module has SDA/SCL pull-ups and verify that any module-mounted or external pull-ups terminate at 3.3 V, never 5 V. Add suitable external pull-ups to `3V3` only if the module does not provide them; account for parallel resistance if more than one set is fitted.
+4. Confirm each button is wired between its input and `GND`: previous/back GPIO10, select/confirm GPIO13, and next GPIO14. With a meter, each button should be open when released and near zero ohms to `GND` when pressed.
+5. Check that no button shorts two GPIOs together and that SDA and SCL are not swapped or shorted.
+
+### 2. Powered idle checks and address probe
+
+Apply power, but do not initialize the OLED yet.
+
+1. Measure OLED `VCC` relative to `GND`; it should be approximately 3.3 V.
+2. Measure idle SDA on GPIO11 and idle SCL on GPIO12. Both should be near 3.3 V. Power down immediately if either bus line rises toward 5 V; correct the OLED supply or pull-up wiring before continuing.
+3. Run `debug display status` and record the diagnostic state.
+4. Run `debug display probe`. Confirm that it tests only 7-bit `0x3c` and `0x3d` at the initial 100 kHz bus rate. The tested module should acknowledge at `0x3c` (8-bit `0x78` write / `0x79` read).
+
+If the expected address does not respond, treat the result as a nonfatal hardware finding. On this dedicated local-UI bus, `debug display scan --force` may identify an unexpected address before further investigation. Otherwise leave the serial core running, power down, and recheck 3.3 V power, common ground, SDA/SCL order, solder joints, and pull-ups. Do not scan a bus shared with unrelated I²C devices.
+
+### 3. Initialization and display patterns
+
+Initialize the address observed during the scan. The tested module uses 7-bit `0x3c`, equivalently 8-bit `0x78` (write) and `0x79` (read):
+
+```text
+debug display init 0x3c
+```
+
+Then run:
+
+```text
+debug display pattern clear
+debug display pattern fill
+debug display pattern checker
+debug display pattern grid
+debug display pattern corners
+```
+
+Confirm that clear and fill affect the full 128×64 area, checker and grid have regular spacing without shifted or wrapped columns, and all four corner markers are visible in the correct locations. Unexpected mirroring, rotation, clipping, or column offsets must be recorded before Phase 7B fixes the display-driver assumptions.
+
+### 4. Row 15/16 color-boundary test
+
+Clear the display, illuminate row 15, and record its physical color and position:
+
+```text
+debug display pattern clear
+debug display row 15
+```
+
+Repeat for row 16:
+
+```text
+debug display pattern clear
+debug display row 16
+```
+
+**Verified result:** row 15 is the last yellow addressable row and row 16 is the first blue addressable row. The two colored areas are separated by a narrow physical black divider, so later UI rendering must treat the 128×16 yellow and 128×48 blue regions as separate panels rather than one visually continuous canvas. Also test another endpoint row if needed with `debug display row <0..63>` to confirm row addressing and orientation.
+
+### 5. Contrast, inversion, and display-off checks
+
+With a visible pattern loaded, exercise the bounded contrast range and confirm that brightness changes without bus errors:
+
+```text
+debug display contrast 0
+debug display contrast 64
+debug display contrast 128
+debug display contrast 255
+```
+
+Then verify inversion toggles all displayed pixels and can be restored:
+
+```text
+debug display invert on
+debug display invert off
+```
+
+Finally run `debug display off` and confirm the panel turns off cleanly. Use `debug display status`, then `debug display init 0x3c` (or equivalently `0x78` or `0x79`) before further display tests.
+
+### 6. Button checks
+
+With all buttons released, run `debug buttons status`. Confirm previous/back GPIO10, select/confirm GPIO13, and next GPIO14 report released/high due to their internal pull-ups; each should report pressed/low while held to `GND`.
+
+Run `debug buttons test` for the default 10-second interval. During the test, press and release each button separately with a deliberate short press, then repeat with a sustained long press. Confirm that the correct button and short/long classification are reported exactly once per intended action.
+
+Repeat with an explicit duration, for example:
+
+```text
+debug buttons test 30
+```
+
+Use the longer run to check:
+
+- **Debounce:** press with normal switch bounce and make several deliberately quick taps; one physical press must not produce a burst of duplicate press/release or short/long events.
+- **Long press:** hold each button long enough for the diagnostic to classify it as long, then release it; it must not also create an unintended short-press action.
+- **Stuck button:** hold one button before starting the test and keep it held. The input must remain identified as pressed/stuck without blocking checks of the other buttons, and the bounded diagnostic must still exit after the selected duration.
+- **Recovery:** release the held button and confirm `debug buttons status` returns to released/high without a reboot.
+
+`debug buttons test [seconds]` accepts 1 through 30 seconds and defaults to 10 seconds when omitted. Record unexpected event duplication, missed transitions, incorrect GPIO mapping, false long presses, or a test that fails to terminate.
 
 ## Configuration A: data and handshake pairs