From 3414e850b8dcb65e46fe949ac573d246e03bb7a5 Mon Sep 17 00:00:00 2001 From: Lars Nolden Date: Tue, 1 Sep 2026 13:16:34 +0200 Subject: [PATCH] docs: design note for future OLED/button local feedback; add display+button to signal wishlist --- README.md | 2 + docs/FUTURE_UI.md | 184 ++++++++++++++++++++++++++++++++++++++ docs/devboard_signals.csv | 5 ++ 3 files changed, 191 insertions(+) create mode 100644 docs/FUTURE_UI.md diff --git a/README.md b/README.md index 30e488b..9087d56 100644 --- a/README.md +++ b/README.md @@ -113,3 +113,5 @@ attenuator, which is not scriptable from the host. - [TESTING.md](docs/TESTING.md) — how to run things, known pitfalls - [DEVBOARD_REQUIREMENTS.md](docs/DEVBOARD_REQUIREMENTS.md) + [devboard_signals.csv](docs/devboard_signals.csv) — future PCB needs +- [FUTURE_UI.md](docs/FUTURE_UI.md) — design note: OLED + button for local + feedback (not implemented; display is untouched by this firmware) diff --git a/docs/FUTURE_UI.md b/docs/FUTURE_UI.md new file mode 100644 index 0000000..b199e43 --- /dev/null +++ b/docs/FUTURE_UI.md @@ -0,0 +1,184 @@ +# Future feature note: 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. + +## 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. diff --git a/docs/devboard_signals.csv b/docs/devboard_signals.csv index 6494166..9c97c93 100644 --- a/docs/devboard_signals.csv +++ b/docs/devboard_signals.csv @@ -14,3 +14,8 @@ ESP_USB_DP,ESP32-S3,20,bidir,3.3,false,false,false,true,flash/console RADIO_VDD_SENSE,SX1262,,analog,3.3,false,true,true,false,current sense to confirm PA activity during TX LOG_UART_TX,ESP32-S3,43,output,3.3,false,false,true,true,always-on boot/log output independent of native USB RF_TAP,antenna,,rf,,false,false,true,false,conducted measurement port with fixed attenuator to avoid observer overload +OLED_SDA,SSD1306,17,bidir,3.3,false,false,true,true,local status UI; must not share a bus with RF-critical peripherals +OLED_SCL,SSD1306,18,output,3.3,false,false,true,true,local status UI +OLED_RST,SSD1306,21,output,3.3,false,false,true,false,display enable/reset; LOW then HIGH with 50ms settle +VEXT_EN,board,36,output,3.3,false,false,true,false,active-low external rail powering the display; verify what else it gates +BTN_USR,ESP32-S3,0,input,3.3,true,false,true,true,user button; also BOOT strap so unusable for boot-time gestures