Files
heltec-repeater/docs/FUTURE_UI.md
T

272 lines
12 KiB
Markdown

# 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.