Files
heltec-repeater/docs/FUTURE_UI.md
T

7.0 KiB

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.