# OLED + button for immediate local feedback Status: **implemented** (firmware/main/ui.c, 2026-09-01). This note holds the design rationale and constraints; deviations of the implementation from the original sketch are listed at the end. Pins were verified against RTNode-HeltecV4 and are now exercised by our firmware (`ui_init ok:true`). ## Why this is worth building The dominant time sink in this experiment was not RF work — it was not knowing *which* device was at fault. Every one of these cost real debugging time and would have been answered instantly by a local display: | Situation that actually happened | What a screen would have shown | |---|---| | 15 min of empty SDR captures; unclear whether meters were absent, the Heltec was deaf, or the dongle was broken | live RX counter ticking up → problem is on the observer side | | `radio_init` reported failure at boot, but the first boot lines were missed because nothing was reading serial yet | init result held on screen until acknowledged | | Radio sat unconfigured in LoRa defaults, in RX, looking healthy | `CFG BAD` indicator from the existing `config_intact` probe | | Needed a laptop to answer "is it repeating right now?" | TX counter and last-repeat age | | Unattended runs drifting toward the 0.1 % duty-cycle ceiling | budget bar (the guard already computes this) | The device is now genuinely standalone — power it and it repeats, with no host needed (verified: 185 s with nothing reading serial, counters kept advancing). A screen is what makes that autonomy *observable* without plugging in a laptop. ## Hardware — VERIFIED against working V4 firmware Values below are from RTNode-HeltecV4 `Display.h` / `Boards.h`, which run on this exact board revision. They are DOCUMENTED, not yet exercised by our firmware, so treat the first bring-up as verification. ``` Display : SSD1306, 128x64, I2C address 0x3C SDA GPIO17 SCL GPIO18 RST GPIO21 (display enable/reset: LOW then HIGH with ~50 ms settle) Vext GPIO36 ACTIVE LOW - must be driven LOW to power the display Button : PRG / user button on GPIO0, active low Reset : hardware button, no firmware involvement ``` Power-up sequence used by the working firmware, worth copying exactly: ``` Vext (36) OUTPUT, LOW -> external rail on delay 50 ms RST (21) OUTPUT, LOW delay 50 ms RST (21) HIGH delay 50 ms Wire.begin(SDA=17, SCL=18) ``` ## Constraints the implementation must respect These are the parts that will bite, and the reason this note exists rather than a quick hack. 1. **Never render from the radio task.** Repeat delay is currently accurate to +1..+8 us against a 200 ms setting, and the RX path already loses ~12 ms per frame to the fixed-255-byte capture tail. A full 1024-byte SSD1306 framebuffer over I2C at 400 kHz costs roughly 23 ms — more than the entire TX airtime. Rendering inside `repeater_task` would visibly corrupt the timing this experiment exists to measure. Use a separate low-priority task that reads a snapshot of `g_stats` / `g_cfg`, and let it be starved without consequence. 2. **Never touch the SX1262 from the UI task.** SPI access is serialised by a mutex in `sx126x.c`; a UI task blocking on it during a repeat would add latency to the RF path. The UI should read cached values that the radio task publishes, not query the radio itself. 3. **GPIO0 is the BOOT strap pin.** Holding it during reset enters USB download mode. So a "hold button at power-up" UI gesture collides with flashing, and a stuck/short-circuited button makes the board unflashable. Keep boot-time gestures off GPIO0 entirely; only sample it well after boot, and debounce (~20-50 ms). 4. **Vext may gate more than the display.** GPIO36 is a shared external rail on Heltec boards. Confirm what else it powers on V4.3 before toggling it for display blanking, and never toggle it while the radio is mid-TX. 5. **Serial JSON stays the source of truth.** Every measurement in this repo is derived from the serial log. If a button can change an RF parameter (TX power, repeat delay, preamble length, duty budget), it MUST emit the same JSON event the console command does, otherwise HIL runs become unreproducible and logs stop being authoritative. That attribution discipline is exactly what made the observer faults diagnosable. 6. **Do not put anything hazardous behind a short press.** Raising TX power or disabling the duty-cycle guard should not be reachable by a single button press on a device that may be left transmitting unattended. If exposed at all, require a long press plus an on-screen confirmation, and log it. ## Suggested screens All fields below already exist in the firmware's telemetry, so no new measurement work is needed — this is presentation only. **Page 1 — Live status (default)** ``` WMBUS RPT 868.95 C1 RX 389 TX 381 OK 100% LAST -51dBm 12s ago DUTY [#####-----] 0.09% RADIO RX CFG OK ``` - `RX`/`TX`/`OK%` from `rx_valid`, `tx_attempts`, `tx_success` - `LAST` from the most recent `wmbus_rx` RSSI + age (answers "is it alive?") - `DUTY` from `tx_duty_cycle_ppm` against `duty_budget_ppm` — directly useful given the 0.1 % ceiling - `RADIO`/`CFG` from the heartbeat's `chip_mode` and `config_intact` **Page 2 — Health / faults** ``` UPTIME 1h31m RECOV 0 RESETS 0 CRC FAIL 700 NOT-C1 594 DUTY BLOCKED 8 TX TMO 0 FAIL 0 ``` Surfaces the counters that distinguish "working" from "working but degrading". `NOT-C1` is worth showing: it was 44 % of sync matches here, and each one costs a receive window. **Page 3 — Last telegram** ``` METER 04766765 LEN 100 A CRC OK RSSI -51 dBm HASH 3832af05 REPEATED +200.0ms ``` Lets you confirm a specific meter is being repeated while standing next to the device — no laptop, no SDR. **Page 4 — Config** ``` DELAY 200ms TXP -9dBm PREAMBLE 8b PA LOW DUTY CAP 1000ppm FEM CSD 1 ``` Because settings are RAM-only and revert on power cycle, showing the *effective* configuration prevents the "I thought it was set to X" class of mistake. ## Suggested button behaviour One button, so keep it obvious: - **Short press** — next page (wraps). Purely visual, zero risk. - **Long press (~2 s)** — page-specific, non-destructive action only: - Page 1: toggle repeat enabled/disabled (logs a JSON event) - Page 2: clear stats (logs it) - Page 3: nothing - Page 4: nothing - **Very long press** — deliberately unassigned. Leave headroom rather than hiding something dangerous behind a timing gesture. Display should blank or dim after a few minutes and wake on button press: this is a device intended to sit powered for hours, and a static OLED image burns in. ## Relationship to the dev board `docs/devboard_signals.csv` now carries the display and button signals. For the instrumented Solenos board the more valuable variant is a display that does **not** share a rail or bus with anything RF-critical, plus at least two buttons so navigation and confirmation are separable — a single button forces gesture overloading, which is how dangerous actions end up behind timing tricks. ## Implementation notes (what was actually built) - `firmware/main/ui.c`: esp_lcd SSD1306 panel over the new i2c_master driver, 5x7 font (`font5x7.h`, host-verified by `firmware/test/test_font_render.c`), UI task at priority 3 pinned to core 0 (radio task is priority 10 on core 1). Rendering is a 1024-byte full-frame draw every 500 ms while awake. - Data flow: radio task publishes `g_ui` (last RX / last TX / heartbeat probe results) in `repeater.c`; the UI additionally reads `g_stats`, `g_cfg`, and `repeater_duty_used_us()`. The UI never touches the SX1262. - Button: short press = next page / wake; hold ~1.5 s = page action. Actions emit `{"event":"ui_action","cmd":...,"value":...}` so serial logs remain authoritative. A press while the display is blanked only wakes it and fires nothing. - Page actions: Status = toggle `repeat_enabled`; Health = clear stats; Config = toggle beacon at a fixed 3000 ms (907 ppm at L=19 — inside the default 1000 ppm duty budget, so a button-started beacon cannot violate the guard). Last-telegram page has no action. - Display blanks after 3 min idle (panel off command; Vext is never toggled). Init failure is non-fatal: `{"event":"ui_init","ok":false}` and the task exits. - Deviations from the sketch: no RESETS counter on the health page (needs NVS boot counting, still unimplemented); the duty bar shows used/budget from the minute-bucket ledger; the config page omits `PA LOW` (the invalid PA row was removed from the firmware entirely) and `fem_rx_csd` (console-only diagnostic). ## Wi-Fi dashboard and QR addition (2026-09-09) Implemented in `wifi_debug.c`, `debug_history.c`, `wifi_qr.c` and `firmware/main/web/`. Two pages follow Config: Wi-Fi credentials and Wi-Fi join QR. A long press on either page toggles the AP; no boot-time gesture is used. The existing four page actions remain unchanged. The radio publishes a separate 256-entry immutable final-outcome history, including silent/verbose-only rejection and skip paths, with synchronized per-row copies. Web clients do not read the deliberately racy OLED snapshot or query the SX1262. Wi-Fi, TCP/IP, HTTP and control processing use core 0; the radio remains on core 1. No network/JSON allocation was added to the radio history producer. Final row IDs correlate reception and transmission directly, not by frame-hash matching. The AP is off at boot and stays on until explicitly disabled or rebooted; display blanking is independent. The password is randomly generated once, persisted in NVS and shown only on the physical display. The QR encodes the same credentials and is generated once per boot when its page is used. Its encoder is the unmodified Nayuki C library v1.8.0 under MIT, with copyright/license notices retained in `firmware/main/vendor/qrcodegen.*`. The 64-pixel display height requires small integer-scaled modules; do not crop the quiet zone or promise camera readability without a physical scan. The dashboard is entirely offline. CSV labels, templates, exports, manufacturer registry lookups and device-type interpretation run in browser JavaScript. Labels never reach the device or persistent browser storage. See README and `docs/TESTING.md` for usage, exact success semantics and the distinction between localhost, USB, phone and RF verification. Both surfaces now use German UI text (ASCII transliterations on the OLED). The phone dashboard puts current events before collapsed diagnosis and optional CSV naming. A shared, nonmodal **?** help panel explains wM-Bus terms without hover, stays outside the refreshed rows, and supports outside click, explicit close and Escape with focus restoration. Its scrollable body and visible close control are bounded to the viewport. Detail-cell spans follow the 560 px radio-column breakpoint, including resize, so expanded rows do not introduce a phantom column on phones. ## Writable settings addition (2026-09-09) `settings.c` is the common coordinator for all ten existing USB settings and OLED toggles. It serializes writers and two-key NVS persistence, publishes accepted values under a short spinlock, and lets the radio owner copy a whole revision at a processing boundary. A pending-only IRQ check drains completed captures and defers known in-flight captures; required radio reinitialization can still interrupt reception. The applied revision acknowledges copying, not RF success. OLED rendering reads the applied snapshot, while settings responses and serial status report accepted values plus both revision numbers. `settings_http.c` adds bounded JSON writes guarded by AP-host/origin checks, a random per-AP CSRF token and boot/revision comparison. WPA2 access remains the authorization boundary. The mobile panel has separate drafts/submit actions, dirty-value preservation, conflict review, persistence labels and confirmation for dangerous duty limits or AP shutdown. Expert controls remain collapsed. Wi-Fi shutdown is queued to its control task, not performed inside the server being stopped. Only delay and duty budget persist, as before. The build embeds deterministic gzip assets and serves them directly, avoiding runtime compression and keeping the existing app/NVS partition layout.