Commander1024/ESP32_Serial_Swiss_Army_Knife
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add OLED and button diagnostics

Browse Source
This commit is contained in:
Commander1024
2026-08-29 14:13:34 +02:00
parent bb04e0ba79
commit ec9ca5e6d2
13 changed files with 1117 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/roadmap.md
+21 -18
View File
@@ -5,6 +5,7 @@ This document tracks the implementation and hardware-validation plan for the ESP
## Status legend
- **Complete** — implemented and validated on the target hardware.
- **In progress** — implementation or validation is actively underway, but the overall phase is not complete.
- **Implemented; validation pending** — code is present and builds, but the current implementation still needs the listed hardware checks.
- **Planned** — accepted project direction, not yet implemented.
- **Under evaluation** — useful candidate whose feasibility, security, or resource cost must be measured before it becomes a commitment.
@@ -36,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 | **Planned** |
| 7 | Local display and button interface | **In progress (7B)** |
| 8 | Security and production hardening | **Planned** |
| 9 | Authenticated, rollback-capable OTA | **Planned** |
| 10 | BLE serial transport and provisioning evaluation | **Planned** |
@@ -175,47 +176,49 @@ The final target-hardware retest covered:
The software-crypto build no longer reproduces the HTTPD watchdog stall. This validates that the failure was a shared hardware-crypto/PSRAM DMA problem rather than heap exhaustion. Phase 6 is complete; these concurrent arrangements remain regression tests for future transport, TLS, memory-placement, and ESP-IDF changes.
## Planned phases
## Current and planned phases
The order below is the current plan. Detailed requirements should be finalized at the start of each phase, and optional features must not weaken the completed serial and recovery paths.
The order below is the current plan. Phase 7 is in progress; later phases remain planned or under evaluation. Detailed requirements should be finalized at the start of each phase, and optional features must not weaken the completed serial and recovery paths.
### Phase 7 — Local display and buttons
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.
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.
#### Hardware baseline
- 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.
- Wire OLED `VCC` to `3V3` and OLED `GND` to `GND`. The OLED must use 3.3 V because module-mounted I²C pull-ups may connect SDA and SCL to `VCC`.
- Wire OLED `SDA` to GPIO11 and OLED `SCL` to GPIO12. These pins are currently unused and sit in the available GPIO10–14 block on the DevKit header.
- Wire three active-low buttons between their GPIO and `GND`, using the ESP32 internal 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.
- Verify whether the module provides suitable SDA/SCL pull-ups and that every external pull-up is tied to 3.3 V, not 5 V; add external pull-ups to 3.3 V if the module does not provide them.
- Hardware verification established yellow rows 0–15 and blue rows 16–63. A narrow physical black divider separates the two regions even though row 15 is the final yellow addressable row and row 16 the first blue addressable row.
- Keep assignments centralized in the board profile rather than scattering display or button GPIO assumptions through UI code.
![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.
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. Phase 7B must render it as a separate 128×16 status panel. The blue 128×48 content panel begins at row 16 and rotates through overview, RS-232, broker-client, and network/service pages; the physical black divider must remain visually clear. 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**
1. **Phase 7A — Electrical bring-up and diagnostics — Complete**
- 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.
3. **Phase 7C — Read-only status UI**
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.
- 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**
4. **Phase 7D — Local controls — Planned**
- 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**
5. **Phase 7E — Reliability, persistence, and documentation — Planned**
- 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.