chore: release 1.5.0

Adds nRF52840 + SX1262 + 1.14" 240×135 ST7789 color TFT support. First
color display board in the project; introduces a BoardDisplay trait so
each board renders to its native pixel format and resolution without
aliasing or color-quantization round-trips.

Architecture:
- New BoardDisplay trait (src/display.rs) bundles render_*, present(),
  set_bright/set_dim. Replaces the old DrawTarget<Color=BinaryColor>
  + DisplayBrightness combo as the LoRaBoard::DisplayDriver bound.
- Mono OLED drivers (Sh1106, Ssd1306Async) get adapter impls that
  delegate to the existing display::render module — no behavior change
  for any existing board.
- T114 ST7789 driver (src/driver/st7789.rs) wraps lcd-async (async fork
  of mipidsi) with a 64,800-byte raw byte framebuffer in .bss. Renders
  via lcd_async::raw_framebuf::RawFrameBuf<Rgb565, _>, 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.
- PWM backlight on PWM0 / P0.15 (active-LOW, inverted polarity) for
  smooth dim/bright transitions instead of GPIO toggle.
- Native 240×135 Rgb565 renderer (src/display/render_color.rs) with
  splash + dashboard + sparkline.
- Shared QR-code blit (src/display/qr.rs), generic over PixelColor,
  re-centers the 64×64 bitmap which has cells in cols 0..50 and ~14 px
  of right-side padding — both mono and color splash now show the QR
  with 7 px quiet zones on all four sides (was visibly left-shifted).
- 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.

Hardware:
- VEXT_ENABLE on P0.21 driven HIGH at boot — powers 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; backlight on P0.15, active LOW.
- TFT SPI2 (SCK P1.08 / MOSI P1.09) at 8 MHz over EasyDMA. Async
  ExclusiveDevice from embedded-hal-bus (with the 'async' feature).
- lcd-async builder at display_size(135, 240), display_offset(52, 40),
  Deg90 rotation, ColorInversion::Inverted — standard 1.14" ST7789
  die mapping.
- Linker: shared ld/nrf52840-memory.x (S140 SoftDevice preserved at
  0x01000-0x26000 per project policy).

CHANGELOG.md

@@ -7,6 +7,442 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- **OLED auto-dim after inactivity.** The display is bright on any
+  activity — splash entry, mode change into a dashboard leaf, packet
+  RX/TX — and dims after a short idle window. Splash holds bright for
+  10 s, then drops to dim while the LearnMore / Info carousel keeps
+  alternating. The dashboard stays bright for 3 s after the last
+  packet or mode change, then dims in place without changing
+  Listening/Transmitting state. Cross-leaf TX↔RX hops transition
+  bright→bright with no intermediate dim — `set_dim` is fired as an
+  action by the 3 s timer handler rather than as a sibling `exit:`
+  action, so mode-change leaf-crossings never see a flash.
+- `DisplayBrightness` trait in `src/driver/mod.rs` unifies the
+  two-level backlight API across the `ssd1306` crate's `Ssd1306Async`
+  and the in-tree `Sh1106` driver. Contrast values centralized as
+  `CONTRAST_BRIGHT` (`0xFF`) and `CONTRAST_DIM` (`0x08`) constants so
+  the two levels can be tuned in one place.
+
+### Changed
+
+- `src/display.rs` statechart restructured:
+  - `Splash` gains `entry: set_bright` plus an action-only
+    `on(after 10s) => set_dim` handler so the splash bright window
+    is time-scoped without disturbing the LM↔Info alternation.
+  - `Dashboard` `Listening` and `Transmitting` each gain a nested
+    `*Bright` substate owning the `entry: set_bright` action. Packet
+    handlers moved into the leaves and target the leaf's `*Bright` —
+    sibling-to-sibling within the leaf restarts the 3 s timer without
+    re-entering the leaf itself (paint / 1 s sparkline timer
+    preserved). The 3 s timeout handler fires `set_dim` as an action
+    and up-transitions to the leaf, parking the machine at the leaf
+    with no active child.
+- `On.on(CmdReset)` now targets `LearnMore` directly rather than
+  `Splash`. Under hsmc 0.2 up-transition semantics, targeting
+  `Splash` from within `Splash.LearnMore` (USB-disconnect race path)
+  would only unwind below `Splash` and park with no active child,
+  leaving the LM↔Info alternation timer dead and the QR frozen on
+  screen.
+- `LoRaBoard::DisplayDriver` trait bound extended with
+  `+ DisplayBrightness` so brightness is part of the board contract
+  alongside `DrawTarget<Color = BinaryColor>`.
+
+### Fixed
+
+- Elecrow ThinkNode-M2 board doc corrected: the shipping revision
+  carries a WCH CH340K USB-UART bridge (USB `1a86:7522`), not a
+  Silicon Labs CP2102. `just flash elecrow_thinknode_m2` now matches
+  the CH340K / CH340 VID:PIDs directly instead of falling through
+  to espflash auto-detect.
+
+### Dependencies
+
+- `hsmc` bumped to `0.2` to pick up the up-transition fix (transition
+  to an already-active ancestor unwinds only the subtree strictly
+  below the target; no exit/entry on the target; no default descent).
+
+## [1.1.0] - 2026-04-22
+
+Small but high-value behavior change: `SET_CONFIG` issued while the
+radio is in continuous RX no longer drops the radio (and the OLED)
+back to idle. The radio now auto-re-arms RX with the new modulation
+once reconfiguration completes, matching DongLoRa Protocol 1.1's
+§3.5 / §6.3 amendments.
+
+### Changed
+
+- `src/radio.rs`: inside `state Receiving`, add `on(ConfigApplied)
+  => ResumingRx` to shadow the parent `Configured` state's
+  `on(ConfigApplied) => Idle` handler. The reconfigure path now
+  runs `apply_set_config` → `ConfigApplied` → `ResumingRx.entry:
+  try_start_rx_hw` → `StartRxOk` → `Receiving` without ever
+  entering `Idle`.
+- The OLED's `Dashboard → Splash` transition was previously driven
+  by `RadioEvent::Idle` firing on `Configured.Idle.entry`. That
+  event no longer fires during a SET_CONFIG-from-Receiving
+  sequence, so the display stays on Dashboard.
+
+### Dependencies
+
+- `donglora-protocol` bumped to `1.1.0` (spec-only change; matches
+  the new normative text the firmware now implements).
+
+### Use-case unlock
+
+- Scanner / time-division / dynamic-modulation workflows that
+  rotate LoRa parameters mid-RX no longer need to re-issue
+  `RX_START` after every `SET_CONFIG`. One call, radio continues
+  to receive.
+
 ## [1.0.0] - 2026-04-22
 
 The 1.0 release. Firmware now speaks DongLoRa Protocol v2 end to end,

