chore: release 1.5.2

chore: release 1.5.1
fix(radio): cache mod params on SET_CONFIG so TX works without prior RX
2026-05-11 15:03:13 -06:00 · 2026-05-11 11:38:38 -06:00 · 2026-05-11 11:15:30 -06:00 · 2026-05-11 11:10:47 -06:00 · 2026-05-11 10:49:32 -06:00 · 2026-04-30 07:11:16 -06:00
46 changed files with 6810 additions and 2693 deletions
@@ -7,6 +7,426 @@ and this project adheres to [Semantic Versioning](https://semver.org/).

 ## [Unreleased]

+## [1.5.2] - 2026-05-11
+
+### Changed
+
+- Refreshed `Cargo.lock` to pull in the latest compatible patch/minor
+  releases of dependencies. Notable bumps:
+  - `donglora-protocol` 1.1.0 → 1.2.0
+  - `esp-hal` 1.1.0 → 1.1.1
+  - `heapless` 0.9.2 → 0.9.3 (propagates through embassy + esp crates)
+  - `embassy-usb-driver` 0.2.0 → 0.2.1
+  - `embassy-usb-synopsys-otg` 0.3.2 → 0.3.3
+  - `enumset` 1.1.10 → 1.1.12
+  - `digest` 0.11.2 → 0.11.3, `hashbrown` 0.17.0 → 0.17.1,
+    `hybrid-array` 0.4.11 → 0.4.12, `cc` 1.2.61 → 1.2.62
+  No source changes; all 10 board targets compile clean and host-side
+  protocol tests pass.
+
+## [1.5.1] - 2026-05-11
+
+### Fixed
+
+- **`LoRaConfig.sync_word` is now actually applied to the SX126x.**
+  `reconfigure_radio` accepted the host's `sync_word` field in name
+  only — the value was stored in `self.config` but never written to
+  the chip's `LoRaSyncwordMSB`/`LoRaSyncwordLSB` register pair
+  (0x0740/0x0741, SX1261/2 datasheet Rev 2.2 §13.4.4). The chip sat
+  on whatever `LoRa::new(_, false, _)` set at cold init —
+  `LORAWAN_PRIVATE_SYNCWORD` (byte `0x12`, register pair `0x1424`).
+  Everyone got byte `0x12` regardless of the requested value. Worked
+  by accident for MeshCore (which uses byte `0x12`); silently broke
+  any host trying to talk to a non-MeshCore network. Fix wires
+  `cfg.sync_word` through to `lora.set_lora_sync_word(byte)` after
+  `enter_standby`, using the new lora-phy API from
+  [lora-rs/lora-rs#433](https://github.com/lora-rs/lora-rs/pull/433).
+  The `u16` protocol field is decoded back to its underlying byte
+  (`byte = (hi & 0xF0) | (lo >> 4)` after `to_be_bytes()`), the
+  inverse of lora-phy's `convert_sync_word` nibble-expansion. Honors
+  SX1261/2 §8.3.1 (BUSY-low precondition) via the existing
+  `ensure_ready + conditional set_standby` preamble in
+  `LoRa::set_lora_sync_word`.
+- **First TX after `SET_CONFIG` no longer fails with `ERR(ERadio)` on
+  a freshly-booted chip.** The chart's `prep_for_cad_act`
+  (`TxCadPrep` entry) and `prep_for_tx_act` (`TxPrep` entry) both
+  read `ctx.mdltn` and emit `TransmitFailed` → `ERR(ERadio)` if it's
+  `None`. But `ctx.mdltn` was only ever assigned on the RX path —
+  `try_start_rx_hw` (`RxArming` entry) and `cache_rx_pkt`
+  (`RxSession` entry). `reconfigure_radio` already called
+  `to_lora_mod_params(lora, cfg)` during `SET_CONFIG` but discarded
+  the result via `let _ = …?;` (the dropped comment claimed image
+  calibration; the function is pure compute on SX126x). Hidden in
+  practice by any prior `RX_START` (ai-bot, `ping_pong --role rx`,
+  etc.) leaving `ctx.mdltn` populated until the next reflash. Fix
+  threads the `ModulationParams` out of `reconfigure_radio` as its
+  return value, and `apply_set_config` caches it in `self.mdltn`
+  alongside `self.config`. First TX on a fresh boot now works
+  without a preceding `RX_START`.
+
+### Changed
+
+- **`lora-phy` `swaits/lora-rs#fixed` bumped from `e8a52ebd` →
+  `043d7659`.** The fork's `fixed` merge now includes a new
+  `feat/set-sync-word` branch alongside the three pre-existing
+  `fix/*` branches.
+  [lora-rs/lora-rs#433](https://github.com/lora-rs/lora-rs/pull/433)
+  adds the runtime `LoRa::set_lora_sync_word(u8)` API the radio fix
+  above depends on (was unavailable in stock lora-phy; the only
+  public sync-word entry points were `with_syncword` /
+  `new(_, public_network: bool, _)` at construction time). Strictly
+  additive in lora-phy: pure addition, no behavioral change to
+  `init_lora` / `with_syncword` / any existing path.
+- **`hsmc` 0.5 → 0.6.** Patch bump tracked via `cargo update -p
+  hsmc`; no behavior change in this crate's usage. Pulled in
+  separately from the radio fixes so the dep churn doesn't blur the
+  fix commits.
+
+## [1.5.0] - 2026-04-30
+
+### Added
+
+- **Heltec Mesh Node T114 board support** (nRF52840 + SX1262 + 1.14"
+  240×135 ST7789 color TFT). The first color display board in the
+  project, and the third nRF52840 + SX1262 board alongside the
+  RAK4631 and Wio Tracker L1.
+  - `VEXT_ENABLE` (P0.21) driven HIGH at boot to power the SX1262 +
+    TFT rail. Without this, lora-phy init succeeds at the SPI level
+    but TX_DONE never fires.
+  - `VTFT_CTRL` on P0.03 (active-LOW); PWM backlight on P0.15
+    (active-LOW, inverted) for smooth dim/bright transitions.
+  - TFT SPI2 (SCK P1.08 / MOSI P1.09) at 8 MHz over EasyDMA, async
+    `ExclusiveDevice` from `embedded-hal-bus`.
+  - Linker uses the shared `ld/nrf52840-memory.x` so the S140
+    SoftDevice region (0x01000–0x26000) is preserved per project
+    policy.
+
+- **`BoardDisplay` trait** (`src/display.rs`) bundles `render_*`,
+  `present()`, `set_bright()`, and `set_dim()`. Replaces the previous
+  `DrawTarget<Color = BinaryColor>` + `DisplayBrightness` combo as
+  the `LoRaBoard::DisplayDriver` bound, so each board renders in its
+  native pixel format and resolution without aliasing or
+  color-quantization round-trips. Existing mono OLED drivers
+  (`Sh1106`, `Ssd1306Async`) get adapter impls that delegate to the
+  existing `display::render` module — no behavior change for any
+  previously supported board.
+
+- **Async ST7789 driver** (`src/driver/st7789.rs`) wrapping
+  `lcd-async` (async fork of `mipidsi`) with a 64,800-byte raw-byte
+  framebuffer in `.bss`. Renders via
+  `lcd_async::raw_framebuf::RawFrameBuf<Rgb565, _>` and presents via
+  a single async DMA blit (`panel.show_raw_data(...).await`); the
+  await yields the executor for the ~65 ms SPI transfer so the radio
+  task isn't starved during repaints.
+
+- **Native 240×135 RGB565 renderer** (`src/display/render_color.rs`)
+  with splash, dashboard, and sparkline parity with the mono path,
+  plus a shared QR-code blit (`src/display/qr.rs`) generic over
+  `PixelColor`. The blit re-centers the 64×64 bitmap (cells in cols
+  0..50 with ~14 px right-side padding), so both mono and color
+  splash now show the QR with 7 px quiet zones on all four sides
+  (was visibly left-shifted on mono).
+
+- **Shared content types** (`BoardInfo`, `DashboardCtx`) decouple
+  *what* to draw from *how* each board renders it. `create_display()`
+  now takes the board's full `DisplayParts` bundle (was just the I2C
+  bus), so non-I2C displays can carry SPI + control pins through.
+
+- **IDF app descriptor on every ESP image.** New
+  `esp-bootloader-esp-idf` 0.5 dependency (chip-feature-gated like
+  the rest of the `esp-*` stack) plus `esp_app_desc!()` in
+  `src/main.rs`, which emits the `.flash.appdesc` section that
+  `espflash` v4 requires in every ESP binary.
+
+### Changed
+
+- **ESP build modernized to upstream crates.io.** Removed the
+  `[patch.crates-io]` block that pinned `esp-hal`, `esp-rtos`,
+  `esp-backtrace`, and `esp-println` to `esp-rs/esp-hal#main`. The
+  versions tracked there (`esp-hal 1.1`, `esp-rtos 0.3`,
+  `esp-backtrace 0.19`, `esp-println 0.17`) have all reached
+  crates.io with the `embassy-executor` 0.10 compatibility we needed,
+  so the local fork pins are no longer required. `cargo:espflash`
+  bumped to v4 in `mise.toml` to match.
+
+- **`hsmc` 0.5.0 → 0.5.1.** Patch bump pulled in transparently with
+  the lockfile refresh; no behavior change.
+
+- **Documentation consolidated.** `PROTOCOL.md` removed from the
+  firmware repo (it now lives canonically in the spec repo, linked
+  from `README.md`). `BLE_MUX_DESIGN_DOC.md` moved to
+  `docs/ble_mux_design.md` so all firmware design docs sit under
+  `docs/`.
+
+## [1.4.1] - 2026-04-29
+
+### Fixed
+
+- **Major LoRa reliability boost across every radio family.** Switched
+  `lora-phy` from crates.io to the
+  [`swaits/lora-rs#fixed`](https://github.com/swaits/lora-rs/tree/fixed)
+  fork branch — a merge of three fixes awaiting upstream PR acceptance,
+  pinned at `e8a52ebd` via `Cargo.lock`:
+  - [#428](https://github.com/lora-rs/lora-rs/pull/428) — sx126x:
+    pre-command BUSY check + standby/IRQ-clear hygiene around CAD.
+  - [#431](https://github.com/lora-rs/lora-rs/pull/431) — sx127x:
+    clear stale IRQ flags in `do_rx` before mode change.
+  - [#432](https://github.com/lora-rs/lora-rs/pull/432) — sx127x:
+    clear stale IRQ flags before reconfiguring DIO mapping in
+    `set_irq_params`.
+
+  Stability gain across the fleet: the sx126x BUSY-race fix lands on
+  every nRF / RP2040 board, and the sx127x IRQ-clear fixes unblock the
+  LilyGo T-Beam (classic) in particular.
+- **UART host RX delivery on UART-only boards.** `RADIO_THROTTLED` was
+  never cleared on UART (`heltec_v3_uart`, `elecrow_thinknode_m2`,
+  `lilygo_tbeam`) — the throttle gate added in v1.3.0's chart-first
+  restructure silently dropped every async RX from boot. Mirrored the
+  USB pattern: clear the throttle on successful `tx.write_all`, re-arm
+  on failure.
+- **UART host watchdog spurious-trip under saturated bidirectional
+  load.** The `select3`-based loop serialised read and write;
+  `tx.write_all` (~25 ms per max frame at 115200 baud) blocked the read
+  poll long enough for `last_frame_at` to age past 1000 ms, cascading a
+  Reset to radio (`Unconfigured`) and display (splash) and leaving
+  subsequent host TX commands timing out. Restructured `host_task` into
+  two sub-loops joined in the same task: `read_loop` owns rx +
+  watchdog, `write_loop` owns tx + throttle. Same executor, disjoint
+  borrows on the split rx/tx halves, no Mutex needed. Also reset the
+  `FrameDecoder` on watchdog fire so a host that resumes mid-frame
+  resyncs cleanly on the next `0x00` sentinel (USB gets this for free
+  via DTR-drop reset; UART has no DTR).
+- **Splash board-name overflow on long names.** Names that don't fit
+  `FONT_6X10` (21 ASCII chars on a 128 px-wide OLED) now fall back to
+  `FONT_5X8` (25 chars). A `const_assert` at the `BOARD_NAME`
+  definition rejects names that overflow even the fallback, so the
+  board porter shortens `NAME` at compile time rather than getting
+  silent overflow at runtime. Also dropped the URL-line font on the
+  "learn more" screen from `FONT_5X8` to `FONT_4X6` so `donglora.com`
+  sits inside the 64 px column with breathing room instead of touching
+  both edges.
+
+### Changed
+
+- **`hsmc` 0.4 → 0.5.** `default(...)` is optional on every state in
+  0.5; collapsed the `WaitingForFirstFrame` substate that existed only
+  because 0.4 required `Connected` to declare a default child.
+  `Connected` itself is now the resting "DTR up, no traffic yet" state,
+  with `on(FrameReceived) => Active` descending into the
+  inactivity-timer state on the first byte. Behavior is identical
+  (entry/exit chain math unchanged); the host/usb chart has one fewer
+  state and one fewer `default()`. Display and Radio charts left as-is
+  — their defaults serve real grouping/lifecycle purposes, not 0.4
+  artifacts.
+- **ESP cross-toolchain pinned in `mise.toml`.** `[env]` now owns the
+  PATH (`xtensa-esp-elf-gcc` bin) and `LIBCLANG_PATH`, so any `mise
+  exec` resolves the linker without sourcing espup's stray
+  `~/export-esp.sh`. New `[tasks.esp-install]` invokes espup with the
+  matching crosstool version pin. `cargo:espup` pinned to `0.17.1` to
+  match the `[env]` paths. Triggered by a real failure where
+  `~/export-esp.sh` was moved to Trash and the ESP build broke with
+  `linker xtensa-esp32s3-elf-gcc not found`. Bumping ESP versions
+  remains a two-touch change: edit version dirs in BOTH
+  `[tasks.esp-install]` and `[env]`.
+- **ESP dependency requirements bumped** to track the upstream
+  `esp-rs/esp-hal` main branch: `esp-hal 1.0 → 1.1`, `esp-rtos 0.2 →
+  0.3`, `esp-backtrace 0.18 → 0.19`, `esp-println 0.16 → 0.17`. `cargo
+  update` had silently invalidated the `[patch.crates-io]` entries (the
+  patched versions were no longer semver-compatible with the old
+  top-level requirements), dropping the patches and falling back to
+  crates.io releases that pin `embassy-executor 0.9` — mismatched with
+  our `0.10`. Catching this keeps the patch suite consistent until the
+  planned `[patch.crates-io]`-removal pass.
+
+## [1.4.0] - 2026-04-25
+
+### Added
+
+- **RAK4631 WisBlock board support** (nRF52840 + SX1262, RAK19007 base
+  + RAK4631 Core + RAK1921 OLED). The second nRF52840 + SX1262 board
+  alongside the Wio Tracker L1.
+  - `SX126X_POWER_EN` (P1.05) driven HIGH at init — the radio is
+    power-gated on this module; without this the chip has no power
+    and SPI hangs.
+  - HFXO + LFXO external crystals selected in `embassy_nrf::Config`.
+    USB CDC-ACM needs ±500 ppm which the internal RC oscillator
+    can't provide.
+  - `SoftwareVbusDetect(true, true)` so USB enumerates without a
+    `CLOCK_POWER` interrupt handler.
+  - Green LED on P1.03 (RAK19007 Base LED1, active-HIGH) via
+    `SimpleLed`.
+  - Hardware-validated end-to-end: ADVERT round-trip with an external
+    receiver on US915.
+  - Added `debug-checkpoint` blink-map coverage at every TX-phase
+    boundary in `radio.rs`, including a new checkpoint between
+    `prepare_for_cad` and `cad()` so future bring-ups can distinguish
+    a modem-setup hang from a DIO1-wait hang.
+
+- **Adaptive listen-before-talk.** The CAD pre-TX retry loop scales to
+  the active LoRa config instead of running a fixed 10 retries × 10 ms
+  (which was roughly one max-length packet at SF7/BW500 and a no-op at
+  SF12/BW125).
+  - Per-retry sleep is sized to the time-on-air of an assumed-peer
+    80-byte packet under the current SF/BW/CR — cached on
+    `RadioContext`, recomputed on every `SET_CONFIG`.
+  - Retry count = `clamp(floor(BUDGET/T)+1, 1, 10)` with `BUDGET = 2.5
+    s`. Fast configs still get up to 10 retries; SF11/12 degrade to
+    single-CAD-and-bail (logged at config-apply).
+  - Sleeps jittered ±20% per iteration to decorrelate
+    simultaneously-backing-off contenders.
+  - ToA math, CR→{1..4} mapping, retry-count derivation, and jitter
+    helper live in a pure `src/lbt.rs` module — host-testable via
+    `DONGLORA_HOST_TEST=1 cargo test` (13 tests).
+  - Validated on-device: 20 iterations of the AI Bot test flow that
+    previously saw ~2 `ChannelBusy` errors now sees zero at the same
+    SF/BW.
+
+### Fixed
+
+- **First-TX-after-boot reliability on SX1262 boards.** Picked up the
+  upstream `lora-phy` fix that moves the BUSY-handshake check from
+  *after* to *before* each SPI op, per Semtech SX1261/2 §8.3.1, LR1121
+  UM §3, and LR1110 DS §1.2.5. The existing post-op wait is preserved
+  as the belt that closes the BUSY-assertion latency window
+  (T_SW ≤ 600 ns) that a single level-poll can miss. Consumed via
+  `[patch.crates-io]` against `swaits/lora-rs#fix/sx126x-busy-race`
+  until the upstream PR merges.
+  - Hardware-verified on Seeed Wio Tracker L1: 20/20 clean-boot TX
+    (vs ~50% before).
+  - Renames `InterfaceVariant::wait_on_busy` → `wait_until_ready` to
+    match the new semantics.
+- **BUSY pin pull-down → none on nRF SX1262 boards.** SX1262's BUSY
+  pin has an internal 20 kΩ pull-up (datasheet p. 53); our
+  `Input::new(..., Pull::Down)` was contending with it, leaving BUSY
+  at an indeterminate voltage and intermittently mis-reading the
+  chip's ready state. Per `lora-rs/lora-rs#260`, switched to
+  `Pull::None` on both Wio Tracker L1 and RAK4631. The RAK4631
+  appeared to work before, but was affected by the same class of bug
+  per the upstream issue — now deterministically correct rather than
+  "happens to work".
+
+### Changed
+
+- **Build-system DX.** `just flash`, `just flash-probe`, and
+  `just build` accept an optional comma-separated `extra_features`
+  argument that is appended to the board feature, e.g. `just flash
+  wio_tracker_l1 debug-checkpoint`. No more dropping to raw
+  `cargo + rust-objcopy + uf2 cp` for iteration loops.
+- **`just` recipes now resolve all tools through `mise`** via
+  `set shell := ["mise", "exec", "--", "sh", "-c"]`. `cargo`,
+  `espflash`, `rust-objcopy`, `cargo-hex-to-uf2` etc. always pick up
+  the versions pinned in `mise.toml` regardless of `PATH` ordering.
+- **`mise.toml` rust pins now carry ARM targets + clippy**, so a fresh
+  `mise install` is sufficient bootstrapping — no manual
+  `rustup target add` for `thumbv6m-none-eabi` /
+  `thumbv7em-none-eabihf` and no separate clippy install.
+- **New `just flash-dfu` recipe** for the Adafruit nRF52 bootloader
+  (VID:PID `239a:0029`) via `adafruit-nrfutil` under `uvx`, with port
+  autodetect.
+- **Per-board `_info` chain in the justfile** collapsed from a long
+  per-board `if/elif` ladder + per-board `:=` variables into a single
+  `case` statement — one place per board, two lists (names +
+  metadata).
+
+## [1.3.1] - 2026-04-23
+
+### Fixed
+
+- **LilyGo T-Beam (classic) red LED now flashes on TX/RX** instead of
+  dimming off. The red LED under the OLED is wired active-LOW on this
+  board (anode to V+, cathode to GPIO4); v1.3.0 drove it as active-HIGH,
+  so the LED sat lit at idle and briefly dimmed during activity.
+  - Empirically verified on hardware against both T-Beam variants.
+  - Introduces `src/driver/inverted_pin.rs::InvertedPin<P>`, a generic
+    `OutputPin` wrapper that swaps `set_high`/`set_low`. Polarity is
+    expressed at the pin (where the physical wiring lives), so
+    `SimpleLed` stays polarity-agnostic and every other board's code
+    path is byte-for-byte unchanged.
+  - Classic T-Beam now constructs its LED as
+    `SimpleLed(InvertedPin(led_pin))` with pin init at `Level::High`
+    (dark at boot).
+
+## [1.3.0] - 2026-04-23
+
+### Added
+
+- LilyGo T-Beam S3 Supreme board support (ESP32-S3 + SX1262 + SH1106
+  OLED + AXP2101 PMIC, native USB-C).
+  - Pin map verified against MeshCore's
+    `variants/lilygo_tbeam_supreme_SX1262`.
+  - New `src/driver/axp.rs` module with an AXP2101 init sequence
+    (ALDO3 = 3.3 V LoRa, ALDO1 = 3.3 V OLED). The PMIC gates LoRa and
+    display power — without it the SX1262 never responds on SPI.
+  - PMIC lives on a dedicated I²C1 bus (SDA=42, SCL=41), separate
+    from the SH1106 on I²C0 (SDA=17, SCL=18). I²C1 is used blocking
+    for a one-shot init and then dropped.
+  - TCXO driven at 1.6 V via DIO3 (MeshCore uses the same).
+- LilyGo T-Beam (classic) board support (ESP32 + SX1276 + SSD1306
+  OLED + AXP192 PMIC, CP2102 USB-UART bridge). This is the first
+  board in the firmware on classic ESP32 (non-S3) and the first on
+  the SX127x radio family.
+  - Pin map verified against MeshCore's `variants/lilygo_tbeam_SX1276`.
+  - New `src/hal/esp32.rs` (classic-ESP32 MCU primitives, peripheral
+    DMA via `DMA_SPI2`) and `src/board/esp32.rs` (SX1276 radio helper
+    + SSD1306 display pipe).
+  - AXP192 init added to `src/driver/axp.rs`: DCDC1 = 3.3 V for the
+    OLED, LDO2 = 3.3 V for the SX1276 PA_BOOST rail. Shares the
+    OLED I²C bus (SDA=21, SCL=22); the I²C instance is built in
+    blocking mode for PMIC init and converted to async for the
+    display task.
+  - SX127x support via lora-phy 3's `Sx127x<Sx1276>` +
+    `GenericSx127xInterfaceVariant` (DIO0 as the sole IRQ; no
+    BUSY line on SX127x). XTAL clocked (no TCXO), `tx_boost = true`
+    for the PA_BOOST path.
+  - `LoRaBoard` trait gains `supported_sf_bitmap()` and
+    `supported_bw_bitmap()` methods with SX126x defaults
+    (`0x1FE0`, `0x03FF`). T-Beam classic overrides SF to `0x1FC0`
+    (SF6–SF12) — the SX1276 has no SF5.
+  - `radio_chip_id()` reports `0x0011` (`RadioChipId::Sx1276`) and
+    `freq_range_hz()` widens to 137 MHz–1020 MHz per the SX1276
+    datasheet.
+
+### Changed
+
+- `Cargo.toml`: the `esp32s3` chip feature has been moved out of
+  the `esp-hal` / `esp-rtos` / `esp-backtrace` / `esp-println`
+  dependency lines and into each ESP board's feature list (as
+  `esp-hal/esp32s3`, etc.). This lets `lilygo_tbeam` select the
+  classic `esp32` chip flavour from the same dependency set.
+
+## [1.2.1] - 2026-04-23
+
+### Fixed
+
+- **Radio no longer drops to Idle mid-RX-session on transient failures.**
+  Extends the v1.1.0 invariant ("`SET_CONFIG` during RX auto-re-arms")
+  to all failure paths that can occur while a client has RX active:
+  - `Receiving.on(RxFailed) => Idle` now transitions to `ResumingRx`
+    instead of `Idle`. A transient `next_packet` error re-arms the chip
+    rather than ending the RX session.
+  - `TransmittingFromRx.on(TransmitFailed) => Idle` now transitions to
+    `ResumingRx`. TX failure during an active RX session returns
+    `TX_FAILED` to the caller and resumes RX, matching the shape of the
+    adjacent `ChannelBusy` handler.
+  - `ResumingRx.on(StartRxFailed) => Idle` is now a bounded retry
+    (5 × 25 ms backoff via a new `bump_resume_retries` action and a
+    `ResumeRxRetry` / `ResumeRxExhausted` pair of internal events).
+    The chip only lands in `Idle` after exhausting the retry budget —
+    which means it's genuinely wedged and needs reconfiguring.
+
+  Visible effect: the OLED dashboard no longer bounces to Splash when
+  `ai-bot` (or any other client that TXes while RX is running) sends a
+  packet. Previously any of the three transitions above would fire
+  `RadioEvent::Idle`, which the display uses as its `Dashboard → Splash`
+  trigger; the radio would land in `Idle` with no client aware enough
+  to re-send `RX_START`, stranding the dashboard until the session was
+  manually torn down and restarted.
+
+- Removed `announce_rx_failed` helper action: its only purpose was
+  emitting `RadioEvent::Idle` on the now-deleted `Receiving.on(RxFailed)
+  => Idle` edge. No replacement needed — `ResumingRx` handles recovery
+  silently.
+
 ## [1.2.0] - 2026-04-22

 ### Added
@@ -3,7 +3,7 @@ members = ["."]

 [package]
 name = "donglora"
-version = "1.2.0"
+version = "1.5.2"
 edition = "2021"
 build = "build.rs"
 authors = ["Stephen Waits <steve@waits.net>"]
@@ -14,12 +14,10 @@ homepage = "https://github.com/donglora/firmware"
 keywords = ["lora", "radio", "embedded", "usb", "firmware"]
 categories = ["embedded", "hardware-support", "no-std"]

-# NOTE: esp-rtos patched from GitHub main (see [patch.crates-io] below).
-# Remove patches once esp-rtos publishes with embassy-executor 0.10 support.
 [dependencies]
 cfg-if = "1.0"
 critical-section = "1.2"
-defmt = "1.0"
+defmt = "0.3"
 embedded-hal = "1.0"
 embedded-hal-async = "1.0"
 embassy-embedded-hal = "0.6"
@@ -31,50 +29,81 @@ embassy-usb-driver = "0.2"
 ucobs = { version = "0.3", features = ["legacy-msrv"] }
 heapless = "0.9"
 donglora-protocol = "1"
-hsmc = { version = "0.2", default-features = false, features = ["embassy"] }
-lora-phy = "3.0"
-portable-atomic = { version = "1", optional = true, default-features = false, features = ["critical-section"] }
+hsmc = { version = "0.6", default-features = false, features = ["embassy", "trace-defmt"] }
+# Fork branch carrying CAD IRQ-clear / standby-after-CAD fixes awaiting upstream PRs.
+# Switch back to crates.io once changes are upstreamed.
+lora-phy = { git = "https://github.com/swaits/lora-rs.git", branch = "fixed", features = ["defmt-03"] }
+portable-atomic = { version = "1", default-features = false, features = ["critical-section"] }
 static_cell = "2.1"

 # Display rendering
 display-interface = "0.5"
 embedded-graphics = "0.8"
 ssd1306 = { version = "0.10", features = ["async"] }
+# T114 ST7789 TFT (color, async SPI). Optional — only pulled in by the
+# heltec_mesh_node_t114 feature. Mono OLED boards keep their existing
+# display-interface + ssd1306/sh1106 stack and don't pay for these.
+#
+# `lcd-async` is an async fork of mipidsi: same model/builder shape but
+# `init()` and pixel writes are `async fn`s. Combined with embassy-nrf's
+# DMA-backed async Spim, the dashboard repaint yields the executor for
+# the duration of the SPI transfer instead of busy-looping for ~65 ms,
+# so the radio task isn't starved.
+#
+# embedded-hal-bus needs the `async` feature for `ExclusiveDevice` to
+# implement `embedded_hal_async::spi::SpiDevice` (in addition to the
+# blocking impl).
+lcd-async = { version = "0.1", optional = true }
+embedded-hal-bus = { version = "0.3", optional = true, features = ["async"] }

 # Async IO traits and combinators
 embedded-io-async = "0.7"
 embassy-futures = "0.1"

-# ESP32-S3 (Heltec V3) — requires esp toolchain (espup)
-esp-backtrace = { version = "0.18", optional = true, features = [
-  "esp32s3",
+# Xtensa ESP crates — requires esp toolchain (espup). The chip feature
+# (esp32 / esp32s3) is selected per board via the board-level feature flag
+# below, so the same dep lines support both classic ESP32 and ESP32-S3.
+esp-backtrace = { version = "0.19", optional = true, features = [
  "panic-handler",
  "defmt",
 ] }
-esp-hal = { version = "1.0", optional = true, features = [
-  "esp32s3",
+esp-hal = { version = "1.1", optional = true, features = [
  "unstable",
 ] }
-esp-println = { version = "0.16", optional = true, features = [
-  "esp32s3",
+esp-println = { version = "0.17", optional = true, features = [
  "defmt-espflash",
 ] }
-esp-rtos = { version = "0.2", optional = true, features = [
-  "esp32s3",
+esp-rtos = { version = "0.3", optional = true, features = [
  "embassy",
 ] }
+# Emits the IDF app descriptor (`.flash.appdesc`) that espflash v4
+# requires in every ESP binary. The chip subfeature is selected per
+# board below alongside the other esp-* chip features.
+esp-bootloader-esp-idf = { version = "0.5", optional = true, features = [
+  "defmt",
+] }

 # nRF52840 (RAK 4631)
 cortex-m = { version = "0.7", optional = true, features = [
  "critical-section-single-core",
 ] }
 cortex-m-rt = { version = "0.7", optional = true }
-defmt-rtt = { version = "1.0", optional = true }
+defmt-rtt = { version = "0.4", optional = true }
 embassy-nrf = { version = "0.10", optional = true, features = [
  "nrf52840",
  "gpiote",
  "time-driver-rtc1",
  "defmt",
+  # UICR pin-config flags — must match what the Adafruit nRF52 bootloader
+  # actually programmed into UICR on this board. Verified empirically on
+  # RAK4631 via `probe-rs read b32 0x10001200 4`:
+  #   PSELRESET[0/1] = 0x12  (P0.18 connected as RESET — NOT gpio)
+  #   NFCPINS        = 0xFFFFFFFE  (bit 0 = 0 → NFC pins as GPIO)
+  # So `nfc-pins-as-gpio` matches; `reset-pin-as-gpio` would NOT match
+  # (would request GPIO when UICR has RESET enabled). The bootloader
+  # uses NRESET for its physical button-reset path, so leaving the pin
+  # as RESET is the right state.
+  "nfc-pins-as-gpio",
 ] }
 panic-probe = { version = "1.0", optional = true, features = ["print-defmt"] }

@@ -90,13 +119,22 @@ minijinja = "2.18"
 owo-colors = "4.3"

 [features]
-# The `embassy` feature gates the async-actions codepath inside the `hsmc`
-# statechart macro. Its `#[cfg(feature = "embassy")]` attributes are
-# evaluated in *this* crate's context (a proc-macro cfg quirk), so every
-# board feature must enable it. `tokio` is declared only to silence the
-# macro's `#[cfg(feature = "tokio")]` checks.
+# Bridge features for hsmc's macro-expanded `#[cfg(feature = "...")]`
+# attributes. Macros expand into the *call-site* crate, so any cfg the
+# macro emits is evaluated against THIS crate's feature set, not hsmc's.
+# That means enabling `hsmc/embassy` or `hsmc/trace-defmt` via the dep
+# only activates them inside hsmc's own compilation — for the cfg gates
+# inside expanded macro bodies to fire here, we need same-named features
+# in this Cargo.toml. `tokio` is declared just to silence the macro's
+# `#[cfg(feature = "tokio")]` checks.
+#
+# `trace-defmt` must be in every board feature so chart trace lines
+# (entries, exits, transitions, etc.) actually compile in. Without it,
+# hsmc 0.4's `__chart_observe!` macro expands to nothing for the defmt
+# arm and you get silent statecharts.
 embassy = []
 tokio = []
+trace-defmt = []
 # When enabled, replaces the display task with a LED-based diagnostic
 # blinker driven by `crate::debug_blink::CHECKPOINT`. Used for diagnosing
 # the firmware on UART-only boards where defmt output would corrupt the
@@ -104,36 +142,110 @@ tokio = []
 # a human watches the pattern and reports N to determine where execution
 # reached / stopped.
 debug-checkpoint = []
+# NOTE: chart auto-tracing in hsmc 0.4 emits `__chart_observe!` calls
+# whose defmt arm is gated on `#[cfg(feature = "trace-defmt")]`. That
+# cfg is evaluated against THIS crate (proc-macro cfg quirk above), so
+# every board feature includes `trace-defmt` to keep the arm live. The
+# `trace;` keyword in `statechart!` blocks is deprecated in 0.4 and
+# no longer gates emission. Whether trace lines actually emit at
+# runtime is still controlled by defmt's standard compile-time level
+# filter (`DEFMT_LOG` env var) -- release builds with `DEFMT_LOG`
+# unset compile the calls out to nothing.
+# When enabled, the SH1106 OLED driver emits a defmt::info! line for
+# every I2C transaction it issues — bytes, lengths, addresses. Used to
+# debug the embassy_nrf::twim assertion panic at twim.rs:541 (cannot
+# happen via the documented call path; instrumenting the SH1106 path
+# captures the actual transaction sequence preceding the panic so we
+# can root-cause). Off by default; opt in via
+# `just flash-attach rak_wisblock_4631 debug-twim`.
+debug-twim = []
 heltec_v3 = [
  "embassy",
+  "trace-defmt",
  "dep:esp-backtrace",
+  "dep:esp-bootloader-esp-idf",
  "dep:esp-hal",
  "dep:esp-println",
  "dep:esp-rtos",
+  "esp-backtrace/esp32s3",
+  "esp-bootloader-esp-idf/esp32s3",
+  "esp-hal/esp32s3",
+  "esp-println/esp32s3",
+  "esp-rtos/esp32s3",
 ]
 heltec_v3_uart = [
  "embassy",
+  "trace-defmt",
  "dep:esp-backtrace",
+  "dep:esp-bootloader-esp-idf",
  "dep:esp-hal",
  "dep:esp-println",
  "dep:esp-rtos",
+  "esp-backtrace/esp32s3",
+  "esp-bootloader-esp-idf/esp32s3",
+  "esp-hal/esp32s3",
+  "esp-println/esp32s3",
+  "esp-rtos/esp32s3",
 ]
 heltec_v4 = [
  "embassy",
+  "trace-defmt",
  "dep:esp-backtrace",
+  "dep:esp-bootloader-esp-idf",
  "dep:esp-hal",
  "dep:esp-println",
  "dep:esp-rtos",
+  "esp-backtrace/esp32s3",
+  "esp-bootloader-esp-idf/esp32s3",
+  "esp-hal/esp32s3",
+  "esp-println/esp32s3",
+  "esp-rtos/esp32s3",
 ]
 elecrow_thinknode_m2 = [
  "embassy",
+  "trace-defmt",
  "dep:esp-backtrace",
+  "dep:esp-bootloader-esp-idf",
  "dep:esp-hal",
  "dep:esp-println",
  "dep:esp-rtos",
+  "esp-backtrace/esp32s3",
+  "esp-bootloader-esp-idf/esp32s3",
+  "esp-hal/esp32s3",
+  "esp-println/esp32s3",
+  "esp-rtos/esp32s3",
+]
+lilygo_tbeam_supreme = [
+  "embassy",
+  "trace-defmt",
+  "dep:esp-backtrace",
+  "dep:esp-bootloader-esp-idf",
+  "dep:esp-hal",
+  "dep:esp-println",
+  "dep:esp-rtos",
+  "esp-backtrace/esp32s3",
+  "esp-bootloader-esp-idf/esp32s3",
+  "esp-hal/esp32s3",
+  "esp-println/esp32s3",
+  "esp-rtos/esp32s3",
+]
+lilygo_tbeam = [
+  "embassy",
+  "trace-defmt",
+  "dep:esp-backtrace",
+  "dep:esp-bootloader-esp-idf",
+  "dep:esp-hal",
+  "dep:esp-println",
+  "dep:esp-rtos",
+  "esp-backtrace/esp32",
+  "esp-bootloader-esp-idf/esp32",
+  "esp-hal/esp32",
+  "esp-println/esp32",
+  "esp-rtos/esp32",
 ]
 rak_wisblock_4631 = [
  "embassy",
+  "trace-defmt",
  "dep:cortex-m",
  "dep:cortex-m-rt",
  "cortex-m-rt/set-vtor",
@@ -145,6 +257,7 @@ rak_wisblock_4631 = [
 ]
 wio_tracker_l1 = [
  "embassy",
+  "trace-defmt",
  "dep:cortex-m",
  "dep:cortex-m-rt",
  "cortex-m-rt/set-vtor",
@@ -154,27 +267,42 @@ wio_tracker_l1 = [
  "embassy-executor/platform-cortex-m",
  "embassy-executor/executor-thread",
 ]
+heltec_mesh_node_t114 = [
+  "embassy",
+  "trace-defmt",
+  "dep:cortex-m",
+  "dep:cortex-m-rt",
+  "cortex-m-rt/set-vtor",
+  "dep:defmt-rtt",
+  "dep:embassy-nrf",
+  "dep:panic-probe",
+  "dep:lcd-async",
+  "dep:embedded-hal-bus",
+  "embassy-executor/platform-cortex-m",
+  "embassy-executor/executor-thread",
+]
 waveshare_rp2040_lora = [
  "embassy",
+  "trace-defmt",
  "dep:cortex-m",
  "dep:cortex-m-rt",
  "dep:defmt-rtt",
  "dep:embassy-rp",
  "dep:panic-probe",
-  "dep:portable-atomic",
  "embassy-executor/platform-cortex-m",
  "embassy-executor/executor-thread",
 ]

-# REVISIT: esp-rtos 0.2.0 on crates.io pins embassy-executor ^0.9. The
-# esp-rs/esp-hal main branch already supports 0.10. Remove these patches once
-# esp-rtos publishes a release with embassy-executor 0.10 support. Track:
-#   https://github.com/esp-rs/esp-hal/tree/main/esp-rtos
-[patch.crates-io]
-esp-hal       = { git = "https://github.com/esp-rs/esp-hal.git", branch = "main" }
-esp-rtos      = { git = "https://github.com/esp-rs/esp-hal.git", branch = "main" }
-esp-backtrace = { git = "https://github.com/esp-rs/esp-hal.git", branch = "main" }
-esp-println   = { git = "https://github.com/esp-rs/esp-hal.git", branch = "main" }
+[lints.rust]
+# hsmc 0.3's `statechart!` macro emits `#[cfg(feature = "journal")]`
+# attributes (and others). check-cfg evaluates those in the CALLER's
+# crate context, so unless donglora declares the same feature names
+# (we don't — they're hsmc's, not ours), rustc lints them. Per hsmc's
+# README, the documented fix is to allow the lint with an explicit
+# check-cfg list so other unexpected cfgs still surface as warnings.
+unexpected_cfgs = { level = "allow", check-cfg = [
+    'cfg(feature, values("tokio", "embassy", "journal", "trace-defmt", "trace-log", "trace-tracing"))',
+] }

 [lints.clippy]
 undocumented_unsafe_blocks = "deny"
@@ -184,4 +312,8 @@ codegen-units = 1
 lto = "fat"
 opt-level = 3     # "s"/"z" break Xtensa (l32r literal range exceeded)
 panic = "abort"
-strip = true
+# `strip = true` was killing defmt's `_defmt_version_` / `_defmt_encoding_`
+# symbols, breaking RTT log decoding via probe-rs. Keep symbols + DWARF
+# so probe-rs can show source locations for log lines.
+strip = false
+debug = 2
@@ -20,10 +20,13 @@ All commands are run from the `firmware/` directory.

 | Board | Feature | MCU | Radio | USB | Target |
 |-------|---------|-----|-------|-----|--------|
+| Heltec Mesh Node T114 | `heltec_mesh_node_t114` | nRF52840 | SX1262 | Native CDC-ACM | thumbv7em-none-eabihf |
 | Heltec V3 | `heltec_v3` | ESP32-S3 | SX1262 | Native CDC-ACM | xtensa-esp32s3-none-elf |
 | Heltec V3 (UART) | `heltec_v3_uart` | ESP32-S3 | SX1262 | CP2102 bridge | xtensa-esp32s3-none-elf |
 | Heltec V4 | `heltec_v4` | ESP32-S3 | SX1262 | Native CDC-ACM | xtensa-esp32s3-none-elf |
 | ELECROW ThinkNode-M2 | `elecrow_thinknode_m2` | ESP32-S3 | SX1262 | CP2102 bridge | xtensa-esp32s3-none-elf |
+| LilyGo T-Beam | `lilygo_tbeam` | ESP32 | SX1276 | CP2102 bridge | xtensa-esp32-none-elf |
+| LilyGo T-Beam S3 Supreme | `lilygo_tbeam_supreme` | ESP32-S3 | SX1262 | Native CDC-ACM | xtensa-esp32s3-none-elf |
 | RAK WisBlock 4631 | `rak_wisblock_4631` | nRF52840 | SX1262 | Native CDC-ACM | thumbv7em-none-eabihf |
 | Waveshare RP2040-LoRa | `waveshare_rp2040_lora` | RP2040 | SX1262 | Native CDC-ACM | thumbv6m-none-eabi |
 | Wio Tracker L1 | `wio_tracker_l1` | nRF52840 | SX1262 | Native CDC-ACM | thumbv7em-none-eabihf |
@@ -60,4 +63,8 @@ See [src/board/PORTING.md](src/board/PORTING.md).

 ## Protocol

-See [PROTOCOL.md](PROTOCOL.md) for the complete wire format specification.
+See [PROTOCOL.md](https://github.com/donglora/protocol-rs/blob/main/PROTOCOL.md)
+in the [donglora-protocol](https://github.com/donglora/protocol-rs) repo
+(crates.io: [`donglora-protocol`](https://crates.io/crates/donglora-protocol))
+for the complete wire format specification — that is the canonical home;
+this firmware just consumes it.
@@ -1,4 +1,37 @@
- LED blinking on TX/RX? colored?
- publish new client, mux, bridge (updates in client for UART crap)
- split out mux and client repos
- move to GH organization
+# Firmware TODO List
+
+## `lora-phy` fix: drop fork pin once PRs #428 / #431 / #432 merge + release
+
+Upstream PRs (all open):
+
+- [#428 — *phy: add pre-command BUSY checks per Semtech
+  datasheets*](https://github.com/lora-rs/lora-rs/pull/428) (sx126x):
+  pre-command BUSY check + standby/IRQ-clear hygiene around CAD.
+- [#431 — *phy: sx127x: clear stale IRQ flags in do_rx before mode
+  change*](https://github.com/lora-rs/lora-rs/pull/431).
+- [#432 — *phy: sx127x: clear stale IRQ flags before reconfiguring DIO
+  mapping in set_irq_params*](https://github.com/lora-rs/lora-rs/pull/432).
+
+Fork branch we ship from:
+[`swaits/lora-rs @ fixed`](https://github.com/swaits/lora-rs/tree/fixed)
+— a merge of all three fix branches kept up-to-date with upstream
+`main`.
+
+Firmware consumes the fixes via a direct `git` dependency in
+`Cargo.toml`:
+
+```toml
+lora-phy = { git = "https://github.com/swaits/lora-rs.git", branch = "fixed", features = ["defmt-03"] }
+```
+
+When all three PRs merge and a `lora-phy` release ships on crates.io
+that contains them, switch this line back to a normal
+`lora-phy = "X.Y"` crates.io version and drop the explanatory comment
+block above it.
+
+Hardware impact: large stability gain on every board — the sx126x
+BUSY-race fix lands on every nRF/RP2040 board, and the sx127x IRQ-clear
+fixes unblock TBeam classic in particular. Hardware-verified on Wio
+Tracker L1 (sx126x): 20/20 clean-boot TX after the fix (vs ~50%
+before). LilyGo T-Beam classic (sx127x): TX confirmed working
+2026-04-30 on the post-esp-hal-1.1 build.
@@ -108,19 +108,31 @@ fn main() {
    println!("cargo:rerun-if-changed=src/board/mod.rs.j2");
    println!("cargo:rerun-if-changed={}", board_dir);

-    // cortex-m-rt's link.x does `INCLUDE memory.x`. Copy the correct layout
-    // into OUT_DIR based on the target MCU family.
+    // cortex-m-rt's link.x does `INCLUDE memory.x`. Resolve the layout
+    // in two steps:
+    //   1. Per-board override: `ld/{board}-memory.x` if it exists.
+    //   2. MCU-family default by target triple.
+    // The override path is for boards that deviate from the family
+    // default (e.g. WIO Tracker L1 currently has no SoftDevice in flash
+    // and needs ORIGIN=0x1000 instead of the SD-aware 0x26000). Drop
+    // the per-board file once the layout matches the family default.
    let target = std::env::var("TARGET").unwrap_or_default();
-    let memory_x = match target.as_str() {
-        "thumbv7em-none-eabihf" => Some("ld/nrf52840-memory.x"),
-        "thumbv6m-none-eabi" => Some("ld/rp2040-memory.x"),
-        _ => None,
+    let board_specific = format!("ld/{}-memory.x", enabled[0]);
+    let memory_x: Option<String> = if std::path::Path::new(&board_specific).exists() {
+        Some(board_specific.clone())
+    } else {
+        match target.as_str() {
+            "thumbv7em-none-eabihf" => Some("ld/nrf52840-memory.x".to_string()),
+            "thumbv6m-none-eabi" => Some("ld/rp2040-memory.x".to_string()),
+            _ => None,
+        }
    };
    if let Some(src) = memory_x {
        let out_dir = std::env::var("OUT_DIR").unwrap();
-        fs::copy(src, format!("{out_dir}/memory.x")).expect("failed to copy memory.x");
+        fs::copy(&src, format!("{out_dir}/memory.x")).expect("failed to copy memory.x");
        println!("cargo:rustc-link-search={out_dir}");
    }
    println!("cargo:rerun-if-changed=ld/nrf52840-memory.x");
    println!("cargo:rerun-if-changed=ld/rp2040-memory.x");
+    println!("cargo:rerun-if-changed={}", board_specific);
 }
@@ -0,0 +1,6 @@
+workers = ["app.routes"]
+
+[settings]
+cache = ".script"
+address = "127.0.0.1"
+port = 3500
@@ -1,41 +1,30 @@
-set shell := ["bash", "-c"]
-
-# Board definitions: feature target chip
-# Xtensa targets use the self-contained esp toolchain (espup-installed) with
-# `-Zbuild-std=core,alloc`. Using `+esp` rather than `+nightly` keeps the
-# compiler and rust-src versions aligned — the public nightly drifts ahead of
-# the esp fork and breaks core-stdlib compilation otherwise.
-# Tool versions are pinned in mise.toml; run `just setup` to install everything.
-heltec_v3      := "heltec_v3 xtensa-esp32s3-none-elf esp32s3"
-heltec_v3_uart := "heltec_v3_uart xtensa-esp32s3-none-elf esp32s3"
-heltec_v4      := "heltec_v4 xtensa-esp32s3-none-elf esp32s3"
-elecrow_thinknode_m2 := "elecrow_thinknode_m2 xtensa-esp32s3-none-elf esp32s3"
-rak_wisblock_4631  := "rak_wisblock_4631 thumbv7em-none-eabihf nRF52840_xxAA"
-wio_tracker_l1     := "wio_tracker_l1 thumbv7em-none-eabihf nRF52840_xxAA"
-waveshare_rp2040_lora := "waveshare_rp2040_lora thumbv6m-none-eabi rp2040"
+# Run every recipe with mise's tool versions active — so `just` invocations
+# of cargo, espflash, rust-objcopy, etc. always resolve to the pinned
+# versions in mise.toml, even if the user has a different version elsewhere
+# on PATH (e.g. a stray `cargo install espflash`).
+set shell := ["mise", "exec", "--", "sh", "-c"]

 builds_dir := "builds"
 version := `sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml`

-# All known boards
-boards := "heltec_v3 heltec_v3_uart heltec_v4 elecrow_thinknode_m2 rak_wisblock_4631 waveshare_rp2040_lora wio_tracker_l1"
+# All known boards. ADD A NEW BOARD HERE and in the `_info` case below.
+#
+# Board metadata ("feature target chip") lives in the `_info` recipe —
+# Xtensa targets are built with `+esp` + `-Zbuild-std=core,alloc` (the
+# self-contained esp toolchain ships its own rust-src; the public
+# nightly drifts ahead and breaks core-stdlib compilation).
+boards := "heltec_mesh_node_t114 heltec_v3 heltec_v3_uart heltec_v4 elecrow_thinknode_m2 lilygo_tbeam lilygo_tbeam_supreme rak_wisblock_4631 waveshare_rp2040_lora wio_tracker_l1"

 # Install all required tools and toolchains
 setup:
    mise trust --yes
    mise install
-    @# ESP Xtensa toolchain (not managed by mise)
+    @# ESP Xtensa toolchain — installed via the `esp-install` mise task
+    @# (which pins versions to match mise.toml's [env] paths).
    @if ! rustup toolchain list | grep -q "^esp"; then \
-        echo "ESP toolchain not found, installing via espup (this may take a while)..."; \
-        espup install || { echo "error: espup install failed" >&2; exit 1; }; \
+        echo "ESP toolchain not found, installing via mise task (this may take a while)..."; \
+        mise run esp-install || { echo "error: esp-install task failed" >&2; exit 1; }; \
    fi
-    @# nightly rust-src for -Zbuild-std
-    @if ! rustup component list --toolchain nightly --installed 2>/dev/null | grep -q "^rust-src"; then \
-        rustup component add rust-src --toolchain nightly; \
-    fi
-    @# ARM targets
-    @rustup target list --installed | grep -q "^thumbv6m-none-eabi$" || rustup target add thumbv6m-none-eabi
-    @rustup target list --installed | grep -q "^thumbv7em-none-eabihf$" || rustup target add thumbv7em-none-eabihf

 # Build release firmware for all boards, installing toolchains as needed
 build-all:
@@ -65,16 +54,20 @@ check-all:
 check board:
    @just _cargo {{board}} "clippy --release" "-- -D warnings"

-# Build release firmware and copy to builds/ with a readable name
-build board profile="release":
-    @just _cargo {{board}} "build --{{profile}}"
+# Build release firmware and copy to builds/ with a readable name.
+# `extra_features` (comma-separated) is appended to the board feature,
+# e.g. `just build wio_tracker_l1 release debug-checkpoint`.
+build board profile="release" extra_features="":
+    @just _cargo {{board}} "build --{{profile}}" "" "{{extra_features}}"
    @just _copy_firmware {{board}} {{profile}}

-# Build and flash a board (espflash for Xtensa, UF2 DFU for ARM)
-flash board:
+# Build and flash a board (espflash for Xtensa, UF2 DFU for ARM).
+# `extra_features` is passed through to the build, e.g.
+# `just flash wio_tracker_l1 debug-checkpoint`.
+flash board extra_features="":
    @just _ensure_tools
-    @just build {{board}} release
-    @read -r feat target chip <<< "$(just _info {{board}})"; \
+    @just build {{board}} release "{{extra_features}}"
+    @set -- $(just _info {{board}}); feat=$1; target=$2; chip=$3; \
    case "$target" in \
        xtensa-*) \
            port=$(just _find_port "303a:1001" "1209:5741" "10c4:ea60" "1a86:7522" "1a86:7523"); \
@@ -88,13 +81,50 @@ flash board:
        *) just _flash_uf2 {{board}} ;; \
    esac

-# Flash ARM board via debug probe (requires J-Link or similar)
-flash-probe board:
+# Flash ARM board via debug probe (requires J-Link or similar).
+# `extra_features` is passed through to the build.
+# Sets DEFMT_LOG at build time so defmt::info!/warn!/error! are actually
+# compiled in (default filter is ERROR-only — strips info logs).
+# `embassy_usb=error` silences the benign Linux modem-manager
+# `SET_INTERFACE: alt setting out of range` WARN that fires once per
+# enumeration; it's a normal STALL response (correct USB behavior),
+# the WARN is just embassy_usb noise. Other crates inherit the `info`
+# default so chart traces, our own info!/warn!/error! all still fire.
+flash-probe board extra_features="":
    @just _ensure_tools
-    @just build {{board}} release
-    @read -r feat target chip <<< "$(just _info {{board}})"; \
+    @DEFMT_LOG=info,embassy_usb=error just build {{board}} release "{{extra_features}}"
+    @set -- $(just _info {{board}}); feat=$1; target=$2; chip=$3; \
    probe-rs run --chip $chip "{{builds_dir}}/donglora-{{board}}-v{{version}}.elf"

+# UF2-flash via the bootloader, then probe-rs attach for RTT log streaming.
+# Required on boards (e.g. RAK4631) where the bootloader gates the app
+# behind a "valid app flag" in its settings page that only the bootloader
+# itself can set — `probe-rs run`'s direct SWD writes bypass that flag and
+# leave the bootloader stuck in DFU mode. UF2 path goes through the
+# bootloader, sets the flag, then we attach for RTT (no reset, no reflash).
+flash-attach board extra_features="":
+    @just _ensure_tools
+    @DEFMT_LOG=info,embassy_usb=error just build {{board}} release "{{extra_features}}"
+    @just _flash_uf2 {{board}}
+    @set -- $(just _info {{board}}); feat=$1; target=$2; chip=$3; \
+    sleep 1; \
+    probe-rs attach --chip $chip --no-catch-reset \
+      "{{builds_dir}}/donglora-{{board}}-v{{version}}.elf"
+
+# Attach probe-rs for live RTT/defmt streaming WITHOUT flashing or
+# resetting the chip. Logs are tee'd to a UTC-timestamped file in /tmp
+# so soak captures don't clobber each other across runs. Use this with
+# the dongle already running the desired firmware (flash via `just flash`
+# or `just flash-attach` first).
+attach board:
+    @just _ensure_tools
+    @set -- $(just _info {{board}}); feat=$1; target=$2; chip=$3; \
+    log="/tmp/donglora-soak-$(date -u +%Y%m%dT%H%M%SZ).log"; \
+    echo "Logging to $log"; \
+    probe-rs attach --chip $chip --no-catch-reset \
+      "{{builds_dir}}/donglora-{{board}}-v{{version}}.elf" 2>&1 \
+      | tee "$log"
+
 # Show binary size for a release build
 size board:
    @just _cargo {{board}} "size --release"
@@ -114,16 +144,17 @@ outdated:
 _ensure_tools:
    @mise trust --yes . 2>/dev/null; mise install --quiet

-# Run a cargo command for a board.
+# Run a cargo command for a board, optionally with extra Cargo features
+# (comma-separated, e.g. "debug-checkpoint").
 # Xtensa: esp toolchain (cargo + rustc + rust-src together) + -Zbuild-std=core
 [private]
-_cargo board cmd extra_args="":
+_cargo board cmd extra_args="" extra_features="":
    @just _ensure_tools
-    @read -r feat target chip <<< "$(just _info {{board}})"; \
+    @set -- $(just _info {{board}}); feat=$1; target=$2; chip=$3; \
+    [ -n "{{extra_features}}" ] && feat="$feat,{{extra_features}}"; \
    extra=""; buildstd=""; \
    case "$target" in xtensa-*) \
        just _require_esp_toolchain; \
-        [ -f "$HOME/export-esp.sh" ] && . "$HOME/export-esp.sh"; \
        extra="+esp"; buildstd="-Zbuild-std=core,alloc";; \
    esac; \
    cargo $extra {{cmd}} --target "$target" --features "$feat" $buildstd {{extra_args}}
@@ -131,21 +162,23 @@ _cargo board cmd extra_args="":
 # Ensure a board's toolchain is available, auto-installing if needed
 [private]
 _can_build board:
-    @read -r feat target chip <<< "$(just _info {{board}})"; \
+    @set -- $(just _info {{board}}); feat=$1; target=$2; chip=$3; \
    case "$target" in \
        xtensa-*) just _require_esp_toolchain ;; \
        *) rustup target list --installed | grep -q "^$target$" || rustup target add "$target" ;; \
    esac

-# Ensure the ESP Xtensa toolchain is installed (espup installed via mise).
-# The esp toolchain ships with its own cargo, rustc, and rust-src — no extra
+# Ensure the ESP Xtensa toolchain is installed. The actual install is
+# delegated to the `esp-install` mise task so the version pin lives in
+# mise.toml alongside the matching [env] PATH/LIBCLANG_PATH entries.
+# The esp toolchain ships its own cargo, rustc, and rust-src — no extra
 # components are needed on top.
 [private]
 _require_esp_toolchain:
    @just _ensure_tools
    @if ! rustup toolchain list | grep -q "^esp"; then \
-        echo "ESP toolchain not found, installing via espup (this may take a while)..." >&2; \
-        espup install || { echo "error: espup install failed" >&2; exit 1; }; \
+        echo "ESP toolchain not found, installing via mise task (this may take a while)..." >&2; \
+        mise run esp-install || { echo "error: esp-install task failed" >&2; exit 1; }; \
    fi

 # Find a serial port matching any of the given VID:PID pairs (checked in order)
@@ -167,25 +200,25 @@ _find_port +vid_pids:
 [private]
 _copy_firmware board profile:
    @mkdir -p {{builds_dir}}
-    @read -r feat target chip <<< "$(just _info {{board}})"; \
+    @set -- $(just _info {{board}}); feat=$1; target=$2; chip=$3; \
    src="target/$target/{{profile}}/donglora"; \
    dst="{{builds_dir}}/donglora-{{board}}-v{{version}}"; \
    if [ -f "$src" ]; then \
        cp "$src" "$dst.elf"; echo "→ $dst.elf"; \
        case "$target" in \
            xtensa-*) \
-                mise exec -- espflash save-image --chip "$chip" --merge --skip-padding "$src" "$dst.bin"; \
+                espflash save-image --chip "$chip" --merge --skip-padding "$src" "$dst.bin"; \
                echo "→ $dst.bin"; \
                ;; \
            thumbv6m-*) \
-                mise exec -- rust-objcopy -O ihex "$src" "$dst.hex"; \
-                mise exec -- cargo-hex-to-uf2 hex-to-uf2 --input-path "$dst.hex" --output-path "$dst.uf2" --family rp2040; \
+                rust-objcopy -O ihex "$src" "$dst.hex"; \
+                cargo-hex-to-uf2 hex-to-uf2 --input-path "$dst.hex" --output-path "$dst.uf2" --family rp2040; \
                rm "$dst.hex"; \
                echo "→ $dst.uf2"; \
                ;; \
            thumbv7em-*) \
-                mise exec -- rust-objcopy -O ihex "$src" "$dst.hex"; \
-                mise exec -- cargo-hex-to-uf2 hex-to-uf2 --input-path "$dst.hex" --output-path "$dst.uf2" --family nrf52840; \
+                rust-objcopy -O ihex "$src" "$dst.hex"; \
+                cargo-hex-to-uf2 hex-to-uf2 --input-path "$dst.hex" --output-path "$dst.uf2" --family nrf52840; \
                rm "$dst.hex"; \
                echo "→ $dst.uf2"; \
                ;; \
@@ -208,13 +241,20 @@ _flash_uf2 board:
    sync; \
    echo "Done — board will reboot automatically"

+# Single source of truth for per-board metadata: "feature target chip".
+# ADD A NEW BOARD HERE and in the `boards` list near the top of this file.
 [private]
 _info name:
-    @if [ "{{name}}" == "heltec_v3" ]; then echo "{{heltec_v3}}"; \
-     elif [ "{{name}}" == "heltec_v3_uart" ]; then echo "{{heltec_v3_uart}}"; \
-     elif [ "{{name}}" == "heltec_v4" ]; then echo "{{heltec_v4}}"; \
-     elif [ "{{name}}" == "elecrow_thinknode_m2" ]; then echo "{{elecrow_thinknode_m2}}"; \
-     elif [ "{{name}}" == "rak_wisblock_4631" ]; then echo "{{rak_wisblock_4631}}"; \
-     elif [ "{{name}}" == "waveshare_rp2040_lora" ]; then echo "{{waveshare_rp2040_lora}}"; \
-     elif [ "{{name}}" == "wio_tracker_l1" ]; then echo "{{wio_tracker_l1}}"; \
-     else echo "Unknown board: {{name}}" >&2; exit 1; fi
+    @case "{{name}}" in \
+        heltec_mesh_node_t114) echo "heltec_mesh_node_t114 thumbv7em-none-eabihf nRF52840_xxAA" ;; \
+        heltec_v3)             echo "heltec_v3 xtensa-esp32s3-none-elf esp32s3" ;; \
+        heltec_v3_uart)        echo "heltec_v3_uart xtensa-esp32s3-none-elf esp32s3" ;; \
+        heltec_v4)             echo "heltec_v4 xtensa-esp32s3-none-elf esp32s3" ;; \
+        elecrow_thinknode_m2)  echo "elecrow_thinknode_m2 xtensa-esp32s3-none-elf esp32s3" ;; \
+        lilygo_tbeam)          echo "lilygo_tbeam xtensa-esp32-none-elf esp32" ;; \
+        lilygo_tbeam_supreme)  echo "lilygo_tbeam_supreme xtensa-esp32s3-none-elf esp32s3" ;; \
+        rak_wisblock_4631)     echo "rak_wisblock_4631 thumbv7em-none-eabihf nRF52840_xxAA" ;; \
+        waveshare_rp2040_lora) echo "waveshare_rp2040_lora thumbv6m-none-eabi rp2040" ;; \
+        wio_tracker_l1)        echo "wio_tracker_l1 thumbv7em-none-eabihf nRF52840_xxAA" ;; \
+        *) echo "Unknown board: {{name}}" >&2; exit 1 ;; \
+    esac
@@ -1,16 +1,21 @@
-/* nRF52840 memory layout — Adafruit UF2 bootloader
+/* nRF52840 memory layout — Adafruit UF2 bootloader + s140 SoftDevice
 *
 *   0x00000 – 0x01000   MBR (Master Boot Record)
- *   0x01000 – 0xEA000   Application  ← we live here
+ *   0x01000 – 0x26000   s140 SoftDevice (dormant — we don't use BLE)
+ *   0x26000 – 0xEA000   Application  ← we live here
 *   0xEA000 – 0xF4000   Reserved (app data)
 *   0xF4000 – 0xFC000   UF2 Bootloader
 *   0xFF000 – 0x100000  Bootloader settings
 *
- * RAM: first 8 bytes reserved for MBR interrupt forwarding.
+ * RAM: first 8 bytes reserved for MBR interrupt forwarding. SoftDevice
+ * RAM (typically 0x20000008–0x20002000) is NOT reserved here because we
+ * never call sd_softdevice_enable — SD sits dormant in flash and never
+ * touches RAM. cortex-m-rt's set-vtor feature handles relocating VTOR
+ * to the app's vector table at 0x26000 at runtime.
 */

 MEMORY
 {
-  FLASH : ORIGIN = 0x00001000, LENGTH = 0xE9000
+  FLASH : ORIGIN = 0x00026000, LENGTH = 0xCE000
  RAM   : ORIGIN = 0x20000008, LENGTH = 255K
 }
@@ -0,0 +1,25 @@
+/* Wio Tracker L1 memory layout — UF2 bootloader, NO SoftDevice
+ *
+ *   0x00000 – 0x01000   MBR (Master Boot Record)
+ *   0x01000 – 0xEA000   Application  ← we live here (no SD present)
+ *   0xEA000 – 0xF4000   Reserved (app data)
+ *   0xF4000 – 0xFC000   UF2 Bootloader
+ *   0xFF000 – 0x100000  Bootloader settings
+ *
+ * Background: Seeed factory firmware ships s140 SoftDevice at
+ * 0x01000–0x26000, but our earlier UF2 flashes (with the original
+ * `ORIGIN = 0x1000` layout) silently overwrote that region. The WIO
+ * bootloader now reports `SoftDevice: not found`; until we restore
+ * s140 via SWD, the app must live at 0x1000 to match the bootloader's
+ * no-SD boot chain.
+ *
+ * Delete this file once SD is reinstalled — `build.rs` will then fall
+ * back to `ld/nrf52840-memory.x` (the SD-aware default at 0x26000)
+ * and the WIO matches every other nRF52840 board.
+ */
+
+MEMORY
+{
+  FLASH : ORIGIN = 0x00001000, LENGTH = 0xE9000
+  RAM   : ORIGIN = 0x20000008, LENGTH = 255K
+}
@@ -1,9 +1,46 @@
 [tools]
-rust = "1.94"
 just = "latest"

-"cargo:cargo-binutils" = "latest"   # `cargo size`, `cargo objdump`, etc.
-"cargo:cargo-hex-to-uf2" = "latest" # ELF → UF2 via Intel HEX for nRF52840 DFU
-"cargo:espup" = "0.16"
-"cargo:espflash" = "3"              # 4.x has broken nix dependency on current stable Rust
-"cargo:probe-rs-tools" = "0.31"
+# Cargo-installed tooling via mise's `cargo:` backend.
+"cargo:cargo-binutils" = "latest"   # rust-objcopy, rust-size
+"cargo:cargo-hex-to-uf2" = "latest" # ELF → UF2 for nRF52 / RP2040 DFU drives
+"cargo:espup" = "0.17.1"            # ESP Xtensa toolchain installer (pinned: [env] paths below match this version's defaults)
+"cargo:espflash" = "4"              # flash + save-image for ESP targets
+"cargo:probe-rs-tools" = "latest"   # debug-probe flash/run for ARM targets
+
+# Stable Rust + cross-compile targets. Targets land under $RUSTUP_HOME for
+# the pinned toolchain, so they're always available under `mise exec` — no
+# extra `rustup target add` step at setup time.
+#
+# Xtensa ESP targets are NOT listed here — they use the self-contained `esp`
+# toolchain populated by `mise run esp-install` (see [tasks] below). That
+# toolchain ships its own rust-src for `-Zbuild-std`.
+#
+# profile = "minimal" (just rustc, rust-std, cargo), "default" (adds rust-docs, rustfmt, clippy)
+#
+[tools.rust]
+version = "1.94"
+profile = "default"
+targets = "thumbv6m-none-eabi,thumbv7em-none-eabihf"
+
+# ESP Xtensa toolchain. `cargo:espup` above only installs the *installer*;
+# the actual rustc-esp + xtensa-esp-elf-gcc + esp-clang toolchains are
+# populated by `mise run esp-install` (or `just setup`).
+#
+# espup hardcodes its install root to ~/.rustup/toolchains/esp/ — there's
+# no --prefix or --install-dir flag — so the binaries necessarily live
+# there. The [env] block below pins the exact PATH and LIBCLANG_PATH so
+# every `mise exec` (which the justfile uses for `set shell`) resolves
+# the cross-toolchain without depending on espup's stray ~/export-esp.sh.
+#
+# Bumping versions: edit the version dirs in BOTH [tasks.esp-install] (so
+# espup installs the matching crosstool) AND [env] (so the path resolves).
+[env]
+_.path = [
+  "{{env.HOME}}/.rustup/toolchains/esp/xtensa-esp-elf/esp-15.2.0_20250920/xtensa-esp-elf/bin",
+]
+LIBCLANG_PATH = "{{env.HOME}}/.rustup/toolchains/esp/xtensa-esp32-elf-clang/esp-20.1.1_20250829/esp-clang/lib"
+
+[tasks.esp-install]
+description = "Install the ESP Xtensa toolchain (rustc-esp + GCC + clang) at versions matching [env]"
+run = "espup install --crosstool-toolchain-version esp-15.2.0_20250920"
@@ -70,8 +70,10 @@ impl LoRaBoard for Board {
 ### 5. Add display init

 ```rust
-pub async fn create_display(i2c: DisplayI2c) -> Option<DisplayDriver> {
-    // Construct and initialize your display driver (SSD1306, SH1106, etc.)
+pub async fn create_display(parts: DisplayParts) -> Option<DisplayDriver> {
+    // Construct and initialize your display driver (SSD1306, SH1106,
+    // ST7789, etc.) using whatever pins/buses you bundled into
+    // DisplayParts in `into_parts()`.
 }
 ```

@@ -48,8 +48,8 @@ pub struct DisplayParts {

 // ── Display init ────────────────────────────────────────────────────

-pub async fn create_display(i2c: DisplayI2c) -> Option<DisplayDriver> {
-    let mut display = Sh1106::new(i2c, 0x3C);
+pub async fn create_display(parts: DisplayParts) -> Option<DisplayDriver> {
+    let mut display = Sh1106::new(parts.i2c, 0x3C);

    embassy_time::Timer::after_millis(100).await;
    if display.init().await.is_err() {
@@ -0,0 +1,103 @@
+//! Shared types and peripheral wiring for classic-ESP32 SX1276 boards.
+//!
+//! Counterpart to `board::esp32s3` for the SX126x line. Builds an
+//! `Sx127x<Sx1276>` driver from an already-initialized SPI bus plus the
+//! board's reset and DIO0 pins. SX127x has no `BUSY` line — DIO0 carries
+//! every IRQ (TX done, RX done, header valid, …) and lora-phy's
+//! `GenericSx127xInterfaceVariant` waits on it directly.
+
+use embassy_embedded_hal::shared_bus::asynch::spi::SpiDevice;
+use embassy_sync::blocking_mutex::raw::NoopRawMutex;
+use embassy_time::Delay;
+use esp_hal::gpio::{Input, InputConfig, InputPin, Level, Output, OutputConfig, OutputPin, Pull};
+
+use lora_phy::iv::GenericSx127xInterfaceVariant;
+use lora_phy::sx127x::{self, Sx127x};
+
+use crate::hal::esp32 as mcu;
+
+// ── Re-export MCU types ─────────────────────────────────────────────
+
+pub use mcu::{I2cBus as DisplayI2c, SpiBus};
+
+// ── Concrete peripheral types ───────────────────────────────────────
+
+type Nss = Output<'static>;
+type Iv = GenericSx127xInterfaceVariant<Output<'static>, Input<'static>>;
+type RadioSpiDevice = SpiDevice<'static, NoopRawMutex, SpiBus, Nss>;
+pub type RadioDriver = Sx127x<RadioSpiDevice, Iv, sx127x::Sx1276>;
+
+// ── Peripheral bundles ──────────────────────────────────────────────
+
+pub struct RadioParts {
+    pub driver: RadioDriver,
+    pub delay: Delay,
+}
+
+pub struct DisplayParts {
+    pub i2c: DisplayI2c,
+}
+
+// ── Display driver ──────────────────────────────────────────────────
+
+pub type DisplayDriver = ssd1306::Ssd1306Async<
+    ssd1306::prelude::I2CInterface<DisplayI2c>,
+    ssd1306::size::DisplaySize128x64,
+    ssd1306::mode::BufferedGraphicsModeAsync<ssd1306::size::DisplaySize128x64>,
+>;
+
+/// Construct and initialize an SSD1306 display from raw I²C.
+pub async fn create_display(parts: DisplayParts) -> Option<DisplayDriver> {
+    use ssd1306::mode::DisplayConfigAsync;
+    use ssd1306::prelude::{Brightness, DisplayRotation};
+    use ssd1306::size::DisplaySize128x64;
+    use ssd1306::{I2CDisplayInterface, Ssd1306Async};
+
+    let interface = I2CDisplayInterface::new(parts.i2c);
+    let mut display = Ssd1306Async::new(interface, DisplaySize128x64, DisplayRotation::Rotate0)
+        .into_buffered_graphics_mode();
+
+    embassy_time::Timer::after_millis(100).await;
+    if display.init().await.is_err() {
+        defmt::error!("SSD1306 display init failed");
+        return None;
+    }
+    let _ = display.set_brightness(Brightness::BRIGHTEST).await;
+    Some(display)
+}
+
+// ── Shared peripheral init helpers ──────────────────────────────────
+
+/// Construct an SX1276 radio from an initialized SPI bus.
+///
+/// `dio0` is the primary IRQ (TX/RX done). The SX1276 module on the T-Beam
+/// runs from a crystal oscillator, not a TCXO, and power comes from the
+/// AXP192's PA_BOOST rail — `tx_boost = true` routes TX through the PA
+/// output for +20 dBm.
+pub fn init_radio(
+    spi_bus: &'static embassy_sync::mutex::Mutex<NoopRawMutex, SpiBus>,
+    nss_pin: impl OutputPin + 'static,
+    reset_pin: impl OutputPin + 'static,
+    dio0_pin: impl InputPin + 'static,
+) -> RadioParts {
+    let nss = Output::new(nss_pin, Level::High, OutputConfig::default());
+    let spi_device = SpiDevice::new(spi_bus, nss);
+
+    let reset = Output::new(reset_pin, Level::High, OutputConfig::default());
+    let dio0 = Input::new(dio0_pin, InputConfig::default().with_pull(Pull::Down));
+
+    let iv =
+        GenericSx127xInterfaceVariant::new(reset, dio0, None, None).expect("SX1276 interface init");
+
+    let sx_config = sx127x::Config {
+        chip: sx127x::Sx1276,
+        tcxo_used: false,
+        tx_boost: true,
+        rx_boost: false,
+    };
+
+    RadioParts {
+        driver: Sx127x::new(spi_device, iv, sx_config),
+        delay: Delay,
+    }
+}
@@ -63,13 +63,13 @@ pub type DisplayDriver = ssd1306::Ssd1306Async<
    feature = "heltec_v3_uart",
    feature = "heltec_v4"
 ))]
-pub async fn create_display(i2c: DisplayI2c) -> Option<DisplayDriver> {
+pub async fn create_display(parts: DisplayParts) -> Option<DisplayDriver> {
    use ssd1306::mode::DisplayConfigAsync;
    use ssd1306::prelude::{Brightness, DisplayRotation};
    use ssd1306::size::DisplaySize128x64;
    use ssd1306::{I2CDisplayInterface, Ssd1306Async};

-    let interface = I2CDisplayInterface::new(i2c);
+    let interface = I2CDisplayInterface::new(parts.i2c);
    let mut display = Ssd1306Async::new(interface, DisplaySize128x64, DisplayRotation::Rotate0)
        .into_buffered_graphics_mode();

@@ -0,0 +1,285 @@
+//! Heltec Mesh Node T114 (nRF52840 + SX1262 + 1.14" ST7789 TFT).
+//!
+//! Hardware reference: cross-verified across MeshCore, Meshtastic, and
+//! RNode firmwares. Pin maps quoted from
+//! `meshcore-spec/references/MeshCore/variants/heltec_t114/variant.h` and
+//! `meshtastic/firmware/variants/nrf52840/heltec_mesh_node_t114/variant.h`.
+//!
+//! Stage 2: panel comes up with static colors via the `St7789Color`
+//! driver. Stage 3 swaps in the proper color renderer module.
+
+use embassy_embedded_hal::shared_bus::asynch::spi::SpiDevice;
+use embassy_nrf::gpio::{Input, Level, Output, OutputDrive, Pull};
+use embassy_nrf::pwm::{Prescaler, SimpleConfig, SimplePwm};
+use embassy_nrf::spim::{self, Spim};
+use embassy_nrf::usb::Driver;
+use embassy_sync::blocking_mutex::raw::NoopRawMutex;
+use embassy_time::{Delay, Timer};
+
+use embedded_hal_bus::spi::ExclusiveDevice;
+use lcd_async::interface::SpiInterface;
+use lcd_async::models::ST7789;
+use lcd_async::options::{ColorInversion, Orientation, Rotation};
+use lora_phy::iv::GenericSx126xInterfaceVariant;
+use lora_phy::sx126x::{self, Sx1262, Sx126x};
+use static_cell::ConstStaticCell;
+
+use super::traits::{BoardParts, LoRaBoard};
+use crate::driver::inverted_pin::InvertedPin;
+use crate::driver::simple_led::SimpleLed;
+use crate::driver::st7789::{St7789Color, FB_BYTES};
+use crate::hal::nrf52840 as mcu;
+
+// ── Concrete peripheral types ───────────────────────────────────────
+
+type Nss = Output<'static>;
+type Iv = GenericSx126xInterfaceVariant<Output<'static>, Input<'static>>;
+type RadioSpiDevice = SpiDevice<'static, NoopRawMutex, mcu::SpiBus, Nss>;
+pub type RadioDriver = Sx126x<RadioSpiDevice, Iv, Sx1262>;
+pub type UsbDriver = mcu::UsbNrfDriver;
+// Green LED on P1.03, active LOW.
+pub type LedDriver = SimpleLed<InvertedPin<Output<'static>>>;
+
+// ── TFT bus and driver type aliases ─────────────────────────────────
+
+type TftSpim = Spim<'static>;
+type TftSpiDevice = ExclusiveDevice<TftSpim, Output<'static>, Delay>;
+type TftInterface = SpiInterface<TftSpiDevice, Output<'static>>;
+pub type DisplayDriver = St7789Color<TftInterface, Output<'static>>;
+
+// ── Peripheral bundles ──────────────────────────────────────────────
+
+pub struct RadioParts {
+    pub driver: RadioDriver,
+    pub delay: Delay,
+}
+
+pub struct UsbParts {
+    pub driver: UsbDriver,
+}
+
+/// Assembled-but-not-yet-initialized TFT plumbing. Real initialization
+/// (power gate, RST cycle, mipidsi init) happens in `create_display`.
+pub struct DisplayParts {
+    interface: TftInterface,
+    rst_pin: Output<'static>,
+    vdd_en: Output<'static>,
+    backlight: SimplePwm<'static>,
+}
+
+// ── Display init ────────────────────────────────────────────────────
+
+pub async fn create_display(parts: DisplayParts) -> Option<DisplayDriver> {
+    let DisplayParts {
+        interface,
+        rst_pin,
+        mut vdd_en,
+        mut backlight,
+    } = parts;
+
+    // 1. Drive TFT VDD enable LOW (active LOW per Meshtastic) and let
+    //    the rail settle. Heltec's schematic has the panel power gated
+    //    by P0.03 — touching SPI before VDD is stable produces snow.
+    vdd_en.set_low();
+    Timer::after_millis(50).await;
+
+    // 2. Build the lcd-async display.
+    //    The T114 panel is wired natively portrait (135w × 240h) at
+    //    chip framebuffer offset (52, 40) — the standard 1.14" 135×240
+    //    ST7789 die mapping. Deg90 rotation rotates the user-facing
+    //    surface to landscape (240w × 135h). Meshtastic's variant.h
+    //    sets TFT_OFFSET_X=0/Y=0 because their fork of TFT_eSPI applies
+    //    these offsets internally; lcd-async expects them in display_offset.
+    //    If the image comes up mirrored or upside-down, swap
+    //    Deg90 ↔ Deg270 or set `mirrored = true`.
+    let mut delay = Delay;
+    let panel = match lcd_async::Builder::new(ST7789, interface)
+        .reset_pin(rst_pin)
+        .display_size(135, 240)
+        .display_offset(52, 40)
+        .orientation(Orientation::new().rotate(Rotation::Deg90))
+        .invert_colors(ColorInversion::Inverted)
+        .init(&mut delay)
+        .await
+    {
+        Ok(p) => p,
+        Err(_) => {
+            defmt::error!("ST7789 init failed");
+            return None;
+        }
+    };
+    defmt::info!("ST7789 init OK");
+
+    // 3. Bring the backlight up at full brightness. Stage 2 uses the
+    //    full-on duty; the splash dimming logic handled by the display
+    //    statechart will hand off to set_dim/set_bright shortly.
+    backlight.set_duty(0, embassy_nrf::pwm::DutyCycle::inverted(0));
+
+    // Forget vdd_en so it stays driven for the lifetime of the program.
+    // We took it by move so we could call set_low() during init.
+    core::mem::forget(vdd_en);
+
+    // Take the static framebuffer (240×135 × 2 bytes Rgb565 BE
+    // = 64,800 bytes zero-initialized in .bss). Stored as raw bytes
+    // so present() can DMA-blit the slice straight to the panel
+    // without an iterator-conversion pass — the lcd-async
+    // `RawFrameBuf<Rgb565, _>` wrapper handles BE byte packing on
+    // each pixel write.
+    static FRAMEBUFFER: ConstStaticCell<[u8; FB_BYTES]> =
+        ConstStaticCell::new([0u8; FB_BYTES]);
+    let fb = FRAMEBUFFER.take();
+
+    Some(St7789Color::new(panel, backlight, fb))
+}
+
+// ── Board init ──────────────────────────────────────────────────────
+
+pub struct Board {
+    p: embassy_nrf::Peripherals,
+}
+
+impl LoRaBoard for Board {
+    const NAME: &'static str = "Heltec Mesh Node T114";
+    const TX_POWER_RANGE: (i8, i8) = (-9, 22);
+
+    type RadioParts = RadioParts;
+    type CommParts = UsbParts;
+    type DisplayParts = DisplayParts;
+    type DisplayDriver = DisplayDriver;
+    type LedDriver = LedDriver;
+
+    fn init() -> Self {
+        // USB requires the 32 MHz HFXO (±50 ppm); the RC oscillator is out of spec.
+        let mut config = embassy_nrf::config::Config::default();
+        config.hfclk_source = embassy_nrf::config::HfclkSource::ExternalXtal;
+        config.lfclk_source = embassy_nrf::config::LfclkSource::ExternalXtal;
+        let p = embassy_nrf::init(config);
+        Self { p }
+    }
+
+    fn mac_address() -> [u8; 6] {
+        mcu::mac_address()
+    }
+
+    fn into_parts(self) -> BoardParts<RadioParts, UsbParts, DisplayParts, LedDriver> {
+        let p = self.p;
+
+        // ── VEXT_ENABLE (P0.21, active HIGH) ────────────────────
+        // Powers the SX1262 *and* the TFT/peripheral 3V3 rail. Must be
+        // driven HIGH before any SPI traffic to the radio or panel —
+        // without this, lora-phy init can succeed (SPI bus works
+        // electrically) but TX_DONE never fires because the PA is
+        // unpowered. Held forever via core::mem::forget. Mirrors
+        // Meshtastic's `VEXT_ENABLE = P0.21, VEXT_ON_VALUE = HIGH`.
+        let vext_en = Output::new(p.P0_21, Level::High, OutputDrive::Standard);
+        core::mem::forget(vext_en);
+
+        // ── SPI3 bus for SX1262 ─────────────────────────────────
+        // Per Heltec T114 schematic + Meshtastic variant.h:
+        //   SCK=P0.19, MOSI=P0.22, MISO=P0.23
+        //   NSS=P0.24, RST=P0.25, BUSY=P0.17, DIO1=P0.20
+        // No external RXEN/TXEN — antenna switch is driven internally
+        // by SX1262 DIO2. TCXO is on DIO3 at 1.8 V.
+        let mut spi_cfg = spim::Config::default();
+        spi_cfg.frequency = spim::Frequency::M1;
+        let spi = Spim::new(p.SPI3, mcu::Irqs, p.P0_19, p.P0_23, p.P0_22, spi_cfg);
+        let spi_bus = mcu::share_spi_bus(spi);
+
+        let nss = Output::new(p.P0_24, Level::High, OutputDrive::Standard);
+        let spi_device = SpiDevice::new(spi_bus, nss);
+
+        let reset = Output::new(p.P0_25, Level::High, OutputDrive::Standard);
+        let dio1 = Input::new(p.P0_20, Pull::Down);
+        // BUSY has an internal 20 kΩ pull-up on the SX1262 die (datasheet
+        // p. 53); an MCU-side Pull fights it. See lora-rs/lora-rs#260.
+        let busy = Input::new(p.P0_17, Pull::None);
+
+        let iv = GenericSx126xInterfaceVariant::new(reset, dio1, busy, None, None)
+            .expect("SX1262 interface init");
+
+        let sx_config = sx126x::Config {
+            chip: Sx1262,
+            tcxo_ctrl: Some(sx126x::TcxoCtrlVoltage::Ctrl1V8),
+            use_dcdc: true,
+            rx_boost: false,
+        };
+
+        let radio = RadioParts {
+            driver: Sx126x::new(spi_device, iv, sx_config),
+            delay: Delay,
+        };
+
+        // ── USB ─────────────────────────────────────────────────
+        let vbus = mcu::alloc_vbus_detect(true, true);
+        let host = UsbParts {
+            driver: Driver::new(p.USBD, mcu::Irqs, vbus),
+        };
+
+        // Battery divider control (P0.06) LOW disables the divider —
+        // saves a few tens of µA. Battery sense (P0.04 / AIN2) deferred
+        // until the protocol gets a battery field.
+        let bat_ctl = Output::new(p.P0_06, Level::Low, OutputDrive::Standard);
+        core::mem::forget(bat_ctl);
+
+        // ── SPI2 bus for ST7789 TFT ─────────────────────────────
+        // Per Meshtastic variant.h:
+        //   SCK=P1.08, MOSI=P1.09, CS=P0.11, DC=P0.12, RST=P0.02
+        //   VDD enable=P0.03 (active HIGH), Backlight=P0.15 (active LOW PWM)
+        // Write-only bus — embassy_nrf::Spim still requires a MISO slot,
+        // so we wire a free unused pin (P1.06) as a no-op input.
+        let mut tft_spi_cfg = spim::Config::default();
+        // 8 MHz lets us repaint the 240×135 panel comfortably. Higher
+        // rates work with mipidsi but are platform-dependent (board
+        // routing, pull strengths). 8 MHz is the safe default.
+        tft_spi_cfg.frequency = spim::Frequency::M8;
+        let tft_spi = Spim::new(p.SPI2, mcu::Irqs, p.P1_08, p.P1_06, p.P1_09, tft_spi_cfg);
+
+        let tft_cs = Output::new(p.P0_11, Level::High, OutputDrive::Standard);
+        let tft_dc = Output::new(p.P0_12, Level::Low, OutputDrive::Standard);
+        let tft_rst = Output::new(p.P0_02, Level::High, OutputDrive::Standard);
+        // VTFT_CTRL is active LOW per Meshtastic
+        // (`#define TFT_BACKLIGHT_ON LOW`, `digitalWrite(VTFT_CTRL, LOW)`
+        // at boot). Start HIGH (panel rail off); create_display drives
+        // LOW to enable the panel.
+        let tft_vdd = Output::new(p.P0_03, Level::High, OutputDrive::Standard);
+
+        let tft_spi_device = ExclusiveDevice::new(tft_spi, tft_cs, Delay)
+            .expect("TFT ExclusiveDevice init");
+
+        // lcd-async's SpiInterface streams pixel data directly from
+        // the caller's slice — no scratch buffer required (mipidsi's
+        // sync version needed one for batching).
+        let tft_interface = SpiInterface::new(tft_spi_device, tft_dc);
+
+        // ── PWM backlight (active-LOW on P0.15) ─────────────────
+        // Default SimpleConfig is fine — countertop=1000 → ~1 kHz
+        // (well above flicker threshold), prescaler default. Channel 0
+        // idle level matches the active-LOW wiring.
+        let mut bl_cfg = SimpleConfig::default();
+        bl_cfg.max_duty = crate::driver::st7789::BL_MAX;
+        bl_cfg.prescaler = Prescaler::Div128;
+        bl_cfg.ch0_idle_level = Level::High;
+        let backlight = SimplePwm::new_1ch(p.PWM0, p.P0_15, &bl_cfg);
+
+        let display_parts = DisplayParts {
+            interface: tft_interface,
+            rst_pin: tft_rst,
+            vdd_en: tft_vdd,
+            backlight,
+        };
+
+        // ── Green LED (P1.03, active LOW) ───────────────────────
+        // Idle level HIGH = LED off. InvertedPin flips polarity so
+        // SimpleLed can use normal "set_high = on" semantics.
+        let led_pin = Output::new(p.P1_03, Level::High, OutputDrive::Standard);
+        let led = SimpleLed(InvertedPin(led_pin));
+
+        BoardParts {
+            radio,
+            host,
+            display: Some(display_parts),
+            led,
+            mac: Self::mac_address(),
+        }
+    }
+}
@@ -0,0 +1,140 @@
+//! LilyGo T-Beam (classic) — ESP32 + SX1276 + SSD1306 OLED + AXP192 PMIC.
+//!
+//! First-generation T-Beam. ESP32 (dual-core Xtensa LX6, no native USB),
+//! SX1276 module with XTAL (no TCXO), 128×64 SSD1306 OLED, AXP192 PMIC
+//! gating the LoRa and OLED rails, CP2102 USB-UART bridge for host I/O.
+//!
+//! The AXP192 shares an I²C bus with the OLED (SDA=21, SCL=22). PMIC init
+//! runs blocking on that bus first, then the same pins are re-initialized
+//! in async mode for the display task.
+//!
+//! Pin map (verified from MeshCore variants/lilygo_tbeam_SX1276/):
+//!   LoRa SPI:  SCK=5, MOSI=27, MISO=19, CS=18
+//!   LoRa ctl:  RESET=23, DIO0=26 (primary IRQ — SX127x has no BUSY)
+//!   OLED I²C:  SDA=21, SCL=22, SSD1306 @ 0x3C (shared with AXP192 @ 0x34)
+//!   UART host: TX=1, RX=3 via CP2102 bridge (USB 10c4:ea60)
+//!   LED:       GPIO4 (active LOW — red LED under the OLED, wrapped in
+//!              InvertedPin so SimpleLed sees normal polarity)
+//!
+//! GPS / battery / IMU / PCF8563 RTC are populated on the board but unused
+//! by this firmware.
+
+use esp_hal::gpio::{Level, Output, OutputConfig};
+use esp_hal::i2c::master::{Config as I2cConfig, I2c};
+
+use super::esp32;
+use super::traits::{BoardParts, LoRaBoard};
+use crate::driver::axp;
+use crate::driver::inverted_pin::InvertedPin;
+use crate::driver::simple_led::SimpleLed;
+use crate::hal::esp32 as mcu;
+use crate::protocol::RadioChipId;
+
+pub use super::esp32::{create_display, DisplayDriver, DisplayParts, RadioDriver, RadioParts};
+
+// ── Concrete peripheral types ───────────────────────────────────────
+
+pub type UartDriver = esp_hal::uart::Uart<'static, esp_hal::Async>;
+pub type LedDriver = SimpleLed<InvertedPin<Output<'static>>>;
+
+// ── Peripheral bundles ──────────────────────────────────────────────
+
+pub struct UartParts {
+    pub driver: UartDriver,
+}
+
+// ── Board init ──────────────────────────────────────────────────────
+
+pub struct Board {
+    p: esp_hal::peripherals::Peripherals,
+}
+
+impl LoRaBoard for Board {
+    const NAME: &'static str = "LilyGo T-Beam";
+    // SX1276 PA_BOOST range per the datasheet: +2 dBm min, +20 dBm max.
+    const TX_POWER_RANGE: (i8, i8) = (2, 20);
+
+    type RadioParts = RadioParts;
+    type CommParts = UartParts;
+    type DisplayParts = DisplayParts;
+    type DisplayDriver = DisplayDriver;
+    type LedDriver = LedDriver;
+
+    fn init() -> Self {
+        let p = esp_hal::init(esp_hal::Config::default());
+        Self { p }
+    }
+
+    fn mac_address() -> [u8; 6] {
+        mcu::mac_address()
+    }
+
+    fn radio_chip_id() -> u16 {
+        RadioChipId::Sx1276.as_u16()
+    }
+
+    fn freq_range_hz() -> (u32, u32) {
+        // SX1276 tuning window per datasheet (LF + HF bands combined).
+        (137_000_000, 1_020_000_000)
+    }
+
+    fn supported_sf_bitmap() -> u16 {
+        // SX127x supports SF6–SF12 (no SF5 like the SX126x).
+        0x1FC0
+    }
+
+    fn into_parts(self) -> BoardParts<RadioParts, UartParts, DisplayParts, LedDriver> {
+        let p = self.p;
+
+        mcu::start_timer(p.TIMG0, p.SW_INTERRUPT);
+
+        // AXP192 and SSD1306 share I²C0 (SDA=21, SCL=22). Build the bus
+        // once as blocking, drive the PMIC init, then convert to async for
+        // the display task — avoids re-consuming the I²C0 peripheral.
+        // PMIC failure isn't fatal to boot: log and proceed so the rest of
+        // the firmware can still emit diagnostics.
+        let mut i2c_blocking = I2c::new(p.I2C0, I2cConfig::default())
+            .expect("I2C0 init")
+            .with_sda(p.GPIO21)
+            .with_scl(p.GPIO22);
+        if let Err(_e) = axp::axp192_init_lora_oled(&mut i2c_blocking) {
+            defmt::error!("AXP192 init failed — LoRa rail may be dead");
+        }
+        // Let DCDC1 / LDO2 settle before SPI or display traffic.
+        esp_hal::delay::Delay::new().delay_millis(20);
+
+        // SPI2 for SX1276: SCK=5, MOSI=27, MISO=19
+        let spi_bus = mcu::init_spi(p.SPI2, p.DMA_SPI2, p.GPIO5, p.GPIO27, p.GPIO19);
+
+        // SX1276: CS=18, RESET=23, DIO0=26 (primary IRQ)
+        let radio = esp32::init_radio(spi_bus, p.GPIO18, p.GPIO23, p.GPIO26);
+
+        // UART0 via CP2102 bridge: TX=1, RX=3 (ESP32 default console)
+        use esp_hal::uart::{Config as UartConfig, Uart};
+        let host = UartParts {
+            driver: Uart::new(p.UART0, UartConfig::default())
+                .expect("UART init")
+                .with_tx(p.GPIO1)
+                .with_rx(p.GPIO3)
+                .into_async(),
+        };
+
+        // Hand the (now async) I²C bus to the SSD1306 display task.
+        let display = Some(DisplayParts {
+            i2c: i2c_blocking.into_async(),
+        });
+
+        // TX activity LED on GPIO4 (active LOW — pin idles HIGH = LED off).
+        // InvertedPin flips set_high/set_low so SimpleLed stays polarity-agnostic.
+        let led_pin = Output::new(p.GPIO4, Level::High, OutputConfig::default());
+        let led = SimpleLed(InvertedPin(led_pin));
+
+        BoardParts {
+            radio,
+            host,
+            display,
+            led,
+            mac: Self::mac_address(),
+        }
+    }
+}
@@ -0,0 +1,153 @@
+//! LilyGo T-Beam S3 Supreme — ESP32-S3 + SX1262 + SH1106 OLED + AXP2101 PMIC.
+//!
+//! Big-brother of the classic T-Beam: ESP32-S3-WROOM-1 module, SX1262 with a
+//! TCXO, 128×64 SH1106 OLED, AXP2101 PMIC on a dedicated I²C1 bus. Native USB
+//! (no UART bridge chip).
+//!
+//! The AXP2101 gates power to the SX1262 and OLED. Without its init sequence
+//! the LoRa chip never responds on SPI and `LoRa::new` fails.
+//!
+//! Pin map (verified from MeshCore variants/lilygo_tbeam_supreme_SX1262/):
+//!   LoRa SPI: SCK=12, MOSI=11, MISO=13, CS=10
+//!   LoRa ctl: RESET=5, DIO1=1, BUSY=4 (TCXO @ 1.6 V via DIO3)
+//!   OLED I²C: SDA=17, SCL=18, SH1106 @ 0x3C (I²C0)
+//!   PMIC I²C: SDA=42, SCL=41, AXP2101 @ 0x34 (I²C1, blocking, PMIC-only)
+//!   USB:      native USB-C on GPIO19/20 (fixed ESP32-S3 D+/D-)
+//!   LED:      GPIO6 (active HIGH indicator, reuses MeshCore's P_LORA_TX_LED)
+//!
+//! GPS / battery / IMU / SD / BME280 are unused — DongLoRa is a transparent
+//! LoRa-over-USB bridge. The PMIC init only enables ALDO1 (OLED) and ALDO3
+//! (LoRa); other rails are left at their AXP2101 power-on defaults.
+
+use esp_hal::gpio::{Level, Output, OutputConfig};
+use esp_hal::i2c::master::{Config as I2cConfig, I2c};
+use static_cell::StaticCell;
+
+use super::esp32s3;
+use super::traits::{BoardParts, LoRaBoard};
+use crate::driver::axp;
+use crate::driver::sh1106::Sh1106;
+use crate::driver::simple_led::SimpleLed;
+use crate::hal::esp32s3 as mcu;
+
+pub use super::esp32s3::{DisplayI2c, RadioDriver, RadioParts};
+
+// ── Concrete peripheral types ───────────────────────────────────────
+
+pub type DisplayDriver = Sh1106<DisplayI2c>;
+pub type UsbDriver = esp_hal::otg_fs::asynch::Driver<'static>;
+pub type LedDriver = SimpleLed<Output<'static>>;
+
+// ── Peripheral bundles ──────────────────────────────────────────────
+
+pub struct UsbParts {
+    pub driver: UsbDriver,
+}
+
+pub struct DisplayParts {
+    pub i2c: DisplayI2c,
+}
+
+// ── Display init ────────────────────────────────────────────────────
+
+pub async fn create_display(parts: DisplayParts) -> Option<DisplayDriver> {
+    let mut display = Sh1106::new(parts.i2c, 0x3C);
+
+    embassy_time::Timer::after_millis(100).await;
+    if display.init().await.is_err() {
+        defmt::error!("SH1106 display init failed");
+        return None;
+    }
+    let _ = display.set_brightness(0xFF).await;
+    Some(display)
+}
+
+// ── Board init ──────────────────────────────────────────────────────
+
+pub struct Board {
+    p: esp_hal::peripherals::Peripherals,
+}
+
+impl LoRaBoard for Board {
+    const NAME: &'static str = "LilyGo T-Beam S3 Supreme";
+    const TX_POWER_RANGE: (i8, i8) = (-9, 22);
+
+    type RadioParts = RadioParts;
+    type CommParts = UsbParts;
+    type DisplayParts = DisplayParts;
+    type DisplayDriver = DisplayDriver;
+    type LedDriver = LedDriver;
+
+    fn init() -> Self {
+        let p = esp_hal::init(esp_hal::Config::default());
+        Self { p }
+    }
+
+    fn mac_address() -> [u8; 6] {
+        mcu::mac_address()
+    }
+
+    fn into_parts(self) -> BoardParts<RadioParts, UsbParts, DisplayParts, LedDriver> {
+        let p = self.p;
+
+        mcu::start_timer(p.TIMG0, p.SW_INTERRUPT);
+
+        // AXP2101 PMIC on I²C1 (SDA=42, SCL=41). Blocking, one-shot: we only
+        // need to flip the LoRa/OLED rails on, then the bus can be dropped.
+        // If this fails the LoRa chip stays unpowered — log and keep going so
+        // the rest of the boot path can still produce diagnostics.
+        {
+            let mut pmic = I2c::new(p.I2C1, I2cConfig::default())
+                .expect("I2C1 init")
+                .with_sda(p.GPIO42)
+                .with_scl(p.GPIO41);
+            if let Err(_e) = axp::axp2101_init_lora_oled(&mut pmic) {
+                defmt::error!("AXP2101 init failed — LoRa rail may be dead");
+            }
+        }
+        // Let ALDO1/ALDO3 settle before touching the LoRa SPI or OLED I²C.
+        esp_hal::delay::Delay::new().delay_millis(20);
+
+        // SPI2 for SX1262: SCK=12, MOSI=11, MISO=13
+        let spi_bus = mcu::init_spi(p.SPI2, p.DMA_CH0, p.GPIO12, p.GPIO11, p.GPIO13);
+
+        // SX1262: CS=10, RESET=5, DIO1=1, BUSY=4, TCXO @ 1.6 V via DIO3.
+        let radio = esp32s3::init_radio(
+            spi_bus,
+            p.GPIO10,
+            p.GPIO5,
+            p.GPIO1,
+            p.GPIO4,
+            lora_phy::sx126x::TcxoCtrlVoltage::Ctrl1V6,
+        );
+
+        // Native USB-C on GPIO19/20. Switches the internal USB PHY from
+        // Serial-JTAG to OTG.
+        let usb_inst = esp_hal::otg_fs::Usb::new(p.USB0, p.GPIO20, p.GPIO19);
+        static EP_OUT_BUF: StaticCell<[u8; 1024]> = StaticCell::new();
+        let ep_out_buf = EP_OUT_BUF.init([0u8; 1024]);
+        let host = UsbParts {
+            driver: esp_hal::otg_fs::asynch::Driver::new(
+                usb_inst,
+                ep_out_buf,
+                esp_hal::otg_fs::asynch::Config::default(),
+            ),
+        };
+
+        // I2C0 for SH1106 OLED: SDA=17, SCL=18 (async, handed to display task).
+        let i2c = mcu::init_i2c(p.I2C0, p.GPIO17, p.GPIO18);
+        let display = Some(DisplayParts { i2c });
+
+        // Activity LED on GPIO6 (active HIGH).
+        let led_pin = Output::new(p.GPIO6, Level::Low, OutputConfig::default());
+        let led = SimpleLed(led_pin);
+
+        BoardParts {
+            radio,
+            host,
+            display,
+            led,
+            mac: Self::mac_address(),
+        }
+    }
+}
@@ -3,7 +3,11 @@ pub mod traits;
 pub use traits::*;

 {% for helper, helper_features in helpers|items -%}
+{% if helper_features|length == 1 -%}
+#[cfg(feature = "{{ helper_features[0] }}")]
+{% else -%}
 #[cfg(any({% for f in helper_features %}feature = "{{ f }}"{% if not loop.last %}, {% endif %}{% endfor %}))]
+{% endif -%}
 mod {{ helper }};
 {% endfor %}
 cfg_if::cfg_if! {
@@ -20,13 +20,20 @@ type RadioSpiDevice = SpiDevice<'static, NoopRawMutex, mcu::SpiBus, Nss>;
 pub type RadioDriver = Sx126x<RadioSpiDevice, Iv, Sx1262>;
 pub type UsbDriver = mcu::UsbNrfDriver;
 pub type DisplayI2c = mcu::I2cBus;
-pub type LedDriver = ();
+pub type LedDriver = crate::driver::simple_led::SimpleLed<Output<'static>>;

-pub type DisplayDriver = ssd1306::Ssd1306Async<
-    ssd1306::prelude::I2CInterface<DisplayI2c>,
-    ssd1306::size::DisplaySize128x64,
-    ssd1306::mode::BufferedGraphicsModeAsync<ssd1306::size::DisplaySize128x64>,
->;
+// SH1106 hand-rolled driver instead of the ssd1306 crate. The RAK1921
+// OLED ships under various Chinese-OEM packaging (e.g. JMD0.96C) that
+// can be either SSD1306 or SH1106 silicon — physically and pin
+// identical, but use different addressing modes. The bigger reason
+// though: ssd1306 0.10's display-interface-i2c emits I2C transaction
+// patterns (consecutive writes, 3+ ops) that embassy_nrf::twim's
+// `unreachable!()` rejects, so even on real SSD1306 silicon the panic
+// would fire. Our hand-rolled SH1106 driver issues only single writes
+// per logical op and is twim-safe. SH1106 init opcodes are similar
+// enough that real SSD1306 silicon mostly works (worst case: mirrored
+// display until proper runtime detection lands).
+pub type DisplayDriver = crate::driver::sh1106::Sh1106<DisplayI2c>;

 // ── Peripheral bundles ──────────────────────────────────────────────

@@ -45,23 +52,30 @@ pub struct DisplayParts {

 // ── Display init ────────────────────────────────────────────────────

-pub async fn create_display(i2c: DisplayI2c) -> Option<DisplayDriver> {
-    use ssd1306::mode::DisplayConfigAsync;
-    use ssd1306::prelude::{Brightness, DisplayRotation};
-    use ssd1306::size::DisplaySize128x64;
-    use ssd1306::{I2CDisplayInterface, Ssd1306Async};
+pub async fn create_display(parts: DisplayParts) -> Option<DisplayDriver> {
+    let mut display = crate::driver::sh1106::Sh1106::new(parts.i2c, 0x3C);

-    let interface = I2CDisplayInterface::new(i2c);
-    let mut display = Ssd1306Async::new(interface, DisplaySize128x64, DisplayRotation::Rotate0)
-        .into_buffered_graphics_mode();
-
-    embassy_time::Timer::after_millis(100).await;
-    if display.init().await.is_err() {
-        defmt::error!("SSD1306 display init failed");
-        return None;
+    // Retry 3× with 100ms backoff. The SH1106's first transaction
+    // after power-on can return Err if the chip's internal voltage
+    // converter hasn't fully settled — observed empirically on
+    // RAK4631/RAK1921. Each attempt is independent (full init
+    // sequence). Display works visibly even if the FIRST attempt
+    // failed, because subsequent attempts succeed.
+    for attempt in 0..3u8 {
+        embassy_time::Timer::after_millis(100).await;
+        if display.init().await.is_ok() {
+            let _ = display.set_brightness(0xFF).await;
+            return Some(display);
+        }
+        if attempt < 2 {
+            defmt::warn!(
+                "SH1106 display init attempt {=u8}/3 failed; retrying",
+                attempt + 1
+            );
+        }
    }
-    let _ = display.set_brightness(Brightness::BRIGHTEST).await;
-    Some(display)
+    defmt::error!("SH1106 display init failed after 3 attempts");
+    None
 }

 // ── Board init ──────────────────────────────────────────────────────
@@ -78,10 +92,14 @@ impl LoRaBoard for Board {
    type CommParts = UsbParts;
    type DisplayParts = DisplayParts;
    type DisplayDriver = DisplayDriver;
-    type LedDriver = ();
+    type LedDriver = LedDriver;

    fn init() -> Self {
-        let p = embassy_nrf::init(Default::default());
+        // USB requires the 32 MHz HFXO (±50 ppm); the RC oscillator is out of spec.
+        let mut config = embassy_nrf::config::Config::default();
+        config.hfclk_source = embassy_nrf::config::HfclkSource::ExternalXtal;
+        config.lfclk_source = embassy_nrf::config::LfclkSource::ExternalXtal;
+        let p = embassy_nrf::init(config);
        Self { p }
    }

@@ -89,12 +107,18 @@ impl LoRaBoard for Board {
        mcu::mac_address()
    }

-    fn into_parts(self) -> BoardParts<RadioParts, UsbParts, DisplayParts, ()> {
+    fn into_parts(self) -> BoardParts<RadioParts, UsbParts, DisplayParts, LedDriver> {
        let p = self.p;

+        // SX1262 is power-gated on P1.05 — must be HIGH before any SPI access.
+        let sx_power_en = Output::new(p.P1_05, Level::High, OutputDrive::Standard);
+        core::mem::forget(sx_power_en);
+
        // ── SPI bus for SX1262 ──────────────────────────────────
        let mut spi_cfg = spim::Config::default();
        spi_cfg.frequency = spim::Frequency::M1;
+        // embassy_nrf::spim::Spim::new args: (spim, irq, sck, miso, mosi, config).
+        // Per RAK4631 BSP: SCK=P1.11, MISO=P1.13, MOSI=P1.12.
        let spi = Spim::new(p.SPI3, mcu::Irqs, p.P1_11, p.P1_13, p.P1_12, spi_cfg);
        let spi_bus = mcu::share_spi_bus(spi);

@@ -103,7 +127,11 @@ impl LoRaBoard for Board {

        let reset = Output::new(p.P1_06, Level::High, OutputDrive::Standard);
        let dio1 = Input::new(p.P1_15, Pull::Down);
-        let busy = Input::new(p.P1_14, Pull::Down);
+        // BUSY has an internal 20 kΩ pull-up on the SX1262 die (datasheet
+        // p. 53); an MCU-side Pull::Down fights it and leaves the line at
+        // an indeterminate voltage, making wait_on_busy unreliable. See
+        // lora-rs/lora-rs#260.
+        let busy = Input::new(p.P1_14, Pull::None);

        let iv = GenericSx126xInterfaceVariant::new(reset, dio1, busy, None, None)
            .expect("SX1262 interface init");
@@ -121,7 +149,9 @@ impl LoRaBoard for Board {
        };

        // ── USB ─────────────────────────────────────────────────
-        let vbus = mcu::alloc_vbus_detect(true, false);
+        // SoftwareVbusDetect(vbus_detected, power_ready). Mark both true so the
+        // driver doesn't block waiting for a power-ready signal we never raise.
+        let vbus = mcu::alloc_vbus_detect(true, true);
        let host = UsbParts {
            driver: Driver::new(p.USBD, mcu::Irqs, vbus),
        };
@@ -138,11 +168,15 @@ impl LoRaBoard for Board {
        );
        let display = Some(DisplayParts { i2c });

+        // Green LED on P1.03 (RAK19007 Base, active HIGH).
+        let led_pin = Output::new(p.P1_03, Level::Low, OutputDrive::Standard);
+        let led = crate::driver::simple_led::SimpleLed(led_pin);
+
        BoardParts {
            radio,
            host,
            display,
-            led: (),
+            led,
            mac: Self::mac_address(),
        }
    }
@@ -6,10 +6,7 @@
 //!
 //! See `src/board/PORTING.md` for a step-by-step guide to adding a new board.

-use embedded_graphics::draw_target::DrawTarget;
-use embedded_graphics::pixelcolor::BinaryColor;
-
-use crate::driver::DisplayBrightness;
+use crate::display::BoardDisplay;

 /// Async RGB LED control. Boards without an LED use `()` which is a no-op.
 pub trait RgbLed {
@@ -37,9 +34,10 @@ pub trait LoRaBoard: Sized {
    /// Display peripheral bundle (I2C bus for display init).
    type DisplayParts;

-    /// Concrete display driver type (must implement DrawTarget for rendering
-    /// and DisplayBrightness for the two-level dim control).
-    type DisplayDriver: DrawTarget<Color = BinaryColor> + DisplayBrightness;
+    /// Concrete display driver type. Each board's driver implements
+    /// [`BoardDisplay`] to render the splash + dashboard content into its
+    /// native pixel format and resolution and to flush / dim the panel.
+    type DisplayDriver: BoardDisplay;

    /// RGB LED driver. Boards without an LED use `()`.
    type LedDriver: RgbLed;
@@ -65,6 +63,21 @@ pub trait LoRaBoard: Sized {
        (150_000_000, 960_000_000)
    }

+    /// Bitmap of supported LoRa spreading factors — bit N = SF N. Defaults
+    /// to SX126x's SF5–SF12 (`0x1FE0`). SX127x boards must override to
+    /// `0x1FC0` (SF6–SF12); LLCC68 boards to `0x0FE0` (SF5–SF11).
+    fn supported_sf_bitmap() -> u16 {
+        0x1FE0
+    }
+
+    /// Bitmap of supported LoRa bandwidths. Bit positions match
+    /// `LoRaBandwidth::as_u8()` (sub-GHz BW enum values 0..9). Defaults
+    /// to all sub-GHz BWs (`0x03FF`). SX128x boards flip the 2.4 GHz
+    /// bits when we add them.
+    fn supported_bw_bitmap() -> u16 {
+        0x03FF
+    }
+
    /// Decompose initialized board into peripheral bundles for each task.
    fn into_parts(
        self,
@@ -41,12 +41,16 @@ pub struct UsbParts {
 }

 pub struct DisplayParts {
+    // No display on this board, but the trait still wants concrete
+    // peripheral types. The i2c bus type is reserved for the future
+    // possibility of an external OLED add-on.
+    #[allow(dead_code)]
    pub i2c: DisplayI2c,
 }

 // ── Display init ───────────────────────────────────────────────────

-pub async fn create_display(_i2c: DisplayI2c) -> Option<DisplayDriver> {
+pub async fn create_display(_parts: DisplayParts) -> Option<DisplayDriver> {
    None
 }

@@ -42,8 +42,8 @@ pub struct DisplayParts {

 // ── Display init ────────────────────────────────────────────────────

-pub async fn create_display(i2c: DisplayI2c) -> Option<DisplayDriver> {
-    let mut display = crate::driver::sh1106::Sh1106::new(i2c, 0x3D);
+pub async fn create_display(parts: DisplayParts) -> Option<DisplayDriver> {
+    let mut display = crate::driver::sh1106::Sh1106::new(parts.i2c, 0x3D);

    embassy_time::Timer::after_millis(100).await;
    if display.init().await.is_err() {
@@ -96,7 +96,11 @@ impl LoRaBoard for Board {

        let reset = Output::new(p.P1_07, Level::High, OutputDrive::Standard);
        let dio1 = Input::new(p.P0_07, Pull::Down);
-        let busy = Input::new(p.P1_10, Pull::Down);
+        // BUSY has an internal 20 kΩ pull-up on the SX1262 die (datasheet
+        // p. 53); an MCU-side Pull::Down fights it and leaves the line at
+        // an indeterminate voltage, making wait_on_busy unreliable. See
+        // lora-rs/lora-rs#260.
+        let busy = Input::new(p.P1_10, Pull::None);

        // RF switch: RXEN on P1.08 (GPIO, toggled by lora_phy), TX via DIO2 (SX1262 internal).
        let rx_enable = Output::new(p.P1_08, Level::Low, OutputDrive::Standard);
@@ -9,9 +9,66 @@

 use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
 use embassy_sync::channel::Channel;
+use portable_atomic::AtomicBool;

 use crate::protocol::{Command, DeviceMessage, LoRaConfig};

+/// True while a Reset has been queued in `CommandChannel` but not yet
+/// consumed by the radio task. Dedupes injections from any host chart
+/// (USB DTR-driven OR UART inactivity-driven) that fires `reset_radio`
+/// repeatedly during quiet/inactive periods. Without this dedup, a slow
+/// or wedged radio causes the host chart's exit action to inject Reset
+/// every cycle, filling the commands channel and producing a "queue
+/// full" warn flood. Cleared by the radio chart's Reset handler
+/// (`reset_to_unconfigured`).
+///
+/// Uses `portable_atomic::AtomicBool` (not `core::sync::atomic`) because
+/// Cortex-M0+ targets (RP2040) lack native CAS for `swap`. portable-atomic
+/// transparently uses native atomics on M3+/M4 and critical-section
+/// emulation on M0/M0+.
+pub static RESET_PENDING: AtomicBool = AtomicBool::new(false);
+
+/// True while the host transport's USB IN endpoint is observed-dead
+/// (write_packet returned Err). Set by `host_task::protocol_loop` on the
+/// first failed write; cleared on the next successful write. Producers of
+/// **async** D→H events — `radio_task::record_packet` (RX) and
+/// `host::framing::emit_async_err` — check this flag before pushing into
+/// `OutboundChannel` and silently skip when set, so the queue does not
+/// fill while the host is gone.
+///
+/// Tag-correlated responses (OK / sync ERR / TX_DONE) are NOT gated by
+/// this flag: they're a small, bounded volume and the protocol contract
+/// requires them to be delivered if we ever reach the host again.
+///
+/// Same `portable_atomic::AtomicBool` rationale as `RESET_PENDING`.
+///
+/// **Initial value `true`**: at boot we have no proof the host can
+/// drain the outbound queue. Until host_task observes its first
+/// successful `write_packet` (and clears this), async-RX producers
+/// silently skip pushing. Otherwise — at boot, with no client
+/// attached or with mux-rs idle — RX events would fill the queue
+/// faster than host_task could drain it (which it can't: `write_packet`
+/// blocks until the host actually polls), and the depth-64 ring would
+/// flood `[WARN] RX dropped: outbound queue full` hundreds of times
+/// per second. Pre-throttle is the structural fix.
+pub static RADIO_THROTTLED: AtomicBool = AtomicBool::new(true);
+
+/// Set by `radio::lora_setup` / `lora_setup_with` when a SHORT-DURATION
+/// lora-phy op blew through its wall-clock budget (almost always BUSY
+/// stuck high — chip is wedged). Read by chart actions and `during:`
+/// activities that called the helper: when they observe a downstream
+/// `Err(_)` AND see this flag set, they emit `WedgeDetected` (which
+/// drives the radio chart into `Recovering` for an in-place NRESET +
+/// `lora.init()` retry) instead of the per-action failure event. The
+/// flag is consumed (`swap(false)`) by whoever reads it so the next
+/// independent op gets a fresh signal.
+///
+/// This is the cleanest plumbing path for "wedge timeout vs ordinary
+/// driver error" given the helper sits below the chart-action layer
+/// (free function, no chart-emit access). One atomic, one concern,
+/// matching the established `RESET_PENDING` / `RADIO_THROTTLED` pattern.
+pub static LORA_WEDGED: AtomicBool = AtomicBool::new(false);
+
 // ── Host → Radio: tag-correlated commands ───────────────────────────

 /// An event flowing from the host task into the radio task.
@@ -42,9 +99,16 @@ pub struct OutboundFrame {
    pub msg: DeviceMessage,
 }

-/// Radio-to-host outbound channel (depth 32: enough to hold a burst of
-/// RX events + queued command responses without stalling the radio ISR).
-pub type OutboundChannel = Channel<CriticalSectionRawMutex, OutboundFrame, 32>;
+/// Radio-to-host outbound channel.
+///
+/// Depth 64: absorbs bursts of RX events plus queued command responses
+/// plus async ERRs while the host transport drains. Each slot is ~280 B
+/// (max RxPayload + envelope), so 64 slots is ~18 KB — well within RAM
+/// budget on every supported MCU. The previous depth-32 was provoking
+/// "outbound queue full" floods during host stalls; the larger queue
+/// plus `RADIO_THROTTLED` backpressure flag (set by host_task on a
+/// failed write_packet) together stop the cascade.
+pub type OutboundChannel = Channel<CriticalSectionRawMutex, OutboundFrame, 64>;

 // ── Internal: display commands (no longer wire-visible) ────────────

@@ -138,15 +138,16 @@ fn phase_depth(n: u8) -> u8 {
    match n {
        18 => 1,  // pre-TX: CmdTransmit just read from commands channel
        6 => 2,   // perform_tx entered
-        7 => 3,   // in CAD
-        8 => 4,   // in prepare_for_tx
-        9 => 5,   // in tx().await
-        10 => 6,  // do_tx returned Ok
-        11 => 7,  // respond_tx_done entered
-        12 => 8,  // respond_tx_done: responses.send returned
-        13 => 9,  // host_task received response from channel
-        14 => 10, // host_task wrote response to UART (terminal success)
-        15 => 11, // TX errored (terminal error)
+        7 => 3,   // in CAD (before prepare_for_cad)
+        19 => 4,  // after prepare_for_cad (awaiting lora.cad IRQ)
+        8 => 5,   // in prepare_for_tx
+        9 => 6,   // in tx().await
+        10 => 7,  // do_tx returned Ok
+        11 => 8,  // respond_tx_done entered
+        12 => 9,  // respond_tx_done: responses.send returned
+        13 => 10, // host_task received response from channel
+        14 => 11, // host_task wrote response to UART (terminal success)
+        15 => 12, // TX errored (terminal error)
        _ => 0,   // not a TX phase
    }
 }
@@ -37,19 +37,80 @@ use embassy_time::Timer;
 use hsmc::statechart;

 use crate::board::{self, Board, DisplayDriver, DisplayParts, LedDriver, LoRaBoard, RgbLed};
-use crate::driver::DisplayBrightness;
 use crate::channel::{DisplayCommand, DisplayCommandChannel, RadioEvent, RadioEventChannel};
 use crate::protocol::LoRaConfig;

-use render::{BoardInfo, RSSI_HISTORY_LEN};
-
 const BOARD_NAME: &str = Board::NAME;
 const VERSION: &str = env!("CARGO_PKG_VERSION");

+/// Number of slots in the dashboard's RSSI/TX sparkline ring buffer.
+pub const RSSI_HISTORY_LEN: usize = 128;
+
+// Mono splash board-name font selection. The mono OLEDs we drive are
+// 128 px wide; the primary font (FONT_6X10, 6 px advance) fits up to 21
+// ASCII chars across, the fallback (FONT_5X8, 5 px advance) fits up to
+// 25. If even the fallback can't fit on a mono OLED, fail at compile
+// time so the board porter shortens NAME rather than silently
+// overflowing the splash. Color renderers have their own size budget
+// and simply use the same NAME with their own font choice.
+const SPLASH_SCREEN_W_PX: u32 = 128;
+const SPLASH_FONT_PRIMARY_W_PX: u32 = 6;
+const SPLASH_FONT_FALLBACK_W_PX: u32 = 5;
+pub(crate) const BOARD_NAME_FITS_PRIMARY_FONT: bool =
+    (BOARD_NAME.len() as u32) * SPLASH_FONT_PRIMARY_W_PX <= SPLASH_SCREEN_W_PX;
+const _: () = assert!(
+    (BOARD_NAME.len() as u32) * SPLASH_FONT_FALLBACK_W_PX <= SPLASH_SCREEN_W_PX,
+    "Board::NAME is too long for the 128 px mono splash screen even with the FONT_5X8 fallback \
+     (max 25 ASCII chars). Shorten the NAME constant in src/board/<board>.rs.",
+);
+
 /// Sentinel: no packet received in this slot. Below SX1262 sensitivity
 /// floor (-120 dBm), so it cannot be confused with a real RSSI value.
 const NO_SIGNAL: i16 = -121;

+/// Hand-authored 64 × 64 pixel-perfect QR bitmap for the splash
+/// "learn more" screen. 1 bit/pixel, MSB-first, row-major. Bit `1` is
+/// "light" (OLED pixel on), bit `0` is "dark" (OLED pixel off), so when
+/// drawn with `BinaryColor::On` = lit, the QR appears with the
+/// traditional dark-on-light look including a proper quiet zone. The
+/// color renderer remaps bit 1 → white, bit 0 → black for the same
+/// visual contrast on a black-background TFT.
+pub(crate) const QR_WIDTH_PX: u32 = 64;
+pub(crate) const QR_BITMAP: [u8; 512] = [
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFE, 0x00, 0x07, 0x9F, 0xFE, 0x60, 0x00, 0x7F, 0xFE,
+    0x00, 0x07, 0x9F, 0xFE, 0x60, 0x00, 0x7F, 0xFE, 0x7F, 0xE6, 0x18, 0x19, 0xE7, 0xFE, 0x7F, 0xFE,
+    0x7F, 0xE6, 0x18, 0x19, 0xE7, 0xFE, 0x7F, 0xFE, 0x60, 0x67, 0x81, 0xE6, 0x66, 0x06, 0x7F, 0xFE,
+    0x60, 0x67, 0x81, 0xE6, 0x66, 0x06, 0x7F, 0xFE, 0x60, 0x66, 0x19, 0x87, 0xE6, 0x06, 0x7F, 0xFE,
+    0x60, 0x66, 0x19, 0x87, 0xE6, 0x06, 0x7F, 0xFE, 0x60, 0x67, 0xE6, 0x1F, 0xE6, 0x06, 0x7F, 0xFE,
+    0x60, 0x67, 0xE6, 0x1F, 0xE6, 0x06, 0x7F, 0xFE, 0x7F, 0xE6, 0x67, 0x80, 0x67, 0xFE, 0x7F, 0xFE,
+    0x7F, 0xE6, 0x67, 0x80, 0x67, 0xFE, 0x7F, 0xFE, 0x00, 0x06, 0x66, 0x66, 0x60, 0x00, 0x7F, 0xFE,
+    0x00, 0x06, 0x66, 0x66, 0x60, 0x00, 0x7F, 0xFF, 0xFF, 0xFF, 0xFE, 0x61, 0xFF, 0xFF, 0xFF, 0xFF,
+    0xFF, 0xFF, 0xFE, 0x61, 0xFF, 0xFF, 0xFF, 0xFE, 0x00, 0x60, 0x06, 0x01, 0x99, 0x99, 0xFF, 0xFE,
+    0x00, 0x60, 0x06, 0x01, 0x99, 0x99, 0xFF, 0xFE, 0x01, 0x98, 0x1F, 0x9E, 0x79, 0xF9, 0xFF, 0xFE,
+    0x01, 0x98, 0x1F, 0x9E, 0x79, 0xF9, 0xFF, 0xFF, 0xE0, 0x66, 0x18, 0x61, 0x9F, 0x98, 0x7F, 0xFF,
+    0xE0, 0x66, 0x18, 0x61, 0x9F, 0x98, 0x7F, 0xFF, 0x98, 0x1E, 0x01, 0xE7, 0x99, 0xFE, 0x7F, 0xFF,
+    0x98, 0x1E, 0x01, 0xE7, 0x99, 0xFE, 0x7F, 0xFF, 0xE1, 0xE6, 0x19, 0xF8, 0x06, 0x60, 0x7F, 0xFF,
+    0xE1, 0xE6, 0x19, 0xF8, 0x06, 0x60, 0x7F, 0xFE, 0x19, 0xF8, 0x06, 0x1E, 0x79, 0x99, 0xFF, 0xFE,
+    0x19, 0xF8, 0x06, 0x1E, 0x79, 0x99, 0xFF, 0xFE, 0x7E, 0x01, 0xFF, 0x80, 0x18, 0x18, 0x7F, 0xFE,
+    0x7E, 0x01, 0xFF, 0x80, 0x18, 0x18, 0x7F, 0xFE, 0x7E, 0x19, 0x9E, 0x1E, 0x78, 0x7E, 0x7F, 0xFE,
+    0x7E, 0x19, 0x9E, 0x1E, 0x78, 0x7E, 0x7F, 0xFE, 0x60, 0x06, 0x66, 0x66, 0x00, 0x67, 0xFF, 0xFE,
+    0x60, 0x06, 0x66, 0x66, 0x00, 0x67, 0xFF, 0xFF, 0xFF, 0xFE, 0x67, 0xF8, 0x7E, 0x1F, 0xFF, 0xFF,
+    0xFF, 0xFE, 0x67, 0xF8, 0x7E, 0x1F, 0xFF, 0xFE, 0x00, 0x06, 0x00, 0x7E, 0x66, 0x60, 0x7F, 0xFE,
+    0x00, 0x06, 0x00, 0x7E, 0x66, 0x60, 0x7F, 0xFE, 0x7F, 0xE7, 0x99, 0xE6, 0x7E, 0x1E, 0x7F, 0xFE,
+    0x7F, 0xE7, 0x99, 0xE6, 0x7E, 0x1E, 0x7F, 0xFE, 0x60, 0x66, 0x61, 0xF8, 0x00, 0x60, 0x7F, 0xFE,
+    0x60, 0x66, 0x61, 0xF8, 0x00, 0x60, 0x7F, 0xFE, 0x60, 0x66, 0x06, 0x01, 0x86, 0x00, 0x7F, 0xFE,
+    0x60, 0x66, 0x06, 0x01, 0x86, 0x00, 0x7F, 0xFE, 0x60, 0x66, 0x67, 0x86, 0x7F, 0x86, 0x7F, 0xFE,
+    0x60, 0x66, 0x67, 0x86, 0x7F, 0x86, 0x7F, 0xFE, 0x7F, 0xE6, 0x66, 0x18, 0x00, 0x1E, 0x7F, 0xFE,
+    0x7F, 0xE6, 0x66, 0x18, 0x00, 0x1E, 0x7F, 0xFE, 0x00, 0x06, 0x66, 0x67, 0x98, 0x00, 0x7F, 0xFE,
+    0x00, 0x06, 0x66, 0x67, 0x98, 0x00, 0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+];
+
 /// Which dashboard badge is in view (drives the RX/TX indicator only).
 #[derive(Debug, Clone, Copy)]
 pub enum Badge {
@@ -57,6 +118,136 @@ pub enum Badge {
    Tx,
 }

+// ── Display content types (shared across all renderers) ───────────────
+//
+// `BoardInfo` and `DashboardCtx` describe *what* to draw on the splash
+// and dashboard screens. Each board's `BoardDisplay` impl decides *how*
+// to render that content for its native pixel format and resolution.
+
+/// Static-ish board identity rendered on the splash + dashboard.
+pub struct BoardInfo<'a> {
+    pub name: &'a str,
+    pub version: &'a str,
+    pub mac: &'a str,
+}
+
+/// Live dashboard data at the moment of a render call.
+pub struct DashboardCtx<'a> {
+    pub badge: Badge,
+    pub config: Option<LoRaConfig>,
+    pub rx_count: u32,
+    pub tx_count: u32,
+    pub last_rssi: Option<i16>,
+    pub last_snr: Option<i16>,
+    pub rssi_history: &'a [i16; RSSI_HISTORY_LEN],
+    pub tx_history: &'a [bool; RSSI_HISTORY_LEN],
+    pub rssi_count: usize,
+    pub current_slot_rssi: i16,
+    pub current_slot_tx: bool,
+    pub board: &'a BoardInfo<'a>,
+}
+
+// ── BoardDisplay trait ────────────────────────────────────────────────
+//
+// One logical display surface, four content states (splash×2, dashboard,
+// blank), plus brightness control and a flush hook. Each board's display
+// driver implements this directly — color depth, resolution, dimming
+// strategy, and any framebuffer flushing live behind the trait.
+
+/// Single trait every board's display driver implements. The display
+/// task talks to the trait; the per-driver impl handles native format.
+///
+/// `present()` is named distinctly from any inherent `flush()` method on
+/// concrete display types so method resolution doesn't get ambiguous.
+pub trait BoardDisplay {
+    fn present(&mut self) -> impl core::future::Future<Output = ()>;
+    fn set_bright(&mut self) -> impl core::future::Future<Output = ()>;
+    fn set_dim(&mut self) -> impl core::future::Future<Output = ()>;
+
+    fn render_splash_learn_more(&mut self);
+    fn render_splash_info(&mut self, info: &BoardInfo<'_>);
+    fn render_dashboard(&mut self, ctx: &DashboardCtx<'_>);
+    fn render_blank(&mut self);
+}
+
+// Color renderer module — used by `crate::driver::st7789::St7789Color` on
+// the Heltec T114 to draw native 240×135 Rgb565 dashboards/splash screens.
+// Gated to the T114 feature so other boards don't pay for the imports.
+#[cfg(feature = "heltec_mesh_node_t114")]
+pub mod render_color;
+
+// Shared QR-code blit, generic over color. Used by both the mono and
+// color splash screens to render the bitmap with proper quiet zones.
+mod qr;
+
+// ── Mono-OLED adapters ────────────────────────────────────────────────
+//
+// SH1106 + SSD1306Async both render `BinaryColor` content into a 128×64
+// framebuffer flushed via I2C. Their `BoardDisplay` impls all delegate
+// to `mod render` — the existing pixel-perfect mono renderer.
+
+#[cfg(any(
+    feature = "wio_tracker_l1",
+    feature = "elecrow_thinknode_m2",
+    feature = "lilygo_tbeam_supreme",
+    feature = "rak_wisblock_4631"
+))]
+impl<I> BoardDisplay for crate::driver::sh1106::Sh1106<I>
+where
+    I: embedded_hal_async::i2c::I2c,
+{
+    async fn present(&mut self) {
+        let _ = crate::driver::sh1106::Sh1106::flush(self).await;
+    }
+    async fn set_bright(&mut self) {
+        crate::driver::DisplayBrightness::set_bright(self).await;
+    }
+    async fn set_dim(&mut self) {
+        crate::driver::DisplayBrightness::set_dim(self).await;
+    }
+    fn render_splash_learn_more(&mut self) {
+        render::learn_more(self);
+    }
+    fn render_splash_info(&mut self, info: &BoardInfo<'_>) {
+        render::info(self, info);
+    }
+    fn render_dashboard(&mut self, ctx: &DashboardCtx<'_>) {
+        render::dashboard(self, ctx);
+    }
+    fn render_blank(&mut self) {
+        render::blank(self);
+    }
+}
+
+impl<DI, SIZE> BoardDisplay
+    for ssd1306::Ssd1306Async<DI, SIZE, ssd1306::mode::BufferedGraphicsModeAsync<SIZE>>
+where
+    DI: display_interface::AsyncWriteOnlyDataCommand,
+    SIZE: ssd1306::size::DisplaySizeAsync,
+{
+    async fn present(&mut self) {
+        let _ = ssd1306::Ssd1306Async::flush(self).await;
+    }
+    async fn set_bright(&mut self) {
+        crate::driver::DisplayBrightness::set_bright(self).await;
+    }
+    async fn set_dim(&mut self) {
+        crate::driver::DisplayBrightness::set_dim(self).await;
+    }
+    fn render_splash_learn_more(&mut self) {
+        render::learn_more(self);
+    }
+    fn render_splash_info(&mut self, info: &BoardInfo<'_>) {
+        render::info(self, info);
+    }
+    fn render_dashboard(&mut self, ctx: &DashboardCtx<'_>) {
+        render::dashboard(self, ctx);
+    }
+    fn render_blank(&mut self) {
+        render::blank(self);
+    }
+}
+
 /// Fine-grained events driving the `Display` statechart.
 #[derive(Debug, Clone)]
 pub enum DisplayEvent {
@@ -164,14 +355,14 @@ impl DisplayContext {
            version: VERSION,
            mac: mac_str,
        };
-        render::info(display, &info);
-        let _ = display.flush().await;
+        display.render_splash_info(&info);
+        display.present().await;
    }

    async fn flush_learn_more(&mut self) {
        let display = &mut self.peripherals.display;
-        render::learn_more(display);
-        let _ = display.flush().await;
+        display.render_splash_learn_more();
+        display.present().await;
    }

    async fn flush_dashboard(&mut self, badge: Badge) {
@@ -183,27 +374,28 @@ impl DisplayContext {
            version: VERSION,
            mac: mac_str,
        };
-        render::dashboard(
-            display,
+        let ctx = DashboardCtx {
            badge,
-            self.run.config,
-            self.run.rx_count,
-            self.run.tx_count,
-            self.run.last_rssi,
-            self.run.last_snr,
-            &self.run.rssi_history,
-            &self.run.tx_history,
-            self.run.rssi_count,
-            self.run.current_slot_rssi,
-            self.run.current_slot_tx,
-            &info,
-        );
-        let _ = display.flush().await;
+            config: self.run.config,
+            rx_count: self.run.rx_count,
+            tx_count: self.run.tx_count,
+            last_rssi: self.run.last_rssi,
+            last_snr: self.run.last_snr,
+            rssi_history: &self.run.rssi_history,
+            tx_history: &self.run.tx_history,
+            rssi_count: self.run.rssi_count,
+            current_slot_rssi: self.run.current_slot_rssi,
+            current_slot_tx: self.run.current_slot_tx,
+            board: &info,
+        };
+        display.render_dashboard(&ctx);
+        display.present().await;
    }

    async fn flush_blank(&mut self) {
-        render::blank(&mut self.peripherals.display);
-        let _ = self.peripherals.display.flush().await;
+        let display = &mut self.peripherals.display;
+        display.render_blank();
+        display.present().await;
    }

    // Boards without an LED use `LedDriver = ()`; the `RgbLed for ()` impl
@@ -237,6 +429,8 @@ statechart! {
    Display {
        context: DisplayContext;
        events: DisplayEvent;
+        // Auto-trace — backend selected by `hsmc/trace-*` cargo feature.
+        trace;
        default(On);

        state Off {
@@ -435,7 +629,7 @@ pub async fn display_task(
        ),
    );

-    let Some(display) = board::create_display(parts.i2c).await else {
+    let Some(display) = board::create_display(parts).await else {
        defmt::error!("display init failed, running LED-only loop");
        loop {
            match display_commands.receive().await {
@@ -489,7 +683,7 @@ pub async fn display_task(
 mod render {
    use core::fmt::Write;

-    use embedded_graphics::mono_font::ascii::{FONT_6X10, FONT_9X15_BOLD};
+    use embedded_graphics::mono_font::ascii::{FONT_5X8, FONT_6X10, FONT_9X15_BOLD};
    use embedded_graphics::mono_font::MonoTextStyle;
    use embedded_graphics::pixelcolor::BinaryColor;
    use embedded_graphics::prelude::*;
@@ -498,10 +692,8 @@ mod render {
    use embedded_graphics::text::{Alignment, Text};
    use heapless::String;

-    use super::Badge;
-    use crate::protocol::{LoRaBandwidth, LoRaConfig};
-
-    pub const RSSI_HISTORY_LEN: usize = 128;
+    use super::{Badge, BoardInfo, DashboardCtx, QR_WIDTH_PX, RSSI_HISTORY_LEN};
+    use crate::protocol::LoRaBandwidth;

    const CHAR_W: i32 = 6;
    const FONT_H: i32 = 10;
@@ -510,72 +702,20 @@ mod render {
    const RSSI_MIN: i16 = -120;
    const RSSI_MAX: i16 = 0;

-    /// Hand-authored 64 × 64 pixel-perfect QR bitmap for the splash
-    /// "learn more" screen. 1 bit/pixel, MSB-first, row-major. Bit `1` is
-    /// "light" (OLED pixel on), bit `0` is "dark" (OLED pixel off), so
-    /// when drawn with `BinaryColor::On` = lit, the QR appears with the
-    /// traditional dark-on-light look including a proper quiet zone.
-    const QR_WIDTH_PX: u32 = 64;
-    const QR_BITMAP: [u8; 512] = [
-        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
-        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
-        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
-        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFE, 0x00, 0x07, 0x9F,
-        0xFE, 0x60, 0x00, 0x7F, 0xFE, 0x00, 0x07, 0x9F, 0xFE, 0x60, 0x00, 0x7F, 0xFE, 0x7F, 0xE6,
-        0x18, 0x19, 0xE7, 0xFE, 0x7F, 0xFE, 0x7F, 0xE6, 0x18, 0x19, 0xE7, 0xFE, 0x7F, 0xFE, 0x60,
-        0x67, 0x81, 0xE6, 0x66, 0x06, 0x7F, 0xFE, 0x60, 0x67, 0x81, 0xE6, 0x66, 0x06, 0x7F, 0xFE,
-        0x60, 0x66, 0x19, 0x87, 0xE6, 0x06, 0x7F, 0xFE, 0x60, 0x66, 0x19, 0x87, 0xE6, 0x06, 0x7F,
-        0xFE, 0x60, 0x67, 0xE6, 0x1F, 0xE6, 0x06, 0x7F, 0xFE, 0x60, 0x67, 0xE6, 0x1F, 0xE6, 0x06,
-        0x7F, 0xFE, 0x7F, 0xE6, 0x67, 0x80, 0x67, 0xFE, 0x7F, 0xFE, 0x7F, 0xE6, 0x67, 0x80, 0x67,
-        0xFE, 0x7F, 0xFE, 0x00, 0x06, 0x66, 0x66, 0x60, 0x00, 0x7F, 0xFE, 0x00, 0x06, 0x66, 0x66,
-        0x60, 0x00, 0x7F, 0xFF, 0xFF, 0xFF, 0xFE, 0x61, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFE,
-        0x61, 0xFF, 0xFF, 0xFF, 0xFE, 0x00, 0x60, 0x06, 0x01, 0x99, 0x99, 0xFF, 0xFE, 0x00, 0x60,
-        0x06, 0x01, 0x99, 0x99, 0xFF, 0xFE, 0x01, 0x98, 0x1F, 0x9E, 0x79, 0xF9, 0xFF, 0xFE, 0x01,
-        0x98, 0x1F, 0x9E, 0x79, 0xF9, 0xFF, 0xFF, 0xE0, 0x66, 0x18, 0x61, 0x9F, 0x98, 0x7F, 0xFF,
-        0xE0, 0x66, 0x18, 0x61, 0x9F, 0x98, 0x7F, 0xFF, 0x98, 0x1E, 0x01, 0xE7, 0x99, 0xFE, 0x7F,
-        0xFF, 0x98, 0x1E, 0x01, 0xE7, 0x99, 0xFE, 0x7F, 0xFF, 0xE1, 0xE6, 0x19, 0xF8, 0x06, 0x60,
-        0x7F, 0xFF, 0xE1, 0xE6, 0x19, 0xF8, 0x06, 0x60, 0x7F, 0xFE, 0x19, 0xF8, 0x06, 0x1E, 0x79,
-        0x99, 0xFF, 0xFE, 0x19, 0xF8, 0x06, 0x1E, 0x79, 0x99, 0xFF, 0xFE, 0x7E, 0x01, 0xFF, 0x80,
-        0x18, 0x18, 0x7F, 0xFE, 0x7E, 0x01, 0xFF, 0x80, 0x18, 0x18, 0x7F, 0xFE, 0x7E, 0x19, 0x9E,
-        0x1E, 0x78, 0x7E, 0x7F, 0xFE, 0x7E, 0x19, 0x9E, 0x1E, 0x78, 0x7E, 0x7F, 0xFE, 0x60, 0x06,
-        0x66, 0x66, 0x00, 0x67, 0xFF, 0xFE, 0x60, 0x06, 0x66, 0x66, 0x00, 0x67, 0xFF, 0xFF, 0xFF,
-        0xFE, 0x67, 0xF8, 0x7E, 0x1F, 0xFF, 0xFF, 0xFF, 0xFE, 0x67, 0xF8, 0x7E, 0x1F, 0xFF, 0xFE,
-        0x00, 0x06, 0x00, 0x7E, 0x66, 0x60, 0x7F, 0xFE, 0x00, 0x06, 0x00, 0x7E, 0x66, 0x60, 0x7F,
-        0xFE, 0x7F, 0xE7, 0x99, 0xE6, 0x7E, 0x1E, 0x7F, 0xFE, 0x7F, 0xE7, 0x99, 0xE6, 0x7E, 0x1E,
-        0x7F, 0xFE, 0x60, 0x66, 0x61, 0xF8, 0x00, 0x60, 0x7F, 0xFE, 0x60, 0x66, 0x61, 0xF8, 0x00,
-        0x60, 0x7F, 0xFE, 0x60, 0x66, 0x06, 0x01, 0x86, 0x00, 0x7F, 0xFE, 0x60, 0x66, 0x06, 0x01,
-        0x86, 0x00, 0x7F, 0xFE, 0x60, 0x66, 0x67, 0x86, 0x7F, 0x86, 0x7F, 0xFE, 0x60, 0x66, 0x67,
-        0x86, 0x7F, 0x86, 0x7F, 0xFE, 0x7F, 0xE6, 0x66, 0x18, 0x00, 0x1E, 0x7F, 0xFE, 0x7F, 0xE6,
-        0x66, 0x18, 0x00, 0x1E, 0x7F, 0xFE, 0x00, 0x06, 0x66, 0x67, 0x98, 0x00, 0x7F, 0xFE, 0x00,
-        0x06, 0x66, 0x67, 0x98, 0x00, 0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
-        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
-        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
-        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
-        0xFF, 0xFF,
-    ];

-    pub struct BoardInfo<'a> {
-        pub name: &'a str,
-        pub version: &'a str,
-        pub mac: &'a str,
-    }
-
-    #[allow(clippy::too_many_arguments)]
-    pub fn dashboard(
-        target: &mut impl DrawTarget<Color = BinaryColor>,
-        badge: Badge,
-        config: Option<LoRaConfig>,
-        rx_count: u32,
-        tx_count: u32,
-        last_rssi: Option<i16>,
-        last_snr: Option<i16>,
-        rssi_history: &[i16; RSSI_HISTORY_LEN],
-        tx_history: &[bool; RSSI_HISTORY_LEN],
-        rssi_count: usize,
-        current_slot_rssi: i16,
-        current_slot_tx: bool,
-        board: &BoardInfo,
-    ) {
+    pub fn dashboard(target: &mut impl DrawTarget<Color = BinaryColor>, ctx: &DashboardCtx<'_>) {
+        let badge = ctx.badge;
+        let config = ctx.config;
+        let rx_count = ctx.rx_count;
+        let tx_count = ctx.tx_count;
+        let last_rssi = ctx.last_rssi;
+        let last_snr = ctx.last_snr;
+        let rssi_history = ctx.rssi_history;
+        let tx_history = ctx.tx_history;
+        let rssi_count = ctx.rssi_count;
+        let current_slot_rssi = ctx.current_slot_rssi;
+        let current_slot_tx = ctx.current_slot_tx;
+        let board = ctx.board;
        let bb = target.bounding_box();
        let w = bb.size.width as i32;
        let h = bb.size.height as i32;
@@ -769,14 +909,31 @@ mod render {
            .draw(target)
            .ok();

-        Text::with_alignment(
-            board.name,
-            Point::new(center_x, 28),
-            style,
-            Alignment::Center,
-        )
-        .draw(target)
-        .ok();
+        // Board-name font picked at compile time by
+        // BOARD_NAME_FITS_PRIMARY_FONT (see top of display.rs). If the
+        // name fits FONT_6X10 we use it; otherwise we fall back to
+        // FONT_5X8. The const_assert at the BOARD_NAME definition
+        // rejects names that overflow even the fallback.
+        if super::BOARD_NAME_FITS_PRIMARY_FONT {
+            Text::with_alignment(
+                board.name,
+                Point::new(center_x, 28),
+                style,
+                Alignment::Center,
+            )
+            .draw(target)
+            .ok();
+        } else {
+            let small_style = MonoTextStyle::new(&FONT_5X8, BinaryColor::On);
+            Text::with_alignment(
+                board.name,
+                Point::new(center_x, 28),
+                small_style,
+                Alignment::Center,
+            )
+            .draw(target)
+            .ok();
+        }

        Text::with_alignment(
            board.mac,
@@ -798,28 +955,35 @@ mod render {
    }

    /// Alternate splash screen: 64 × 64 pixel-perfect QR bitmap on the
-    /// right (with its own quiet zone baked in), centered text column on
-    /// the left inviting the user to visit the URL.
+    /// right (centered within its quiet zone via `super::qr::draw`),
+    /// centered text column on the left inviting the user to visit the URL.
    pub fn learn_more(target: &mut impl DrawTarget<Color = BinaryColor>) {
-        use embedded_graphics::image::{Image, ImageRaw};
-        use embedded_graphics::mono_font::ascii::{FONT_5X8, FONT_7X14_BOLD};
+        use embedded_graphics::mono_font::ascii::{FONT_4X6, FONT_7X14_BOLD};

        let bb = target.bounding_box();
        let w = bb.size.width as i32;

        let _ = target.clear(BinaryColor::Off);

-        // ── QR code: flush to the right edge, 1:1 pixel rendering ───
+        // ── QR code: rightmost 64 × 64 region, centered cells ───────
        let qr_x = w - QR_WIDTH_PX as i32;
-        let qr_raw: ImageRaw<BinaryColor> = ImageRaw::new(&QR_BITMAP, QR_WIDTH_PX);
-        Image::new(&qr_raw, Point::new(qr_x, 0)).draw(target).ok();
+        super::qr::draw(
+            target,
+            Point::new(qr_x, 0),
+            BinaryColor::On,
+            BinaryColor::Off,
+        );

        // ── Text column (everything left of the QR) ─────────────────
        let col_w = qr_x;
        let col_center = col_w / 2;

        let title_style = MonoTextStyle::new(&FONT_7X14_BOLD, BinaryColor::On);
-        let text_style = MonoTextStyle::new(&FONT_5X8, BinaryColor::On);
+        // FONT_4X6 (4 px advance) on the URL line so "donglora.com"
+        // (12 chars × 4 = 48 px) fits the 64 px left column with ~8 px
+        // breathing room either side, instead of FONT_5X8's 60 px which
+        // visually touches both edges.
+        let text_style = MonoTextStyle::new(&FONT_4X6, BinaryColor::On);

        // Layout on a 64 px display:
        //   blank
@@ -0,0 +1,74 @@
+//! Shared QR-code blit for splash screens.
+//!
+//! The 512-byte QR bitmap in the parent module is laid out asymmetrically
+//! within its 64×64 frame: rows 0-6 and 57-63 are top/bottom quiet zones,
+//! but the QR cells start at col 0 (no left quiet zone) and extend to
+//! col ~49, leaving ~14 px of white padding on the right plus one stray
+//! black pixel at col 63. Rendering the bitmap as-is leaves the QR
+//! visually shifted toward the left of its rendering area, which looks
+//! wrong on any layout that doesn't tuck the bitmap flush against a
+//! screen edge.
+//!
+//! [`draw`] re-centers the QR data: it skips the bitmap's right padding
+//! (cols 50-63), fills the rendering area's left and right 7 px with
+//! the foreground "quiet zone" color, and renders the actual QR cells
+//! (bitmap cols 0..50) at +7 horizontal offset. Rows are rendered as-is
+//! so the bitmap's existing top/bottom quiet zones land where expected.
+//!
+//! Generic over color so the mono renderer (`BinaryColor`) and the
+//! T114's color renderer (`Rgb565`) share a single implementation —
+//! they pass their own foreground (white / lit) and background (black /
+//! unlit) values.
+
+use embedded_graphics::draw_target::DrawTarget;
+use embedded_graphics::geometry::{Point, Size};
+use embedded_graphics::pixelcolor::PixelColor;
+use embedded_graphics::primitives::Rectangle;
+use embedded_graphics::Pixel;
+
+use super::{QR_BITMAP, QR_WIDTH_PX};
+
+/// Width of the actual QR data within the bitmap (cols 0..QR_DATA_W).
+const QR_DATA_W: i32 = 50;
+/// White padding on left + right to center the QR cells. With
+/// QR_DATA_W=50 and total area=64 (= QR_WIDTH_PX), padding = 7 each side.
+const PAD_X: i32 = (QR_WIDTH_PX as i32 - QR_DATA_W) / 2;
+
+/// Render the 64×64 QR with proper quiet zones on all four sides.
+///
+/// `fg` is the "quiet zone / light cell" color (white on a TFT, "on"
+/// on a mono OLED). `bg` is the "dark cell" color. Bitmap rows 0-6 and
+/// 57-63 already encode top/bottom quiet zones in `fg`; this function
+/// fills the missing left/right padding columns explicitly.
+pub fn draw<D, C>(target: &mut D, origin: Point, fg: C, bg: C)
+where
+    D: DrawTarget<Color = C>,
+    C: PixelColor,
+{
+    // Fill left padding (cols 0..PAD_X) with fg.
+    let _ = target.fill_solid(
+        &Rectangle::new(origin, Size::new(PAD_X as u32, QR_WIDTH_PX)),
+        fg,
+    );
+    // Fill right padding (cols PAD_X+QR_DATA_W..QR_WIDTH_PX) with fg.
+    let right_pad_w = QR_WIDTH_PX as i32 - PAD_X - QR_DATA_W;
+    let _ = target.fill_solid(
+        &Rectangle::new(
+            Point::new(origin.x + PAD_X + QR_DATA_W, origin.y),
+            Size::new(right_pad_w as u32, QR_WIDTH_PX),
+        ),
+        fg,
+    );
+
+    // Render bitmap cols 0..QR_DATA_W at +PAD_X horizontal offset.
+    let bytes_per_row = (QR_WIDTH_PX / 8) as usize;
+    let pixels = (0..QR_WIDTH_PX as i32).flat_map(move |y| {
+        (0..QR_DATA_W).map(move |x| {
+            let byte = QR_BITMAP[y as usize * bytes_per_row + (x as usize) / 8];
+            let bit = (byte >> (7 - (x as u8 & 7))) & 1;
+            let color = if bit == 1 { fg } else { bg };
+            Pixel(Point::new(origin.x + PAD_X + x, origin.y + y), color)
+        })
+    });
+    let _ = target.draw_iter(pixels);
+}
@@ -0,0 +1,422 @@
+//! Native 240×135 Rgb565 renderer for the Heltec T114 ST7789 panel.
+//!
+//! Mirrors the content shape of the mono OLED renderer in `display::render`
+//! (same `BoardInfo` / `DashboardCtx` inputs) but lays things out for the
+//! T114's bigger color screen with native font sizes and colored badges.
+//! Each board's `BoardDisplay` impl picks the renderer that matches its
+//! native pixel format — no per-pixel color quantization, no scaling,
+//! no aliasing.
+
+use core::fmt::Write;
+
+use embedded_graphics::mono_font::ascii::{
+    FONT_6X10, FONT_8X13, FONT_8X13_BOLD, FONT_9X15_BOLD, FONT_10X20,
+};
+use embedded_graphics::mono_font::MonoTextStyle;
+use embedded_graphics::pixelcolor::Rgb565;
+use embedded_graphics::prelude::*;
+use embedded_graphics::primitives::{Line, PrimitiveStyle, Rectangle};
+use embedded_graphics::text::renderer::CharacterStyle;
+use embedded_graphics::text::{Alignment, Text};
+use heapless::String;
+
+use super::{qr, Badge, BoardInfo, DashboardCtx, QR_WIDTH_PX, RSSI_HISTORY_LEN};
+use crate::protocol::LoRaBandwidth;
+
+// ── Panel dimensions ──────────────────────────────────────────────────
+
+const W: i32 = 240;
+const H: i32 = 135;
+
+// ── Palette ───────────────────────────────────────────────────────────
+
+const BG: Rgb565 = Rgb565::BLACK;
+const FG: Rgb565 = Rgb565::WHITE;
+const DIM: Rgb565 = Rgb565::new(12, 24, 12); // muted gray
+const ACCENT: Rgb565 = Rgb565::new(8, 30, 31); // bright cyan
+const RX_COLOR: Rgb565 = Rgb565::new(8, 60, 8); // bright green
+const TX_COLOR: Rgb565 = Rgb565::new(31, 16, 8); // amber-red
+const SPARK_COLOR: Rgb565 = Rgb565::new(20, 50, 24); // soft green
+
+// ── Sparkline ────────────────────────────────────────────────────────
+
+const RSSI_MIN: i16 = -120;
+const RSSI_MAX: i16 = 0;
+/// Sentinel: no packet received in this slot. Mirrors `display::NO_SIGNAL`.
+const NO_SIGNAL: i16 = -121;
+
+// ── Public render entry points ────────────────────────────────────────
+
+pub fn blank<D: DrawTarget<Color = Rgb565>>(target: &mut D) {
+    let _ = target.clear(BG);
+}
+
+pub fn splash_learn_more<D: DrawTarget<Color = Rgb565>>(target: &mut D) {
+    let _ = target.clear(BG);
+
+    // QR pinned to the right side, vertically centered. 64×64 fits with
+    // ~36 px headroom top/bottom on the 135-tall panel.
+    let qr_w = QR_WIDTH_PX as i32;
+    let qr_x = W - qr_w - 8;
+    let qr_y = (H - qr_w) / 2;
+    qr::draw(target, Point::new(qr_x, qr_y), FG, BG);
+
+    // Text column to the left of the QR.
+    let col_w = qr_x - 8;
+    let col_center = col_w / 2 + 4;
+
+    let title_style = MonoTextStyle::new(&FONT_10X20, ACCENT);
+    let url_style = MonoTextStyle::new(&FONT_8X13, FG);
+    let caption_style = MonoTextStyle::new(&FONT_6X10, DIM);
+
+    let _ = Text::with_alignment(
+        "DongLoRa",
+        Point::new(col_center, 45),
+        title_style,
+        Alignment::Center,
+    )
+    .draw(target);
+
+    let _ = Text::with_alignment(
+        "donglora.com",
+        Point::new(col_center, 73),
+        url_style,
+        Alignment::Center,
+    )
+    .draw(target);
+
+    let _ = Text::with_alignment(
+        "Scan for docs",
+        Point::new(col_center, 95),
+        caption_style,
+        Alignment::Center,
+    )
+    .draw(target);
+}
+
+pub fn splash_info<D: DrawTarget<Color = Rgb565>>(target: &mut D, info: &BoardInfo<'_>) {
+    let _ = target.clear(BG);
+
+    let title_style = MonoTextStyle::new(&FONT_10X20, ACCENT);
+    let board_style = MonoTextStyle::new(&FONT_9X15_BOLD, FG);
+    let mac_style = MonoTextStyle::new(&FONT_8X13, FG);
+    let small_style = MonoTextStyle::new(&FONT_6X10, DIM);
+
+    // Title at top.
+    let _ = Text::with_alignment(
+        "DongLoRa",
+        Point::new(W / 2, 22),
+        title_style,
+        Alignment::Center,
+    )
+    .draw(target);
+
+    // Board name.
+    let _ = Text::with_alignment(
+        info.name,
+        Point::new(W / 2, 50),
+        board_style,
+        Alignment::Center,
+    )
+    .draw(target);
+
+    // MAC.
+    let _ = Text::with_alignment(
+        info.mac,
+        Point::new(W / 2, 75),
+        mac_style,
+        Alignment::Center,
+    )
+    .draw(target);
+
+    // Version.
+    let mut version_buf: String<24> = String::new();
+    let _ = write!(version_buf, "v{}", info.version);
+    let _ = Text::with_alignment(
+        &version_buf,
+        Point::new(W / 2, 95),
+        small_style,
+        Alignment::Center,
+    )
+    .draw(target);
+
+    // Waiting line.
+    let _ = Text::with_alignment(
+        "Waiting for host...",
+        Point::new(W / 2, 120),
+        small_style,
+        Alignment::Center,
+    )
+    .draw(target);
+}
+
+pub fn dashboard<D: DrawTarget<Color = Rgb565>>(target: &mut D, ctx: &DashboardCtx<'_>) {
+    let _ = target.clear(BG);
+
+    // ── Top bar (badge + radio config) ──────────────────────────
+    let top_h = 24;
+    let badge_w = 38;
+    let (badge_color, badge_text) = match ctx.badge {
+        Badge::Rx => (RX_COLOR, "RX"),
+        Badge::Tx => (TX_COLOR, "TX"),
+    };
+
+    let badge_rect = Rectangle::new(Point::zero(), Size::new(badge_w as u32, top_h as u32));
+    let _ = badge_rect
+        .into_styled(PrimitiveStyle::with_fill(badge_color))
+        .draw(target);
+
+    let mut badge_style = MonoTextStyle::new(&FONT_8X13_BOLD, FG);
+    badge_style.set_background_color(Some(badge_color));
+    let _ = Text::with_alignment(
+        badge_text,
+        Point::new(badge_w / 2, 16),
+        badge_style,
+        Alignment::Center,
+    )
+    .draw(target);
+
+    // Radio config text right of the badge.
+    let cfg_style = MonoTextStyle::new(&FONT_8X13, FG);
+    let mut buf: String<48> = String::new();
+    if let Some(cfg) = ctx.config {
+        let bw_str = bw_label(cfg.bw);
+        let cr_str = cr_label(cfg.cr);
+        let freq_mhz = cfg.freq_hz / 1_000_000;
+        let freq_khz = (cfg.freq_hz % 1_000_000) / 1_000;
+        let _ = write!(
+            buf,
+            "{}.{:03} {} SF{} CR{}",
+            freq_mhz, freq_khz, bw_str, cfg.sf, cr_str
+        );
+    } else {
+        let _ = write!(buf, "Awaiting config");
+    }
+    let _ = Text::with_alignment(
+        &buf,
+        Point::new(W - 4, 16),
+        cfg_style,
+        Alignment::Right,
+    )
+    .draw(target);
+
+    // Separator line under top bar.
+    let _ = Line::new(Point::new(0, top_h + 1), Point::new(W - 1, top_h + 1))
+        .into_styled(PrimitiveStyle::with_stroke(DIM, 1))
+        .draw(target);
+
+    // ── Bottom bar (counters + RSSI) ───────────────────────────
+    let bottom_h = 30;
+    let bottom_top = H - bottom_h;
+    let _ = Line::new(
+        Point::new(0, bottom_top - 1),
+        Point::new(W - 1, bottom_top - 1),
+    )
+    .into_styled(PrimitiveStyle::with_stroke(DIM, 1))
+    .draw(target);
+
+    let stat_style = MonoTextStyle::new(&FONT_8X13, FG);
+
+    let mut rxtx_buf: String<24> = String::new();
+    let _ = write!(
+        rxtx_buf,
+        "RX {} TX {}",
+        compact_count(ctx.rx_count).as_str(),
+        compact_count(ctx.tx_count).as_str()
+    );
+    let _ = Text::with_alignment(
+        &rxtx_buf,
+        Point::new(4, bottom_top + 11),
+        stat_style,
+        Alignment::Left,
+    )
+    .draw(target);
+
+    let mut rssi_buf: String<32> = String::new();
+    match (ctx.last_rssi, ctx.last_snr) {
+        (Some(rssi), Some(snr)) => {
+            let _ = write!(rssi_buf, "{} dBm  SNR {}", rssi, snr);
+        }
+        (Some(rssi), None) => {
+            let _ = write!(rssi_buf, "{} dBm", rssi);
+        }
+        _ => {
+            let _ = write!(rssi_buf, "no signal");
+        }
+    }
+    let _ = Text::with_alignment(
+        &rssi_buf,
+        Point::new(W - 4, bottom_top + 11),
+        stat_style,
+        Alignment::Right,
+    )
+    .draw(target);
+
+    let secondary = MonoTextStyle::new(&FONT_6X10, DIM);
+    let _ = Text::with_alignment(
+        ctx.board.mac,
+        Point::new(W / 2, bottom_top + 25),
+        secondary,
+        Alignment::Center,
+    )
+    .draw(target);
+
+    // ── Sparkline ──────────────────────────────────────────────
+    let spark_top = top_h + 4;
+    let spark_h = (bottom_top - 2) - spark_top;
+    if spark_h > 0 {
+        // 240 wide / 2 px per bar = 120 visible bars (subset of the
+        // 128-slot ring). Matches the mono renderer's
+        // `visible_bars = w / 2` heuristic.
+        let visible_bars = ((W / 2) as usize).min(RSSI_HISTORY_LEN);
+        rssi_sparkline(
+            target,
+            ctx.rssi_history,
+            ctx.tx_history,
+            ctx.rssi_count,
+            ctx.current_slot_rssi,
+            ctx.current_slot_tx,
+            spark_top,
+            spark_h,
+            visible_bars,
+        );
+    }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+fn bw_label(bw: LoRaBandwidth) -> &'static str {
+    match bw {
+        LoRaBandwidth::Khz7 => "7.8k",
+        LoRaBandwidth::Khz10 => "10.4k",
+        LoRaBandwidth::Khz15 => "15.6k",
+        LoRaBandwidth::Khz20 => "20.8k",
+        LoRaBandwidth::Khz31 => "31.2k",
+        LoRaBandwidth::Khz41 => "41.7k",
+        LoRaBandwidth::Khz62 => "62.5k",
+        LoRaBandwidth::Khz125 => "125k",
+        LoRaBandwidth::Khz250 => "250k",
+        LoRaBandwidth::Khz500 => "500k",
+        LoRaBandwidth::Khz200 => "200k",
+        LoRaBandwidth::Khz400 => "400k",
+        LoRaBandwidth::Khz800 => "800k",
+        LoRaBandwidth::Khz1600 => "1.6M",
+    }
+}
+
+fn cr_label(cr: crate::protocol::LoRaCodingRate) -> &'static str {
+    match cr {
+        crate::protocol::LoRaCodingRate::Cr4_5 => "5",
+        crate::protocol::LoRaCodingRate::Cr4_6 => "6",
+        crate::protocol::LoRaCodingRate::Cr4_7 => "7",
+        crate::protocol::LoRaCodingRate::Cr4_8 => "8",
+    }
+}
+
+fn compact_count(n: u32) -> String<10> {
+    let mut s: String<10> = String::new();
+    if n > 9_999_999 {
+        let _ = write!(s, "{}M", n / 1_000_000);
+    } else if n > 999_999 {
+        let _ = write!(s, "{}k", n / 1_000);
+    } else {
+        let _ = write!(s, "{}", n);
+    }
+    s
+}
+
+#[allow(clippy::too_many_arguments)]
+fn rssi_sparkline<D: DrawTarget<Color = Rgb565>>(
+    target: &mut D,
+    history: &[i16; RSSI_HISTORY_LEN],
+    tx_history: &[bool; RSSI_HISTORY_LEN],
+    count: usize,
+    current_rssi: i16,
+    current_tx: bool,
+    spark_top: i32,
+    spark_h: i32,
+    visible_bars: usize,
+) {
+    let live = current_rssi > RSSI_MIN || current_tx;
+    let committed = count.min(RSSI_HISTORY_LEN);
+    let hist_slots = if live {
+        committed.min(visible_bars.saturating_sub(1))
+    } else {
+        committed.min(visible_bars)
+    };
+    let total = hist_slots + if live { 1 } else { 0 };
+
+    if total == 0 {
+        return;
+    }
+
+    for i in 0..hist_slots {
+        let idx = if count <= RSSI_HISTORY_LEN {
+            let effective_bars = if live { visible_bars - 1 } else { visible_bars };
+            i + committed.saturating_sub(effective_bars)
+        } else {
+            let start = count - RSSI_HISTORY_LEN;
+            let skip = RSSI_HISTORY_LEN.saturating_sub(if live {
+                visible_bars - 1
+            } else {
+                visible_bars
+            });
+            (start + skip + i) % RSSI_HISTORY_LEN
+        };
+        let is_tx = tx_history[idx];
+        let rssi = history[idx];
+
+        if let Some(bar_h) = bar_height(rssi, is_tx, spark_h) {
+            let x = (visible_bars - total + i) as i32 * 2;
+            draw_bar(target, x, bar_h, is_tx, spark_top, spark_h);
+        }
+    }
+
+    if live {
+        if let Some(bar_h) = bar_height(current_rssi, current_tx, spark_h) {
+            let x = (visible_bars - 1) as i32 * 2;
+            draw_bar(target, x, bar_h, current_tx, spark_top, spark_h);
+        }
+    }
+}
+
+fn bar_height(rssi: i16, is_tx: bool, spark_h: i32) -> Option<i32> {
+    let h = if rssi <= RSSI_MIN || rssi == NO_SIGNAL {
+        if is_tx {
+            spark_h / 3
+        } else {
+            return None;
+        }
+    } else {
+        let clamped = rssi.clamp(RSSI_MIN, RSSI_MAX);
+        ((clamped - RSSI_MIN) as i32 * spark_h) / (RSSI_MAX - RSSI_MIN) as i32
+    };
+    if h == 0 { None } else { Some(h) }
+}
+
+fn draw_bar<D: DrawTarget<Color = Rgb565>>(
+    target: &mut D,
+    x: i32,
+    bar_h: i32,
+    is_tx: bool,
+    spark_top: i32,
+    spark_h: i32,
+) {
+    let y = spark_top + spark_h - bar_h;
+    let color = if is_tx { TX_COLOR } else { SPARK_COLOR };
+    if is_tx {
+        // Hatched bar — every other pixel row — mirrors the mono
+        // renderer's TX visual cue.
+        for row in 0..bar_h {
+            if row % 2 == 0 {
+                let _ = Rectangle::new(Point::new(x, y + row), Size::new(2, 1))
+                    .into_styled(PrimitiveStyle::with_fill(color))
+                    .draw(target);
+            }
+        }
+    } else {
+        let _ = Rectangle::new(Point::new(x, y), Size::new(2, bar_h as u32))
+            .into_styled(PrimitiveStyle::with_fill(color))
+            .draw(target);
+    }
+}
@@ -0,0 +1,121 @@
+//! AXP PMIC init — turn on the rails that feed LoRa and the OLED.
+//!
+//! T-Beam–class boards gate LoRa, OLED (and GPS/sensors, which this firmware
+//! does not use) through an X-Powers PMIC on I²C. Until the PMIC is told to
+//! enable the right LDOs/DCDCs, the SX126x/SX127x chip sits unpowered and
+//! `LoRa::new` fails. This module's only job is to flip those switches.
+//!
+//! Two PMICs are covered:
+//!
+//! * [`axp2101_init_lora_oled`] — LilyGo T-Beam S3 Supreme. ALDO3 = 3.3 V
+//!   feeds the SX1262; ALDO1 = 3.3 V feeds the SH1106 OLED. Both live on a
+//!   dedicated I²C1 bus (separate from the display).
+//! * [`axp192_init_lora_oled`] — LilyGo T-Beam (classic). LDO2 = 3.3 V feeds
+//!   the SX1276; DCDC1 = 3.3 V feeds the SSD1306 OLED. PMIC shares the
+//!   display I²C bus.
+//!
+//! Everything unrelated to LoRa + OLED (GPS, sensors, SD, batt ADC) is left
+//! alone. Out-of-scope for a transparent LoRa-over-USB bridge.
+//!
+//! Init is blocking on purpose. It runs once during `into_parts`, which is a
+//! synchronous function called before task spawning. Using the blocking
+//! `embedded_hal` trait keeps the PMIC wiring out of the async machinery and
+//! lets the caller drop the I²C bus immediately after init (no bus handoff).
+
+use embedded_hal::i2c::I2c;
+
+/// Both chips respond at this 7-bit I²C address.
+const PMIC_ADDR: u8 = 0x34;
+
+// ── AXP2101 (T-Beam S3 Supreme) ──────────────────────────────────────
+
+#[cfg(feature = "lilygo_tbeam_supreme")]
+mod axp2101 {
+    use super::{I2c, PMIC_ADDR};
+
+    /// LDO on/off control register. Bits:
+    ///   0 = ALDO1, 1 = ALDO2, 2 = ALDO3, 3 = ALDO4, 4 = BLDO1, 5 = BLDO2.
+    const REG_LDO_ONOFF: u8 = 0x90;
+    /// ALDO1 voltage register (OLED rail on T-Beam Supreme).
+    const REG_ALDO1_V: u8 = 0x92;
+    /// ALDO3 voltage register (LoRa rail on T-Beam Supreme).
+    const REG_ALDO3_V: u8 = 0x94;
+
+    /// Voltage code for 3.3 V on ALDOx: 0.5 V + 28 × 100 mV.
+    const V_3V3: u8 = 28;
+
+    /// Mask enabling ALDO1 + ALDO3 in [`REG_LDO_ONOFF`].
+    const ALDO1_ALDO3: u8 = 0b0000_0101;
+
+    /// Bring up LoRa (ALDO3) and OLED (ALDO1) rails at 3.3 V.
+    ///
+    /// Voltage registers are set before the enable bits to avoid glitching
+    /// the rails through the reset-default voltage. Other rails are left
+    /// untouched (read-modify-write on the enable register) so any
+    /// board-specific OTP defaults stay intact.
+    pub fn init_lora_oled<I: I2c>(i2c: &mut I) -> Result<(), I::Error> {
+        i2c.write(PMIC_ADDR, &[REG_ALDO3_V, V_3V3])?;
+        i2c.write(PMIC_ADDR, &[REG_ALDO1_V, V_3V3])?;
+
+        let mut onoff = [0u8; 1];
+        i2c.write_read(PMIC_ADDR, &[REG_LDO_ONOFF], &mut onoff)?;
+        i2c.write(PMIC_ADDR, &[REG_LDO_ONOFF, onoff[0] | ALDO1_ALDO3])?;
+
+        Ok(())
+    }
+}
+
+#[cfg(feature = "lilygo_tbeam_supreme")]
+pub use axp2101::init_lora_oled as axp2101_init_lora_oled;
+
+// ── AXP192 (T-Beam classic) ──────────────────────────────────────────
+
+#[cfg(feature = "lilygo_tbeam")]
+mod axp192 {
+    use super::{I2c, PMIC_ADDR};
+
+    /// DCDC/LDO enable register. Bit layout:
+    ///   0 = DCDC1, 1 = DCDC3, 2 = LDO2, 3 = LDO3, 4 = DCDC2, 6 = EXTEN.
+    const REG_ONOFF: u8 = 0x12;
+    /// DCDC1 output voltage register (OLED rail on T-Beam classic).
+    /// 7-bit code, 25 mV step, 0.7 V offset → 3.3 V = 104 = `0x68`.
+    const REG_DCDC1_V: u8 = 0x26;
+    /// LDO2/LDO3 voltage register. Upper nibble = LDO2 (LoRa), lower nibble
+    /// = LDO3 (GPS). 100 mV step, 1.8 V offset → 3.3 V = 15 = `0xF`.
+    const REG_LDO23_V: u8 = 0x28;
+
+    /// DCDC1 code for 3.3 V.
+    const DCDC1_3V3: u8 = 0x68;
+    /// LDO2 nibble for 3.3 V in the upper half of [`REG_LDO23_V`].
+    const LDO2_3V3_UPPER: u8 = 0xF0;
+
+    /// Mask enabling DCDC1 + LDO2 in [`REG_ONOFF`].
+    const DCDC1_LDO2: u8 = 0b0000_0101;
+
+    /// Bring up LoRa (LDO2) and OLED (DCDC1) rails at 3.3 V on the
+    /// classic T-Beam's AXP192.
+    ///
+    /// GPS (LDO3) and EXTEN are not touched — this firmware has no GPS,
+    /// and any board-default for LDO3 voltage is preserved by
+    /// read-modify-write. Voltage is programmed before the enable bit
+    /// flips so the rail doesn't glitch through its reset default.
+    pub fn init_lora_oled<I: I2c>(i2c: &mut I) -> Result<(), I::Error> {
+        let mut ldo23 = [0u8; 1];
+        i2c.write_read(PMIC_ADDR, &[REG_LDO23_V], &mut ldo23)?;
+        i2c.write(
+            PMIC_ADDR,
+            &[REG_LDO23_V, (ldo23[0] & 0x0F) | LDO2_3V3_UPPER],
+        )?;
+
+        i2c.write(PMIC_ADDR, &[REG_DCDC1_V, DCDC1_3V3])?;
+
+        let mut onoff = [0u8; 1];
+        i2c.write_read(PMIC_ADDR, &[REG_ONOFF], &mut onoff)?;
+        i2c.write(PMIC_ADDR, &[REG_ONOFF, onoff[0] | DCDC1_LDO2])?;
+
+        Ok(())
+    }
+}
+
+#[cfg(feature = "lilygo_tbeam")]
+pub use axp192::init_lora_oled as axp192_init_lora_oled;
@@ -0,0 +1,30 @@
+//! Generic `OutputPin` wrapper that inverts logic levels.
+//!
+//! When a peripheral is wired active-low (LED anode to V+, cathode to GPIO;
+//! reset line idle-high, etc.) the physical polarity is a property of the
+//! board, not of the driver. Wrapping the pin in `InvertedPin` lets drivers
+//! keep "set_high = assert" semantics while the board file expresses the
+//! wiring reality at construction time.
+//!
+//! ```ignore
+//! let pin = Output::new(p.GPIO4, Level::High, OutputConfig::default()); // off
+//! let led = SimpleLed(InvertedPin(pin)); // driver sees normal polarity
+//! ```
+
+use embedded_hal::digital::{ErrorType, OutputPin};
+
+pub struct InvertedPin<P>(pub P);
+
+impl<P: ErrorType> ErrorType for InvertedPin<P> {
+    type Error = P::Error;
+}
+
+impl<P: OutputPin> OutputPin for InvertedPin<P> {
+    fn set_low(&mut self) -> Result<(), Self::Error> {
+        self.0.set_high()
+    }
+
+    fn set_high(&mut self) -> Result<(), Self::Error> {
+        self.0.set_low()
+    }
+}
@@ -1,11 +1,29 @@
-#[cfg(any(feature = "wio_tracker_l1", feature = "elecrow_thinknode_m2"))]
+#[cfg(any(
+    feature = "wio_tracker_l1",
+    feature = "elecrow_thinknode_m2",
+    feature = "lilygo_tbeam_supreme",
+    feature = "rak_wisblock_4631"
+))]
 pub mod sh1106;

+#[cfg(any(feature = "lilygo_tbeam_supreme", feature = "lilygo_tbeam"))]
+pub mod axp;
+
+#[cfg(any(feature = "lilygo_tbeam", feature = "heltec_mesh_node_t114"))]
+pub mod inverted_pin;
+
+#[cfg(feature = "heltec_mesh_node_t114")]
+pub mod st7789;
+
 #[cfg(any(
+    feature = "heltec_mesh_node_t114",
    feature = "heltec_v3",
    feature = "heltec_v3_uart",
    feature = "heltec_v4",
    feature = "elecrow_thinknode_m2",
+    feature = "lilygo_tbeam_supreme",
+    feature = "lilygo_tbeam",
+    feature = "rak_wisblock_4631",
    feature = "wio_tracker_l1",
    feature = "waveshare_rp2040_lora"
 ))]
@@ -51,7 +69,12 @@ where
    }
 }

-#[cfg(any(feature = "wio_tracker_l1", feature = "elecrow_thinknode_m2"))]
+#[cfg(any(
+    feature = "wio_tracker_l1",
+    feature = "elecrow_thinknode_m2",
+    feature = "lilygo_tbeam_supreme",
+    feature = "rak_wisblock_4631"
+))]
 impl<I> DisplayBrightness for sh1106::Sh1106<I>
 where
    I: embedded_hal_async::i2c::I2c,
@@ -37,6 +37,12 @@ impl<I: I2c> Sh1106<I> {
    /// Send a sequence of commands (each prefixed with the I2C command byte 0x00).
    async fn cmd(&mut self, commands: &[u8]) -> Result<(), I::Error> {
        for &c in commands {
+            #[cfg(feature = "debug-twim")]
+            defmt::info!(
+                "[sh1106] cmd write: addr=0x{=u8:02X} bytes=[0x00, 0x{=u8:02X}]",
+                self.addr,
+                c,
+            );
            self.i2c.write(self.addr, &[0x00, c]).await?;
        }
        Ok(())
@@ -44,6 +50,8 @@ impl<I: I2c> Sh1106<I> {

    /// Initialize the display with sensible defaults.
    pub async fn init(&mut self) -> Result<(), I::Error> {
+        #[cfg(feature = "debug-twim")]
+        defmt::info!("[sh1106] init: starting");
        self.cmd(&[
            0xAE, // display off
            0xD5, 0x80, // clock div: default
@@ -71,6 +79,8 @@ impl<I: I2c> Sh1106<I> {
        page_buf[0] = 0x40;

        for page in 0..PAGES {
+            #[cfg(feature = "debug-twim")]
+            defmt::info!("[sh1106] flush page {=usize}: addr cmds (3 bytes)", page);
            // Set page address and column start (with SH1106 2-column offset).
            self.cmd(&[
                0xB0 | page as u8,        // page address
@@ -81,6 +91,12 @@ impl<I: I2c> Sh1106<I> {

            let start = page * WIDTH;
            page_buf[1..].copy_from_slice(&self.buffer[start..start + WIDTH]);
+            #[cfg(feature = "debug-twim")]
+            defmt::info!(
+                "[sh1106] flush page {=usize}: data write {=usize} bytes (0x40 prefix + 128 pixels)",
+                page,
+                page_buf.len(),
+            );
            self.i2c.write(self.addr, &page_buf).await?;
        }
        Ok(())
@@ -88,6 +104,8 @@ impl<I: I2c> Sh1106<I> {

    /// Set display brightness (contrast).
    pub async fn set_brightness(&mut self, value: u8) -> Result<(), I::Error> {
+        #[cfg(feature = "debug-twim")]
+        defmt::info!("[sh1106] set_brightness: 0x{=u8:02X}", value);
        self.cmd(&[0x81, value]).await
    }
 }
@@ -0,0 +1,123 @@
+//! ST7789 240×135 IPS TFT driver wrapper for the Heltec Mesh Node T114.
+//!
+//! Wraps `lcd_async::Display<…, models::ST7789, …>` (async fork of
+//! mipidsi) with an in-RAM raw byte framebuffer (240×135 × 2 bytes
+//! Rgb565 BE = 64,800 bytes) and an active-LOW PWM backlight on PWM0.
+//!
+//! Renderers draw into the framebuffer via `lcd_async::raw_framebuf::RawFrameBuf`;
+//! `present()` awaits a single async DMA blit of the entire buffer to
+//! the panel via `panel.show_raw_data(...).await`. The await lets
+//! embassy-nrf's DMA-backed Spim yield the executor for the duration
+//! of the ~65 ms SPI transfer, so the radio task can run alongside
+//! and the SX1262 IRQ handler isn't starved during repaints.
+
+use embassy_nrf::pwm::{DutyCycle, SimplePwm};
+use embedded_graphics::pixelcolor::Rgb565;
+use lcd_async::interface::Interface;
+use lcd_async::models::ST7789;
+use lcd_async::raw_framebuf::RawFrameBuf;
+use lcd_async::Display;
+
+use crate::display::{render_color, BoardDisplay, BoardInfo, DashboardCtx};
+
+/// PWM countertop. Drives the backlight at ~1 kHz (well above flicker).
+pub const BL_MAX: u16 = 1000;
+
+fn bl_bright() -> DutyCycle {
+    // Inverted polarity: HIGH for 0 counts → always LOW → full bright.
+    DutyCycle::inverted(0)
+}
+
+fn bl_dim() -> DutyCycle {
+    // ~80% HIGH → ~20% LOW → 20% brightness.
+    DutyCycle::inverted((BL_MAX * 4) / 5)
+}
+
+#[allow(dead_code)]
+fn bl_off() -> DutyCycle {
+    DutyCycle::inverted(BL_MAX)
+}
+
+// ── Framebuffer ───────────────────────────────────────────────────────
+
+pub const FB_W: usize = 240;
+pub const FB_H: usize = 135;
+/// Bytes for one full Rgb565 frame (2 bytes/pixel, big-endian — matches
+/// what ST7789 expects in 16-bit color mode).
+pub const FB_BYTES: usize = FB_W * FB_H * 2;
+
+// ── St7789Color ───────────────────────────────────────────────────────
+
+pub struct St7789Color<DI, RST>
+where
+    DI: Interface,
+    RST: embedded_hal::digital::OutputPin,
+{
+    panel: Display<DI, ST7789, RST>,
+    backlight: SimplePwm<'static>,
+    fb: &'static mut [u8; FB_BYTES],
+}
+
+impl<DI, RST> St7789Color<DI, RST>
+where
+    DI: Interface,
+    RST: embedded_hal::digital::OutputPin,
+{
+    pub fn new(
+        panel: Display<DI, ST7789, RST>,
+        backlight: SimplePwm<'static>,
+        fb: &'static mut [u8; FB_BYTES],
+    ) -> Self {
+        Self { panel, backlight, fb }
+    }
+
+    /// Wrap the raw byte buffer as a `RawFrameBuf<Rgb565, _>` so
+    /// `embedded-graphics` primitives can draw into it, then run `f`.
+    /// The borrow ends when this returns, freeing `self.fb` for the
+    /// subsequent blit in `present()`.
+    fn with_fb<F: FnOnce(&mut RawFrameBuf<Rgb565, &mut [u8]>)>(&mut self, f: F) {
+        let mut fbuf = RawFrameBuf::<Rgb565, _>::new(&mut self.fb[..], FB_W, FB_H);
+        f(&mut fbuf);
+    }
+}
+
+impl<DI, RST> BoardDisplay for St7789Color<DI, RST>
+where
+    DI: Interface<Word = u8>,
+    RST: embedded_hal::digital::OutputPin,
+{
+    /// Blit the entire framebuffer to the panel via the async SPI
+    /// interface. embassy-nrf's Spim runs the transfer over EasyDMA;
+    /// the `.await` yields the executor for the duration so the radio
+    /// task can process SX1262 IRQs concurrently.
+    async fn present(&mut self) {
+        let _ = self
+            .panel
+            .show_raw_data(0, 0, FB_W as u16, FB_H as u16, self.fb.as_ref())
+            .await;
+    }
+
+    async fn set_bright(&mut self) {
+        self.backlight.set_duty(0, bl_bright());
+    }
+
+    async fn set_dim(&mut self) {
+        self.backlight.set_duty(0, bl_dim());
+    }
+
+    fn render_splash_learn_more(&mut self) {
+        self.with_fb(|fb| render_color::splash_learn_more(fb));
+    }
+
+    fn render_splash_info(&mut self, info: &BoardInfo<'_>) {
+        self.with_fb(|fb| render_color::splash_info(fb, info));
+    }
+
+    fn render_dashboard(&mut self, ctx: &DashboardCtx<'_>) {
+        self.with_fb(|fb| render_color::dashboard(fb, ctx));
+    }
+
+    fn render_blank(&mut self) {
+        self.with_fb(|fb| render_color::blank(fb));
+    }
+}
@@ -0,0 +1,80 @@
+//! ESP32 (classic / non-S3) MCU initialization primitives.
+//!
+//! Mirror of `hal::esp32s3` with a single delta: the classic ESP32 uses a
+//! peripheral-bound DMA (`DMA_SPI2`) rather than the S3's channel-addressed
+//! GDMA (`DMA_CH0`). Timer, I²C, and eFuse access are otherwise identical
+//! between the two Xtensa parts in this esp-hal vintage.
+
+use embassy_sync::blocking_mutex::raw::NoopRawMutex;
+use esp_hal::dma::{DmaRxBuf, DmaTxBuf};
+use esp_hal::gpio::interconnect::{PeripheralInput, PeripheralOutput};
+use esp_hal::i2c::master::I2c;
+use esp_hal::spi::master::{Config as SpiConfig, Spi, SpiDmaBus};
+use esp_hal::spi::Mode as SpiMode;
+use esp_hal::time::Rate;
+use esp_hal::timer::timg::TimerGroup;
+use static_cell::StaticCell;
+
+// ── MCU-level types ─────────────────────────────────────────────────
+
+pub type SpiBus = SpiDmaBus<'static, esp_hal::Async>;
+pub type I2cBus = I2c<'static, esp_hal::Async>;
+
+// ── Timer ───────────────────────────────────────────────────────────
+
+/// Start the ESP-RTOS scheduler and Embassy time driver.
+pub fn start_timer(
+    timg0: esp_hal::peripherals::TIMG0<'static>,
+    sw_int: esp_hal::peripherals::SW_INTERRUPT<'static>,
+) {
+    let timg0 = TimerGroup::new(timg0);
+    let sw_ints = esp_hal::interrupt::software::SoftwareInterruptControl::new(sw_int);
+    esp_rtos::start(timg0.timer0, sw_ints.software_interrupt0);
+}
+
+// ── SPI bus ─────────────────────────────────────────────────────────
+
+/// Initialize SPI2 with peripheral-bound DMA and wrap in a shared bus
+/// (`StaticCell` + `Mutex`).
+///
+/// Generic over pin type. The classic ESP32's matrix of GPIO → peripheral
+/// routes lets any GPIO serve as any SPI signal — same as the S3.
+pub fn init_spi(
+    spi2: esp_hal::peripherals::SPI2<'static>,
+    dma_spi2: esp_hal::peripherals::DMA_SPI2<'static>,
+    sck: impl PeripheralOutput<'static>,
+    mosi: impl PeripheralOutput<'static>,
+    miso: impl PeripheralInput<'static>,
+) -> &'static embassy_sync::mutex::Mutex<NoopRawMutex, SpiBus> {
+    let spi = Spi::new(
+        spi2,
+        SpiConfig::default()
+            .with_frequency(Rate::from_mhz(1))
+            .with_mode(SpiMode::_0),
+    )
+    .expect("SPI init")
+    .with_sck(sck)
+    .with_mosi(mosi)
+    .with_miso(miso)
+    .with_dma(dma_spi2);
+
+    let (rx_buf, rx_desc, tx_buf, tx_desc) = esp_hal::dma_buffers!(256);
+    let dma_rx = DmaRxBuf::new(rx_desc, rx_buf).expect("DMA RX buf");
+    let dma_tx = DmaTxBuf::new(tx_desc, tx_buf).expect("DMA TX buf");
+
+    let spi = spi.with_buffers(dma_rx, dma_tx).into_async();
+
+    static SPI_BUS: StaticCell<embassy_sync::mutex::Mutex<NoopRawMutex, SpiBus>> =
+        StaticCell::new();
+    SPI_BUS.init(embassy_sync::mutex::Mutex::new(spi))
+}
+
+// ── MAC address ─────────────────────────────────────────────────────
+
+/// Read the factory-programmed MAC address from eFuse.
+pub fn mac_address() -> [u8; 6] {
+    esp_hal::efuse::base_mac_address()
+        .as_bytes()
+        .try_into()
+        .expect("MAC is 6 bytes")
+}
@@ -7,11 +7,19 @@
    feature = "heltec_v3",
    feature = "heltec_v3_uart",
    feature = "heltec_v4",
-    feature = "elecrow_thinknode_m2"
+    feature = "elecrow_thinknode_m2",
+    feature = "lilygo_tbeam_supreme"
 ))]
 pub mod esp32s3;

-#[cfg(any(feature = "rak_wisblock_4631", feature = "wio_tracker_l1"))]
+#[cfg(feature = "lilygo_tbeam")]
+pub mod esp32;
+
+#[cfg(any(
+    feature = "heltec_mesh_node_t114",
+    feature = "rak_wisblock_4631",
+    feature = "wio_tracker_l1"
+))]
 pub mod nrf52840;

 #[cfg(feature = "waveshare_rp2040_lora")]
@@ -13,11 +13,23 @@ bind_interrupts!(pub struct Irqs {
    USBD => embassy_nrf::usb::InterruptHandler<embassy_nrf::peripherals::USBD>;
    SPIM3 => embassy_nrf::spim::InterruptHandler<embassy_nrf::peripherals::SPI3>;
    TWISPI0 => embassy_nrf::twim::InterruptHandler<embassy_nrf::peripherals::TWISPI0>;
+    // SPIM2 is the second free SPI peripheral on nRF52840. Only used
+    // today by the Heltec T114 (ST7789 TFT panel on a write-only bus
+    // that can't share with the SX1262 on SPIM3 because the pins
+    // differ). Boards that don't use SPI2 don't construct anything
+    // against it and this binding is a no-op for them.
+    SPI2 => embassy_nrf::spim::InterruptHandler<embassy_nrf::peripherals::SPI2>;
 });

 // ── MCU-level types ─────────────────────────────────────────────────

 pub type SpiBus = embassy_nrf::spim::Spim<'static>;
+// I2C is used by some nRF boards (RAK4631 / Wio Tracker L1 OLED) but not
+// others (T114 uses SPI for the TFT). The `#[allow(dead_code)]` keeps
+// the type available for any board that wants it without per-feature
+// gating; rustc otherwise fires a dead-code lint when the active board
+// doesn't construct one.
+#[allow(dead_code)]
 pub type I2cBus = embassy_nrf::twim::Twim<'static>;
 pub type UsbNrfDriver =
    embassy_nrf::usb::Driver<'static, &'static embassy_nrf::usb::vbus_detect::SoftwareVbusDetect>;
@@ -37,6 +49,8 @@ pub fn share_spi_bus(spi: SpiBus) -> &'static embassy_sync::mutex::Mutex<NoopRaw
 ///
 /// Every nRF52840 Twim user needs a `&'static mut [u8]` buffer.
 /// This provides one via StaticCell so board files don't repeat the pattern.
+/// Unused on nRF boards that don't expose I2C (e.g. T114 uses SPI for the TFT).
+#[allow(dead_code)]
 pub fn alloc_i2c_buffer() -> &'static mut [u8; 256] {
    static TWIM_BUF: StaticCell<[u8; 256]> = StaticCell::new();
    TWIM_BUF.init([0u8; 256])
@@ -56,6 +70,76 @@ pub fn alloc_vbus_detect(
    ))
 }

+// ── Reset reason ────────────────────────────────────────────────────
+
+/// Read the POWER.RESETREAS register, log a human-readable summary,
+/// then clear it so the next boot reflects only the next reset cause.
+///
+/// This is the post-mortem diagnostic for soak runs: if the firmware
+/// crashes and the chip resets, the next boot's RESETREAS tells us
+/// what happened (cortex-m lockup, watchdog, soft reset, debugger,
+/// pin reset, etc.). Without this, a self-rebooting firmware just
+/// looks like log restarts with no signal as to why.
+///
+/// nRF52840 `POWER.RESETREAS` (PS §15.4.1): bits are write-1-to-clear.
+/// The register accumulates causes across resets until cleared, so
+/// always clear after reading.
+pub fn dump_reset_reason() {
+    // POWER.RESETREAS lives at 0x40000400 (POWER base 0x40000000 +
+    // offset 0x400). Direct memory access avoids requiring embassy_nrf's
+    // `unstable-pac` feature. Bit layout per nRF52840 PS §15.4.1:
+    //   0  RESETPIN  - external NRESET pin asserted
+    //   1  DOG       - watchdog reset
+    //   2  SREQ      - software-requested reset (cortex SYSRESETREQ)
+    //   3  LOCKUP    - cortex-m core lockup
+    //  16  OFF       - wake from System OFF via DETECT
+    //  17  LPCOMP    - wake from System OFF via ANADETECT
+    //  18  DIF       - wake from System OFF via debug interface
+    //  24  NFC       - wake from System OFF via NFC field
+    const RESETREAS_ADDR: *mut u32 = 0x4000_0400 as *mut u32;
+    // SAFETY: 0x40000400 is the POWER.RESETREAS register on nRF52840;
+    // read/write_volatile is correct for memory-mapped hardware.
+    let raw = unsafe { core::ptr::read_volatile(RESETREAS_ADDR) };
+    let dog = (raw & (1 << 1)) != 0;
+    let lockup = (raw & (1 << 3)) != 0;
+    if raw == 0 {
+        defmt::info!("boot: cold POR (RESETREAS=0)");
+    } else if dog || lockup {
+        // Real problems: watchdog timeout (hung task) OR CPU lockup
+        // (HardFault → escalated). Worth a WARN — these are bugs.
+        defmt::warn!(
+            "boot: ABNORMAL reset RESETREAS=0x{=u32:08x} resetpin={=bool} dog={=bool} sreq={=bool} lockup={=bool} off={=bool} lpcomp={=bool} dif={=bool} nfc={=bool}",
+            raw,
+            (raw & (1 << 0)) != 0,
+            dog,
+            (raw & (1 << 2)) != 0,
+            lockup,
+            (raw & (1 << 16)) != 0,
+            (raw & (1 << 17)) != 0,
+            (raw & (1 << 18)) != 0,
+            (raw & (1 << 24)) != 0,
+        );
+    } else {
+        // Normal reset paths: RESETPIN (UF2 bootloader pulses NRESET on
+        // app start; user reset button), SREQ (deliberate sys_reset),
+        // OFF/LPCOMP/DIF/NFC (wake from System OFF). All expected
+        // operational reasons; INFO not WARN.
+        defmt::info!(
+            "boot: RESETREAS=0x{=u32:08x} resetpin={=bool} sreq={=bool} off={=bool} lpcomp={=bool} dif={=bool} nfc={=bool}",
+            raw,
+            (raw & (1 << 0)) != 0,
+            (raw & (1 << 2)) != 0,
+            (raw & (1 << 16)) != 0,
+            (raw & (1 << 17)) != 0,
+            (raw & (1 << 18)) != 0,
+            (raw & (1 << 24)) != 0,
+        );
+    }
+    // Clear all bits — write-1-to-clear per nRF52840 PS §15.4.1.
+    // SAFETY: same justification as the read above.
+    unsafe { core::ptr::write_volatile(RESETREAS_ADDR, 0xFFFF_FFFF) };
+}
+
 // ── MAC address ─────────────────────────────────────────────────────

 /// Read the factory-programmed device address from FICR registers.
@@ -54,7 +54,16 @@ pub async fn dispatch_frame(
 }

 /// Emit an async framing error (tag = 0x0000) per spec §2.5.
+///
+/// Backpressure: if the host transport's IN endpoint is observed-dead
+/// (RADIO_THROTTLED set by host_task), drop silently. Without this gate,
+/// a bad-frame burst from a wedged host fills `OutboundChannel` faster
+/// than host_task can drain it (because it can't drain it at all when
+/// write_packet keeps failing), producing the warn flood seen in soak.
 pub async fn emit_async_err(outbound: &OutboundChannel, code: ErrorCode) {
+    if crate::channel::RADIO_THROTTLED.load(portable_atomic::Ordering::Acquire) {
+        return;
+    }
    let frame = OutboundFrame {
        tag: 0,
        msg: DeviceMessage::Err(code),
@@ -106,15 +115,31 @@ pub fn encode_outbound(frame: &OutboundFrame, out: &mut [u8; MAX_WIRE_FRAME]) ->
    ) {
        Ok(n) => Some(n),
        Err(FrameEncodeError::BufferTooSmall) => {
-            warn!("encode_frame: output buffer too small");
+            warn!(
+                "encode_frame: output buffer too small (type={=u8}, tag={=u16}, payload={=usize}B, out_buf={=usize}B)",
+                frame.msg.type_id(),
+                frame.tag,
+                payload_len,
+                out.len(),
+            );
            None
        }
        Err(FrameEncodeError::PayloadTooLarge) => {
-            warn!("encode_frame: payload exceeds MAX_PAYLOAD_FIELD");
+            warn!(
+                "encode_frame: payload exceeds MAX_PAYLOAD_FIELD (type={=u8}, tag={=u16}, payload={=usize}B)",
+                frame.msg.type_id(),
+                frame.tag,
+                payload_len,
+            );
            None
        }
        Err(FrameEncodeError::CobsEncode) => {
-            warn!("encode_frame: COBS encode refused");
+            warn!(
+                "encode_frame: COBS encode refused (type={=u8}, tag={=u16}, payload={=usize}B)",
+                frame.msg.type_id(),
+                frame.tag,
+                payload_len,
+            );
            None
        }
    }
@@ -6,7 +6,11 @@
 pub mod framing;

 cfg_if::cfg_if! {
-    if #[cfg(any(feature = "heltec_v3_uart", feature = "elecrow_thinknode_m2"))] {
+    if #[cfg(any(
+        feature = "heltec_v3_uart",
+        feature = "elecrow_thinknode_m2",
+        feature = "lilygo_tbeam"
+    ))] {
        mod uart;
        pub use uart::host_task;
    } else {
@@ -4,7 +4,7 @@
 //! rely entirely on the spec §3.4 inactivity watchdog (1 s of silence
 //! → Disconnected → drop radio to Unconfigured).

-use defmt::warn;
+use defmt::{info, warn};
 use embassy_executor::task;
 use embassy_time::{Duration, Instant};
 use embedded_io_async::Write;
@@ -34,25 +34,32 @@ pub async fn host_task(
        display_commands.send(DisplayCommand::On).await;
    }

-    let mut read_buf = [0u8; READ_BUF];
-    let mut write_buf: [u8; MAX_WIRE_FRAME] = [0u8; MAX_WIRE_FRAME];
-    let mut decoder = FrameDecoder::new();
-    let mut last_frame_at = Instant::now();
-    let mut connected = true;
+    // Two sub-loops joined in the same task. Splitting read and write
+    // is what stops a long-running tx.write_all (~25 ms for a max-size
+    // frame at 115_200 baud, multiplied across a saturated outbound
+    // queue) from starving the inbound poll. While write_all sits in
+    // its FIFO-drain await, join re-polls the read future on the next
+    // wake, so last_frame_at keeps refreshing and the §3.4 watchdog
+    // does not spuriously fire under sustained bidirectional load.
+    // Same task = single executor + disjoint borrows on the split
+    // rx/tx halves, so no Mutex is needed.
+    let read_loop = async {
+        let mut read_buf = [0u8; READ_BUF];
+        let mut decoder = FrameDecoder::new();
+        let mut last_frame_at = Instant::now();
+        let mut connected = true;

-    loop {
-        use embassy_futures::select::{select3, Either3};
+        loop {
+            use embassy_futures::select::{select, Either};

-        match select3(
-            embedded_io_async::Read::read(&mut rx, &mut read_buf),
-            outbound.receive(),
-            embassy_time::Timer::after(Duration::from_millis(100)),
-        )
-        .await
-        {
-            Either3::First(result) => match result {
-                Ok(0) => continue,
-                Ok(n) => {
+            match select(
+                embedded_io_async::Read::read(&mut rx, &mut read_buf),
+                embassy_time::Timer::after(Duration::from_millis(100)),
+            )
+            .await
+            {
+                Either::First(Ok(0)) => {}
+                Either::First(Ok(n)) => {
                    last_frame_at = Instant::now();
                    if !connected {
                        if has_display {
@@ -62,31 +69,72 @@ pub async fn host_task(
                    }
                    dispatch_bytes(&mut decoder, &read_buf[..n], commands, outbound).await;
                }
-                Err(_) => {
+                Either::First(Err(_)) => {
+                    // Byte-level error (FIFO overrun, UART framing,
+                    // parity). Per PROTOCOL.md §3.4: only "byte stream
+                    // activity that results in a complete frame
+                    // arriving" resets the inactivity timer, so we do
+                    // NOT touch last_frame_at here. The 100 ms sleep
+                    // is anti-spin: a stuck driver pumping continuous
+                    // Errs would otherwise burn the executor.
                    decoder.reset();
                    embassy_time::Timer::after_millis(100).await;
                }
-            },
-            Either3::Second(frame) => {
-                if let Some(n) = encode_outbound(&frame, &mut write_buf) {
-                    if tx.write_all(&write_buf[..n]).await.is_err() {
-                        warn!("UART write failed, frame dropped");
+                Either::Second(()) => {}
+            }
+
+            // Inactivity watchdog (PROTOCOL.md §3.4, 1000 ms).
+            if connected && last_frame_at.elapsed() >= Duration::from_millis(INACTIVITY_MS) {
+                warn!("UART host inactivity timeout fired");
+                let _ = commands.try_send(InboundEvent::Reset);
+                if has_display {
+                    let _ = display_commands.try_send(DisplayCommand::Reset);
+                }
+                // Drop in-flight frame state. When the host resumes it
+                // may pick up mid-frame; without resetting the decoder
+                // we'd chew through garbage until the next 0x00
+                // sentinel. USB gets the equivalent for free via
+                // DTR-drop reset (host/usb.rs Disconnected entry); UART
+                // has no DTR.
+                decoder.reset();
+                connected = false;
+            }
+        }
+    };
+
+    let write_loop = async {
+        let mut write_buf: [u8; MAX_WIRE_FRAME] = [0u8; MAX_WIRE_FRAME];
+
+        loop {
+            let frame = outbound.receive().await;
+            let Some(n) = encode_outbound(&frame, &mut write_buf) else {
+                continue;
+            };
+            // Mirror src/host/usb.rs:349-374. The throttle gate at
+            // src/radio.rs:2017 silently drops async RX into the
+            // outbound queue while RADIO_THROTTLED is true; clear it
+            // on every successful write and re-arm it on failure,
+            // same contract as USB.
+            match tx.write_all(&write_buf[..n]).await {
+                Ok(()) => {
+                    if crate::channel::RADIO_THROTTLED
+                        .load(portable_atomic::Ordering::Acquire)
+                    {
+                        info!("UART write recovered; clearing radio throttle");
+                        crate::channel::RADIO_THROTTLED
+                            .store(false, portable_atomic::Ordering::Release);
                    }
                }
+                Err(_) => {
+                    warn!("UART write failed, frame dropped, throttling radio");
+                    crate::channel::RADIO_THROTTLED
+                        .store(true, portable_atomic::Ordering::Release);
+                }
            }
-            Either3::Third(()) => {}
        }
+    };

-        // Inactivity watchdog.
-        if connected && last_frame_at.elapsed() >= Duration::from_millis(INACTIVITY_MS) {
-            warn!("UART host inactivity timeout fired");
-            let _ = commands.try_send(InboundEvent::Reset);
-            if has_display {
-                let _ = display_commands.try_send(DisplayCommand::Reset);
-            }
-            connected = false;
-        }
-    }
+    embassy_futures::join::join(read_loop, write_loop).await;
 }

 async fn dispatch_bytes(
@@ -2,24 +2,35 @@
 //!
 //! ```text
 //! Host
-//! ├── Disconnected   (default)   no DTR, or inactivity timer fired
-//! └── Connected                  host attached, liveness OK
-//!     entry: wake_display, start_liveness_timer
-//!     exit:  reset_radio, reset_display, stop_liveness_timer
+//! ├── Disconnected   (default)   no DTR
+//! └── Connected                  host attached, DTR up
+//!     │                          resting here means no traffic yet —
+//!     │                          NO inactivity timer (boot quiet is
+//!     │                          normal; chart structurally blocks the
+//!     │                          spurious 1s fire).
+//!     └── Active                 ≥1 frame seen since connect
+//!                                inactivity timer (1s) armed and
+//!                                restarted by every frame via
+//!                                self-transition.
 //! ```
 //!
-//! The statechart tracks one state bit: "is a host present?". DTR drives
-//! connect edges; the 1-second inactivity watchdog (spec §3.4) drives
-//! the disconnect edge when DTR is held high but no bytes arrive.
+//! Two chart-level invariants made structurally impossible by the shape:
+//! 1. **No spurious inactivity at boot.** The 1-second timer only exists
+//!    in `Active`, which requires a `FrameReceived` event to enter.
+//!    A freshly-connected host that holds DTR high but sends nothing
+//!    rests at `Connected` indefinitely (hsmc 0.5 optional-default
+//!    "microwave Standby" pattern) — no timer, no warn, no Reset cascade.
+//! 2. **Chart-owned timer scope.** Per hsmc README rule §7 (timers
+//!    armed by state lifecycle), the inactivity timer is cancelled on
+//!    every exit of `Active`, restarted on every entry. No global
+//!    `last_frame_at` instant, no manual elapsed check in the loop.
 //!
 //! The data plane (frame decode, command dispatch, frame encode) stays
-//! imperative in `protocol_loop` for the same reason the radio's
-//! `rx_once` stayed out of its chart: `read_packet` blocks.
+//! imperative in `protocol_loop` because `read_packet` blocks.

-use defmt::warn;
 use embassy_executor::task;
 use embassy_futures::join::join;
-use embassy_time::{Duration, Instant};
+use embassy_time::Duration;
 use embassy_usb::class::cdc_acm::{CdcAcmClass, Receiver, Sender, State};
 use embassy_usb::Builder;
 use hsmc::{statechart, Duration as HsmcDuration};
@@ -35,17 +46,24 @@ const MAX_USB_PACKET: usize = 64;

 /// Spec §3.4: inactivity timer period. The device must see at least one
 /// frame (good or bad) every 1000 ms or the session is considered lost.
+/// Declared in the chart on `Active` — chart owns timer lifecycle.
 const INACTIVITY_MS: u64 = 1000;

-/// Poll interval for the DTR edge detector / inactivity check.
+/// Poll interval for the DTR edge detector. Chart owns the inactivity
+/// timer; this is only the cadence at which protocol_loop wakes when
+/// no other event is pending, to re-check DTR.
 const POLL_INTERVAL_MS: u64 = 100;

 #[derive(Debug, Clone)]
 pub enum HostInput {
    DtrRaised,
    DtrDropped,
-    /// Host went silent for >1 s; kick the radio back to Unconfigured.
-    InactivityTimeout,
+    /// A USB read returned ≥1 byte. Drives `Connected → Active` on
+    /// the first frame after DTR up, and the `Active → Active`
+    /// self-transition that restarts the inactivity timer per
+    /// hsmc README rule §4 (self-transition exits + re-enters target,
+    /// re-arming its timer).
+    FrameReceived,
 }

 pub struct HostContext {
@@ -68,8 +86,22 @@ impl HostContext {
    }

    fn send_radio_reset(&self) {
+        use portable_atomic::Ordering;
+        // Dedupe: if a Reset is already queued (and not yet consumed by
+        // the radio task), don't queue another. Without this, a slow or
+        // wedged radio + repeated chart exits (DTR drop, inactivity,
+        // both transports) fill the commands channel and produce the
+        // "queue full" warn flood. The radio chart's reset_to_unconfigured
+        // clears the flag once it processes the queued Reset.
+        if crate::channel::RESET_PENDING.swap(true, Ordering::AcqRel) {
+            return;
+        }
        if self.commands.try_send(InboundEvent::Reset).is_err() {
-            warn!("radio Reset inject: command queue full");
+            // Channel genuinely full of non-Reset commands; this is the
+            // edge case worth knowing about. Clear the flag so future
+            // Reset attempts can re-try once the channel drains.
+            defmt::warn!("radio Reset inject: command queue full");
+            crate::channel::RESET_PENDING.store(false, Ordering::Release);
        }
    }
 }
@@ -78,6 +110,8 @@ statechart! {
    Host {
        context: HostContext;
        events: HostInput;
+        // Auto-trace — backend selected by `hsmc/trace-*` cargo feature.
+        trace;
        default(Disconnected);

        state Disconnected {
@@ -88,7 +122,28 @@ statechart! {
            entry: wake_display;
            exit: reset_radio, reset_display;
            on(DtrDropped) => Disconnected;
-            on(InactivityTimeout) => Disconnected;
+            // hsmc 0.5 microwave-Standby pattern: Connected itself is the
+            // resting "DTR up, no traffic yet" state. No inactivity timer
+            // here — boot quiet is normal (mux-rs holds DTR high before
+            // any client attaches), so the chart structurally cannot fire
+            // a 1 s warn before the first byte. The first FrameReceived
+            // descends into Active, which owns the inactivity timer.
+            on(FrameReceived) => Active;
+
+            // Inactivity timer is chart-scoped: armed on every entry to
+            // Active (from Connected on the first frame, or from the
+            // self-transition below on each subsequent frame), cancelled
+            // on every exit (per hsmc README rule §7). The self-transition
+            // re-enters Active per rule §4, re-arming the timer —
+            // equivalent to the "reset last_frame_at on each byte" pattern
+            // but expressed in chart shape.
+            //
+            // hsmc's `after` triggers want `hsmc::Duration` (re-export
+            // of `core::time::Duration`), not `embassy_time::Duration`.
+            state Active {
+                on(after HsmcDuration::from_millis(INACTIVITY_MS)) => Disconnected;
+                on(FrameReceived) => Active;
+            }
        }
    }
 }
@@ -133,20 +188,34 @@ pub async fn host_task(
    }
    config.serial_number = Some(core::str::from_utf8(serial_buf).expect("MAC hex is valid UTF-8"));

+    // CTRL_BUF was 64 bytes; bumped to 128 because the previous size
+    // matches the panic site "control buffer too small" in
+    // embassy_usb/src/lib.rs:758. CdcAcmClass only requires >= 7 for
+    // SET_LINE_CODING, but composite descriptor handlers and string
+    // descriptor responses may overrun a 64 B buffer for some host
+    // enumerations. 128 is safely above the largest CDC-ACM control
+    // request and well within RAM budget.
    static DESC_BUF: StaticCell<[u8; 256]> = StaticCell::new();
    static CONF_BUF: StaticCell<[u8; 256]> = StaticCell::new();
    static BOS_BUF: StaticCell<[u8; 256]> = StaticCell::new();
-    static CTRL_BUF: StaticCell<[u8; 64]> = StaticCell::new();
+    static CTRL_BUF: StaticCell<[u8; 128]> = StaticCell::new();
    static CDC_STATE: StaticCell<State> = StaticCell::new();

    let desc_buf = DESC_BUF.init([0; 256]);
    let conf_buf = CONF_BUF.init([0; 256]);
    let bos_buf = BOS_BUF.init([0; 256]);
-    let ctrl_buf = CTRL_BUF.init([0; 64]);
+    let ctrl_buf = CTRL_BUF.init([0; 128]);
    let cdc_state = CDC_STATE.init(State::new());

    let mut builder = Builder::new(parts.driver, config, desc_buf, conf_buf, bos_buf, ctrl_buf);

+    // Note: when this device enumerates on Linux, modem-manager's
+    // CDC-ACM probe issues SET_INTERFACE with alt settings beyond what
+    // we declare, triggering a "SET_INTERFACE: alt setting out of
+    // range" WARN from embassy_usb. The probe is normal Linux
+    // behavior; embassy_usb's STALL response is correct USB negotiation.
+    // The WARN is benign noise — do NOT add dummy alt settings just to
+    // silence it (risks breaking Windows/macOS enumeration).
    let class = CdcAcmClass::new(&mut builder, cdc_state, MAX_USB_PACKET as u16);
    let mut usb_dev = builder.build();
    let (sender, receiver) = class.split();
@@ -186,8 +255,6 @@ async fn protocol_loop<'d, D: embassy_usb_driver::Driver<'d>>(
    let mut write_buf: [u8; MAX_WIRE_FRAME] = [0u8; MAX_WIRE_FRAME];
    let mut decoder = FrameDecoder::new();

-    let mut last_frame_at = Instant::now();
-
    loop {
        match select3(
            receiver.read_packet(&mut read_buf),
@@ -196,52 +263,145 @@ async fn protocol_loop<'d, D: embassy_usb_driver::Driver<'d>>(
        )
        .await
        {
-            Either3::First(Ok(0)) => {}
+            Either3::First(Ok(0)) => {
+                defmt::info!("host_task: read_packet returned 0 bytes");
+            }
            Either3::First(Ok(n)) => {
-                last_frame_at = Instant::now();
+                defmt::info!(
+                    "host_task: read_packet got {=usize}B (DTR={=bool})",
+                    n,
+                    receiver.dtr(),
+                );
+                // Drives Connected → Active on first byte and
+                // Active → Active (timer-restart) on every byte after.
+                // The chart owns inactivity from here.
+                let _ = machine.dispatch(HostInput::FrameReceived).await;
                dispatch_bytes(&mut decoder, &read_buf[..n], commands, outbound).await;
            }
-            Either3::First(Err(_)) => {
+            Either3::First(Err(e)) => {
+                // Per embassy_usb_driver::EndpointError, `read_packet`
+                // returns one of two errors:
+                //   - `Disabled`:       OUT endpoint not enabled by the host
+                //                       (USB enumeration in progress, host
+                //                       suspended, or interface not yet
+                //                       configured). Completely normal during
+                //                       bring-up + every host disconnect.
+                //   - `BufferOverflow`: incoming packet larger than read_buf.
+                //                       read_buf is sized to MAX_USB_PACKET
+                //                       (64) which matches the CDC-ACM EP
+                //                       max packet size, so this should
+                //                       never happen in practice.
+                //
+                // `Disabled` floods at boot before USB enumeration finishes
+                // (the OS hasn't sent SET_CONFIGURATION yet) — was previously
+                // logging dozens of "read_packet error" lines per second.
+                // Demote to debug-level since it's expected; reserve WARN
+                // for BufferOverflow which IS a real bug.
+                use embassy_usb_driver::EndpointError;
+                match e {
+                    EndpointError::Disabled => {
+                        defmt::debug!(
+                            "host_task: read_packet returned Disabled (USB endpoint not yet enabled by host — normal during enumeration)"
+                        );
+                    }
+                    EndpointError::BufferOverflow => {
+                        defmt::warn!(
+                            "host_task: read_packet BufferOverflow — host sent a packet larger than {=usize}B (max EP packet size); decoder reset",
+                            MAX_USB_PACKET,
+                        );
+                    }
+                }
                decoder.reset();
                embassy_time::Timer::after_millis(100).await;
            }
            Either3::Second(frame) => {
+                let frame_tag = frame.tag;
                if let Some(n) = encode_outbound(&frame, &mut write_buf) {
-                    for chunk in write_buf[..n].chunks(MAX_USB_PACKET) {
+                    defmt::info!(
+                        "host_task: sending {=usize}B frame tag={=u16}",
+                        n,
+                        frame_tag,
+                    );
+                    // Per embassy_usb 0.6: write_packet only returns
+                    // EndpointError::Disabled when the IN endpoint is
+                    // dead (host gone or USB suspended). If a chunk
+                    // mid-frame fails, the partial bytes already sent
+                    // are unrecoverable — host's framing layer will see
+                    // corruption until a clean frame arrives. Bail on
+                    // the rest of THIS frame and set RADIO_THROTTLED so
+                    // the radio task stops generating async events
+                    // until the host comes back. Without the throttle,
+                    // every subsequent frame would also fail mid-write
+                    // and produce more wire corruption.
+                    let mut frame_failed = false;
+                    for (chunk_idx, chunk) in
+                        write_buf[..n].chunks(MAX_USB_PACKET).enumerate()
+                    {
+                        defmt::info!(
+                            "host_task: write_packet chunk {=usize} ({=usize}B) tag={=u16}",
+                            chunk_idx,
+                            chunk.len(),
+                            frame_tag,
+                        );
                        if sender.write_packet(chunk).await.is_err() {
-                            warn!("USB write failed, frame dropped");
+                            defmt::warn!(
+                                "USB write failed (host stalled or gone); frame dropped tag={=u16}, throttling radio",
+                                frame_tag,
+                            );
+                            crate::channel::RADIO_THROTTLED
+                                .store(true, portable_atomic::Ordering::Release);
+                            frame_failed = true;
                            break;
                        }
+                        defmt::info!(
+                            "host_task: write_packet OK chunk {=usize} tag={=u16}",
+                            chunk_idx,
+                            frame_tag,
+                        );
                    }
+                    if !frame_failed
+                        && crate::channel::RADIO_THROTTLED
+                            .load(portable_atomic::Ordering::Acquire)
+                    {
+                        defmt::info!(
+                            "USB write recovered (tag={=u16}); clearing radio throttle",
+                            frame_tag,
+                        );
+                        crate::channel::RADIO_THROTTLED
+                            .store(false, portable_atomic::Ordering::Release);
+                    }
+                    defmt::info!("host_task: frame done tag={=u16}", frame_tag);
                }
            }
-            Either3::Third(()) => {}
+            Either3::Third(()) => {
+                // Heartbeat tick — drives DTR edge polling + inactivity
+                // watchdog below. No log: it would fire every
+                // POLL_INTERVAL_MS and bury the interesting traffic.
+            }
        }

-        // DTR edge detection — drives Connected / Disconnected transitions.
-        let connected = receiver.dtr();
-        let was_connected = matches!(machine.current_state(), HostState::Connected);
-        match (was_connected, connected) {
+        // DTR edge detection — drives Connected / Disconnected
+        // transitions. The chart's `current_state()` may be
+        // Disconnected, Connected (resting), or Connected/Active.
+        // We're connected if current state is anywhere inside
+        // Connected.
+        let dtr_high = receiver.dtr();
+        let was_connected = !matches!(
+            machine.current_state(),
+            HostState::Disconnected
+        );
+        match (was_connected, dtr_high) {
            (false, true) => {
+                defmt::info!("host_task: DTR raised");
                let _ = machine.dispatch(HostInput::DtrRaised).await;
-                last_frame_at = Instant::now();
            }
            (true, false) => {
+                defmt::info!("host_task: DTR dropped");
                decoder.reset();
                let _ = machine.dispatch(HostInput::DtrDropped).await;
            }
            _ => {}
        }
-
-        // Inactivity watchdog (spec §3.4): while Connected, if no frame
-        // arrived in the last INACTIVITY_MS, drive the session back to
-        // Disconnected.
-        if matches!(machine.current_state(), HostState::Connected)
-            && last_frame_at.elapsed() >= Duration::from_millis(INACTIVITY_MS)
-        {
-            warn!("host inactivity timeout fired");
-            let _ = machine.dispatch(HostInput::InactivityTimeout).await;
-        }
    }
 }

@@ -0,0 +1,285 @@
+//! Pure-math helpers for Listen-Before-Talk (CAD) retry timing.
+//!
+//! The CAD retry loop in `radio::do_tx` scales its backoff to the active
+//! LoRa configuration: per-retry sleep is one time-on-air of an assumed
+//! peer packet, total retry budget is capped at `CAD_BUDGET_US`. This
+//! module owns the ToA math (Semtech AN1200.13) and the retry-count
+//! derivation, split out so it can be unit-tested host-side without the
+//! radio module's hardware dependencies.
+
+use crate::protocol::{LoRaCodingRate, LoRaConfig, LoRaHeaderMode};
+
+/// Total LBT budget: the maximum time the CAD retry loop is allowed to
+/// tie up the radio before returning `ChannelBusy`.
+pub const CAD_BUDGET_US: u32 = 2_500_000;
+/// Upper bound on retries, independent of budget — caps the work on
+/// very fast configs (SF7/BW500 would otherwise get 60+ retries).
+pub const CAD_HARD_CAP: u8 = 10;
+/// Assumed peer-packet payload (bytes) used to size the per-retry sleep.
+/// 80 is a representative median for typical mesh traffic. Peers sending
+/// larger packets may be partially under-waited (accepted trade-off —
+/// host-level retry handles collisions).
+#[allow(dead_code)] // consumed by `radio.rs`, which is gated out of test builds
+pub const CAD_ASSUMED_PEER_PAYLOAD_B: u16 = 80;
+/// Jitter applied to each sleep, in tenths of a percent (±20 % = 200).
+pub const CAD_JITTER_TENTHS_PCT: u32 = 200;
+
+/// ToA formula expects CR ∈ {1..4} for 4/5..4/8 (each coded symbol carries
+/// `CR+4` bits). The protocol enum starts at 0, so map explicitly — using
+/// `as u32` alone would underestimate airtime by one code bit everywhere.
+pub fn cr_numeric(cr: LoRaCodingRate) -> u32 {
+    match cr {
+        LoRaCodingRate::Cr4_5 => 1,
+        LoRaCodingRate::Cr4_6 => 2,
+        LoRaCodingRate::Cr4_7 => 3,
+        LoRaCodingRate::Cr4_8 => 4,
+    }
+}
+
+/// Worst-case LoRa time-on-air in microseconds (Semtech AN1200.13).
+///
+/// Uses `N_preamble + 4.25` quarter-symbols for preamble duration; SX126x
+/// uses 6.25 at SF5/SF6, so the result is low by 2·T_sym at those SFs
+/// (sub-millisecond — negligible at the LBT-budget scale).
+pub fn toa_us(cfg: &LoRaConfig, payload_len: u16) -> u32 {
+    let sf = cfg.sf as u64;
+    let bw_hz = cfg.bw.as_hz() as u64;
+    // Symbol time in µs: (2^SF / BW_Hz) * 1e6. u64 avoids overflow at
+    // SF12/BW7 where T_sym ≈ 524 ms.
+    let t_sym_us = (1u64 << sf) * 1_000_000 / bw_hz.max(1);
+    let de: i64 = if t_sym_us > 16_000 { 1 } else { 0 };
+    let crc: i64 = if cfg.payload_crc { 1 } else { 0 };
+    let h: i64 = if matches!(cfg.header_mode, LoRaHeaderMode::Implicit) {
+        1
+    } else {
+        0
+    };
+    let pl = payload_len as i64;
+    let sf_i = sf as i64;
+
+    // Payload symbol count (signed intermediates — `num` goes negative
+    // for small PL at SF12 with H=1, CRC=0).
+    let num = 8 * pl - 4 * sf_i + 28 + 16 * crc - 20 * h;
+    let den = 4 * (sf_i - 2 * de);
+    let payload_sym_ceil = if num <= 0 || den <= 0 {
+        0i64
+    } else {
+        (num + den - 1) / den
+    };
+    let cr_num = cr_numeric(cfg.cr) as i64;
+    let n_payload = 8 + (payload_sym_ceil * (cr_num + 4)).max(0);
+    let t_payload_us = n_payload as u64 * t_sym_us;
+
+    // Preamble duration: (N + 4.25) * T_sym = (4·N + 17) * T_sym / 4.
+    let t_preamble_us = (cfg.preamble_len as u64 * 4 + 17) * t_sym_us / 4;
+
+    (t_preamble_us + t_payload_us).min(u32::MAX as u64) as u32
+}
+
+/// Derive the CAD retry count and per-retry sleep from the cached
+/// `cad_retry_delay_us`. Retries form: N CADs separated by N-1 sleeps.
+/// When one assumed-packet wait exceeds the total budget, `retries = 1`
+/// — a single CAD, bail on busy, no sleep.
+pub fn cad_retries(cad_retry_delay_us: u32) -> (u8, u32) {
+    if cad_retry_delay_us == 0 {
+        // Unconfigured should never reach this path; fall back to a
+        // single CAD with no sleep rather than divide-by-zero.
+        return (1, 0);
+    }
+    let n_sleeps = CAD_BUDGET_US / cad_retry_delay_us;
+    let retries = (n_sleeps + 1).clamp(1, CAD_HARD_CAP as u32) as u8;
+    (retries, cad_retry_delay_us)
+}
+
+/// Apply ±`CAD_JITTER_TENTHS_PCT`/10 % jitter around `base_us`.
+/// `entropy` is a raw 32-bit source; caller provides it so this stays
+/// pure (radio task passes `Instant::now().as_ticks() as u32`).
+pub fn jittered_sleep_us(base_us: u32, entropy: u32) -> u32 {
+    let mixed = entropy.wrapping_mul(0x9E37_79B9);
+    let span = 2 * CAD_JITTER_TENTHS_PCT + 1; // e.g. 401 for ±20 %
+    let r = mixed % span; // 0..=2·CAD_JITTER_TENTHS_PCT
+    // factor_thousandths ∈ [1000 − CAD_JITTER_TENTHS_PCT, 1000 + CAD_JITTER_TENTHS_PCT]
+    let factor_thousandths = 1000 - CAD_JITTER_TENTHS_PCT + r;
+    ((base_us as u64 * factor_thousandths as u64) / 1000) as u32
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::protocol::{LoRaBandwidth, LoRaCodingRate, LoRaConfig, LoRaHeaderMode};
+
+    fn cfg(sf: u8, bw: LoRaBandwidth, cr: LoRaCodingRate, preamble: u16, implicit: bool, crc: bool) -> LoRaConfig {
+        LoRaConfig {
+            freq_hz: 915_000_000,
+            sf,
+            bw,
+            cr,
+            preamble_len: preamble,
+            sync_word: 0x1424,
+            tx_power_dbm: 0,
+            header_mode: if implicit {
+                LoRaHeaderMode::Implicit
+            } else {
+                LoRaHeaderMode::Explicit
+            },
+            payload_crc: crc,
+            iq_invert: false,
+        }
+    }
+
+    /// Helper: assert `actual` is within `tolerance_pct`% of `expected_us`.
+    fn approx(actual_us: u32, expected_us: u32, tolerance_pct: u32) {
+        let diff = actual_us.abs_diff(expected_us);
+        let tol = expected_us * tolerance_pct / 100;
+        assert!(
+            diff <= tol,
+            "actual {} us not within {}% of expected {} us (diff {}, tol {})",
+            actual_us,
+            tolerance_pct,
+            expected_us,
+            diff,
+            tol
+        );
+    }
+
+    // Reference values sanity-checked against Semtech's LoRa calculator
+    // and AN1200.13.
+
+    #[test]
+    fn toa_sf7_bw125_cr45_pl10_explicit_crc() {
+        let c = cfg(7, LoRaBandwidth::Khz125, LoRaCodingRate::Cr4_5, 8, false, true);
+        // Hand-computed reference from AN1200.13:
+        //   T_sym = 128/125 kHz = 1.024 ms
+        //   T_preamble = (8 + 4.25) · 1.024 = 12.544 ms
+        //   n_payload = 8 + ceil((80 − 28 + 28 + 16) / 28) · 5 = 8 + 4·5 = 28
+        //   T_payload = 28 · 1.024 = 28.672 ms
+        //   Total ≈ 41.22 ms
+        approx(toa_us(&c, 10), 41_216, 2);
+    }
+
+    #[test]
+    fn toa_sf12_bw125_cr45_pl10_explicit_crc() {
+        let c = cfg(12, LoRaBandwidth::Khz125, LoRaCodingRate::Cr4_5, 8, false, true);
+        // Reference: ~991 ms for PL=10 at SF12/BW125/CR4/5 (LDRO on).
+        approx(toa_us(&c, 10), 991_000, 2);
+    }
+
+    #[test]
+    fn toa_sf10_bw125_cr45_pl255_max() {
+        let c = cfg(10, LoRaBandwidth::Khz125, LoRaCodingRate::Cr4_5, 8, false, true);
+        // Reference: ~2.34 s for PL=255 at SF10/BW125/CR4/5.
+        approx(toa_us(&c, 255), 2_335_000, 2);
+    }
+
+    #[test]
+    fn toa_ldro_activates_at_sf11_and_sf12_bw125() {
+        // T_sym > 16 ms → DE=1. SF11/BW125: T_sym = 16.384 ms. SF10/BW125: 8.192 ms.
+        let sf10 = cfg(10, LoRaBandwidth::Khz125, LoRaCodingRate::Cr4_5, 8, false, true);
+        let sf11 = cfg(11, LoRaBandwidth::Khz125, LoRaCodingRate::Cr4_5, 8, false, true);
+        let sf12 = cfg(12, LoRaBandwidth::Khz125, LoRaCodingRate::Cr4_5, 8, false, true);
+        // Crude check: each step roughly doubles airtime (LDRO doesn't
+        // break the doubling trend — it just shifts constants).
+        let t10 = toa_us(&sf10, 80);
+        let t11 = toa_us(&sf11, 80);
+        let t12 = toa_us(&sf12, 80);
+        assert!(t11 > t10 * 15 / 10, "SF11 should be > 1.5x SF10, got {} vs {}", t11, t10);
+        assert!(t12 > t11 * 15 / 10, "SF12 should be > 1.5x SF11, got {} vs {}", t12, t11);
+    }
+
+    #[test]
+    fn toa_assumed_peer_80b_matches_plan_table() {
+        let mk = |sf, bw| cfg(sf, bw, LoRaCodingRate::Cr4_5, 8, false, true);
+        // Plan table values (approximate, within 5%).
+        approx(toa_us(&mk(7, LoRaBandwidth::Khz500), 80), 36_000, 5);
+        approx(toa_us(&mk(7, LoRaBandwidth::Khz250), 80), 72_000, 5);
+        approx(toa_us(&mk(7, LoRaBandwidth::Khz125), 80), 144_000, 5);
+        approx(toa_us(&mk(8, LoRaBandwidth::Khz125), 80), 257_000, 5);
+        approx(toa_us(&mk(9, LoRaBandwidth::Khz125), 80), 452_000, 5);
+        approx(toa_us(&mk(10, LoRaBandwidth::Khz125), 80), 862_000, 5);
+        approx(toa_us(&mk(11, LoRaBandwidth::Khz125), 80), 1_806_000, 5);
+        approx(toa_us(&mk(12, LoRaBandwidth::Khz125), 80), 3_285_000, 5);
+    }
+
+    #[test]
+    fn toa_no_underflow_at_small_pl_sf12_implicit_no_crc() {
+        // num = 8·PL − 4·SF + 28 + 16·CRC − 20·H goes negative here; the
+        // i64 + max(0) guard must kick in without panicking or wrapping.
+        let c = cfg(12, LoRaBandwidth::Khz125, LoRaCodingRate::Cr4_5, 8, true, false);
+        let t = toa_us(&c, 1);
+        // Only 8 payload symbols survive (the formula floors to 0 extra);
+        // should be preamble + 8·T_sym ≈ 401 + 262 = 663 ms roughly.
+        approx(t, 663_000, 5);
+    }
+
+    // Retry-count derivation table from the plan.
+
+    #[test]
+    fn retries_sf7_bw500_hits_hard_cap() {
+        let (n, s) = cad_retries(36_000);
+        assert_eq!(n, 10);
+        assert_eq!(s, 36_000);
+    }
+
+    #[test]
+    fn retries_sf10_bw125() {
+        // T_assumed ≈ 862 ms; budget 2.5 s ⇒ 2 sleeps ⇒ 3 retries.
+        let (n, _) = cad_retries(862_000);
+        assert_eq!(n, 3);
+    }
+
+    #[test]
+    fn retries_sf11_bw125() {
+        // T_assumed ≈ 1.81 s; budget 2.5 s ⇒ 1 sleep ⇒ 2 retries.
+        let (n, _) = cad_retries(1_806_000);
+        assert_eq!(n, 2);
+    }
+
+    #[test]
+    fn retries_sf12_bw125_degraded() {
+        // T_assumed ≈ 3.29 s > 2.5 s budget ⇒ 0 sleeps ⇒ 1 retry (bail on busy).
+        let (n, _) = cad_retries(3_285_000);
+        assert_eq!(n, 1);
+    }
+
+    #[test]
+    fn retries_zero_delay_falls_back_to_single_cad() {
+        // Unconfigured safety: avoid divide-by-zero.
+        let (n, s) = cad_retries(0);
+        assert_eq!(n, 1);
+        assert_eq!(s, 0);
+    }
+
+    // Jitter sanity.
+
+    #[test]
+    fn jitter_stays_within_pm_20_pct() {
+        let base = 1_000_000u32;
+        // Exhaustive over the low byte — enough to cover the `% span` range.
+        let mut saw_low = false;
+        let mut saw_high = false;
+        for e in 0u32..=u16::MAX as u32 {
+            let j = jittered_sleep_us(base, e);
+            // ±20% ⇒ [800_000, 1_200_000].
+            assert!(
+                (800_000..=1_200_000).contains(&j),
+                "jitter {} us out of ±20% bounds for entropy {}",
+                j,
+                e
+            );
+            if j <= 850_000 {
+                saw_low = true;
+            }
+            if j >= 1_150_000 {
+                saw_high = true;
+            }
+        }
+        assert!(saw_low && saw_high, "jitter didn't span the expected range");
+    }
+
+    #[test]
+    fn jitter_zero_base_is_zero() {
+        for e in [0u32, 1, 42, 0xDEAD_BEEF] {
+            assert_eq!(jittered_sleep_us(0, e), 0);
+        }
+    }
+}
@@ -29,6 +29,7 @@ mod driver;
 mod hal;
 #[cfg(not(test))]
 mod host;
+mod lbt;
 mod protocol;
 #[cfg(not(test))]
 mod radio;
@@ -45,12 +46,15 @@ use crate::protocol::{cap, Info, MAX_MCU_UID_LEN, MAX_RADIO_UID_LEN};

 #[cfg(not(test))]
 cfg_if::cfg_if! {
-    if #[cfg(any(feature = "rak_wisblock_4631", feature = "wio_tracker_l1", feature = "waveshare_rp2040_lora"))] {
+    if #[cfg(any(feature = "heltec_mesh_node_t114", feature = "rak_wisblock_4631", feature = "wio_tracker_l1", feature = "waveshare_rp2040_lora"))] {
        use defmt_rtt as _;
        use panic_probe as _;
-    } else if #[cfg(any(feature = "heltec_v3", feature = "heltec_v3_uart", feature = "heltec_v4", feature = "elecrow_thinknode_m2"))] {
+    } else if #[cfg(any(feature = "heltec_v3", feature = "heltec_v3_uart", feature = "heltec_v4", feature = "elecrow_thinknode_m2", feature = "lilygo_tbeam_supreme", feature = "lilygo_tbeam"))] {
        use esp_backtrace as _;
        use esp_println as _;
+        // Emits the IDF app descriptor into `.flash.appdesc`. espflash v4
+        // refuses any ESP image that lacks it.
+        esp_bootloader_esp_idf::esp_app_desc!();
    }
 }

@@ -67,12 +71,12 @@ static mut INFO: Option<Info> = None;

 #[cfg(not(test))]
 cfg_if::cfg_if! {
-    if #[cfg(any(feature = "rak_wisblock_4631", feature = "wio_tracker_l1", feature = "waveshare_rp2040_lora"))] {
+    if #[cfg(any(feature = "heltec_mesh_node_t114", feature = "rak_wisblock_4631", feature = "wio_tracker_l1", feature = "waveshare_rp2040_lora"))] {
        #[embassy_executor::main]
        async fn main(spawner: Spawner) {
            run(spawner).await;
        }
-    } else if #[cfg(any(feature = "heltec_v3", feature = "heltec_v3_uart", feature = "heltec_v4", feature = "elecrow_thinknode_m2"))] {
+    } else if #[cfg(any(feature = "heltec_v3", feature = "heltec_v3_uart", feature = "heltec_v4", feature = "elecrow_thinknode_m2", feature = "lilygo_tbeam_supreme", feature = "lilygo_tbeam"))] {
        #[esp_rtos::main]
        async fn main(spawner: Spawner) {
            run(spawner).await;
@@ -83,6 +87,15 @@ cfg_if::cfg_if! {
 #[cfg(not(test))]
 async fn run(spawner: Spawner) {
    let board = <board::Board as LoRaBoard>::init();
+
+    // Read + log + clear POWER.RESETREAS before any other boot output so
+    // the cause of the *previous* reset (if any) lands at the very top
+    // of the RTT log. Critical for soak-debugging silent crash-reboots:
+    // a self-rebooting firmware otherwise looks like the log just
+    // restarted with no explanation. nRF52840-only.
+    #[cfg(any(feature = "heltec_mesh_node_t114", feature = "rak_wisblock_4631", feature = "wio_tracker_l1"))]
+    crate::hal::nrf52840::dump_reset_reason();
+
    let parts = board.into_parts();

    // Build the GET_INFO struct once at boot. This is the authoritative
@@ -140,6 +153,8 @@ fn build_info(mac: [u8; 6]) -> Info {
    let (fmin, fmax) = <board::Board as LoRaBoard>::freq_range_hz();
    let chip_id = <board::Board as LoRaBoard>::radio_chip_id();
    let (tx_min, tx_max) = board::Board::TX_POWER_RANGE;
+    let supported_sf = <board::Board as LoRaBoard>::supported_sf_bitmap();
+    let supported_bw = <board::Board as LoRaBoard>::supported_bw_bitmap();

    let mut mcu_uid = [0u8; MAX_MCU_UID_LEN];
    mcu_uid[..6].copy_from_slice(&mac);
@@ -152,12 +167,8 @@ fn build_info(mac: [u8; 6]) -> Info {
        fw_patch: parse_u8_or(env!("CARGO_PKG_VERSION_PATCH"), 0),
        radio_chip_id: chip_id,
        capability_bitmap: cap::LORA | cap::CAD_BEFORE_TX,
-        // SX126x supports SF5–SF12 (LLCC68 tops out at SF11 — that board
-        // can override this via a board-level trait method later).
-        supported_sf_bitmap: 0x1FE0,
-        // Sub-GHz BW enum values 0..9. SX128x would flip 10..13; add as
-        // boards come online.
-        supported_bw_bitmap: 0x03FF,
+        supported_sf_bitmap: supported_sf,
+        supported_bw_bitmap: supported_bw,
        max_payload_bytes: crate::protocol::MAX_OTA_PAYLOAD as u16,
        // Real channel depths from channel.rs.
        rx_queue_capacity: 32,