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