Document repeater validation and operating limits

This commit is contained in:
Lars Nolden
2026-09-21 12:31:22 +02:00
parent 8c44c54131
commit 3a0d342314
11 changed files with 890 additions and 267 deletions
+93 -6
View File
@@ -1,10 +1,9 @@
# Future feature note: OLED + button for immediate local feedback
# OLED + button for immediate local feedback
Status: **design note only. Not implemented.** The task description
explicitly excluded a "production OLED UI" from this experiment, and the
display is untouched by the current firmware. This note records what a
local UI should show and the constraints it must respect, while the
reasoning is still fresh.
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
@@ -182,3 +181,91 @@ 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.