272 lines
12 KiB
Markdown
272 lines
12 KiB
Markdown
# OLED + button for immediate local feedback
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
## 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.
|