Add Panel-Aware Local OLED Display Service

docs/command_reference.md

@@ -117,7 +117,7 @@ SSH listens on port 22 and uses the same `admin` credentials as HTTPS, but a sep
 | `debug display scan --force` | Scan usable 7-bit addresses `0x08`–`0x77` at 100 kHz; use only on this dedicated local-UI bus. |
 | `debug display init [address]` | Initialize the OLED at 7-bit `0x3c`/`0x3d`, or their 8-bit write/read aliases: `0x78`/`0x79` and `0x7a`/`0x7b`. |
 | `debug display off` | Turn off the initialized OLED. |
-| `debug display pattern <clear|fill|checker|grid|corners>` | Draw a full-screen electrical and geometry test pattern. |
+| `debug display pattern <clear|fill|checker|grid|corners|layout>` | Draw a full-screen electrical and geometry test pattern; `layout` renders separate status- and content-panel text. |
 | `debug display row <0..63>` | Draw the selected one-pixel display row for addressing and color-boundary checks. |
 | `debug display contrast <0..255>` | Set the OLED contrast to the specified bounded value. |
 | `debug display invert <on|off>` | Enable or disable OLED pixel inversion. |

docs/electrical_tests.md

@@ -49,7 +49,17 @@ 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
+### 4. Rendered status/content layout
+
+Run the Phase 7B panel-layout pattern:
+
+```text
+debug display pattern layout
+```
+
+Confirm that the status text is entirely in the yellow 128×16 panel (rows 0–15), content text is entirely in the blue 128×48 panel (rows 16–63), and the physical black divider between them remains visible. Record any text crossing the divider, clipping, incorrect panel color, or divider obscuration.
+
+### 5. Row 15/16 color-boundary test
 
 Clear the display, illuminate row 15, and record its physical color and position:
 
@@ -67,9 +77,9 @@ 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
+### 6. Contrast, inversion, and display-off checks
 
-With a visible pattern loaded, exercise the bounded contrast range and confirm that brightness changes without bus errors:
+With a visible pattern loaded, exercise the bounded contrast range and confirm that brightness changes without bus errors. On the validated module, the useful visible brightness range begins at `1` and extends through `255`:
 
 ```text
 debug display contrast 0
@@ -87,7 +97,7 @@ 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
+### 7. 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`.
 

docs/roadmap.md

@@ -37,7 +37,7 @@ These constraints apply across all phases:
 | 5A | Authenticated HTTPS administration foundation | **Complete** |
 | 5B | Offline xterm.js WebSocket serial terminal | **Complete** |
 | 6 | Authenticated SSH serial transport | **Complete** |
-| 7 | Local display and button interface | **In progress (7B)** |
+| 7 | Local display and button interface | **In progress (7C)** |
 | 8 | Security and production hardening | **Planned** |
 | 9 | Authenticated, rollback-capable OTA | **Planned** |
 | 10 | BLE serial transport and provisioning evaluation | **Planned** |
@@ -184,7 +184,7 @@ The order below is the current plan. Phase 7 is in progress; later phases remain
 
 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. Phase 7A confirmed SSD1306-compatible operation, 7-bit I²C address `0x3c`, orientation, column mapping, contrast/inversion behavior, button inputs, and the physical color geometry on the selected hardware.
 
-Phase 7A diagnostics and target-hardware electrical validation are complete. Phase 7 overall remains in progress with Phase 7B next; Phases 7B through 7E are not complete.
+Phase 7A diagnostics and target-hardware electrical validation are complete. Phase 7B display-driver validation is complete; Phase 7 overall remains in progress (7C). Phases 7C through 7E are not complete.
 
 #### Hardware baseline
 
@@ -206,10 +206,12 @@ The persistent yellow strip is reserved for serial-service state, Wi-Fi strength
    - Bounded low-level display and button diagnostics are available under the existing `debug` submenu.
    - The selected module acknowledged at 7-bit `0x3c` (8-bit `0x78` write / `0x79` read). A guarded full scan is retained for the dedicated local-UI bus; an absent display remains nonfatal and does not make the serial core dependent on the OLED.
    - Hardware validation passed for geometry, orientation, row/column addressing, contrast, inversion, button pull-ups/debounce/short-press/long-press/stuck behavior, and the color geometry: yellow rows 0–15, blue rows 16–63, with a physical black separator between the regions.
-2. **Phase 7B — Display driver — Planned**
-   - 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.
+2. **Phase 7B — Display driver — Complete**
+   - The `local_display` service owns the local I²C bus, SSD1315-compatible panel, and framebuffer. It uses a static 1 KiB 128×64 framebuffer, a compact 5×7 uppercase/digit/punctuation renderer, and an internal mutex; do not add LVGL for this fixed monochrome UI.
+   - Rendering treats the yellow 128×16 status panel (rows 0–15) and blue 128×48 content panel (rows 16–63) as separate panels so the physical divider remains clear.
+   - Frame commits refresh only dirty 8-pixel pages. I²C runs at 100 kHz with bounded transactions.
+   - The display bus initializes at boot; a known display is automatically initialized and cleared. A missing or unresponsive display is nonfatal and does not make the serial core dependent on it.
+   - Target-hardware validation passed for initialization, all display diagnostic patterns, the rendered panel layout and physical divider, row 15/16 boundary, contrast, inversion, display-off/reinitialization, and button diagnostics. Observed contrast control has a useful brightness range of 1–255.
 3. **Phase 7C — Read-only status UI — Planned**
    - 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.