docs: design note for future OLED/button local feedback; add display+button to signal wishlist

This commit is contained in:
Lars Nolden
2026-09-01 13:16:34 +02:00
parent b9d5a6138f
commit 3414e850b8
3 changed files with 191 additions and 0 deletions
+2
View File
@@ -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)
+184
View File
@@ -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.
+5
View File
@@ -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
1 signal device gpio direction voltage interrupt timing_critical test_point_required header_required reason
14 RADIO_VDD_SENSE SX1262 analog 3.3 false true true false current sense to confirm PA activity during TX
15 LOG_UART_TX ESP32-S3 43 output 3.3 false false true true always-on boot/log output independent of native USB
16 RF_TAP antenna rf false false true false conducted measurement port with fixed attenuator to avoid observer overload
17 OLED_SDA SSD1306 17 bidir 3.3 false false true true local status UI; must not share a bus with RF-critical peripherals
18 OLED_SCL SSD1306 18 output 3.3 false false true true local status UI
19 OLED_RST SSD1306 21 output 3.3 false false true false display enable/reset; LOW then HIGH with 50ms settle
20 VEXT_EN board 36 output 3.3 false false true false active-low external rail powering the display; verify what else it gates
21 BTN_USR ESP32-S3 0 input 3.3 true false true true user button; also BOOT strap so unusable for boot-time gestures