Cargo.lock

@@ -2,6 +2,17 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "aes"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66bd29a732b644c0431c6140f370d097879203d79b80c94a6747ba0872adaef8"
+dependencies = [
+ "cipher",
+ "cpubits",
+ "cpufeatures 0.3.0",
+]
+
 [[package]]
 name = "ahash"
 version = "0.8.12"
@@ -114,9 +125,9 @@ checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
 
 [[package]]
 name = "bitflags"
-version = "2.11.0"
+version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
+checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 
 [[package]]
 name = "block-buffer"
@@ -127,6 +138,15 @@ dependencies = [
  "generic-array",
 ]
 
+[[package]]
+name = "block-buffer"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdd35008169921d80bc60d3d0ab416eecb028c4cd653352907921d95084790be"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "byte-slice-cast"
 version = "1.2.3"
@@ -147,9 +167,9 @@ checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
 [[package]]
 name = "cc"
-version = "1.2.60"
+version = "1.2.61"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20"
+checksum = "d16d90359e986641506914ba71350897565610e87ce0ad9e6f28569db3dd5c6d"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -172,6 +192,33 @@ dependencies = [
  "pure-rust-locales",
 ]
 
+[[package]]
+name = "cipher"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e34d8227fe1ba289043aeb13792056ff80fd6de1a9f49137a5f499de8e8c78ea"
+dependencies = [
+ "crypto-common 0.2.1",
+ "inout",
+]
+
+[[package]]
+name = "cmac"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac78aa94ce13e432b332a4d1bf2eff167d3a2520188ee05b337180a42fd2e62e"
+dependencies = [
+ "cipher",
+ "dbl",
+ "digest 0.11.2",
+]
+
+[[package]]
+name = "cmov"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f88a43d011fc4a6876cb7344703e297c71dda42494fee094d5f7c76bf13f746"
+
 [[package]]
 name = "codespan-reporting"
 version = "0.11.1"
@@ -225,6 +272,12 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "cpubits"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15b85f9c39137c3a891689859392b1bd49812121d0d61c9caf00d46ed5ce06ae"
+
 [[package]]
 name = "cpufeatures"
 version = "0.2.17"
@@ -234,6 +287,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "crc-any"
 version = "2.5.0"
@@ -265,6 +327,24 @@ dependencies = [
  "typenum",
 ]
 
+[[package]]
+name = "crypto-common"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77727bb15fa921304124b128af125e7e3b968275d1b108b379190264f4423710"
+dependencies = [
+ "hybrid-array",
+]
+
+[[package]]
+name = "ctutils"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d5515a3834141de9eafb9717ad39eea8247b5674e6066c404e8c4b365d2a29e"
+dependencies = [
+ "cmov",
+]
+
 [[package]]
 name = "darling"
 version = "0.20.11"
@@ -368,6 +448,15 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "dbl"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0d7a944e61df464668c5f51f56cc667396a8821434273112948ea0b66e405d7"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "debug-helper"
 version = "0.3.13"
@@ -417,12 +506,12 @@ dependencies = [
 
 [[package]]
 name = "defmt-rtt"
-version = "1.1.0"
+version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "93d5a25c99d89c40f5676bec8cefe0614f17f0f40e916f98e345dae941807f9e"
+checksum = "c6eca0aae8aa2cf8333200ecbd236274697bc0a394765c858b3d9372eb1abcfa"
 dependencies = [
  "critical-section",
- "defmt 1.0.1",
+ "defmt 0.3.100",
 ]
 
 [[package]]
@@ -442,8 +531,19 @@ version = "0.10.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
- "block-buffer",
- "crypto-common",
+ "block-buffer 0.10.4",
+ "crypto-common 0.1.7",
+]
+
+[[package]]
+name = "digest"
+version = "0.11.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4850db49bf08e663084f7fb5c87d202ef91a3907271aff24a94eb97ff039153c"
+dependencies = [
+ "block-buffer 0.12.0",
+ "crypto-common 0.2.1",
+ "ctutils",
 ]
 
 [[package]]
