From bb04e0ba79c7492022ab635fe9f35232c89754ef Mon Sep 17 00:00:00 2001 From: Commander1024 Date: Thu, 27 Aug 2026 16:46:08 +0200 Subject: [PATCH] Document Phase 7 display hardware and implementation plan --- docs/phase7_display_mockup.svg | 87 ++++++++++++++++++++++++++++++++++ docs/roadmap.md | 49 ++++++++++++++----- 2 files changed, 125 insertions(+), 11 deletions(-) create mode 100644 docs/phase7_display_mockup.svg diff --git a/docs/phase7_display_mockup.svg b/docs/phase7_display_mockup.svg new file mode 100644 index 0000000..73f2003 --- /dev/null +++ b/docs/phase7_display_mockup.svg @@ -0,0 +1,87 @@ + + + Phase 7 dual-color OLED overview-screen mockup + An enlarged mockup of the proposed 128 by 64 pixel local status display. The upper sixteen rows are yellow and show service, Wi-Fi, client, writer, and alert status. The lower forty-eight rows are blue and show IP address, RS-232 configuration, modem signals, traffic counters, and page navigation. Three buttons below are labeled previous, OK, and next. + + + + + + + + + + + + + + + + + + + + + + + + + + + Phase 7 — 128×64 local status display + + + + + + + + + + + + + + + + + SER● WIFI▮▮▮ U1 W1 S1 + WR:SSH CLIENTS:3 !:0 + + + IP 192.168.122.42 + RS232 230400 8N1 + FLOW:NONE VLD:1 + DCD0 DSR1 CTS1 RI0 + RX:1.23M TX:633 + ‹ OVERVIEW 1/4 › + + + + + row 0 + row 15 + row 16 + row 63 + 128 px + Expected split: yellow rows 0–15 · blue rows 16–63 + + + + + + + + ◀ + OK + ▶ + + + previous / hold: back + select / hold: confirm + next + + + + Mockup only — final glyph metrics and the physical color boundary will be verified on hardware. + diff --git a/docs/roadmap.md b/docs/roadmap.md index 21f8aab..8368552 100644 --- a/docs/roadmap.md +++ b/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