Document Phase 7 display hardware and implementation plan

docs/roadmap.md

@@ -181,20 +181,47 @@ The order below is the current plan. Detailed requirements should be finalized a
 
 ### Phase 7 — Local display and buttons
 
-Add a standalone local status/control interface without making it a dependency of the serial core.
+Add a standalone local status/control interface without making it a dependency of the serial core. The planning baseline uses a 128×64 dual-color monochrome I²C OLED sold with an SSD1315 controller. Its expected SSD1306-compatible command set, I²C address, orientation, column mapping, and physical color boundary must be confirmed on the actual modules before the UI layout becomes fixed.
 
-Planned work:
+#### Hardware baseline
 
-- Select the actual display, button arrangement, electrical interface, and remaining GPIO assignment before implementation.
-- Add a board-profile abstraction where required instead of scattering new pin assumptions.
-- Show concise serial, Wi-Fi, service, client-count, and writer-owner status.
-- Provide safe button actions for navigation and common lifecycle or writer-control operations.
-- Require deliberate confirmation for destructive or security-sensitive actions.
-- Avoid displaying passwords or private-key material during ordinary operation.
-- Keep UART0 fully functional as the authoritative recovery interface if the display or buttons fail.
-- Bound display refresh and event processing so they cannot interfere with UART or network transport timing.
+- Power the OLED from 3.3 V so any module-mounted I²C pull-ups remain ESP32-safe.
+- Use GPIO11 for SDA and GPIO12 for SCL. These pins are currently unused and sit in the available GPIO10–14 block on the DevKit header.
+- Use three active-low buttons with pull-ups: GPIO10 for previous/back, GPIO13 for select/confirm, and GPIO14 for next.
+- Use short left/right presses for page or item navigation, short select for entry, a long left press for back/home, and an explicit select hold for disruptive confirmation.
+- Verify whether the module provides suitable SDA/SCL pull-ups; add external pull-ups to 3.3 V if needed.
+- Expect yellow rows 0–15 and blue rows 16–63, but determine the exact split with a movable one-pixel row test instead of relying on seller descriptions.
+- Keep assignments centralized in the board profile rather than scattering display or button GPIO assumptions through UI code.
 
-Completion requires electrical validation, operation with all current transports, and documented recovery behavior.
+![Proposed Phase 7 overview display](phase7_display_mockup.svg)
+
+The persistent yellow strip is reserved for serial-service state, Wi-Fi strength, active USB/Web/SSH counts, current writer, total clients, and an alert indicator. The blue area rotates through overview, RS-232, broker-client, and network/service pages. No password, Wi-Fi secret, private-key material, or routine credential data may appear on the display.
+
+#### Implementation sequence
+
+1. **Phase 7A — Electrical bring-up and diagnostics**
+   - Add bounded low-level display and button diagnostics under the existing `debug` submenu.
+   - Probe only the expected `0x3C` and `0x3D` addresses, then validate geometry, orientation, row/column addressing, contrast, inversion, and the yellow/blue row boundary.
+   - Validate each active-low button, pull-up behavior, debounce interval, short press, long press, and stuck-button handling.
+2. **Phase 7B — Display driver**
+   - Place the SSD1315 behind a small local panel interface and use ESP-IDF's SSD1306-compatible support if hardware testing confirms compatibility.
+   - Use a bounded 1 KiB 128×64 framebuffer, a compact 5×7 font, and a small project-owned status-icon set; do not add LVGL for this fixed monochrome UI.
+   - Prefer dirty 8-pixel-page updates, bounded I²C transaction timeouts, and nonfatal recovery after a missing or unresponsive display.
+3. **Phase 7C — Read-only status UI**
+   - Build display state from existing serial, Wi-Fi, broker, USB, WebSocket, HTTPS, and SSH snapshot APIs rather than parsing CLI output or reaching into transport internals.
+   - Provide overview, RS-232/modem, broker-client/writer, and network/service pages.
+   - Refresh at a bounded low rate, initially about 4 Hz, from a low-priority owner task. Never hold a service lock across an I²C transaction.
+4. **Phase 7D — Local controls**
+   - Add a shallow menu for safe serial, Wi-Fi, HTTPS, SSH, writer-release, display, and reboot actions through direct service APIs.
+   - Require a visible confirmation screen and a timed select hold before stopping active services, revoking a writer, rebooting, or performing another disruptive action.
+   - A local display is not a serial broker client and cannot silently acquire the writer lease.
+5. **Phase 7E — Reliability, persistence, and documentation**
+   - Add contrast and optional dim/blank timeout settings to limit OLED burn-in without making the display necessary for recovery.
+   - Validate display removal, I²C NACK/timeouts, stuck buttons, queue saturation, and repeated actions.
+   - Re-run concurrent USB CDC, WebSocket, and SSH traffic while the UI refreshes and confirm UART0 remains responsive.
+   - Update wiring, electrical-test, command-reference, and recovery documentation.
+
+Completion requires electrical validation on the selected module, correct operation with all current transports, bounded display/button failure behavior, safe action confirmation, no unexplained serial or broker loss, and documented UART0 recovery.
 
 ### Phase 8 — Security and production hardening