@@ -486,13 +586,13 @@ dependencies = [
 
 [[package]]
 name = "donglora"
-version = "1.0.0"
+version = "1.5.0"
 dependencies = [
  "cfg-if",
  "cortex-m",
  "cortex-m-rt",
  "critical-section",
- "defmt 1.0.1",
+ "defmt 0.3.100",
  "defmt-rtt",
  "display-interface",
  "donglora-protocol",
@@ -508,13 +608,16 @@ dependencies = [
  "embedded-graphics",
  "embedded-hal 1.0.0",
  "embedded-hal-async",
+ "embedded-hal-bus",
  "embedded-io-async 0.7.0",
  "esp-backtrace",
+ "esp-bootloader-esp-idf",
  "esp-hal",
  "esp-println",
  "esp-rtos",
  "heapless 0.9.2",
  "hsmc",
+ "lcd-async",
  "lora-phy",
  "minijinja",
  "owo-colors",
@@ -527,9 +630,9 @@ dependencies = [
 
 [[package]]
 name = "donglora-protocol"
-version = "1.0.0"
+version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c8f2743ac7668845500e3686890917cdf5b0a09d17ec099bde2db4d3fae2a4a4"
+checksum = "6bae9e9e5a8cebc6b4167f9ef696b61ce25b94c6d8283dbe1b2e97075a481b9d"
 dependencies = [
  "defmt 1.0.1",
  "heapless 0.9.2",
@@ -643,7 +746,7 @@ version = "0.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b715380574504335c40ec3016bc44598fac3c385f82959b26c41b25c30b7648d"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "cfg-if",
  "cortex-m",
  "cortex-m-rt",
@@ -780,12 +883,12 @@ dependencies = [
 
 [[package]]
 name = "embassy-time-queue-utils"
-version = "0.3.0"
+version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "80e2ee86063bd028a420a5fb5898c18c87a8898026da1d4c852af2c443d0a454"
+checksum = "168297bf80aaf114b3c9ad589bf38b01b3009b9af7f97cd18086c5bbf96f5693"
 dependencies = [
  "embassy-executor-timer-queue",
- "heapless 0.8.0",
+ "heapless 0.9.2",
 ]
 
 [[package]]
@@ -794,7 +897,7 @@ version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a25746d8b152b72fbf2a217f489a083dbbe243f281f09184a1f2cfbe9bbb245f"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "defmt 1.0.1",
  "embassy-futures",
  "embassy-net-driver-channel",
@@ -885,6 +988,17 @@ dependencies = [
  "embedded-hal 1.0.0",
 ]
 
+[[package]]
+name = "embedded-hal-bus"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "513e0b3a8fb7d3013a8ae17a834283f170deaf7d0eeab0a7c1a36ad4dd356d22"
+dependencies = [
+ "critical-section",
+ "embedded-hal 1.0.0",
+ "embedded-hal-async",
+]
+
 [[package]]
 name = "embedded-hal-nb"
 version = "1.0.0"
@@ -984,8 +1098,9 @@ checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
 
 [[package]]
 name = "esp-backtrace"
-version = "0.18.1"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "0.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37950e24b2dfd98f1581102d1798281d4d9547af881e6bffc2c2b534c026ec8f"
 dependencies = [
  "cfg-if",
  "defmt 1.0.1",
@@ -999,10 +1114,29 @@ dependencies = [
  "xtensa-lx",
 ]
 
+[[package]]
+name = "esp-bootloader-esp-idf"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35ffc117c3a9859835d89d0e90f5ee9886ce2264a71a849a7a22ab5308f6653c"
+dependencies = [
+ "cfg-if",
+ "defmt 1.0.1",
+ "document-features",
+ "embedded-storage",
+ "esp-config",
+ "esp-hal-procmacros",
+ "esp-metadata-generated",
+ "esp-rom-sys",
+ "jiff",
+ "strum",
+]
+
 [[package]]
 name = "esp-config"
-version = "0.6.1"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4d9b92fd9cfb0b4f8f1b6219b9763269a335571e307b014903b8201619374b80"
 dependencies = [
  "document-features",
  "esp-metadata-generated",
@@ -1013,16 +1147,17 @@ dependencies = [
 
 [[package]]
 name = "esp-hal"
-version = "1.0.0"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6af8fa8216bc126941bd43b5a200a50eab16e43881ccd0dd0b6792f4a82805f0"
 dependencies = [
  "bitfield 0.19.4",
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "bytemuck",
  "cfg-if",
  "critical-section",
  "delegate",
- "digest",
+ "digest 0.10.7",
  "document-features",
  "embassy-embedded-hal",
  "embassy-futures",
@@ -1056,10 +1191,12 @@ dependencies = [
  "nb 1.1.0",
  "paste",
  "portable-atomic",
- "rand_core 0.10.0",
+ "rand_core 0.10.1",
  "rand_core 0.6.4",
  "rand_core 0.9.5",
  "riscv",
+ "sha1",
+ "sha2",
  "strum",
  "ufmt-write",
  "xtensa-lx",
@@ -1068,8 +1205,9 @@ dependencies = [
 
 [[package]]
 name = "esp-hal-procmacros"
-version = "0.21.0"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "0.22.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6aebfabb2c21bec45e575e4f6cb6bb7aa8e1b33e7ac45b5dffa0f9d33ff59105"
 dependencies = [
  "document-features",
  "object",
@@ -1082,13 +1220,15 @@ dependencies = [
 
 [[package]]
 name = "esp-metadata-generated"
-version = "0.3.0"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42c2ee95b945a4780796e4359e72c033aed3b45073880e8029458f538532db8a"
 
 [[package]]
 name = "esp-println"
-version = "0.16.1"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42dee1e9ac7c3539bf6464db1707b0edd7557168f98278cf3c84fe70e63c6ce6"
 dependencies = [
  "defmt 1.0.1",
  "document-features",
@@ -1100,8 +1240,9 @@ dependencies = [
 
 [[package]]
 name = "esp-riscv-rt"
-version = "0.13.0"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66a814ae91452de56a5e74f69aebfee40579511756837d3774a56fd24cf0ab79"
 dependencies = [
  "document-features",
  "riscv",
@@ -1110,19 +1251,22 @@ dependencies = [
 
 [[package]]
 name = "esp-rom-sys"
-version = "0.1.3"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eae852ccb08971155023d1371c96d5490cbc26860f06aee2d629ef73f1a890c3"
 dependencies = [
  "cfg-if",
  "document-features",
  "esp-metadata-generated",
+ "esp32",
  "esp32s3",
 ]
 
 [[package]]
 name = "esp-rtos"
-version = "0.2.0"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "551f90766e1527edaa0c91e8d559e9e2a60397b545e93357ac61fb31845e5712"
 dependencies = [
  "cfg-if",
  "document-features",
@@ -1143,8 +1287,9 @@ dependencies = [
 
 [[package]]
 name = "esp-sync"
-version = "0.1.1"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4736bfbbb9e3f6353344e14fc61b6d18d3b877c3286914cf8c0a037be0ed224"
 dependencies = [
  "cfg-if",
  "document-features",
@@ -1171,67 +1316,73 @@ dependencies = [
 
 [[package]]
 name = "esp32"
-version = "0.39.0"
-source = "git+https://github.com/esp-rs/esp-pacs?rev=fc3e6d4#fc3e6d4b34cfc885f750641d27e6fe3e63bad5d2"
+version = "0.40.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5726e07689249d1a2cb7c492077bc424837fb68a64f7eb5d46569325352e9428"
 dependencies = [
- "critical-section",
  "vcell",
 ]
 
 [[package]]
 name = "esp32c2"
-version = "0.28.0"
-source = "git+https://github.com/esp-rs/esp-pacs?rev=fc3e6d4#fc3e6d4b34cfc885f750641d27e6fe3e63bad5d2"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ef0b623533bbaa37e348c18b6b41cfd5b47c3cb64a4b9e44f0295941d62aa2e"
 dependencies = [
- "critical-section",
  "vcell",
 ]
 
 [[package]]
 name = "esp32c3"
-version = "0.31.0"
-source = "git+https://github.com/esp-rs/esp-pacs?rev=fc3e6d4#fc3e6d4b34cfc885f750641d27e6fe3e63bad5d2"
+version = "0.32.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21e89ed62cf6c043a6d29c520b02a13b359ec8a75d67b65d4330ed717d15fe97"
 dependencies = [
- "critical-section",
  "vcell",
 ]
 
 [[package]]
 name = "esp32c6"
-version = "0.22.0"
-source = "git+https://github.com/esp-rs/esp-pacs?rev=fc3e6d4#fc3e6d4b34cfc885f750641d27e6fe3e63bad5d2"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c58f34ff2633968c12125efc7f4f8f101078d5d34c7cb60eab82268db20986f9"
 dependencies = [
- "critical-section",
  "vcell",
 ]
 
 [[package]]
 name = "esp32h2"
-version = "0.18.0"
-source = "git+https://github.com/esp-rs/esp-pacs?rev=fc3e6d4#fc3e6d4b34cfc885f750641d27e6fe3e63bad5d2"
+version = "0.19.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c5bab026020ed4606ce113b6fde598dbc48f7eefcc46e9469ece77cc2b1aa4be"
 dependencies = [
- "critical-section",
  "vcell",
 ]
 
 [[package]]
 name = "esp32s2"
-version = "0.30.0"
-source = "git+https://github.com/esp-rs/esp-pacs?rev=fc3e6d4#fc3e6d4b34cfc885f750641d27e6fe3e63bad5d2"
+version = "0.31.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0ad6f21cdf6ec7b06b7f7e0fbe51f0d975fd6a5fa67c3f8a5a910d3981af531"
 dependencies = [
- "critical-section",
  "vcell",
 ]
 
 [[package]]
 name = "esp32s3"
-version = "0.34.0"
-source = "git+https://github.com/esp-rs/esp-pacs?rev=fc3e6d4#fc3e6d4b34cfc885f750641d27e6fe3e63bad5d2"
+version = "0.35.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b4b8c4e4d9f187553ecdb7173edec7b2deb2beea106eedefecdb1654b8ee25a"
 dependencies = [
- "critical-section",
  "vcell",
 ]
 
+[[package]]
+name = "fastrand"
+version = "2.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -1280,12 +1431,42 @@ dependencies = [
  "gcd",
 ]
 
+[[package]]
+name = "futures"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b147ee9d1f6d097cef9ce628cd2ee62288d963e16fb287bd9286455b241382d"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-sink",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+]
+
 [[package]]
 name = "futures-core"
 version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
 
+[[package]]
+name = "futures-io"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718"
+
 [[package]]
 name = "futures-sink"
 version = "0.3.32"
@@ -1305,6 +1486,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
 dependencies = [
  "futures-core",
+ "futures-sink",
  "futures-task",
  "pin-project-lite",
 ]
@@ -1371,9 +1553,9 @@ dependencies = [
 
 [[package]]
 name = "hashbrown"
-version = "0.16.1"
+version = "0.17.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+checksum = "4f467dd6dccf739c208452f8014c75c18bb8301b050ad1cfb27153803edb0f51"
 
 [[package]]
 name = "heapless"
@@ -1403,11 +1585,18 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
 [[package]]
-name = "hsmc"
-version = "0.1.0"
+name = "hex"
+version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2d8cb8820e7ff5fa4fa4b5dbb78b9f59d26ccc8e3bcf69d8f4c4ce29ee01b93a"
+checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
+
+[[package]]
+name = "hsmc"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "497ed9593e4baf6ef120b24aff80cb898f6832d32cdf01be9d90be0c06624e77"
 dependencies = [
+ "defmt 0.3.100",
  "embassy-futures",
  "embassy-sync 0.8.0",
  "embassy-time",
@@ -1417,15 +1606,24 @@ dependencies = [
 
 [[package]]
 name = "hsmc-macros"
-version = "0.1.0"
+version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4fa4dad2c05309fae4f6d15b74d9b37c1fd7325a96701972fdad89637635160"
+checksum = "49d0b1413ed69ba168f9d0edbf4a8ea21569eaf352edf4e11335ae3d765ba004"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "hybrid-array"
+version = "0.4.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08d46837a0ed51fe95bd3b05de33cd64a1ee88fc797477ca48446872504507c5"
+dependencies = [
+ "typenum",
+]
+
 [[package]]
 name = "ident_case"
 version = "1.0.1"
@@ -1434,12 +1632,12 @@ checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
 
 [[package]]
 name = "indexmap"
-version = "2.13.0"
+version = "2.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown 0.16.1",
+ "hashbrown 0.17.0",
 ]
 
 [[package]]
@@ -1451,6 +1649,15 @@ dependencies = [
  "rustversion",
 ]
 
+[[package]]
+name = "inout"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4250ce6452e92010fdf7268ccc5d14faa80bb12fc741938534c58f16804e03c7"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "instability"
 version = "0.3.12"
@@ -1479,13 +1686,37 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
+[[package]]
+name = "jiff"
+version = "0.2.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f00b5dbd620d61dfdcb6007c9c1f6054ebd75319f163d886a9055cec1155073d"
+dependencies = [
+ "jiff-static",
+ "log",
+ "portable-atomic",
+ "portable-atomic-util",
+ "serde_core",
+]
+
+[[package]]
+name = "jiff-static"
+version = "0.2.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e000de030ff8022ea1da3f466fbb0f3a809f5e51ed31f6dd931c35181ad8e6d7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "keccak"
 version = "0.1.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cb26cec98cce3a3d96cbb7bced3c4b16e3d13f27ec56dbd62cbc8f39cfb9d653"
 dependencies = [
- "cpufeatures",
+ "cpufeatures 0.2.17",
 ]
 
 [[package]]
@@ -1527,10 +1758,22 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 
 [[package]]
-name = "libc"
-version = "0.2.184"
+name = "lcd-async"
+version = "0.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
+checksum = "359805d2afdff45f3abad226ae27a61ee980309562d14084842c542af29b422a"
+dependencies = [
+ "embedded-graphics",
+ "embedded-graphics-core",
+ "embedded-hal 1.0.0",
+ "embedded-hal-async",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
 [[package]]
 name = "litrs"
@@ -1569,22 +1812,62 @@ dependencies = [
 [[package]]
 name = "lora-modulation"
 version = "0.1.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2c96c4a41a1f1ad04de765306e1829c7007a37898fe4033204fa82cf2e055624"
+source = "git+https://github.com/swaits/lora-rs.git?branch=fixed#e8a52ebd35352ce0267148fd392a0b1956d7735f"
+dependencies = [
+ "defmt 0.3.100",
+]
 
 [[package]]
 name = "lora-phy"
-version = "3.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "61471c3b2909789e3332083577f6cf6c41a4fcf37674ef15156bcbb20504ac65"
+version = "3.0.2-alpha"
+source = "git+https://github.com/swaits/lora-rs.git?branch=fixed#e8a52ebd35352ce0267148fd392a0b1956d7735f"
 dependencies = [
  "defmt 0.3.100",
+ "document-features",
  "embedded-hal 1.0.0",
  "embedded-hal-async",
  "lora-modulation",
+ "lorawan-device",
  "num-traits",
 ]
 
+[[package]]
+name = "lorawan"
+version = "0.9.1"
+source = "git+https://github.com/swaits/lora-rs.git?branch=fixed#e8a52ebd35352ce0267148fd392a0b1956d7735f"
+dependencies = [
+ "aes",
+ "cmac",
+ "defmt 0.3.100",
+ "hex",
+ "lorawan-macros",
+]
+
+[[package]]
+name = "lorawan-device"
+version = "0.12.2"
+source = "git+https://github.com/swaits/lora-rs.git?branch=fixed#e8a52ebd35352ce0267148fd392a0b1956d7735f"
+dependencies = [
+ "defmt 0.3.100",
+ "document-features",
+ "fastrand",
+ "futures",
+ "heapless 0.9.2",
+ "lora-modulation",
+ "lorawan",
+ "rand_core 0.6.4",
+]
+
+[[package]]
+name = "lorawan-macros"
+version = "0.1.0"
+source = "git+https://github.com/swaits/lora-rs.git?branch=fixed#e8a52ebd35352ce0267148fd392a0b1956d7735f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "matchers"
 version = "0.2.0"
@@ -1627,9 +1910,9 @@ checksum = "c3c8dda44ff03a2f238717214da50f65d5a53b45cd213a7370424ffdb6fae815"
 
 [[package]]
 name = "minijinja"
-version = "2.18.0"
+version = "2.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "328251e58ad8e415be6198888fc207502727dc77945806421ab34f35bf012e7d"
+checksum = "805bfd7352166bae857ee569628b52bcd85a1cecf7810861ebceb1686b72b75d"
 dependencies = [
  "memo-map",
  "serde",
@@ -1853,6 +2136,15 @@ dependencies = [
  "critical-section",
 ]
 
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+dependencies = [
+ "portable-atomic",
+]
+
 [[package]]
 name = "precomputed-hash"
 version = "0.1.1"
@@ -1929,7 +2221,7 @@ version = "0.11.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "679341d22c78c6c649893cbd6c3278dcbe9fc4faa62fea3a9296ae2b50c14625"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
  "memchr",
  "unicase",
 ]
@@ -1972,9 +2264,9 @@ checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
 
 [[package]]
 name = "rand_core"
-version = "0.10.0"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c8d0fd677905edcbeedbf2edb6494d676f0e98d54d5cf9bda0b061cb8fb8aba"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
 
 [[package]]
 name = "redox_syscall"
@@ -1982,7 +2274,7 @@ version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 ]
 
 [[package]]
@@ -2204,6 +2496,28 @@ dependencies = [
  "unsafe-libyaml",
 ]
 
+[[package]]
+name = "sha1"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest 0.10.7",
+]
+
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest 0.10.7",
+]
+
 [[package]]
 name = "sha2-const-stable"
 version = "0.1.0"
@@ -2212,11 +2526,11 @@ checksum = "5f179d4e11094a893b82fff208f74d448a7512f99f5a0acbd5c679b705f83ed9"
 
 [[package]]
 name = "sha3"
-version = "0.10.8"
+version = "0.10.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "75872d278a8f37ef87fa0ddbda7802605cb18344497949862c0d4dcb291eba60"
+checksum = "77fd7028345d415a4034cf8777cd4f8ab1851274233b45f84e3d955502d93874"
 dependencies = [
- "digest",
+ "digest 0.10.7",
  "keccak",
 ]
 
@@ -2439,9 +2753,9 @@ dependencies = [
 
 [[package]]
 name = "toml_edit"
-version = "0.25.9+spec-1.1.0"
+version = "0.25.11+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "da053d28fe57e2c9d21b48261e14e7b4c8b670b54d2c684847b91feaf4c7dac5"
+checksum = "0b59c4d22ed448339746c59b905d24568fcbb3ab65a500494f7b8c3e97739f2b"
 dependencies = [
  "indexmap",
  "toml_datetime",
@@ -2451,9 +2765,9 @@ dependencies = [
 
 [[package]]
 name = "toml_parser"
-version = "1.1.1+spec-1.1.0"
+version = "1.1.2+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "39ca317ebc49f06bd748bfba29533eac9485569dc9bf80b849024b025e814fb9"
+checksum = "a2abe9b86193656635d2411dc43050282ca48aa31c2451210f4202550afb7526"
 dependencies = [
  "winnow",
 ]
@@ -2521,9 +2835,9 @@ dependencies = [
 
 [[package]]
 name = "typenum"
-version = "1.19.0"
+version = "1.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
+checksum = "40ce102ab67701b8526c123c1bab5cbe42d7040ccfd0f64af1a385808d2f43de"
 
 [[package]]
 name = "ucobs"
@@ -2690,9 +3004,9 @@ dependencies = [
 
 [[package]]
 name = "winnow"
-version = "1.0.1"
+version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09dac053f1cd375980747450bfc7250c264eaae0583872e845c0c7cd578872b5"
+checksum = "2ee1708bef14716a11bae175f579062d4554d95be2c6829f518df847b7b3fdd0"
 dependencies = [
  "memchr",
 ]
@@ -2700,15 +3014,17 @@ dependencies = [
 [[package]]
 name = "xtensa-lx"
 version = "0.13.0"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e012d667b0aa6d2592ace8ef145a98bff3e76cca7a644f4181ecd7a916ed289b"
 dependencies = [
  "critical-section",
 ]
 
 [[package]]
 name = "xtensa-lx-rt"
-version = "0.21.0"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+version = "0.22.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "409a9b4629d429e995cde4dfbd9fe562ccae66f7624514e200733fc5d0ea8905"
 dependencies = [
  "document-features",
  "xtensa-lx",
@@ -2718,7 +3034,8 @@ dependencies = [
 [[package]]
 name = "xtensa-lx-rt-proc-macros"
 version = "0.5.0"
-source = "git+https://github.com/esp-rs/esp-hal.git?branch=main#70930f20d9f681a30ff20aced39d0bd5363126d5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96fb42cd29c42f8744c74276e9f5bee7b06685bbe5b88df891516d72cb320450"
 dependencies = [
  "proc-macro2",
  "quote",

Cargo.toml

@@ -3,7 +3,7 @@ members = ["."]
 
 [package]
 name = "donglora"
-version = "1.0.0"
+version = "1.5.0"
 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"
@@ -30,51 +28,82 @@ embassy-usb = { version = "0.6", features = ["defmt"] }
 embassy-usb-driver = "0.2"
 ucobs = { version = "0.3", features = ["legacy-msrv"] }
 heapless = "0.9"
-donglora-protocol = "1.0.0"
-hsmc = { version = "0.1.0", default-features = false, features = ["embassy"] }
-lora-phy = "3.0"
-portable-atomic = { version = "1", optional = true, default-features = false, features = ["critical-section"] }
+donglora-protocol = "1"
+hsmc = { version = "0.5", 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

README.md

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

TODO.md

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

build.rs

@@ -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);
 }

config.toml

@@ -0,0 +1,6 @@
+workers = ["app.routes"]
+
+[settings]
+cache = ".script"
+address = "127.0.0.1"
+port = 3500

justfile

@@ -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,19 +54,23 @@ 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"); \
+            port=$(just _find_port "303a:1001" "1209:5741" "10c4:ea60" "1a86:7522" "1a86:7523"); \
             if [ -n "$port" ]; then \
                 echo "Using $port"; \
                 espflash flash -p "$port" "{{builds_dir}}/donglora-{{board}}-v{{version}}.elf"; \
@@ -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

ld/nrf52840-memory.x

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

ld/wio_tracker_l1-memory.x

@@ -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
+}

mise.toml

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

src/board/PORTING.md

@@ -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()`.
 }
 ```
 

src/board/elecrow_thinknode_m2.rs

@@ -1,8 +1,8 @@
 //! ELECROW ThinkNode-M2 — ESP32-S3 Meshtastic handset with SH1106 OLED.
 //!
 //! Tamagotchi-form-factor handheld: ESP32-S3-WROOM-1-N4 + SX1262 + 1.3" SH1106
-//! OLED + CP2102 UART bridge + 1000 mAh Li-Po. Sold pre-loaded with Meshtastic;
-//! this firmware turns it into a DongLoRa radio bridge.
+//! OLED + WCH CH340K UART bridge + 1000 mAh Li-Po. Sold pre-loaded with
+//! Meshtastic; this firmware turns it into a DongLoRa radio bridge.
 //!
 //! Pin map (verified from Meshtastic's variants/esp32s3/ELECROW-ThinkNode-M2
 //! and PR meshtastic/firmware#6354):
@@ -11,7 +11,7 @@
 //!   LoRa pwr: GPIO48 (must be HIGH before any SPI traffic)
 //!   OLED:     I2C0 SDA=16, SCL=15, SH1106 @ 0x3C
 //!   VEXT:     GPIO46 (active HIGH — gates OLED supply)
-//!   UART:     TX=43, RX=44 via CP2102 bridge
+//!   UART:     TX=43, RX=44 via CH340K bridge (USB 1a86:7522)
 //!   LED:      GPIO6 (active HIGH indicator)
 //!
 //! Notable differences from the Heltec ESP32-S3 boards:
@@ -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() {

src/board/esp32.rs

@@ -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,
+    }
+}

src/board/esp32s3.rs

@@ -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();
 

src/board/heltec_mesh_node_t114.rs

@@ -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(),
+        }
+    }
+}

src/board/lilygo_tbeam.rs

@@ -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(),
+        }
+    }
+}

src/board/lilygo_tbeam_supreme.rs

@@ -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(),
+        }
+    }
+}

src/board/mod.rs.j2

@@ -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! {

src/board/rak_wisblock_4631.rs

@@ -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(),
         }
     }

src/board/traits.rs

@@ -6,8 +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::display::BoardDisplay;
 
 /// Async RGB LED control. Boards without an LED use `()` which is a no-op.
 pub trait RgbLed {
@@ -35,8 +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).
-    type DisplayDriver: DrawTarget<Color = BinaryColor>;
+    /// 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;
@@ -62,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,

src/board/waveshare_rp2040_lora.rs

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

src/board/wio_tracker_l1.rs

@@ -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);

src/channel.rs

@@ -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) ────────────
 

src/debug_blink.rs

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

src/display.rs

@@ -40,15 +40,77 @@ use crate::board::{self, Board, DisplayDriver, DisplayParts, LedDriver, LoRaBoar
 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 {
@@ -56,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 {
@@ -163,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) {
@@ -182,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
@@ -220,6 +413,14 @@ impl DisplayContext {
         Timer::after_millis(50).await;
         self.peripherals.led.set_rgb(0, 0, 0).await;
     }
+
+    async fn oled_bright(&mut self) {
+        self.peripherals.display.set_bright().await;
+    }
+
+    async fn oled_dim(&mut self) {
+        self.peripherals.display.set_dim().await;
+    }
 }
 
 // ── Statechart ─────────────────────────────────────────────────────
@@ -228,6 +429,8 @@ statechart! {
     Display {
         context: DisplayContext;
         events: DisplayEvent;
+        // Auto-trace — backend selected by `hsmc/trace-*` cargo feature.
+        trace;
         default(On);
 
         state Off {
@@ -243,16 +446,26 @@ statechart! {
             on(CmdOff) => Off;
             // `CmdReset` + `RadioIdle` race on USB disconnect; this handler
             // makes either ordering land in the same place. Reset the run
-            // state, turn off any blink-in-progress, and re-enter Splash —
-            // descend_defaults lands us in LearnMore with a fresh 5 s timer.
-            on(CmdReset) => reset_run_state, turn_led_off, Splash;
+            // state, turn off any blink-in-progress, and land in LearnMore
+            // with a fresh 5 s timer. We target `LearnMore` (not `Splash`)
+            // because under hsmc 0.2 up-transition semantics, targeting a
+            // state that's already on the active path would only unwind
+            // below it — we'd park at `Splash` with no active child and
+            // the alternation timer would never restart.
+            on(CmdReset) => reset_run_state, turn_led_off, LearnMore;
             // Config can arrive before the dashboard is up; cache it anywhere.
             on(ConfigChanged(cfg: LoRaConfig)) => save_new_config;
 
+            // Splash is bright for the first 10 s of (re-)entry, then the
+            // action-only `on(after 10s)` handler drops the OLED to dim.
+            // LearnMore ↔ Info keep alternating underneath — their own
+            // timers are independent of the 10 s window.
             state Splash {
+                entry: set_bright;
                 default(LearnMore);
                 on(EnteredRx) => Listening;
                 on(EnteredTx) => Transmitting;
+                on(after Duration::from_secs(10)) => set_dim;
 
                 state LearnMore {
                     entry: paint_learn_more;
@@ -265,24 +478,56 @@ statechart! {
                 }
             }
 
+            // Dashboard brightness pattern: each mode-leaf holds a `Bright`
+            // substate. `entry: set_bright` owns the backlight going on;
+            // `set_dim` is fired **as an action** by the 3 s timeout
+            // handler, immediately before the up-transition that parks
+            // the machine at the leaf. The symmetric `exit: set_dim`
+            // would also fire on mode-change leaf-crossings (e.g.
+            // ListeningBright → TransmittingBright via EnteredTx), and
+            // the subsequent default descent would fire `set_bright`
+            // again — producing a visible dim/bright flash on every
+            // TX↔RX swap. Anchoring dim to the *timer* handler instead
+            // means leaf-crossings go bright→bright with no intermediate
+            // dim action. CmdOff/CmdReset exit paths don't fire set_dim
+            // either, which is fine — the display is blanked or walked
+            // back to Splash, which re-asserts its own brightness.
             state Dashboard {
                 default(Listening);
                 on(RadioIdle) => Splash;
 
-                // Packet events are pure data + one-shot LED feedback.
-                on(PacketRx { rssi: i16, snr: Option<i16> }) => record_rx_packet, blink_rx_led;
-                on(PacketTx) => record_tx_packet, blink_tx_led;
-
                 state Listening {
                     entry: paint_listening;
+                    default(ListeningBright);
                     on(EnteredTx) => Transmitting;
                     on(every Duration::from_millis(1000)) => advance_sparkline, paint_listening;
+                    // Split from the transition below because hsmc rejects
+                    // payload bindings on transition-bearing handlers.
+                    on(PacketRx { rssi: i16, snr: Option<i16> }) => record_rx_packet, blink_rx_led;
+                    on(PacketRx) => ListeningBright;
+                    on(PacketTx) => record_tx_packet, blink_tx_led;
+                    on(PacketTx) => ListeningBright;
+
+                    state ListeningBright {
+                        entry: set_bright;
+                        on(after Duration::from_secs(3)) => set_dim, Listening;
+                    }
                 }
 
                 state Transmitting {
                     entry: paint_transmitting;
+                    default(TransmittingBright);
                     on(EnteredRx) => Listening;
                     on(every Duration::from_millis(1000)) => advance_sparkline, paint_transmitting;
+                    on(PacketRx { rssi: i16, snr: Option<i16> }) => record_rx_packet, blink_rx_led;
+                    on(PacketRx) => TransmittingBright;
+                    on(PacketTx) => record_tx_packet, blink_tx_led;
+                    on(PacketTx) => TransmittingBright;
+
+                    state TransmittingBright {
+                        entry: set_bright;
+                        on(after Duration::from_secs(3)) => set_dim, Transmitting;
+                    }
                 }
             }
         }
@@ -355,6 +600,14 @@ impl DisplayActions for DisplayActionContext<'_> {
     async fn advance_sparkline(&mut self) {
         self.run.advance_slot();
     }
+
+    async fn set_bright(&mut self) {
+        self.oled_bright().await;
+    }
+
+    async fn set_dim(&mut self) {
+        self.oled_dim().await;
+    }
 }
 
 // ── Task entry point ───────────────────────────────────────────────
@@ -376,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 {
@@ -430,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::*;
@@ -439,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;
@@ -451,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;
@@ -710,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,
@@ -739,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

src/display/qr.rs

@@ -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);
+}

src/display/render_color.rs

@@ -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);
+    }
+}

src/driver/axp.rs

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

src/driver/inverted_pin.rs

@@ -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()
+    }
+}

src/driver/mod.rs

@@ -1,12 +1,88 @@
-#[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"
 ))]
 pub mod simple_led;
+
+// ── Display brightness ────────────────────────────────────────────────
+//
+// The display statechart dims the OLED a few seconds after the last
+// activity. Our two driver families (`ssd1306` crate and our in-tree
+// `sh1106`) expose incompatible brightness APIs, so we wrap them in a
+// single async trait that the state-machine actions can call uniformly.
+
+/// Two-level backlight control used by the display dashboard.
+pub trait DisplayBrightness {
+    fn set_bright(&mut self) -> impl core::future::Future<Output = ()>;
+    fn set_dim(&mut self) -> impl core::future::Future<Output = ()>;
+}
+
+// Contrast values for the two brightness levels, picked to be common across
+// both driver families. `0xFF` is the SSD1306/SH1106 maximum; `0x08` is ~3%
+// of max — visible in a dim room, barely noticeable in daylight. Tune here.
+const CONTRAST_BRIGHT: u8 = 0xFF;
+const CONTRAST_DIM: u8 = 0x08;
+
+impl<DI, SIZE, MODE> DisplayBrightness for ssd1306::Ssd1306Async<DI, SIZE, MODE>
+where
+    DI: display_interface::AsyncWriteOnlyDataCommand,
+    SIZE: ssd1306::size::DisplaySizeAsync,
+{
+    async fn set_bright(&mut self) {
+        // `Brightness::custom(precharge, contrast)`. Matches the shape of
+        // the crate's BRIGHTEST preset (precharge 0x2) at max contrast.
+        let _ = self
+            .set_brightness(ssd1306::prelude::Brightness::custom(0x2, CONTRAST_BRIGHT))
+            .await;
+    }
+    async fn set_dim(&mut self) {
+        // Low precharge pairs with low contrast — same combination the
+        // crate's DIMMEST preset uses.
+        let _ = self
+            .set_brightness(ssd1306::prelude::Brightness::custom(0x1, CONTRAST_DIM))
+            .await;
+    }
+}
+
+#[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,
+{
+    async fn set_bright(&mut self) {
+        let _ = self.set_brightness(CONTRAST_BRIGHT).await;
+    }
+    async fn set_dim(&mut self) {
+        let _ = self.set_brightness(CONTRAST_DIM).await;
+    }
+}

src/driver/sh1106.rs

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

src/driver/st7789.rs

@@ -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));
+    }
+}

src/hal/esp32.rs

@@ -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")
+}

src/hal/mod.rs

@@ -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")]

src/hal/nrf52840.rs

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

src/host/framing.rs

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

src/host/mod.rs

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

src/host/uart.rs

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

src/host/usb.rs

@@ -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;
-        }
     }
 }
 

src/lbt.rs

@@ -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);
+        }
+    }
+}

src/main.rs

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