chore: release 1.4.0

The CAD pre-TX loop previously ran up to 10 retries with a fixed 10 ms
sleep — roughly one max-length packet only at SF7/BW500. At SF10/BW125
the 100 ms total was ~4% of one packet; at SF12/BW125 LBT was a no-op.

Now the per-retry sleep is sized to one time-on-air of an assumed-peer
80-byte packet under the active config, cached on RadioContext and
recomputed on every SET_CONFIG. Retries scale as
clamp(floor(BUDGET/T)+1, 1, 10) with BUDGET=2.5 s, so fast configs
still get up to 10 retries while SF11/12 degrade to single-CAD-and-bail
(logged at config-apply). Sleeps are jittered ±20% per iteration to
decorrelate simultaneously-backing-off contenders.

The ToA math, CR→{1..4} mapping, retry-count derivation, and jitter
helper live in a pure src/lbt.rs module so they're 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 see zero at the same SF/BW.

.cargo/config.toml

@@ -4,3 +4,17 @@ rustflags = [
     "-C", "link-arg=-Wl,-Tdefmt.x",
     "-C", "link-arg=-nostartfiles",
 ]
+
+[target.thumbv7em-none-eabihf]
+rustflags = [
+    "-C", "link-arg=-Tlink.x",
+    "-C", "link-arg=-Tdefmt.x",
+    "-C", "opt-level=z",
+]
+
+[target.thumbv6m-none-eabi]
+rustflags = [
+    "-C", "link-arg=-Tlink.x",
+    "-C", "link-arg=-Tdefmt.x",
+    "-C", "opt-level=z",
+]

CHANGELOG.md

@@ -0,0 +1,513 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [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,
+depends on the freshly-published `donglora-protocol` 1.0.0 and `hsmc`
+0.1.0 from crates.io, and ships GitHub Release binaries for every
+supported board.
+
+### Breaking
+
+- **DongLoRa Protocol v2 wire format** (wire-incompatible with 0.x
+  clients and firmware). Every `type_id`, tag-correlation rule, and
+  field layout follows `PROTOCOL.md` v1.0.
+- **Host framing replaced.** `src/host/framing.rs` now drives a
+  streaming `FrameDecoder` from `donglora-protocol` and emits
+  `(type_id, tag, payload)` frames; the 0.x COBS-per-response shim is
+  gone.
+- **Radio task reshape.** `src/radio.rs` emits v2 `TX_DONE` /
+  `SetConfigResult` / `RxPayload` / `RxOrigin` shapes directly; no 0.x
+  translation layer remains.
+
+### Changed
+
+- `hsmc` switched from path-dep on the local workspace to
+  `version = "0.1.0"` from crates.io.
+- `donglora-protocol` switched from path-dep on `../protocol` to
+  `version = "1.0.0"` from crates.io; firmware builds are now
+  reproducible from a clean checkout with no sibling repo required.
+- `PROTOCOL.md` updated to the DongLoRa Protocol v2 normative spec,
+  kept byte-for-byte in sync with the `donglora-protocol` crate's
+  copy.
+
+### Infrastructure
+
+- Cargo.toml `repository` + `homepage` now point at the canonical
+  `https://github.com/donglora/firmware` (the `swaits/donglora`
+  repo is archived).
+
+## [0.5.0] - 2026-04-16
+
+### Added
+
+- BLE soft-mesh multiplexer design document (`BLE_MUX_DESIGN_DOC.md`) —
+  specification for turning a dongle from a 1:1 USB device into a shared
+  near-field radio gateway for multiple BLE-attached phones. Three-phase
+  rollout (v1 MVP, v2 hardening, v3 multi-dongle mesh) with regulatory
+  duty-cycle and TX-access-control enforcement from v1. Targets nRF52840
+  first; ESP32-S3 reserved for v2.
+- `debug-checkpoint` cargo feature with a dedicated `debug_blink` task and
+  a latching atomic checkpoint — LED-pattern diagnostic for UART-only
+  boards where defmt output would corrupt the host protocol. Zero
+  footprint when the feature is off.
+
+### Changed
+
+- Radio task rewritten as an `hsmc` statechart (`Unconfigured` /
+  `Configured.{Idle, StartingRx, Receiving, ResumingRx,
+  Transmitting.{FromIdle, FromRx}}`). The main loop is now a single
+  `machine.run().await`; command reading, packet RX, and TX are
+  state-scoped `during:` activities. Post-TX RX re-arm is modeled as
+  state identity (`TransmittingFromRx` → `ResumingRx`) instead of a
+  `was_receiving` flag.
+- Display task rewritten as an `hsmc` statechart (`Off` /
+  `On.{Splash.{LearnMore, Info}, Dashboard.{Listening, Transmitting}}`).
+  The 5 s splash alternation and 1 s sparkline tick use `on(after …)` /
+  `on(every …)` transitions — no external timer task.
+- USB host task now carries a small `hsmc` statechart (`Disconnected` /
+  `Connected`) whose entry/exit actions handle display wake, radio
+  `StopRx`, and display reset — replacing the open-coded `was_connected`
+  edge detector.
+- Radio → Display channel switched from a `RadioStatus` watch to a typed
+  `RadioEvent` queue. The radio emits discrete `EnteredRx` / `EnteredTx`
+  / `Idle` / `PacketRx` / `PacketTx` / `ConfigChanged` events; downstream
+  consumers observe transitions directly rather than diffing snapshots.
+- Wire protocol types and COBS framing moved out of firmware into the
+  shared `donglora-protocol` crate (path dep on `../protocol`). Firmware
+  `src/protocol.rs` is now a re-export shim preserving every call site;
+  `src/host/framing.rs` keeps only the embassy-specific `route_command`.
+
+### Fixed
+
+- USB disconnect recovery: on a read error the DTR-edge-detect branch
+  now runs unconditionally (was early-continuing in some paths, starving
+  the display-reset / radio-stop handoff).
+
+## [0.4.0] - 2026-04-11
+
+### Added
+
+- ELECROW ThinkNode-M2 board support (ESP32-S3 + SX1262 + 1.3" SH1106 OLED
+  via CP2102 UART bridge, 1000 mAh Li-Po handheld)
+  - Pin map verified against Meshtastic's
+    `variants/esp32s3/ELECROW-ThinkNode-M2`
+  - DIO3 TCXO driven at 3.3 V (not 1.8 V like Heltec)
+  - Dedicated `LORA_POWER_EN` (GPIO48) sequenced HIGH before SPI init
+  - `VEXT_ENABLE` (GPIO46) is active HIGH — opposite polarity from Heltec
+  - Reuses the existing async SH1106 driver at I2C address 0x3C
+
+### Changed
+
+- `hal::esp32s3::{init_spi, init_i2c}` and `board::esp32s3::init_radio` are
+  now generic over GPIO type, so ESP32-S3 boards with different pin
+  assignments can share the helpers.
+- `board::esp32s3::init_radio` takes a `TcxoCtrlVoltage` parameter instead
+  of hardcoding `Ctrl1V8` — needed for ThinkNode-M2's 3.3 V TCXO.
+- SSD1306 display items in `board::esp32s3` are now cfg-gated to Heltec
+  boards (ThinkNode-M2 supplies its own SH1106 `create_display`).
+- `justfile` uses `cargo +esp` for Xtensa targets instead of `cargo +nightly`
+  with a `RUSTC=esp` override — the self-contained esp toolchain keeps its
+  cargo, rustc, and rust-src versions aligned. Public nightly's rust-src
+  had drifted ahead of the esp fork, breaking `-Zbuild-std`.
+- Migrated to embassy-executor 0.10 and embassy-rp 0.10
+- ESP crates (esp-hal, esp-rtos, esp-backtrace, esp-println) patched from
+  esp-rs/esp-hal main branch until esp-rtos publishes with 0.10 support
+- Adapted to embassy-executor 0.10 SpawnToken API (task functions now return
+  `Result<SpawnToken, SpawnError>`, `Spawner::spawn` no longer returns Result)
+- Adapted to esp-hal main branch API changes: `efuse::base_mac_address()`,
+  `esp_rtos::start` now requires `SoftwareInterrupt`, embassy-rp SPI
+  constructor now requires DMA interrupt bindings
+- `just check` now runs clippy with `-D warnings` instead of plain `cargo check`
+- Rust toolchain bumped to 1.94 in mise.toml
+
+### Fixed
+
+- `core::mem::forget(output)` pattern in ESP32-S3 board files is now
+  `let _vext = Output::new(...)` — current esp-hal makes `Output` non-Drop,
+  which made `forget` a no-op and tripped clippy's `forget_non_drop` lint.
+- UART boards (heltec_v3_uart) display stuck on splash screen after boot.
+  Host task sent `DisplayCommand::Reset` (which sets disconnected=true) instead
+  of `DisplayCommand::On`. UART has no DTR, so nothing ever cleared it.
+
+## [0.3.0] - 2026-04-10
+
+### Added
+
+- Waveshare RP2040-LoRa board support (RP2040 + SX1262, no OLED, LED on GPIO25)
+  - First RP2040 board — third MCU family after ESP32-S3 and nRF52840
+  - New `hal/rp2040.rs` module with MCU primitives (SPI, USB, flash unique ID)
+  - USB-C via FPC ribbon cable to adapter board
+  - PE4259 antenna switch on GPIO17, 850-930 MHz (HF)
+
+### Changed
+
+- `cortex-m-rt/set-vtor` moved from global dependency to per-board feature
+  (Cortex-M0+ has no VTOR register)
+- `build.rs` memory.x selection is now target-aware (thumbv6m vs thumbv7em)
+
+## [0.2.1] - 2026-04-07
+
+### Fixed
+
+- Display stuck on status screen after USB disconnect (stale radio status
+  updates re-rendered dashboard over splash because `disconnected` flag was
+  not set in the `Reset` handler)
+- Radio left running after host disconnect, now sends `StopRx` when DTR drops
+- System deadlock when host app closes serial port while radio is receiving
+  (unsolicited responses in radio task now use `try_send` to avoid blocking
+  on a full response channel)
+- LED orphaned if OLED display initialization fails (display task now falls
+  back to a LED-only event loop instead of returning early)
+
+## [0.2.0] - 2026-04-07
+
+### Added
+
+- Wio Tracker L1 board support (nRF52840 + SX1262, SH1106 OLED)
+- LED blink on packet activity: brief flash on RX and TX when display is on
+  - RX brightness scales with SNR (stronger signal = brighter)
+  - Works on all boards with a user LED (Heltec V3/V4, Wio Tracker)
+- Native USB CDC-ACM support for Heltec V3 (requires hardware mod: solder R29/R3)
+- `heltec_v3_uart` feature for stock (unmodified) V3 boards via CP2102 bridge
+- `RgbLed` trait and `SimpleLed` driver for GPIO-based LEDs
+- `LoRaBoard` trait with full associated types (`RadioParts`, `CommParts`,
+  `DisplayParts`, `DisplayDriver`, `LedDriver`) and `BoardParts<R, C, D, L>` struct
+
+### Changed
+
+- Major firmware architecture reorganization:
+  - `hal/` module for MCU-specific primitives (ESP32-S3, nRF52840)
+  - `driver/` module for hardware peripheral drivers (SH1106, SimpleLed)
+  - `host/` module for unified USB/UART communication with internal cfg dispatch
+  - `board/` contains only board definitions — no MCU helpers or drivers mixed in
+  - Board files are declarative wiring diagrams calling hal primitives
+- `run()` function has zero board-specific conditional compilation
+- Display init moved to board layer (`create_display()`) — display task has no cfg
+- Flattened `radio/` and `display/` directories (no single-file directories)
+- `build.rs` auto-discovers boards by content (implements `LoRaBoard`) and
+  helper modules by `use super::` imports — no exclusion lists
+- `check` and `clippy` commands now use `--release` profile
+- Deduplicated USB/UART protocol framing (shared `CobsDecoder` + `route_command`)
+- Removed `ErrorCode::CrcError` (SX1262 silently drops bad-CRC packets)
+
+### Fixed
+
+- Display stuck on splash screen for UART boards (disconnected flag started true)
+
+## [0.1.0] - 2026-03-15
+
+### Added
+
+- Transparent LoRa radio over USB CDC-ACM (VID `1209`, PID `5741`)
+- COBS-framed fixed-size LE binary protocol (9 commands, 7 responses)
+- Radio configuration: frequency, bandwidth, spreading factor, coding rate, TX power
+- Continuous RX mode with RSSI/SNR per packet
+- Single-shot TX with optional per-packet config override
+- SSD1306 OLED display support with status dashboard
+  - Radio state, frequency, modulation parameters
+  - Packet counters (RX/TX)
+  - RSSI sparkline (1-minute history, TX shown as dotted bars)
+  - Combined splash/waiting screen on disconnect
+- Auto-detect USB host connect/disconnect via DTR
+- Config validation against per-board hardware limits
+- `TX_POWER_MAX` sentinel (`-128`): auto-use the board's maximum TX power
+- Board support: Heltec V3, Heltec V4, RAK WisBlock 4631
+- Python host library (`donglora` on PyPI) with `pip install` and `donglora-mux` CLI
+- USB multiplexer for sharing one dongle with multiple applications
+- Two-way LoRa bridge over TCP (`examples/lora_bridge.py`)
+
+### Technical
+
+- Embassy async runtime (no threads, CPU sleeps when idle)
+- Zero-config: boots and waits for host commands
+- Protocol-agnostic: firmware has no opinion about what you transmit
+- Tasks never panic: all errors reported to host or logged
+- Board abstraction: one `.rs` file + one Cargo feature per board

Cargo.toml

@@ -3,34 +3,40 @@ members = ["."]
 
 [package]
 name = "donglora"
-version = "0.1.0"
+version = "1.4.0"
 edition = "2021"
 build = "build.rs"
 authors = ["Stephen Waits <steve@waits.net>"]
 license = "MIT"
 description = "Transparent LoRa radio over USB — plug in a board, talk LoRa from your host"
-repository = "https://github.com/swaits/donglora"
+repository = "https://github.com/donglora/firmware"
+homepage = "https://github.com/donglora/firmware"
 keywords = ["lora", "radio", "embedded", "usb", "firmware"]
 categories = ["embedded", "hardware-support", "no-std"]
 
-# UPGRADE BLOCKED: embassy-executor 0.10 and ucobs 0.3 need Rust >= 1.93
-# stable. The ESP Xtensa toolchain (espup) is a nightly fork that may not
-# support the required language features or pass MSRV gating. Revisit when
-# espup catches up. Check: rustup run esp rustc --version
+# 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"
+embedded-hal = "1.0"
 embedded-hal-async = "1.0"
 embassy-embedded-hal = "0.6"
-embassy-executor = "0.9"
+embassy-executor = "0.10"
 embassy-sync = "0.8"
 embassy-time = "0.5"
 embassy-usb = { version = "0.6", features = ["defmt"] }
 embassy-usb-driver = "0.2"
 ucobs = { version = "0.3", features = ["legacy-msrv"] }
 heapless = "0.9"
-lora-phy = "3.0"
+donglora-protocol = "1"
+hsmc = { version = "0.2", default-features = false, features = ["embassy"] }
+# Pulled from swaits/lora-rs fork until lora-rs/lora-rs#428 (pre-command
+# BUSY check) is merged + released on crates.io. Switch back to a normal
+# crates.io version then.
+lora-phy = { git = "https://github.com/swaits/lora-rs.git", branch = "fix/sx126x-busy-race", features = ["defmt-03"] }
+portable-atomic = { version = "1", optional = true, default-features = false, features = ["critical-section"] }
 static_cell = "2.1"
 
 # Display rendering
@@ -42,27 +48,29 @@ ssd1306 = { version = "0.10", features = ["async"] }
 embedded-io-async = "0.7"
 embassy-futures = "0.1"
 
-# ESP32-S3 (Heltec V3) — requires esp toolchain (espup)
+# 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.18", optional = true, features = [
-  "esp32s3",
   "panic-handler",
   "defmt",
 ] }
 esp-hal = { version = "1.0", optional = true, features = [
-  "esp32s3",
   "unstable",
 ] }
 esp-println = { version = "0.16", optional = true, features = [
-  "esp32s3",
   "defmt-espflash",
 ] }
 esp-rtos = { version = "0.2", optional = true, features = [
-  "esp32s3",
   "embassy",
 ] }
 
 # 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 }
 embassy-nrf = { version = "0.10", optional = true, features = [
   "nrf52840",
   "gpiote",
@@ -71,30 +79,141 @@ embassy-nrf = { version = "0.10", optional = true, features = [
 ] }
 panic-probe = { version = "1.0", optional = true, features = ["print-defmt"] }
 
+# RP2040 (Waveshare RP2040-LoRa)
+embassy-rp = { version = "0.10", optional = true, features = [
+  "rp2040",
+  "time-driver",
+  "defmt",
+] }
+
 [build-dependencies]
 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.
+embassy = []
+tokio = []
+# 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
+# host protocol on the same UART. The LED flashes N times then pauses —
+# a human watches the pattern and reports N to determine where execution
+# reached / stopped.
+debug-checkpoint = []
 heltec_v3 = [
+  "embassy",
   "dep:esp-backtrace",
   "dep:esp-hal",
   "dep:esp-println",
   "dep:esp-rtos",
+  "esp-backtrace/esp32s3",
+  "esp-hal/esp32s3",
+  "esp-println/esp32s3",
+  "esp-rtos/esp32s3",
+]
+heltec_v3_uart = [
+  "embassy",
+  "dep:esp-backtrace",
+  "dep:esp-hal",
+  "dep:esp-println",
+  "dep:esp-rtos",
+  "esp-backtrace/esp32s3",
+  "esp-hal/esp32s3",
+  "esp-println/esp32s3",
+  "esp-rtos/esp32s3",
 ]
 heltec_v4 = [
+  "embassy",
   "dep:esp-backtrace",
   "dep:esp-hal",
   "dep:esp-println",
   "dep:esp-rtos",
+  "esp-backtrace/esp32s3",
+  "esp-hal/esp32s3",
+  "esp-println/esp32s3",
+  "esp-rtos/esp32s3",
+]
+elecrow_thinknode_m2 = [
+  "embassy",
+  "dep:esp-backtrace",
+  "dep:esp-hal",
+  "dep:esp-println",
+  "dep:esp-rtos",
+  "esp-backtrace/esp32s3",
+  "esp-hal/esp32s3",
+  "esp-println/esp32s3",
+  "esp-rtos/esp32s3",
+]
+lilygo_tbeam_supreme = [
+  "embassy",
+  "dep:esp-backtrace",
+  "dep:esp-hal",
+  "dep:esp-println",
+  "dep:esp-rtos",
+  "esp-backtrace/esp32s3",
+  "esp-hal/esp32s3",
+  "esp-println/esp32s3",
+  "esp-rtos/esp32s3",
+]
+lilygo_tbeam = [
+  "embassy",
+  "dep:esp-backtrace",
+  "dep:esp-hal",
+  "dep:esp-println",
+  "dep:esp-rtos",
+  "esp-backtrace/esp32",
+  "esp-hal/esp32",
+  "esp-println/esp32",
+  "esp-rtos/esp32",
 ]
 rak_wisblock_4631 = [
+  "embassy",
+  "dep:cortex-m",
   "dep:cortex-m-rt",
+  "cortex-m-rt/set-vtor",
+  "dep:defmt-rtt",
   "dep:embassy-nrf",
   "dep:panic-probe",
-  "embassy-executor/arch-cortex-m",
+  "embassy-executor/platform-cortex-m",
   "embassy-executor/executor-thread",
 ]
+wio_tracker_l1 = [
+  "embassy",
+  "dep:cortex-m",
+  "dep:cortex-m-rt",
+  "cortex-m-rt/set-vtor",
+  "dep:defmt-rtt",
+  "dep:embassy-nrf",
+  "dep:panic-probe",
+  "embassy-executor/platform-cortex-m",
+  "embassy-executor/executor-thread",
+]
+waveshare_rp2040_lora = [
+  "embassy",
+  "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.clippy]
 undocumented_unsafe_blocks = "deny"
@@ -102,4 +221,6 @@ undocumented_unsafe_blocks = "deny"
 [profile.release]
 codegen-units = 1
 lto = "fat"
-opt-level = 3  # "s"/"z" break Xtensa (l32r literal range exceeded)
+opt-level = 3     # "s"/"z" break Xtensa (l32r literal range exceeded)
+panic = "abort"
+strip = true

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen Waits <steve@waits.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -18,11 +18,43 @@ All commands are run from the `firmware/` directory.
 
 ## Supported Boards
 
-| Board | MCU | Radio | Target |
-|-------|-----|-------|--------|
-| Heltec V3 | ESP32-S3 | SX1262 | xtensa-esp32s3-none-elf |
-| Heltec V4 | ESP32-S3 | SX1262 | xtensa-esp32s3-none-elf |
-| RAK WisBlock 4631 | nRF52840 | SX1262 | thumbv7em-none-eabihf |
+| Board | Feature | MCU | Radio | USB | Target |
+|-------|---------|-----|-------|-----|--------|
+| 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 |
+
+### Heltec V3 USB Note
+
+The default `heltec_v3` build uses **native USB CDC-ACM**, which requires a
+hardware modification to your board. Stock Heltec V3 boards route USB through a
+CP2102 bridge chip to UART — the ESP32-S3's native USB pins (GPIO19/GPIO20) are
+routed to header pins but not connected to the USB connector.
+
+**To enable native USB on a Heltec V3:**
+
+1. Solder 0-ohm (or 22-ohm) resistors at pads **R29** (D+) and **R3** (D-)
+2. Disconnect the CP2102 from the USB connector's D+/D- lines (cut traces or
+   remove the CP2102 bridge resistors)
+
+After this mod, the board appears as `/dev/ttyACM0` with the DongLoRa VID:PID
+(1209:5741), just like the V4 and nRF boards.
+
+**If you have a stock (unmodified) V3**, use `heltec_v3_uart` instead:
+
+```sh
+just build heltec_v3_uart
+just flash heltec_v3_uart
+```
+
+This builds firmware that communicates via the CP2102 bridge (appears as
+`/dev/ttyUSB0`).
 
 ## Adding a Board
 

TODO.md

@@ -0,0 +1,165 @@
+# Firmware TODO List
+
+## `lora-phy` fix: drop fork pin once PR #428 merges + releases
+
+Upstream PR: [lora-rs/lora-rs#428 — *phy: add pre-command BUSY checks
+per Semtech datasheets*](https://github.com/lora-rs/lora-rs/pull/428)
+(open).
+Fork branch we ship from:
+[`swaits/lora-rs @ fix/sx126x-busy-race`](https://github.com/swaits/lora-rs/tree/fix/sx126x-busy-race).
+
+Firmware consumes the fix via a direct `git` dependency in
+`Cargo.toml`:
+
+```toml
+lora-phy = { git = "https://github.com/swaits/lora-rs.git", branch = "fix/sx126x-busy-race", features = ["defmt-03"] }
+```
+
+When PR #428 merges and a `lora-phy` release ships on crates.io that
+contains it, switch this line back to a normal `lora-phy = "X.Y"`
+crates.io version and drop the explanatory comment block above it.
+
+Hardware-verified on Wio Tracker L1: 20/20 clean-boot TX after the fix
+(vs ~50% before). The fix adds a pre-command BUSY check before each
+`SpiInterface` read/write op, keeping the existing post-command wait
+in place — belt-and-suspenders bracketing that closes the
+BUSY-assertion latency window (T_SW ≤ 600 ns) a single level-poll can
+miss.
+
+---
+
+## Drop `[patch.crates-io]` + upgrade esp-hal / esp-rtos + add `esp_app_desc!()` + bump espflash to v4
+
+Single coordinated change that clears our last remaining dep-graph debt
+on the ESP boards. All four pieces are coupled, so they land together.
+
+### Why
+
+Today `Cargo.toml` overrides `esp-hal`, `esp-rtos`, `esp-backtrace`, and
+`esp-println` with a git pin to `esp-rs/esp-hal#main`. The note in that
+block explains the historical reason:
+
+> 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.
+
+**That condition is now met.** `esp-rtos 0.3.0` is published on crates.io
+and depends on `embassy-executor ^0.10` and `esp-hal ~1.1.0-rc.0` — exactly
+what our patches were pulling unofficially. Keeping the patches is no
+longer free: it blocks `espflash` v4, blocks `esp-bootloader-esp-idf`, and
+ties reproducible builds to whatever commit happens to be on
+`esp-rs/esp-hal#main`.
+
+The immediate trigger is `espflash` v4's required
+`esp_bootloader_esp_idf::esp_app_desc!()` check. `save-image` refuses any
+ESP binary that lacks the IDF app descriptor. The crate that provides the
+macro (`esp-bootloader-esp-idf`) uses the same `esp-rom-sys` native
+library as `esp-hal` — two copies of the same `links = "esp_rom_sys"` is
+a hard cargo error, so `esp-bootloader-esp-idf` must come from the _same
+source_ as `esp-hal`. Easiest way to guarantee that: both from crates.io,
+no patches.
+
+### What changes
+
+1. **`Cargo.toml`** — delete the entire `[patch.crates-io]` block and the
+   preceding `REVISIT:` comment. Bump the four esp-rs deps to published
+   versions:
+   - `esp-hal = "1.0"` → `"1.1.0-rc.0"` (pre-release selector — see Gotchas)
+   - `esp-rtos = "0.2"` → `"0.3"`
+   - `esp-backtrace = "0.18"` → whatever matches esp-rtos 0.3 (check its deps)
+   - `esp-println = "0.16"` → same
+     Add a new optional dep + feature wiring for
+     `esp-bootloader-esp-idf = "0.5"` with `defmt` feature, plus per-board
+     chip feature (`esp-bootloader-esp-idf/esp32s3` for the S3 boards,
+     `esp-bootloader-esp-idf/esp32` for LilyGo T-Beam classic).
+
+2. **`src/main.rs`** — inside the ESP-family branch of the existing
+   `cfg_if!` block (around line 51), invoke the macro at module scope:
+
+   ```rust
+   esp_bootloader_esp_idf::esp_app_desc!();
+   ```
+
+   Zero runtime cost. Emits ~256 bytes in `.rodata_desc` with app
+   metadata (name, version, build date) that the ESP-IDF 2nd-stage
+   bootloader + `espflash save-image` look for.
+
+3. **`mise.toml`** — `"cargo:espflash" = "3"` → `"4"`. Drop the deferral
+   comment on that line.
+
+4. **Possible API drift fixes** — esp-hal's pre-release versions
+   occasionally rename or move items. Most likely touch points:
+   - `src/board/esp32.rs`, `src/board/esp32s3.rs`
+   - Any board file in `src/board/heltec_*.rs`, `lilygo_*.rs`,
+     `elecrow_*.rs` that calls into esp-hal / esp-rtos init
+     Run `just check-all` after steps 1–3 and patch up whatever surfaces.
+     Don't guess — read the actual compiler errors.
+
+### How (step by step)
+
+1. `jj new -m "chore(esp): drop esp-hal patches, bump to published versions, add esp_app_desc!()"`
+2. Edit `Cargo.toml` — delete `[patch.crates-io]` + `REVISIT:` comment;
+   bump the four versions; add `esp-bootloader-esp-idf` dep + feature
+   wiring for each ESP board feature block.
+3. Edit `src/main.rs` — add `esp_bootloader_esp_idf::esp_app_desc!();`
+   to the ESP branch of the top-level `cfg_if!`.
+4. Edit `mise.toml` — espflash `"3"` → `"4"`.
+5. `mise install` to pull espflash 4.x.
+6. `cargo update` to let the resolver pick a consistent tree with the
+   new requirements.
+7. `just check-all` — expect some compilation errors from API drift on
+   ESP boards. Fix them one at a time; consult the official examples
+   in `esp-rs/esp-hal` if in doubt.
+8. `just build heltec_v3` (or any ESP board you have) — verify
+   `espflash save-image` now succeeds end-to-end producing a valid
+   `.bin`.
+9. Flash to real hardware if available. **The RAK4631 and Wio Tracker
+   L1 (nRF52) boards should be untouched.**
+
+### Verification
+
+- `just check-all` clean on all 9 boards.
+- `just test` (host-side protocol tests) still green.
+- For each ESP board that has been physically validated before
+  (Heltec V3, LilyGo T-Beam units): flash + confirm radio TX works
+  end-to-end via ai-bot or a known peer.
+- RAK4631 + Wio Tracker L1 unchanged; re-check via `just check` on
+  both, but no re-flash needed (they don't go through the ESP code
+  path).
+
+### Gotchas
+
+- **Pre-release version selector**: `esp-hal = "1.1.0-rc.0"` by itself
+  does NOT match pre-release versions in cargo's default semver rules.
+  Use an exact pre-release like `"1.1.0-rc.0"`, `"~1.1.0-rc.0"` (only
+  `1.1.0-rc.0`, `1.1.0-rc.1`, … with any patch), or `">=1.1.0-rc.0"`.
+  `"1.1"` will NOT resolve to a pre-release.
+- **Two copies of `esp-rom-sys`**: the root cause of the first failed
+  attempt at this task. If cargo errors with _"Only one package in the
+  dependency graph may specify the same links value"_ for
+  `esp_rom_sys`, it means `esp-hal` and `esp-bootloader-esp-idf` are
+  being pulled from different sources (one crates.io, one git). Either
+  both from crates.io (this task's plan) or both from the same git
+  commit.
+- **`esp-bootloader-esp-idf` chip features**: the crate needs exactly
+  one of `esp32 / esp32s3 / esp32c3 / esp32c6 / …` to be enabled.
+  Without it, the build panics at its `build.rs`: _"Expected exactly
+  one of the following features to be enabled: esp32, esp32c2, ..."_.
+  Wire per-board the same way we wire `esp-hal/esp32s3` etc.
+- **Probe-less repro**: `mise install` after bumping espflash to "4"
+  only installs mise's copy. If the user's global
+  `~/.cargo/bin/espflash` is stale/different, it still wins on PATH.
+  The justfile `set shell := ["mise", "exec", "--", "sh", "-c"]`
+  prepends mise's paths but does NOT reorder `~/.cargo/bin` ahead of
+  them. Either `cargo uninstall espflash` globally, or change the
+  justfile recipes to call `$(mise which espflash)` explicitly.
+
+### Why not now
+
+Tried it alongside the RAK4631 bring-up in April 2026 and bounced off
+the `esp-rom-sys` two-copies problem. Backed out the attempt and left
+espflash pinned at v3 + the patches in place so the bring-up commit
+stayed atomic and shippable. This task is what's needed to unblock v4
+properly, but it deserves its own focused session — not as
+"while-I'm-here" scope on a board bring-up.

build.rs

@@ -1,32 +1,48 @@
 use minijinja::{context, Environment};
 use owo_colors::OwoColorize;
+use std::collections::HashMap;
 use std::fs;
 
 fn main() {
-    // Protocol tests run on the host without a board feature. Cargo doesn't
-    // expose `cfg(test)` to build scripts, so we rely on an env var set by
-    // the justfile `test` recipe. See: `just test`
+    // Protocol tests run on the host without a board feature.
     if std::env::var_os("DONGLORA_HOST_TEST").is_some() {
         return;
     }
 
     let board_dir = "src/board";
-    let boards: Vec<String> = fs::read_dir(board_dir)
-        .expect("failed to read src/board directory")
-        .filter_map(|e| {
-            let p = e.ok()?.path();
-            let stem = p.file_stem()?.to_str()?;
-            // Exclude non-board files: mod.rs, traits.rs, and platform helpers (esp32s3.rs).
-            if p.is_file()
-                && p.extension()? == "rs"
-                && !matches!(stem, "mod" | "traits" | "esp32s3")
-            {
-                return Some(p.file_stem()?.to_str()?.to_string());
-            }
-            None
-        })
-        .collect();
 
+    // ── Discover boards vs helpers by content ───────────────────────
+    //
+    // A .rs file in src/board/ that implements LoRaBoard is a board.
+    // Everything else (traits.rs, esp32s3.rs, etc.) is a helper module.
+    // No exclusion lists — detection is based on what the file contains.
+    let mut boards: Vec<String> = Vec::new();
+
+    for entry in fs::read_dir(board_dir).expect("failed to read src/board directory") {
+        let p = match entry {
+            Ok(e) => e.path(),
+            Err(_) => continue,
+        };
+        if !p.is_file() || p.extension().and_then(|e| e.to_str()) != Some("rs") {
+            continue;
+        }
+        let stem = match p.file_stem().and_then(|s| s.to_str()) {
+            Some("mod") => continue, // Skip generated file
+            Some(s) => s.to_string(),
+            None => continue,
+        };
+        let content = match fs::read_to_string(&p) {
+            Ok(c) => c,
+            Err(_) => continue,
+        };
+        if content.contains("LoRaBoard for Board") {
+            boards.push(stem);
+        }
+    }
+
+    boards.sort(); // Deterministic ordering
+
+    // ── Validate exactly one board feature is enabled ───────────────
     let enabled: Vec<_> = std::env::vars()
         .filter(|(k, _)| k.starts_with("CARGO_FEATURE_"))
         .map(|(k, _)| k.replace("CARGO_FEATURE_", "").to_lowercase())
@@ -49,18 +65,62 @@ fn main() {
         ),
     }
 
+    // ── Auto-discover helper modules used by board files ────────────
+    //
+    // Scan each board file for `use super::<name>` to find which helper
+    // modules they depend on. Generate cfg gates so helpers compile only
+    // when a dependent board is selected.
+    let mut helper_boards: HashMap<String, Vec<String>> = HashMap::new();
+
+    for board in &boards {
+        let path = format!("{}/{}.rs", board_dir, board);
+        if let Ok(content) = fs::read_to_string(&path) {
+            for line in content.lines() {
+                let trimmed = line.trim();
+                if let Some(rest) = trimmed.strip_prefix("use super::") {
+                    let helper = rest
+                        .split(|c: char| !c.is_alphanumeric() && c != '_')
+                        .next()
+                        .unwrap_or("");
+                    if !helper.is_empty() && helper != "traits" {
+                        helper_boards
+                            .entry(helper.to_string())
+                            .or_default()
+                            .push(board.clone());
+                    }
+                }
+            }
+        }
+    }
+
+    // ── Render board module template ────────────────────────────────
     let mut env = Environment::new();
-    let template =
-        fs::read_to_string("src/board/mod.rs.j2").expect("missing src/board/mod.rs.j2");
+    let template = fs::read_to_string("src/board/mod.rs.j2").expect("missing src/board/mod.rs.j2");
     env.add_template("mod", &template)
         .expect("failed to parse board template");
     let rendered = env
         .get_template("mod")
         .expect("template not found")
-        .render(context!(boards => boards))
+        .render(context!(boards => boards, helpers => helper_boards))
         .expect("failed to render board module");
     fs::write("src/board/mod.rs", rendered).expect("failed to write src/board/mod.rs");
 
     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.
+    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,
+    };
+    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");
+        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");
 }

justfile

@@ -1,32 +1,29 @@
-set shell := ["bash", "-c"]
-
-# Board definitions: feature target chip
-# Xtensa targets use nightly cargo + esp rustc + -Zbuild-std=core.
-# Tool versions are pinned in mise.toml; run `just setup` to install everything.
-heltec_v3 := "heltec_v3 xtensa-esp32s3-none-elf esp32s3"
-heltec_v4 := "heltec_v4 xtensa-esp32s3-none-elf esp32s3"
-rak_wisblock_4631  := "rak_wisblock_4631 thumbv7em-none-eabihf nRF52840_xxAA"
+# 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_v4 rak_wisblock_4631"
+# 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_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 (not a rustup component — installed out-of-band by espup)
     @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; }; \
     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 target
-    @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:
@@ -52,37 +49,45 @@ check-all:
         fi; \
     done
 
-# Check a single board compiles
+# Check a single board compiles (clippy with warnings as errors)
 check board:
-    @just _cargo {{board}} check
+    @just _cargo {{board}} "clippy --release" "-- -D warnings"
 
-# Run clippy on a single board
-clippy board:
-    @just _cargo {{board}} "clippy" "-- -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, probe-rs 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"); \
+            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}}-release.elf"; \
+                espflash flash -p "$port" "{{builds_dir}}/donglora-{{board}}-v{{version}}.elf"; \
             else \
                 echo "No port found, falling back to espflash auto-detection..." >&2; \
-                espflash flash "{{builds_dir}}/donglora-{{board}}-release.elf"; \
+                espflash flash "{{builds_dir}}/donglora-{{board}}-v{{version}}.elf"; \
             fi ;; \
-        *) probe-rs run --chip $chip "{{builds_dir}}/donglora-{{board}}-release.elf" ;; \
+        *) just _flash_uf2 {{board}} ;; \
     esac
 
+# Flash ARM board via debug probe (requires J-Link or similar).
+# `extra_features` is passed through to the build.
+flash-probe board extra_features="":
+    @just _ensure_tools
+    @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"
+
 # Show binary size for a release build
 size board:
     @just _cargo {{board}} "size --release"
@@ -93,10 +98,7 @@ test:
 
 # Check for outdated dependencies
 outdated:
-    @# embassy-executor 0.10 renamed arch-* → platform-* features.
-    @# esp-rtos 0.2 still pins embassy-executor ^0.9, blocking the upgrade.
-    @# cargo-outdated crashes trying to resolve 0.10 with the old feature name.
-    cargo outdated --exclude embassy-executor
+    cargo outdated
 
 # ── Private helpers ───────────────────────────────────────────────────
 
@@ -105,40 +107,40 @@ outdated:
 _ensure_tools:
     @mise trust --yes . 2>/dev/null; mise install --quiet
 
-# Run a cargo command for a board.
-# Xtensa: nightly cargo + esp rustc (via RUSTC override) + -Zbuild-std=core
+# 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}})"; \
-    env=""; extra=""; \
+    @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"; \
-        env="RUSTC=$(rustup which rustc --toolchain esp)"; extra="+nightly"; buildstd="-Zbuild-std=core,alloc";; \
+        extra="+esp"; buildstd="-Zbuild-std=core,alloc";; \
     esac; \
-    eval $env cargo $extra {{cmd}} --target "$target" --features "$feat" $buildstd {{extra_args}}
+    cargo $extra {{cmd}} --target "$target" --features "$feat" $buildstd {{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)
+# 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
+# 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; }; \
-    fi; \
-    if ! rustup component list --toolchain nightly --installed 2>/dev/null | grep -q "^rust-src"; then \
-        echo "Installing nightly rust-src (needed for -Zbuild-std)..." >&2; \
-        rustup component add rust-src --toolchain nightly || { echo "error: failed to install rust-src" >&2; exit 1; }; \
     fi
 
 # Find a serial port matching any of the given VID:PID pairs (checked in order)
@@ -160,14 +162,60 @@ _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}}-{{profile}}"; \
-    if [ -f "$src" ]; then cp "$src" "$dst.elf"; echo "→ $dst.elf"; fi
+    dst="{{builds_dir}}/donglora-{{board}}-v{{version}}"; \
+    if [ -f "$src" ]; then \
+        cp "$src" "$dst.elf"; echo "→ $dst.elf"; \
+        case "$target" in \
+            xtensa-*) \
+                espflash save-image --chip "$chip" --merge --skip-padding "$src" "$dst.bin"; \
+                echo "→ $dst.bin"; \
+                ;; \
+            thumbv6m-*) \
+                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-*) \
+                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"; \
+                ;; \
+        esac; \
+    fi
 
+# Copy UF2 to a mounted UF2 bootloader drive
+[private]
+_flash_uf2 board:
+    @uf2="{{builds_dir}}/donglora-{{board}}-v{{version}}.uf2"; \
+    if [ ! -f "$uf2" ]; then \
+        echo "error: $uf2 not found — run 'just build {{board}}' first" >&2; exit 1; \
+    fi; \
+    mnt="$(find /run/media -maxdepth 3 -name INFO_UF2.TXT -printf '%h\n' -quit 2>/dev/null)"; \
+    if [ -z "$mnt" ]; then \
+        echo "error: no UF2 drive found — double-tap reset to enter bootloader" >&2; exit 1; \
+    fi; \
+    echo "Copying to $mnt ..."; \
+    cp "$uf2" "$mnt/"; \
+    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_v4" ]; then echo "{{heltec_v4}}"; \
-     elif [ "{{name}}" == "rak_wisblock_4631" ]; then echo "{{rak_wisblock_4631}}"; \
-     else echo "Unknown board: {{name}}" >&2; exit 1; fi
+    @case "{{name}}" in \
+        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

@@ -0,0 +1,16 @@
+/* nRF52840 memory layout — Adafruit UF2 bootloader
+ *
+ *   0x00000 – 0x01000   MBR (Master Boot Record)
+ *   0x01000 – 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.
+ */
+
+MEMORY
+{
+  FLASH : ORIGIN = 0x00001000, LENGTH = 0xE9000
+  RAM   : ORIGIN = 0x20000008, LENGTH = 255K
+}

ld/rp2040-memory.x

@@ -0,0 +1,24 @@
+/* RP2040 memory layout — UF2 bootloader (ROM boot2)
+ *
+ *   0x10000000 – 0x10000100   boot2 (second-stage bootloader, 256 bytes)
+ *   0x10000100 – 0x10200000   Application  <- we live here
+ *
+ * Flash: 2MB (W25Q16JV on Waveshare RP2040-LoRa)
+ * RAM: 264KB SRAM (two 256KB banks + 2x 4KB scratch)
+ */
+
+MEMORY
+{
+  BOOT2 : ORIGIN = 0x10000000, LENGTH = 0x100
+  FLASH : ORIGIN = 0x10000100, LENGTH = 2048K - 0x100
+  RAM   : ORIGIN = 0x20000000, LENGTH = 264K
+}
+
+EXTERN(BOOT2_FIRMWARE)
+
+SECTIONS {
+    .boot2 ORIGIN(BOOT2) :
+    {
+        KEEP(*(.boot2));
+    } > BOOT2
+} INSERT BEFORE .text;

mise.toml

@@ -1,8 +1,24 @@
 [tools]
-rust = "1.93"
 just = "latest"
 
-"cargo:cargo-binutils" = "latest"   # `cargo size`, `cargo objdump`, etc.
-"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" = "latest"            # bootstraps the ESP Xtensa toolchain
+"cargo:espflash" = "3"              # flash + save-image for ESP targets (4.x requires esp_app_desc!() in app — revisit alongside esp-hal 1.1+ / drop-the-patches cleanup)
+"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 installed out-of-band by `espup` (see `just setup`). 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"

src/board/PORTING.md

@@ -5,14 +5,15 @@
 ### 1. Create the board file
 
 Create `src/board/your_board.rs`. Use an existing board as a template:
-- ESP32-S3 boards: copy `heltec_v4.rs` (uses shared helpers from `esp32s3.rs`)
-- nRF52840 boards: copy `rak_wisblock_4631.rs`
+- ESP32-S3 boards: copy `heltec_v4.rs` (uses shared helpers from `board/esp32s3.rs` and `hal/esp32s3.rs`)
+- nRF52840 boards: copy `rak_wisblock_4631.rs` (uses shared helpers from `hal/nrf52840.rs`)
+- RP2040 boards: copy `waveshare_rp2040_lora.rs` (uses shared helpers from `hal/rp2040.rs`)
+- New MCU family: create a new `hal/<mcu>.rs` with MCU primitives first
 
-ESP32-S3 boards share common type aliases, peripheral bundles, and init helpers
-via `src/board/esp32s3.rs`. Your board file only needs the trait impl and
-board-specific init (Vext GPIO, display reset). If you add a new ESP32-S3 board,
-add its feature to the `#[cfg(any(...))]` gate on `mod esp32s3` in
-`src/board/mod.rs.j2`.
+`build.rs` auto-discovers your board file — any `.rs` file in `src/board/` that
+implements `LoRaBoard for Board` is automatically detected as a board. Helper
+modules (like `esp32s3.rs`) are auto-discovered via `use super::<helper>` imports
+in board files. No template editing or exclusion lists needed.
 
 ### 2. Define concrete types
 
@@ -21,7 +22,9 @@ Your board must export these type aliases:
 ```rust
 pub type RadioDriver = ...; // Must work with lora_phy::LoRa<RadioDriver, Delay>
 pub type UsbDriver = ...;   // Must implement embassy_usb_driver::Driver<'static>
+                             // (or UartDriver for UART boards)
 pub type DisplayI2c = ...;  // Must implement embedded_hal_async::i2c::I2c
+pub type DisplayDriver = ...; // Must implement DrawTarget<Color = BinaryColor>
 ```
 
 ### 3. Define peripheral bundles
@@ -32,39 +35,43 @@ pub struct RadioParts {
     pub delay: embassy_time::Delay,
 }
 
-pub struct UsbParts {
+pub struct UsbParts {  // or UartParts for UART boards
     pub driver: UsbDriver,
 }
 
 pub struct DisplayParts {
     pub i2c: DisplayI2c,
-    pub mac: [u8; 6],
 }
 ```
 
 ### 4. Implement the LoRaBoard trait
 
 ```rust
-use super::traits::LoRaBoard;
+use super::traits::{BoardParts, LoRaBoard};
 
 impl LoRaBoard for Board {
     const NAME: &'static str = "Your Board Name";
     const TX_POWER_RANGE: (i8, i8) = (-9, 22); // check your radio + PA
+
+    type RadioParts = RadioParts;
+    type CommParts = UsbParts;       // or UartParts
+    type DisplayParts = DisplayParts;
+    type DisplayDriver = DisplayDriver;
+
     fn init() -> Self { ... }
     fn mac_address() -> [u8; 6] { ... } // read from efuse, FICR, etc.
+    fn into_parts(self) -> BoardParts<RadioParts, UsbParts, DisplayParts> {
+        // Initialize buses via hal::, construct drivers, return BoardParts
+        BoardParts { radio, host, display: Some(display_parts), mac: Self::mac_address() }
+    }
 }
 ```
 
-The compiler will refuse to build if any of these are missing.
-
-### 5. Implement `Board::into_parts()`
+### 5. Add display init
 
 ```rust
-impl Board {
-    pub fn into_parts(self) -> (RadioParts, UsbParts, Option<DisplayParts>) {
-        // Initialize SPI, DMA, radio, USB, I2C
-        // Return peripheral bundles
-    }
+pub async fn create_display(i2c: DisplayI2c) -> Option<DisplayDriver> {
+    // Construct and initialize your display driver (SSD1306, SH1106, etc.)
 }
 ```
 
@@ -79,7 +86,7 @@ your_board = ["dep:your-hal", ...]
 
 ### 7. Add to justfile
 
-Add your board's feature/target/chip to the `boards` list at the top of `justfile`.
+Add your board's feature/target/chip to the board definitions at the top of `justfile`.
 
 ### 8. Build and test
 
@@ -88,5 +95,3 @@ just check your_board    # Must compile
 just clippy your_board   # Must be clean
 just build your_board    # Produces firmware
 ```
-
-`build.rs` auto-discovers your `.rs` file — no template editing needed.

src/board/elecrow_thinknode_m2.rs

@@ -0,0 +1,141 @@
+//! ELECROW ThinkNode-M2 — ESP32-S3 Meshtastic handset with SH1106 OLED.
+//!
+//! Tamagotchi-form-factor handheld: ESP32-S3-WROOM-1-N4 + SX1262 + 1.3" SH1106
+//! 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):
+//!   LoRa SPI: SCK=12, MOSI=11, MISO=13, CS=10
+//!   LoRa ctl: RESET=21, BUSY=14, DIO1=3
+//!   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 CH340K bridge (USB 1a86:7522)
+//!   LED:      GPIO6 (active HIGH indicator)
+//!
+//! Notable differences from the Heltec ESP32-S3 boards:
+//!   * Display is SH1106 (not SSD1306) — uses the existing sh1106 driver.
+//!   * VEXT_ENABLE polarity is reversed (active HIGH here, active LOW on Heltec).
+//!   * Dedicated LoRa power enable on GPIO48 — must be sequenced before SPI init.
+//!   * TCXO is driven at 3.3 V via DIO3 (Heltec uses 1.8 V).
+
+use esp_hal::gpio::{Level, Output, OutputConfig};
+
+use super::esp32s3;
+use super::traits::{BoardParts, LoRaBoard};
+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 UartDriver = esp_hal::uart::Uart<'static, esp_hal::Async>;
+pub type LedDriver = SimpleLed<Output<'static>>;
+
+// ── Peripheral bundles ──────────────────────────────────────────────
+
+pub struct UartParts {
+    pub driver: UartDriver,
+}
+
+pub struct DisplayParts {
+    pub i2c: DisplayI2c,
+}
+
+// ── Display init ────────────────────────────────────────────────────
+
+pub async fn create_display(i2c: DisplayI2c) -> Option<DisplayDriver> {
+    let mut display = Sh1106::new(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 = "ELECROW ThinkNode-M2";
+    const TX_POWER_RANGE: (i8, i8) = (-9, 22);
+
+    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 into_parts(self) -> BoardParts<RadioParts, UartParts, DisplayParts, LedDriver> {
+        let p = self.p;
+
+        mcu::start_timer(p.TIMG0, p.SW_INTERRUPT);
+
+        // VEXT_ENABLE: GPIO46, active HIGH — powers OLED rail (opposite of Heltec).
+        // Output has no Drop impl, so the pin stays HIGH for program lifetime.
+        let _vext = Output::new(p.GPIO46, Level::High, OutputConfig::default());
+        esp_hal::delay::Delay::new().delay_millis(10);
+
+        // LORA_POWER_EN: GPIO48, active HIGH — must be HIGH before any SPI traffic.
+        let _lora_pwr = Output::new(p.GPIO48, Level::High, OutputConfig::default());
+        esp_hal::delay::Delay::new().delay_millis(10);
+
+        // 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=21, DIO1=3, BUSY=14, TCXO driven at 3.3 V via DIO3.
+        let radio = esp32s3::init_radio(
+            spi_bus,
+            p.GPIO10,
+            p.GPIO21,
+            p.GPIO3,
+            p.GPIO14,
+            lora_phy::sx126x::TcxoCtrlVoltage::Ctrl3V3,
+        );
+
+        // UART0 via CP2102 bridge: TX=43, RX=44
+        use esp_hal::uart::{Config as UartConfig, Uart};
+        let host = UartParts {
+            driver: Uart::new(p.UART0, UartConfig::default())
+                .expect("UART init")
+                .with_tx(p.GPIO43)
+                .with_rx(p.GPIO44)
+                .into_async(),
+        };
+
+        // I2C0 for SH1106 OLED: SDA=16, SCL=15
+        let i2c = mcu::init_i2c(p.I2C0, p.GPIO16, p.GPIO15);
+        let display = Some(DisplayParts { i2c });
+
+        // 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/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(i2c: DisplayI2c) -> 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 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

@@ -1,100 +1,102 @@
-//! Shared types and initialization helpers for ESP32-S3 boards.
+//! Shared types and peripheral wiring for ESP32-S3 boards.
 //!
-//! All ESP32-S3 boards in this project share the same SPI/DMA, USB OTG,
-//! and I2C peripheral wiring. This module provides the common type aliases,
-//! peripheral bundle structs, and init functions. Each board file re-exports
-//! these types and calls the helpers from its own `Board::into_parts()`.
+//! Delegates MCU-level init to `hal::esp32s3` and defines peripheral-level
+//! types (RadioDriver, display) used by ESP32-S3 board files.
+//! Each board defines its own comm types (UsbParts/UartParts) directly.
 
 use embassy_embedded_hal::shared_bus::asynch::spi::SpiDevice;
 use embassy_sync::blocking_mutex::raw::NoopRawMutex;
 use embassy_time::Delay;
-use esp_hal::dma::{DmaRxBuf, DmaTxBuf};
-use esp_hal::gpio::{Input, InputConfig, Level, Output, OutputConfig, Pull};
-use esp_hal::i2c::master::{Config as I2cConfig, 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;
+use esp_hal::gpio::{Input, InputConfig, InputPin, Level, Output, OutputConfig, OutputPin, Pull};
 
 use lora_phy::iv::GenericSx126xInterfaceVariant;
 use lora_phy::sx126x::{self, Sx1262, Sx126x};
 
-// ── Concrete peripheral types ────────────────────────────────────────
+use crate::hal::esp32s3 as mcu;
+
+// ── Re-export MCU types ─────────────────────────────────────────────
+
+pub use mcu::{I2cBus as DisplayI2c, SpiBus};
+
+// ── Concrete peripheral types ───────────────────────────────────────
 
-type SpiBus = SpiDmaBus<'static, esp_hal::Async>;
 type Nss = Output<'static>;
 type Iv = GenericSx126xInterfaceVariant<Output<'static>, Input<'static>>;
 type RadioSpiDevice = SpiDevice<'static, NoopRawMutex, SpiBus, Nss>;
 pub type RadioDriver = Sx126x<RadioSpiDevice, Iv, Sx1262>;
 
-pub type UsbDriver = esp_hal::otg_fs::asynch::Driver<'static>;
-
-pub type DisplayI2c = I2c<'static, esp_hal::Async>;
-
-// ── Peripheral bundles ───────────────────────────────────────────────
+// ── Peripheral bundles ──────────────────────────────────────────────
 
 pub struct RadioParts {
     pub driver: RadioDriver,
     pub delay: Delay,
 }
 
-pub struct UsbParts {
-    pub driver: UsbDriver,
-}
-
+// SSD1306 display support is Heltec-specific. ESP32-S3 boards that use a
+// different controller (e.g. ThinkNode-M2 uses SH1106) provide their own
+// DisplayParts / DisplayDriver / create_display directly.
+#[cfg(any(
+    feature = "heltec_v3",
+    feature = "heltec_v3_uart",
+    feature = "heltec_v4"
+))]
 pub struct DisplayParts {
     pub i2c: DisplayI2c,
-    pub mac: [u8; 6],
 }
 
-// ── Shared initialization helpers ───────────────────────────────────
+// ── Display driver ──────────────────────────────────────────────────
 
-/// Start the ESP-RTOS scheduler and Embassy time driver.
-pub fn start_timer(timg0: esp_hal::peripherals::TIMG0<'static>) {
-    let timg0 = TimerGroup::new(timg0);
-    esp_rtos::start(timg0.timer0);
+#[cfg(any(
+    feature = "heltec_v3",
+    feature = "heltec_v3_uart",
+    feature = "heltec_v4"
+))]
+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 I2C.
+#[cfg(any(
+    feature = "heltec_v3",
+    feature = "heltec_v3_uart",
+    feature = "heltec_v4"
+))]
+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};
+
+    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;
+    }
+    let _ = display.set_brightness(Brightness::BRIGHTEST).await;
+    Some(display)
 }
 
-/// Initialize SPI + DMA + SX1262 radio.
+// ── Shared peripheral init helpers ──────────────────────────────────
+
+/// Construct SX1262 radio from an initialized SPI bus.
 ///
-/// All current ESP32-S3 boards use the same SPI/radio pin mapping:
-/// SCK=GPIO9, MOSI=GPIO10, MISO=GPIO11, NSS=GPIO8,
-/// Reset=GPIO12, DIO1=GPIO14, BUSY=GPIO13.
-#[allow(clippy::too_many_arguments)]
+/// Generic over GPIO type so boards with different radio pin assignments can
+/// share this helper. `tcxo_voltage` selects the DIO3-driven TCXO supply:
+/// Heltec boards use `Ctrl1V8`, the ELECROW ThinkNode-M2 uses `Ctrl3V3`, etc.
 pub fn init_radio(
-    spi2: esp_hal::peripherals::SPI2<'static>,
-    dma_ch0: esp_hal::peripherals::DMA_CH0<'static>,
-    sck: esp_hal::peripherals::GPIO9<'static>,
-    mosi: esp_hal::peripherals::GPIO10<'static>,
-    miso: esp_hal::peripherals::GPIO11<'static>,
-    nss_pin: esp_hal::peripherals::GPIO8<'static>,
-    reset_pin: esp_hal::peripherals::GPIO12<'static>,
-    dio1_pin: esp_hal::peripherals::GPIO14<'static>,
-    busy_pin: esp_hal::peripherals::GPIO13<'static>,
+    spi_bus: &'static embassy_sync::mutex::Mutex<NoopRawMutex, SpiBus>,
+    nss_pin: impl OutputPin + 'static,
+    reset_pin: impl OutputPin + 'static,
+    dio1_pin: impl InputPin + 'static,
+    busy_pin: impl InputPin + 'static,
+    tcxo_voltage: sx126x::TcxoCtrlVoltage,
 ) -> RadioParts {
-    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_ch0);
-
-    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();
-    let spi_bus = SPI_BUS.init(embassy_sync::mutex::Mutex::new(spi));
-
     let nss = Output::new(nss_pin, Level::High, OutputConfig::default());
     let spi_device = SpiDevice::new(spi_bus, nss);
 
@@ -107,7 +109,7 @@ pub fn init_radio(
 
     let sx_config = sx126x::Config {
         chip: Sx1262,
-        tcxo_ctrl: Some(sx126x::TcxoCtrlVoltage::Ctrl1V7),
+        tcxo_ctrl: Some(tcxo_voltage),
         use_dcdc: true,
         rx_boost: false,
     };
@@ -117,34 +119,3 @@ pub fn init_radio(
         delay: Delay,
     }
 }
-
-/// Initialize USB OTG CDC-ACM driver.
-pub fn init_usb(
-    usb0: esp_hal::peripherals::USB0<'static>,
-    dp: esp_hal::peripherals::GPIO20<'static>,
-    dm: esp_hal::peripherals::GPIO19<'static>,
-) -> UsbParts {
-    let usb_inst = esp_hal::otg_fs::Usb::new(usb0, dp, dm);
-    static EP_OUT_BUF: StaticCell<[u8; 1024]> = StaticCell::new();
-    let ep_out_buf = EP_OUT_BUF.init([0u8; 1024]);
-    UsbParts {
-        driver: esp_hal::otg_fs::asynch::Driver::new(
-            usb_inst,
-            ep_out_buf,
-            esp_hal::otg_fs::asynch::Config::default(),
-        ),
-    }
-}
-
-/// Initialize I2C bus for display.
-pub fn init_display_i2c(
-    i2c0: esp_hal::peripherals::I2C0<'static>,
-    sda: esp_hal::peripherals::GPIO17<'static>,
-    scl: esp_hal::peripherals::GPIO18<'static>,
-) -> DisplayI2c {
-    I2c::new(i2c0, I2cConfig::default())
-        .expect("I2C init")
-        .with_sda(sda)
-        .with_scl(scl)
-        .into_async()
-}

src/board/heltec_v3.rs

@@ -1,12 +1,27 @@
+//! Heltec WiFi LoRa 32 V3 — native USB (requires hardware mod).
+//!
+//! Stock V3 boards route USB through a CP2102 bridge to UART. To use native
+//! USB CDC-ACM, solder R29 (D+) and R3 (D-) on the PCB and disconnect the
+//! CP2102 from the USB data lines. See the project README for details.
+//!
+//! For stock (unmodified) V3 boards, use the `heltec_v3_uart` feature instead.
+
 use esp_hal::gpio::{Level, Output, OutputConfig};
+use static_cell::StaticCell;
 
 use super::esp32s3;
-use super::traits::LoRaBoard;
+use super::traits::{BoardParts, LoRaBoard};
+use crate::driver::simple_led::SimpleLed;
+use crate::hal::esp32s3 as mcu;
 
-#[allow(unused_imports)] // Re-exported for other modules (display, radio, usb tasks)
-pub use super::esp32s3::{DisplayI2c, DisplayParts, RadioDriver, RadioParts, UsbDriver, UsbParts};
+pub use super::esp32s3::{create_display, DisplayDriver, DisplayParts, RadioDriver, RadioParts};
 
-// ── Board init ───────────────────────────────────────────────────────
+pub type UsbDriver = esp_hal::otg_fs::asynch::Driver<'static>;
+pub type LedDriver = SimpleLed<Output<'static>>;
+
+pub struct UsbParts {
+    pub driver: UsbDriver,
+}
 
 pub struct Board {
     p: esp_hal::peripherals::Peripherals,
@@ -16,35 +31,72 @@ impl LoRaBoard for Board {
     const NAME: &'static str = "Heltec V3";
     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] {
-        esp_hal::efuse::Efuse::mac_address()
+        mcu::mac_address()
     }
-}
 
-impl Board {
-    pub fn into_parts(self) -> (RadioParts, UsbParts, Option<DisplayParts>) {
+    fn into_parts(self) -> BoardParts<RadioParts, UsbParts, DisplayParts, LedDriver> {
         let p = self.p;
 
-        esp32s3::start_timer(p.TIMG0);
+        mcu::start_timer(p.TIMG0, p.SW_INTERRUPT);
 
-        // Vext power: GPIO21, active LOW to enable OLED
-        let vext = Output::new(p.GPIO21, Level::Low, OutputConfig::default());
-        core::mem::forget(vext); // hold pin low permanently; drop would reset it
+        // Vext power: GPIO36, active LOW to enable peripherals.
+        // Output has no Drop impl, so the pin stays configured for program lifetime.
+        let _vext = Output::new(p.GPIO36, Level::Low, OutputConfig::default());
 
+        let spi_bus = mcu::init_spi(p.SPI2, p.DMA_CH0, p.GPIO9, p.GPIO10, p.GPIO11);
         let radio = esp32s3::init_radio(
-            p.SPI2, p.DMA_CH0, p.GPIO9, p.GPIO10, p.GPIO11, p.GPIO8, p.GPIO12, p.GPIO14,
+            spi_bus,
+            p.GPIO8,
+            p.GPIO12,
+            p.GPIO14,
             p.GPIO13,
+            lora_phy::sx126x::TcxoCtrlVoltage::Ctrl1V8,
         );
-        let usb = esp32s3::init_usb(p.USB0, p.GPIO20, p.GPIO19);
-        let i2c = esp32s3::init_display_i2c(p.I2C0, p.GPIO17, p.GPIO18);
-        let mac = Self::mac_address();
-        let display = Some(DisplayParts { i2c, mac });
 
-        (radio, usb, display)
+        // Note: switches 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(),
+            ),
+        };
+
+        // SSD1306 display reset: pulse GPIO21 low->high before I2C init.
+        // Output has no Drop impl; pin stays HIGH after this block.
+        let mut display_rst = Output::new(p.GPIO21, Level::Low, OutputConfig::default());
+        esp_hal::delay::Delay::new().delay_millis(10);
+        display_rst.set_high();
+        esp_hal::delay::Delay::new().delay_millis(10);
+
+        let i2c = mcu::init_i2c(p.I2C0, p.GPIO17, p.GPIO18);
+        let display = Some(DisplayParts { i2c });
+
+        // White LED on GPIO35
+        let led_pin = Output::new(p.GPIO35, Level::Low, OutputConfig::default());
+        let led = SimpleLed(led_pin);
+
+        BoardParts {
+            radio,
+            host,
+            display,
+            led,
+            mac: Self::mac_address(),
+        }
     }
 }

src/board/heltec_v3_uart.rs

@@ -0,0 +1,98 @@
+//! Heltec WiFi LoRa 32 V3 — stock UART (via CP2102 bridge).
+//!
+//! This is for unmodified V3 boards where USB goes through the CP2102
+//! bridge to UART0. The board appears as /dev/ttyUSB* (not ttyACM*).
+//!
+//! If you've done the hardware mod (solder R29/R3, disconnect CP2102),
+//! use the `heltec_v3` feature instead for native USB CDC-ACM support.
+
+use esp_hal::gpio::{Level, Output, OutputConfig};
+
+use super::esp32s3;
+use super::traits::{BoardParts, LoRaBoard};
+use crate::driver::simple_led::SimpleLed;
+use crate::hal::esp32s3 as mcu;
+
+pub use super::esp32s3::{create_display, DisplayDriver, DisplayParts, RadioDriver, RadioParts};
+
+pub type UartDriver = esp_hal::uart::Uart<'static, esp_hal::Async>;
+pub type LedDriver = SimpleLed<Output<'static>>;
+
+pub struct UartParts {
+    pub driver: UartDriver,
+}
+
+pub struct Board {
+    p: esp_hal::peripherals::Peripherals,
+}
+
+impl LoRaBoard for Board {
+    const NAME: &'static str = "Heltec V3 (UART)";
+    const TX_POWER_RANGE: (i8, i8) = (-9, 22);
+
+    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 into_parts(self) -> BoardParts<RadioParts, UartParts, DisplayParts, LedDriver> {
+        let p = self.p;
+
+        mcu::start_timer(p.TIMG0, p.SW_INTERRUPT);
+
+        // Vext power: GPIO36, active LOW to enable peripherals.
+        // Output has no Drop impl, so the pin stays configured for program lifetime.
+        let _vext = Output::new(p.GPIO36, Level::Low, OutputConfig::default());
+
+        let spi_bus = mcu::init_spi(p.SPI2, p.DMA_CH0, p.GPIO9, p.GPIO10, p.GPIO11);
+        let radio = esp32s3::init_radio(
+            spi_bus,
+            p.GPIO8,
+            p.GPIO12,
+            p.GPIO14,
+            p.GPIO13,
+            lora_phy::sx126x::TcxoCtrlVoltage::Ctrl1V8,
+        );
+
+        use esp_hal::uart::{Config as UartConfig, Uart};
+        let host = UartParts {
+            driver: Uart::new(p.UART0, UartConfig::default())
+                .expect("UART init")
+                .with_tx(p.GPIO43)
+                .with_rx(p.GPIO44)
+                .into_async(),
+        };
+
+        // SSD1306 display reset: pulse GPIO21 low->high before I2C init.
+        // Output has no Drop impl; pin stays HIGH after this block.
+        let mut display_rst = Output::new(p.GPIO21, Level::Low, OutputConfig::default());
+        esp_hal::delay::Delay::new().delay_millis(10);
+        display_rst.set_high();
+        esp_hal::delay::Delay::new().delay_millis(10);
+
+        let i2c = mcu::init_i2c(p.I2C0, p.GPIO17, p.GPIO18);
+        let display = Some(DisplayParts { i2c });
+
+        // White LED on GPIO35
+        let led_pin = Output::new(p.GPIO35, Level::Low, OutputConfig::default());
+        let led = SimpleLed(led_pin);
+
+        BoardParts {
+            radio,
+            host,
+            display,
+            led,
+            mac: Self::mac_address(),
+        }
+    }
+}

src/board/heltec_v4.rs

@@ -1,12 +1,20 @@
 use esp_hal::gpio::{Level, Output, OutputConfig};
+use static_cell::StaticCell;
 
 use super::esp32s3;
-use super::traits::LoRaBoard;
+use super::traits::{BoardParts, LoRaBoard};
+use crate::driver::simple_led::SimpleLed;
+use crate::hal::esp32s3 as mcu;
 
-#[allow(unused_imports)] // Re-exported for other modules (display, radio, usb tasks)
-pub use super::esp32s3::{DisplayI2c, DisplayParts, RadioDriver, RadioParts, UsbDriver, UsbParts};
+pub use super::esp32s3::{create_display, DisplayDriver, DisplayParts, RadioDriver, RadioParts};
 
-// ── Board implementation ────────────────────────────────────────────
+pub type UsbDriver = esp_hal::otg_fs::asynch::Driver<'static>;
+
+pub type LedDriver = SimpleLed<Output<'static>>;
+
+pub struct UsbParts {
+    pub driver: UsbDriver,
+}
 
 pub struct Board {
     p: esp_hal::peripherals::Peripherals,
@@ -16,46 +24,72 @@ impl LoRaBoard for Board {
     const NAME: &'static str = "Heltec V4";
     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] {
-        esp_hal::efuse::Efuse::mac_address()
+        mcu::mac_address()
     }
-}
 
-impl Board {
-    pub fn into_parts(self) -> (RadioParts, UsbParts, Option<DisplayParts>) {
+    fn into_parts(self) -> BoardParts<RadioParts, UsbParts, DisplayParts, LedDriver> {
         let p = self.p;
 
-        esp32s3::start_timer(p.TIMG0);
+        mcu::start_timer(p.TIMG0, p.SW_INTERRUPT);
 
-        // Vext power: GPIO36, active LOW to enable peripherals
-        let vext = Output::new(p.GPIO36, Level::Low, OutputConfig::default());
-        core::mem::forget(vext); // hold pin low permanently; drop would reset it
+        // Vext power: GPIO36, active LOW to enable peripherals.
+        // Output has no Drop impl, so the pin stays configured for program lifetime.
+        let _vext = Output::new(p.GPIO36, Level::Low, OutputConfig::default());
 
+        let spi_bus = mcu::init_spi(p.SPI2, p.DMA_CH0, p.GPIO9, p.GPIO10, p.GPIO11);
         let radio = esp32s3::init_radio(
-            p.SPI2, p.DMA_CH0, p.GPIO9, p.GPIO10, p.GPIO11, p.GPIO8, p.GPIO12, p.GPIO14,
+            spi_bus,
+            p.GPIO8,
+            p.GPIO12,
+            p.GPIO14,
             p.GPIO13,
+            lora_phy::sx126x::TcxoCtrlVoltage::Ctrl1V8,
         );
 
         // Note: switches internal USB PHY from Serial-JTAG to OTG.
-        // espflash --monitor will stop working after this point.
-        let usb = esp32s3::init_usb(p.USB0, p.GPIO20, p.GPIO19);
+        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(),
+            ),
+        };
 
-        // SSD1315 display reset: pulse GPIO21 low->high before I2C init
+        // SSD1315 display reset: pulse GPIO21 low->high before I2C init.
+        // Output has no Drop impl; pin stays HIGH after this block.
         let mut display_rst = Output::new(p.GPIO21, Level::Low, OutputConfig::default());
         esp_hal::delay::Delay::new().delay_millis(10);
         display_rst.set_high();
         esp_hal::delay::Delay::new().delay_millis(10);
-        core::mem::forget(display_rst); // hold reset high permanently
 
-        let i2c = esp32s3::init_display_i2c(p.I2C0, p.GPIO17, p.GPIO18);
-        let mac = Self::mac_address();
-        let display = Some(DisplayParts { i2c, mac });
+        let i2c = mcu::init_i2c(p.I2C0, p.GPIO17, p.GPIO18);
+        let display = Some(DisplayParts { i2c });
 
-        (radio, usb, display)
+        // Orange LED on GPIO35
+        let led_pin = Output::new(p.GPIO35, Level::Low, OutputConfig::default());
+        let led = SimpleLed(led_pin);
+
+        BoardParts {
+            radio,
+            host,
+            display,
+            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(i2c: DisplayI2c) -> Option<DisplayDriver> {
+    let mut display = Sh1106::new(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

@@ -2,9 +2,14 @@
 pub mod traits;
 pub use traits::*;
 
-#[cfg(any(feature = "heltec_v3", feature = "heltec_v4"))]
-mod esp32s3;
-
+{% 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! {
     {%- for board in boards %}
     {% if loop.first %}if{% else %}else if{% endif %} #[cfg(feature = "{{ board }}")] {

src/board/rak_wisblock_4631.rs

@@ -1,40 +1,34 @@
 use embassy_embedded_hal::shared_bus::asynch::spi::SpiDevice;
 use embassy_nrf::gpio::{Input, Level, Output, OutputDrive, Pull};
 use embassy_nrf::spim::{self, Spim};
-use embassy_nrf::twim::{self, Twim};
+use embassy_nrf::twim;
 use embassy_nrf::usb::Driver;
-use embassy_nrf::{bind_interrupts, Peripherals};
 use embassy_sync::blocking_mutex::raw::NoopRawMutex;
 use embassy_time::Delay;
-use static_cell::StaticCell;
 
 use lora_phy::iv::GenericSx126xInterfaceVariant;
 use lora_phy::sx126x::{self, Sx1262, Sx126x};
 
-use super::traits::LoRaBoard;
+use super::traits::{BoardParts, LoRaBoard};
+use crate::hal::nrf52840 as mcu;
 
-bind_interrupts!(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>;
-});
+// ── Concrete peripheral types ───────────────────────────────────────
 
-// ── Concrete peripheral types ────────────────────────────────────────
-
-type SpiBus = Spim<'static>;
 type Nss = Output<'static>;
 type Iv = GenericSx126xInterfaceVariant<Output<'static>, Input<'static>>;
-type RadioSpiDevice = SpiDevice<'static, NoopRawMutex, SpiBus, Nss>;
-/// SX126x driver (pre-LoRa construction — LoRa::new is async).
+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 = crate::driver::simple_led::SimpleLed<Output<'static>>;
 
-/// USB driver for CDC-ACM.
-pub type UsbDriver = Driver<'static, &'static embassy_nrf::usb::vbus_detect::SoftwareVbusDetect>;
+pub type DisplayDriver = ssd1306::Ssd1306Async<
+    ssd1306::prelude::I2CInterface<DisplayI2c>,
+    ssd1306::size::DisplaySize128x64,
+    ssd1306::mode::BufferedGraphicsModeAsync<ssd1306::size::DisplaySize128x64>,
+>;
 
-/// I2C bus for an optional SSD1306 OLED.
-pub type DisplayI2c = Twim<'static>;
-
-// ── Peripheral bundles ───────────────────────────────────────────────
+// ── Peripheral bundles ──────────────────────────────────────────────
 
 pub struct RadioParts {
     pub driver: RadioDriver,
@@ -47,72 +41,90 @@ pub struct UsbParts {
 
 pub struct DisplayParts {
     pub i2c: DisplayI2c,
-    pub mac: [u8; 6],
 }
 
-// ── Board init ───────────────────────────────────────────────────────
+// ── 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};
+
+    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;
+    }
+    let _ = display.set_brightness(Brightness::BRIGHTEST).await;
+    Some(display)
+}
+
+// ── Board init ──────────────────────────────────────────────────────
 
 pub struct Board {
-    p: Peripherals,
+    p: embassy_nrf::Peripherals,
 }
 
-impl super::traits::LoRaBoard for Board {
+impl LoRaBoard for Board {
     const NAME: &'static str = "RAK WisBlock 4631";
     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 = 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 }
     }
 
     fn mac_address() -> [u8; 6] {
-        // SAFETY: 0x10000000 is the nRF52840 FICR (Factory Information Configuration
-        // Registers) base address. Offsets 0x0A4 and 0x0A8 are the DEVICEADDR[0] and
-        // DEVICEADDR[1] registers containing the factory-programmed device address.
-        // read_volatile is correct for memory-mapped hardware registers.
-        unsafe {
-            let ficr = 0x10000000 as *const u32;
-            let addr0 = core::ptr::read_volatile(ficr.byte_add(0x0A4));
-            let addr1 = core::ptr::read_volatile(ficr.byte_add(0x0A8));
-            [
-                addr0 as u8,
-                (addr0 >> 8) as u8,
-                (addr0 >> 16) as u8,
-                (addr0 >> 24) as u8,
-                addr1 as u8,
-                (addr1 >> 8) as u8,
-            ]
-        }
+        mcu::mac_address()
     }
-}
 
-impl Board {
-
-    pub fn into_parts(self) -> (RadioParts, UsbParts, Option<DisplayParts>) {
+    fn into_parts(self) -> BoardParts<RadioParts, UsbParts, DisplayParts, LedDriver> {
         let p = self.p;
 
-        // ── SPI bus for SX1262 ───────────────────────────────────
+        // 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;
-        let spi = Spim::new(p.SPI3, Irqs, p.P1_11, p.P1_13, p.P1_12, spi_cfg);
-
-        static SPI_BUS: StaticCell<embassy_sync::mutex::Mutex<NoopRawMutex, SpiBus>> =
-            StaticCell::new();
-        let spi_bus = SPI_BUS.init(embassy_sync::mutex::Mutex::new(spi));
+        // 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);
 
         let nss = Output::new(p.P1_10, Level::High, OutputDrive::Standard);
         let spi_device = SpiDevice::new(spi_bus, nss);
 
-        // ── SX1262 control pins ──────────────────────────────────
         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");
+        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::Ctrl1V7),
+            tcxo_ctrl: Some(sx126x::TcxoCtrlVoltage::Ctrl1V8),
             use_dcdc: true,
             rx_boost: false,
         };
@@ -122,24 +134,36 @@ impl Board {
             delay: Delay,
         };
 
-        // ── USB ──────────────────────────────────────────────────
-        static VBUS: StaticCell<embassy_nrf::usb::vbus_detect::SoftwareVbusDetect> =
-            StaticCell::new();
-        let vbus = VBUS.init(embassy_nrf::usb::vbus_detect::SoftwareVbusDetect::new(true, false));
-        let usb = UsbParts {
-            driver: Driver::new(p.USBD, Irqs, vbus),
+        // ── USB ─────────────────────────────────────────────────
+        // 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),
         };
 
-        // ── Display (optional RAK1921 SSD1306 OLED on I2C) ──────
-        // Always provide the I2C bus; display_task detects presence
-        // via SSD1306 init (fails gracefully if no display attached).
-        static TWIM_BUF: StaticCell<[u8; 256]> = StaticCell::new();
-        let twim_buf = TWIM_BUF.init([0u8; 256]);
-        let i2c_cfg = twim::Config::default();
-        let i2c = Twim::new(p.TWISPI0, Irqs, p.P0_13, p.P0_14, i2c_cfg, twim_buf);
-        let mac = Self::mac_address();
-        let display = Some(DisplayParts { i2c, mac });
+        // ── Display (optional RAK1921 SSD1306 OLED on I2C) ─────
+        let twim_buf = mcu::alloc_i2c_buffer();
+        let i2c = embassy_nrf::twim::Twim::new(
+            p.TWISPI0,
+            mcu::Irqs,
+            p.P0_13,
+            p.P0_14,
+            twim::Config::default(),
+            twim_buf,
+        );
+        let display = Some(DisplayParts { i2c });
 
-        (radio, usb, display)
+        // 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,
+            mac: Self::mac_address(),
+        }
     }
 }

src/board/traits.rs

@@ -1,31 +1,96 @@
 //! Board abstraction trait.
 //!
-//! Every board must implement [`LoRaBoard`]. The compiler enforces completeness —
-//! missing constants or methods are compile errors, not runtime surprises.
-//!
-//! Board modules also export concrete types (`RadioParts`, `UsbParts`,
-//! `DisplayParts`, `RadioDriver`, `UsbDriver`, `DisplayI2c`) that the tasks
-//! use directly. The trait verifies metadata and initialization; the types
-//! verify hardware compatibility.
+//! Every board must implement [`LoRaBoard`] with concrete associated types
+//! for its radio, host communication, display, and LED peripherals. The
+//! compiler enforces completeness — missing types or methods are compile errors.
 //!
 //! See `src/board/PORTING.md` for a step-by-step guide to adding a new board.
 
+use embedded_graphics::draw_target::DrawTarget;
+use embedded_graphics::pixelcolor::BinaryColor;
+
+use crate::driver::DisplayBrightness;
+
+/// Async RGB LED control. Boards without an LED use `()` which is a no-op.
+pub trait RgbLed {
+    fn set_rgb(&mut self, r: u8, g: u8, b: u8) -> impl core::future::Future<Output = ()>;
+}
+
+impl RgbLed for () {
+    async fn set_rgb(&mut self, _r: u8, _g: u8, _b: u8) {}
+}
+
 /// Compile-time contract for a DongLoRa board.
-///
-/// Every board's `Board` struct must implement this trait. It verifies that
-/// the board provides all required metadata and initialization methods.
-/// The tasks use the board's concrete types directly (not the trait's
-/// associated types) because Embassy tasks must be concrete.
-pub trait LoRaBoard {
+pub trait LoRaBoard: Sized {
     /// Human-readable board name (shown on display splash screen).
     const NAME: &'static str;
 
     /// TX power range in dBm (min, max) for this board's radio + PA.
     const TX_POWER_RANGE: (i8, i8);
 
+    /// Radio peripheral bundle (driver + delay).
+    type RadioParts;
+
+    /// Host communication peripheral bundle (USB or UART driver).
+    type CommParts;
+
+    /// Display peripheral bundle (I2C bus for display init).
+    type DisplayParts;
+
+    /// Concrete display driver type (must implement DrawTarget for rendering
+    /// and DisplayBrightness for the two-level dim control).
+    type DisplayDriver: DrawTarget<Color = BinaryColor> + DisplayBrightness;
+
+    /// RGB LED driver. Boards without an LED use `()`.
+    type LedDriver: RgbLed;
+
     /// Initialize the board hardware.
     fn init() -> Self;
 
     /// Read the board's unique hardware address (MAC, device ID, etc.).
     fn mac_address() -> [u8; 6];
+
+    /// Radio chip identifier reported in `GET_INFO`. Defaults to SX1262
+    /// (`0x0002`), matching every currently-supported board. Override for
+    /// boards that carry a different chip (LLCC68, SX1261, LR11xx, …).
+    fn radio_chip_id() -> u16 {
+        // SX1262 — see PROTOCOL.md §8.
+        0x0002
+    }
+
+    /// (freq_min_hz, freq_max_hz) — the RF front-end's effective tuning
+    /// window on this specific board. Reported in `GET_INFO`. Defaults
+    /// to the SX1262's nominal 150–960 MHz range.
+    fn freq_range_hz() -> (u32, u32) {
+        (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,
+    ) -> BoardParts<Self::RadioParts, Self::CommParts, Self::DisplayParts, Self::LedDriver>;
+}
+
+/// Peripheral bundles for each firmware task, produced by [`LoRaBoard::into_parts`].
+pub struct BoardParts<R, C, D, L> {
+    pub radio: R,
+    pub host: C,
+    pub display: Option<D>,
+    pub led: L,
+    pub mac: [u8; 6],
 }

src/board/waveshare_rp2040_lora.rs

@@ -0,0 +1,150 @@
+use embassy_embedded_hal::shared_bus::asynch::spi::SpiDevice;
+use embassy_rp::gpio::{Input, Level, Output, Pull};
+use embassy_rp::spi;
+use embassy_sync::blocking_mutex::raw::NoopRawMutex;
+use embassy_time::Delay;
+
+use lora_phy::iv::GenericSx126xInterfaceVariant;
+use lora_phy::sx126x::{self, Sx1262, Sx126x};
+
+use super::traits::{BoardParts, LoRaBoard};
+use crate::hal::rp2040 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::UsbRpDriver;
+pub type LedDriver = crate::driver::simple_led::SimpleLed<Output<'static>>;
+
+// Display types — never instantiated (no OLED on this board), but the
+// trait requires concrete associated types that satisfy the bounds.
+pub type DisplayI2c =
+    embassy_rp::i2c::I2c<'static, embassy_rp::peripherals::I2C0, embassy_rp::i2c::Async>;
+pub type DisplayDriver = ssd1306::Ssd1306Async<
+    ssd1306::prelude::I2CInterface<DisplayI2c>,
+    ssd1306::size::DisplaySize128x64,
+    ssd1306::mode::BufferedGraphicsModeAsync<ssd1306::size::DisplaySize128x64>,
+>;
+
+// ── Peripheral bundles ─────────────────────────────────────────────
+
+pub struct RadioParts {
+    pub driver: RadioDriver,
+    pub delay: Delay,
+}
+
+pub struct UsbParts {
+    pub driver: UsbDriver,
+}
+
+pub struct DisplayParts {
+    pub i2c: DisplayI2c,
+}
+
+// ── Display init ───────────────────────────────────────────────────
+
+pub async fn create_display(_i2c: DisplayI2c) -> Option<DisplayDriver> {
+    None
+}
+
+// ── Board init ─────────────────────────────────────────────────────
+
+pub struct Board {
+    p: embassy_rp::Peripherals,
+}
+
+impl LoRaBoard for Board {
+    const NAME: &'static str = "Waveshare RP2040-LoRa";
+    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 = embassy_rp::init(Default::default());
+        Self { p }
+    }
+
+    fn mac_address() -> [u8; 6] {
+        mcu::mac_address()
+    }
+
+    fn into_parts(self) -> BoardParts<RadioParts, UsbParts, DisplayParts, LedDriver> {
+        let p = self.p;
+
+        // ── MAC address from flash unique ID ───────────────────
+        let mut flash =
+            embassy_rp::flash::Flash::<_, _, { 2 * 1024 * 1024 }>::new_blocking(p.FLASH);
+        mcu::init_mac(&mut flash);
+
+        // ── SPI1 bus for SX1262 ────────────────────────────────
+        //
+        // Pin mapping from Meshtastic & MeshCore firmware (confirmed working):
+        //   SCK = GPIO14, MOSI = GPIO15, MISO = GPIO24, CS = GPIO13
+        //
+        // The Waveshare wiki (https://www.waveshare.com/wiki/RP2040-LoRa) lists
+        // different pins (MOSI=11, MISO=8, CS=9) but those don't work in practice.
+        // Both sets are valid SPI1 alternate functions on RP2040.
+        let mut spi_cfg = spi::Config::default();
+        spi_cfg.frequency = 1_000_000;
+        let spi = spi::Spi::new(
+            p.SPI1,
+            p.PIN_14,
+            p.PIN_15,
+            p.PIN_24,
+            p.DMA_CH0,
+            p.DMA_CH1,
+            mcu::Irqs,
+            spi_cfg,
+        );
+        let spi_bus = mcu::share_spi_bus(spi);
+
+        let nss = Output::new(p.PIN_13, Level::High);
+        let spi_device = SpiDevice::new(spi_bus, nss);
+
+        let reset = Output::new(p.PIN_23, Level::High);
+        let dio1 = Input::new(p.PIN_16, Pull::Down);
+        let busy = Input::new(p.PIN_18, Pull::Down);
+
+        // PE4259 antenna switch: GPIO17 = !CTRL (rx_enable).
+        // DIO2 is internally wired as CTRL (tx_enable), managed by the SX1262.
+        let rx_enable = Output::new(p.PIN_17, Level::Low);
+        let iv = GenericSx126xInterfaceVariant::new(reset, dio1, busy, Some(rx_enable), None)
+            .expect("SX1262 interface init");
+
+        let sx_config = sx126x::Config {
+            chip: Sx1262,
+            tcxo_ctrl: None, // No TCXO on this board
+            use_dcdc: true,
+            rx_boost: false,
+        };
+
+        let radio = RadioParts {
+            driver: Sx126x::new(spi_device, iv, sx_config),
+            delay: Delay,
+        };
+
+        // ── USB ────────────────────────────────────────────────
+        let host = UsbParts {
+            driver: embassy_rp::usb::Driver::new(p.USB, mcu::Irqs),
+        };
+
+        // ── LED on GPIO25 ──────────────────────────────────────
+        let led_pin = Output::new(p.PIN_25, Level::Low);
+        let led = crate::driver::simple_led::SimpleLed(led_pin);
+
+        BoardParts {
+            radio,
+            host,
+            display: None,
+            led,
+            mac: Self::mac_address(),
+        }
+    }
+}

src/board/wio_tracker_l1.rs

@@ -0,0 +1,156 @@
+use embassy_embedded_hal::shared_bus::asynch::spi::SpiDevice;
+use embassy_nrf::gpio::{Input, Level, Output, OutputDrive, Pull};
+use embassy_nrf::spim::{self, Spim};
+use embassy_nrf::twim;
+use embassy_nrf::usb::Driver;
+use embassy_sync::blocking_mutex::raw::NoopRawMutex;
+use embassy_time::Delay;
+
+use lora_phy::iv::GenericSx126xInterfaceVariant;
+use lora_phy::sx126x::{self, Sx1262, Sx126x};
+
+use super::traits::{BoardParts, LoRaBoard};
+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;
+pub type DisplayI2c = mcu::I2cBus;
+
+pub type LedDriver = crate::driver::simple_led::SimpleLed<Output<'static>>;
+
+pub type DisplayDriver = crate::driver::sh1106::Sh1106<DisplayI2c>;
+
+// ── Peripheral bundles ──────────────────────────────────────────────
+
+pub struct RadioParts {
+    pub driver: RadioDriver,
+    pub delay: Delay,
+}
+
+pub struct UsbParts {
+    pub driver: UsbDriver,
+}
+
+pub struct DisplayParts {
+    pub i2c: DisplayI2c,
+}
+
+// ── Display init ────────────────────────────────────────────────────
+
+pub async fn create_display(i2c: DisplayI2c) -> Option<DisplayDriver> {
+    let mut display = crate::driver::sh1106::Sh1106::new(i2c, 0x3D);
+
+    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: embassy_nrf::Peripherals,
+}
+
+impl LoRaBoard for Board {
+    const NAME: &'static str = "Wio Tracker L1";
+    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 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;
+
+        // ── SPI bus for SX1262 ──────────────────────────────────
+        let mut spi_cfg = spim::Config::default();
+        spi_cfg.frequency = spim::Frequency::M1;
+        let spi = Spim::new(p.SPI3, mcu::Irqs, p.P0_30, p.P0_03, p.P0_28, spi_cfg);
+        let spi_bus = mcu::share_spi_bus(spi);
+
+        let nss = Output::new(p.P1_14, Level::High, OutputDrive::Standard);
+        let spi_device = SpiDevice::new(spi_bus, nss);
+
+        let reset = Output::new(p.P1_07, Level::High, OutputDrive::Standard);
+        let dio1 = Input::new(p.P0_07, 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);
+        let iv = GenericSx126xInterfaceVariant::new(reset, dio1, busy, Some(rx_enable), 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),
+        };
+
+        // ── BAT_CTL: P0.04, active HIGH — enables power to OLED and battery sense
+        let bat_ctl = Output::new(p.P0_04, Level::High, OutputDrive::Standard);
+        core::mem::forget(bat_ctl);
+
+        // ── Display (SH1106 OLED on I2C) ────────────────────────
+        let twim_buf = mcu::alloc_i2c_buffer();
+        let i2c = embassy_nrf::twim::Twim::new(
+            p.TWISPI0,
+            mcu::Irqs,
+            p.P0_06,
+            p.P0_05,
+            twim::Config::default(),
+            twim_buf,
+        );
+        let display = Some(DisplayParts { i2c });
+
+        // Green LED on P1.01
+        let led_pin = Output::new(p.P1_01, Level::Low, OutputDrive::Standard);
+        let led = crate::driver::simple_led::SimpleLed(led_pin);
+
+        BoardParts {
+            radio,
+            host,
+            display,
+            led,
+            mac: Self::mac_address(),
+        }
+    }
+}

src/channel.rs

@@ -1,67 +1,84 @@
-//! Inter-task communication channels.
+//! Inter-task communication channels for DongLoRa Protocol v2.
 //!
-//! Each channel connects exactly two tasks:
-//! - [`CommandChannel`]: USB → Radio (host commands)
-//! - [`ResponseChannel`]: Radio → USB (firmware responses)
-//! - [`DisplayCommandChannel`]: USB → Display (on/off/reset)
-//! - [`StatusWatch`]: Radio → Display (observable radio state)
+//! - [`CommandChannel`]: host_task → radio_task (tag-correlated commands)
+//! - [`OutboundChannel`]: radio_task → host_task (tag-correlated OK/ERR/TX_DONE
+//!   and tag-0 async RX/ERR events in one queue)
+//! - [`DisplayCommandChannel`]: host_task → display_task (internal only —
+//!   `On` on connect, `Reset` on disconnect; no longer driven from the wire)
+//! - [`RadioEventChannel`]: radio_task → display_task (typed mode/packet events)
 
 use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
 use embassy_sync::channel::Channel;
-use embassy_sync::watch::Watch;
 
-use crate::protocol::{Command, RadioConfig, Response};
+use crate::protocol::{Command, DeviceMessage, LoRaConfig};
 
-/// Display commands routed from usb_task to display_task.
-#[derive(Debug, Clone, Copy, defmt::Format)]
-pub enum DisplayCommand {
-    On,
-    Off,
+// ── Host → Radio: tag-correlated commands ───────────────────────────
+
+/// An event flowing from the host task into the radio task.
+///
+/// `Command` carries a non-zero correlation tag (the host framing layer
+/// rejects tag=0 before it reaches here). `Reset` is a lifecycle signal
+/// from the host transport layer (DTR drop, UART teardown, or spec §3.4
+/// inactivity timeout) telling the radio to park back to Unconfigured
+/// and drain queues silently.
+#[allow(clippy::large_enum_variant)]
+#[derive(Debug, Clone)]
+pub enum InboundEvent {
+    Command { tag: u16, cmd: Command },
     Reset,
 }
 
-/// USB-to-display command channel (depth 4: display commands are rare events).
+/// Host-to-radio event channel (depth 8).
+pub type CommandChannel = Channel<CriticalSectionRawMutex, InboundEvent, 8>;
+
+// ── Radio → Host: OK / ERR / TX_DONE / RX / async ERR ──────────────
+
+/// One outbound D→H frame carrying its tag. Tag-correlated messages
+/// (OK, ERR in response, TX_DONE) carry the originating command's tag;
+/// async events (RX, async ERR) carry `tag = 0x0000`.
+#[derive(Debug, Clone)]
+pub struct OutboundFrame {
+    pub tag: u16,
+    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>;
+
+// ── Internal: display commands (no longer wire-visible) ────────────
+
+/// Internal display command routed from host_task to display_task. The
+/// wire protocol no longer carries DisplayOn/Off (`PROTOCOL.md §15.2`);
+/// these values drive the display statechart from local events only.
+#[derive(Debug, Clone, Copy, defmt::Format)]
+#[allow(dead_code)] // `Off` is reserved for future diagnostic paths.
+pub enum DisplayCommand {
+    /// Host connected (DTR rose on USB, or UART came up). Wake display.
+    On,
+    /// Host disconnected. Park display.
+    Off,
+    /// Reset cumulative counters (e.g., on config change).
+    Reset,
+}
+
+/// Host-to-display command channel.
 pub type DisplayCommandChannel = Channel<CriticalSectionRawMutex, DisplayCommand, 4>;
 
-/// Host-to-radio command channel (depth 16: buffer bursty host command sequences).
-pub type CommandChannel = Channel<CriticalSectionRawMutex, Command, 16>;
+// ── Radio → Display: typed packet/mode events ──────────────────────
 
-/// Radio-to-host response channel (depth 32: buffer RX packets while USB writes).
-pub type ResponseChannel = Channel<CriticalSectionRawMutex, Response, 32>;
-
-/// Observable radio status for the display task (2 receivers max).
-/// Display always sees the latest state — intermediate updates may be
-/// skipped, which is fine for a status display.
-pub type StatusWatch = Watch<CriticalSectionRawMutex, RadioStatus, 2>;
-
-/// Current radio state exposed to observers (e.g. display).
+/// Radio → downstream typed events. These drive the display; they are
+/// NOT the same thing as `OutboundFrame` (which goes out the host
+/// transport). Mode events describe what the radio is doing now; packet
+/// events describe what just happened.
 #[derive(Debug, Clone, defmt::Format)]
-pub struct RadioStatus {
-    pub state: RadioState,
-    pub config: Option<RadioConfig>,
-    pub rx_count: u32,
-    pub tx_count: u32,
-    pub last_rssi: Option<i16>,
-    pub last_snr: Option<i16>,
-}
-
-/// Radio state machine states.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, defmt::Format)]
-pub enum RadioState {
+pub enum RadioEvent {
+    EnteredRx,
+    EnteredTx,
     Idle,
-    Receiving,
-    Transmitting,
+    PacketRx { rssi: i16, snr: Option<i16> },
+    PacketTx,
+    ConfigChanged(LoRaConfig),
 }
 
-impl Default for RadioStatus {
-    fn default() -> Self {
-        Self {
-            state: RadioState::Idle,
-            config: None,
-            rx_count: 0,
-            tx_count: 0,
-            last_rssi: None,
-            last_snr: None,
-        }
-    }
-}
+pub type RadioEventChannel = Channel<CriticalSectionRawMutex, RadioEvent, 32>;

src/debug_blink.rs

@@ -0,0 +1,230 @@
+//! LED-based diagnostic blinker (opt-in via the `debug-checkpoint` cargo
+//! feature).
+//!
+//! On boards whose UART is also the host protocol (heltec_v3_uart, any
+//! UART-only variant), defmt output would corrupt the COBS-framed host
+//! protocol. We can't use `defmt::info!` for live debugging on those
+//! boards while the host is connected. Instead we expose a single global
+//! atomic checkpoint; code sets it at interesting points in the boot /
+//! dispatch flow, and a dedicated task continuously flashes the board
+//! LED N times, pauses, and repeats — so a human can count the flashes
+//! and report "it got to N."
+//!
+//! Blink pattern:
+//! * Each flash: 400 ms ON, 400 ms OFF.
+//! * After N flashes: 2000 ms pause (LED held OFF).
+//! * Repeat indefinitely with the current `CHECKPOINT` value.
+//!
+//! Usage:
+//! ```ignore
+//! #[cfg(feature = "debug-checkpoint")]
+//! crate::debug_blink::set(3);  // "we reached checkpoint 3"
+//! ```
+//!
+//! The task replaces `display_task` when the `debug-checkpoint` feature is
+//! enabled — it takes the board LED and drives it exclusively.
+//!
+//! # Current checkpoint map
+//!
+//! Defined by the `crate::radio` module. Updated here any time the
+//! numbering changes there.
+//!
+//! | Flashes | Meaning                                                |
+//! |--------:|--------------------------------------------------------|
+//! |   1     | `radio_task` entered (pre-`LoRa::new`)                  |
+//! |   2     | `LoRa::new` succeeded                                   |
+//! |   3     | Machine constructed; about to enter `run()`             |
+//! |   4     | In `Idle` state                                         |
+//! |   5     | In `Receiving` state                                    |
+//! |   6     | TX phase 1: entered `perform_tx` (engages latch)        |
+//! |   7     | TX phase 2: in CAD                                      |
+//! |   8     | TX phase 3: in `prepare_for_tx`                         |
+//! |   9     | TX phase 4: awaiting `tx()`                             |
+//! |  10     | TX phase 5: `do_tx` returned OK                         |
+//! |  11     | TX phase 6: `respond_tx_done` handler entered           |
+//! |  12     | TX phase 7: `responses.send(TxDone)` returned           |
+//! |  13     | TX phase 8: `host_task` received the response from chan |
+//! |  14     | TX phase 9: `host_task` wrote response bytes to UART — TERMINAL SUCCESS |
+//! |  15     | TX errored somewhere — TERMINAL ERROR                   |
+//! |  16     | Boot error: `LoRa::new` failed                          |
+//! |  17     | Boot error: `start_rx` failed inside `start_rx_hw`      |
+//!
+//! # Latching
+//!
+//! * Latch engages **only** on `set(6)` (entry to `perform_tx`).
+//! * While latched, only TX-phase values (6–15) can update `CHECKPOINT`,
+//!   and only if strictly deeper than the current value.
+//! * Terminals (14 success, 15 error) freeze the latch until reboot.
+//! * `set(13)` and `set(14)` called from `host_task` are **no-ops before
+//!   the latch engages** — this prevents unrelated SetConfig/Ok responses
+//!   from polluting the display before any TX has happened.
+//!
+//! # Diagnostic logic
+//!
+//! If ai-bot reports a timeout but the LED shows:
+//! * **10** → `do_tx` ok, but `TransmitDone` event never dispatched.
+//! * **11** → handler entered, but `responses.send(...)` hung.
+//! * **12** → send pushed to channel, but `host_task` never picked it up.
+//! * **13** → `host_task` picked it up, but `tx.write_all` to UART hung.
+//! * **14** → full end-to-end firmware success. Hang is on the host side
+//!   of the UART (mux or wire).
+//! * **15** → TX errored somewhere along the way.
+//!
+//! # Building with the feature
+//!
+//! The `just` build/flash recipes pass a fixed feature list and don't
+//! surface an `extra-features` argument. To build a debug image:
+//!
+//! ```sh
+//! cd firmware
+//! . ~/export-esp.sh   # if building for xtensa (esp32s3)
+//! cargo +esp build --release \
+//!     --target xtensa-esp32s3-none-elf \
+//!     --features heltec_v3_uart,debug-checkpoint \
+//!     -Zbuild-std=core,alloc
+//! cp target/xtensa-esp32s3-none-elf/release/donglora \
+//!    builds/donglora-heltec_v3_uart-v$(sed -n 's/^version = "\(.*\)"/\1/p' \
+//!    Cargo.toml).elf
+//! espflash flash -p /dev/ttyUSB0 builds/donglora-heltec_v3_uart-v0.4.0.elf
+//! ```
+//!
+//! The normal `just flash heltec_v3_uart` command builds without the
+//! feature, so the debug code has zero footprint on release firmware.
+
+use core::sync::atomic::{AtomicBool, AtomicU8, Ordering};
+
+use embassy_executor::task;
+use embassy_time::{Duration, Timer};
+
+use crate::board::{LedDriver, RgbLed};
+
+/// Current diagnostic checkpoint — read by the blinker task. Zero means
+/// "no checkpoint set yet."
+///
+/// Write policy (see [`set`]): once a TX-phase value (6, 11, 12, 13) is
+/// stored, the latch engages and:
+/// * subsequent TX-phase writes update the value only if strictly deeper,
+/// * non-TX-phase writes (including the 7/10 terminal markers and the
+///   steady-state 4/5 post-TX writes) are **ignored** so the deepest phase
+///   reached on the FIRST TX attempt persists.
+///
+/// Rationale: a stuck-then-recovered TX attempt would normally flicker
+/// through the display too quickly to count. Latching preserves the
+/// evidence until reboot.
+pub static CHECKPOINT: AtomicU8 = AtomicU8::new(0);
+
+/// Has the TX-phase latch engaged yet? Written by [`set`], checked by
+/// [`set`]. Not intended for external inspection.
+static HAS_LATCHED: AtomicBool = AtomicBool::new(false);
+
+#[inline]
+fn is_host_phase(n: u8) -> bool {
+    // Values set only from `host_task` — meaningless before a TX has
+    // started, so we refuse to overwrite with them when the latch is
+    // not yet engaged.
+    n == 13 || n == 14
+}
+
+/// Ordered depth of each TX-related checkpoint. Returns `0` for values
+/// that are NOT TX phases (e.g. boot / steady-state / error indicators).
+///
+/// Value 18 ("next_command received CmdTransmit") is intentionally the
+/// SHALLOWEST TX phase — it fires before `perform_tx` entry (value 6)
+/// but is numerically higher because it was added last. The latch uses
+/// `phase_depth` rather than raw numeric comparison so 18 can engage
+/// the latch at depth 1 and later TX phases (6..=15) deepen over it.
+#[inline]
+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 (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
+    }
+}
+
+#[inline]
+fn is_tx_phase(n: u8) -> bool {
+    phase_depth(n) > 0
+}
+
+#[inline]
+fn is_tx_terminal(n: u8) -> bool {
+    n == 14 || n == 15
+}
+
+/// Record that we reached checkpoint `n`. A no-op in terms of visible
+/// behavior unless the blinker task is spawned; the store itself is very
+/// cheap so leaving these calls in non-debug builds is harmless.
+///
+/// Latch semantics:
+/// * `set(18)` (CmdTransmit received by `next_command`) or `set(6)`
+///   (entry to `perform_tx`) engage the latch.
+/// * While latched, only strictly-deeper TX phases (by `phase_depth`)
+///   update the checkpoint.
+/// * Terminal values (14 success, 15 error) freeze the latch until
+///   reboot.
+/// * Host-phase values (13, 14) called from `host_task` are ignored
+///   before the latch engages, so unrelated `Response::Ok` writes from
+///   SetConfig don't pollute the LED reading before any TX.
+#[inline]
+pub fn set(n: u8) {
+    if HAS_LATCHED.load(Ordering::Relaxed) {
+        let cur = CHECKPOINT.load(Ordering::Relaxed);
+        if is_tx_terminal(cur) {
+            return;
+        }
+        if phase_depth(n) > phase_depth(cur) {
+            CHECKPOINT.store(n, Ordering::Relaxed);
+        }
+        return;
+    }
+
+    // Latch not yet engaged.
+    if is_host_phase(n) {
+        // `host_task` is draining the response channel before any TX —
+        // these values would be misleading. Skip them.
+        return;
+    }
+
+    CHECKPOINT.store(n, Ordering::Relaxed);
+    if is_tx_phase(n) {
+        HAS_LATCHED.store(true, Ordering::Relaxed);
+    }
+}
+
+/// Dedicated task that continuously flashes the LED to show the current
+/// checkpoint. Owns the board's LED driver exclusively — on boards where
+/// the display task would normally own the LED for RX/TX blips, spawn
+/// *either* this task *or* `display_task`, not both.
+#[task]
+pub async fn debug_blink_task(mut led: LedDriver) {
+    // Start with the LED off so the first flash is unambiguous.
+    led.set_rgb(0, 0, 0).await;
+
+    loop {
+        let n = CHECKPOINT.load(Ordering::Relaxed);
+        if n == 0 {
+            // No checkpoint yet — wait and re-check.
+            Timer::after(Duration::from_millis(200)).await;
+            continue;
+        }
+        for _ in 0..n {
+            led.set_rgb(255, 255, 255).await;
+            Timer::after(Duration::from_millis(400)).await;
+            led.set_rgb(0, 0, 0).await;
+            Timer::after(Duration::from_millis(400)).await;
+        }
+        // Long pause to separate cycles so the human can count.
+        Timer::after(Duration::from_millis(2000)).await;
+    }
+}

src/display.rs

@@ -0,0 +1,977 @@
+//! OLED display dashboard, driven by a hsmc statechart.
+//!
+//! ```text
+//! Display
+//! ├── Off            display blank, LED off
+//! └── On
+//!     ├── Splash                         radio idle / no activity
+//!     │   ├── LearnMore   (default)      QR code + "donglora.com"
+//!     │   └── Info                       firmware version + MAC
+//!     └── Dashboard
+//!         ├── Listening   (default)      radio in RX
+//!         └── Transmitting               radio in TX
+//! ```
+//!
+//! The two Splash substates alternate on a 5 s timer via `on(after …)`
+//! transitions pointing at each other. No ticker, no timer task — hsmc
+//! handles the flip entirely inside the statechart.
+//!
+//! `CmdReset` (sent by the host task on USB disconnect) runs a reset
+//! action and re-enters `Splash`. This is order-idempotent with the
+//! `RadioIdle` that arrives from the radio at the same moment: whichever
+//! event the machine sees first, we end up in `Splash.LearnMore` with a
+//! fresh timer and a cleared run state.
+//!
+//! Display subscribes to [`RadioEventChannel`] (published by the radio task)
+//! and [`DisplayCommandChannel`] (published by the host task). Two trivial
+//! forwarder futures translate each source into [`DisplayEvent`]s on the
+//! machine's own channel — the machine is the single source of truth.
+
+use core::time::Duration;
+
+use embassy_executor::task;
+use embassy_futures::join::join3;
+use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
+use embassy_sync::channel::Channel;
+use embassy_time::Timer;
+use hsmc::statechart;
+
+use crate::board::{self, Board, DisplayDriver, DisplayParts, LedDriver, LoRaBoard, RgbLed};
+use crate::channel::{DisplayCommand, DisplayCommandChannel, RadioEvent, RadioEventChannel};
+use crate::driver::DisplayBrightness;
+use crate::protocol::LoRaConfig;
+
+use render::{BoardInfo, RSSI_HISTORY_LEN};
+
+const BOARD_NAME: &str = Board::NAME;
+const VERSION: &str = env!("CARGO_PKG_VERSION");
+
+/// 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;
+
+/// Which dashboard badge is in view (drives the RX/TX indicator only).
+#[derive(Debug, Clone, Copy)]
+pub enum Badge {
+    Rx,
+    Tx,
+}
+
+/// Fine-grained events driving the `Display` statechart.
+#[derive(Debug, Clone)]
+pub enum DisplayEvent {
+    CmdOn,
+    CmdOff,
+    CmdReset,
+    /// Radio moved into RX mode.
+    EnteredRx,
+    /// Radio moved into TX mode.
+    EnteredTx,
+    /// Radio returned to Idle.
+    RadioIdle,
+    /// A packet was received (data only — does not imply a mode change).
+    PacketRx {
+        rssi: i16,
+        snr: Option<i16>,
+    },
+    /// A packet was transmitted (data only — does not imply a mode change).
+    PacketTx,
+    ConfigChanged(LoRaConfig),
+}
+
+impl From<RadioEvent> for DisplayEvent {
+    fn from(ev: RadioEvent) -> Self {
+        match ev {
+            RadioEvent::EnteredRx => DisplayEvent::EnteredRx,
+            RadioEvent::EnteredTx => DisplayEvent::EnteredTx,
+            RadioEvent::Idle => DisplayEvent::RadioIdle,
+            RadioEvent::PacketRx { rssi, snr } => DisplayEvent::PacketRx { rssi, snr },
+            RadioEvent::PacketTx => DisplayEvent::PacketTx,
+            RadioEvent::ConfigChanged(cfg) => DisplayEvent::ConfigChanged(cfg),
+        }
+    }
+}
+
+static DISPLAY_EVENTS: Channel<CriticalSectionRawMutex, DisplayEvent, 8> = Channel::new();
+
+// ── Context ────────────────────────────────────────────────────────
+
+/// Peripherals the display task owns for its entire lifetime.
+struct Peripherals {
+    display: DisplayDriver,
+    led: LedDriver,
+    mac_str: heapless::String<18>,
+}
+
+/// Everything `CmdReset` should clear — the dashboard's "view" of the radio.
+struct RunState {
+    rssi_history: [i16; RSSI_HISTORY_LEN],
+    tx_history: [bool; RSSI_HISTORY_LEN],
+    rssi_count: usize,
+    current_slot_rssi: i16,
+    current_slot_tx: bool,
+    config: Option<LoRaConfig>,
+    rx_count: u32,
+    tx_count: u32,
+    last_rssi: Option<i16>,
+    last_snr: Option<i16>,
+}
+
+impl RunState {
+    fn new() -> Self {
+        Self {
+            rssi_history: [NO_SIGNAL; RSSI_HISTORY_LEN],
+            tx_history: [false; RSSI_HISTORY_LEN],
+            rssi_count: 0,
+            current_slot_rssi: NO_SIGNAL,
+            current_slot_tx: false,
+            config: None,
+            rx_count: 0,
+            tx_count: 0,
+            last_rssi: None,
+            last_snr: None,
+        }
+    }
+
+    fn record_rssi(&mut self, rssi: i16) {
+        if self.current_slot_rssi == NO_SIGNAL || rssi > self.current_slot_rssi {
+            self.current_slot_rssi = rssi;
+        }
+    }
+
+    fn advance_slot(&mut self) {
+        let idx = self.rssi_count % RSSI_HISTORY_LEN;
+        self.rssi_history[idx] = self.current_slot_rssi;
+        self.tx_history[idx] = self.current_slot_tx;
+        self.rssi_count += 1;
+        self.current_slot_rssi = NO_SIGNAL;
+        self.current_slot_tx = false;
+    }
+}
+
+pub struct DisplayContext {
+    peripherals: Peripherals,
+    run: RunState,
+}
+
+impl DisplayContext {
+    async fn flush_info(&mut self) {
+        let Peripherals {
+            display, mac_str, ..
+        } = &mut self.peripherals;
+        let info = BoardInfo {
+            name: BOARD_NAME,
+            version: VERSION,
+            mac: mac_str,
+        };
+        render::info(display, &info);
+        let _ = display.flush().await;
+    }
+
+    async fn flush_learn_more(&mut self) {
+        let display = &mut self.peripherals.display;
+        render::learn_more(display);
+        let _ = display.flush().await;
+    }
+
+    async fn flush_dashboard(&mut self, badge: Badge) {
+        let Peripherals {
+            display, mac_str, ..
+        } = &mut self.peripherals;
+        let info = BoardInfo {
+            name: BOARD_NAME,
+            version: VERSION,
+            mac: mac_str,
+        };
+        render::dashboard(
+            display,
+            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;
+    }
+
+    async fn flush_blank(&mut self) {
+        render::blank(&mut self.peripherals.display);
+        let _ = self.peripherals.display.flush().await;
+    }
+
+    // Boards without an LED use `LedDriver = ()`; the `RgbLed for ()` impl
+    // makes `set_rgb` a noop returning `()`. Clippy's unit_arg lint
+    // misreads method calls on unit values as "passing a unit value to a
+    // function" — silence it here where the noop is intentional.
+    #[allow(clippy::unit_arg)]
+    async fn led_off(&mut self) {
+        self.peripherals.led.set_rgb(0, 0, 0).await;
+    }
+
+    #[allow(clippy::unit_arg)]
+    async fn led_blip(&mut self, r: u8, g: u8, b: u8) {
+        self.peripherals.led.set_rgb(r, g, b).await;
+        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 ─────────────────────────────────────────────────────
+
+statechart! {
+    Display {
+        context: DisplayContext;
+        events: DisplayEvent;
+        default(On);
+
+        state Off {
+            entry: blank_display, turn_led_off;
+            on(CmdOn) => On;
+            // Stay off, but scrub any stale run state so reconnecting
+            // doesn't surface old counters/sparkline.
+            on(CmdReset) => reset_run_state;
+        }
+
+        state On {
+            default(Splash);
+            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 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;
+                    on(after Duration::from_secs(5)) => Info;
+                }
+
+                state Info {
+                    entry: paint_info;
+                    on(after Duration::from_secs(5)) => LearnMore;
+                }
+            }
+
+            // 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;
+
+                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;
+                    }
+                }
+            }
+        }
+    }
+}
+
+// ── Actions ────────────────────────────────────────────────────────
+
+/// Map SNR (dB) to LED brightness (4..64). Stronger signal = brighter.
+fn snr_brightness(snr: Option<i16>) -> u8 {
+    let snr = snr.unwrap_or(-10);
+    let clamped = snr.clamp(-20, 15) as i32;
+    ((clamped + 20) * 60 / 35 + 4) as u8
+}
+
+impl DisplayActions for DisplayActionContext<'_> {
+    async fn blank_display(&mut self) {
+        self.flush_blank().await;
+    }
+
+    async fn turn_led_off(&mut self) {
+        self.led_off().await;
+    }
+
+    async fn reset_run_state(&mut self) {
+        self.run = RunState::new();
+    }
+
+    async fn paint_info(&mut self) {
+        self.flush_info().await;
+    }
+
+    async fn paint_learn_more(&mut self) {
+        self.flush_learn_more().await;
+    }
+
+    async fn paint_listening(&mut self) {
+        self.flush_dashboard(Badge::Rx).await;
+    }
+
+    async fn paint_transmitting(&mut self) {
+        self.flush_dashboard(Badge::Tx).await;
+    }
+
+    async fn record_rx_packet(&mut self, rssi: i16, snr: Option<i16>) {
+        self.run.rx_count = self.run.rx_count.wrapping_add(1);
+        self.run.last_rssi = Some(rssi);
+        self.run.last_snr = snr;
+        self.run.record_rssi(rssi);
+    }
+
+    async fn record_tx_packet(&mut self) {
+        self.run.tx_count = self.run.tx_count.wrapping_add(1);
+        self.run.current_slot_tx = true;
+    }
+
+    async fn blink_rx_led(&mut self, _rssi: i16, snr: Option<i16>) {
+        let brightness = snr_brightness(snr);
+        self.led_blip(0, brightness, 0).await;
+    }
+
+    async fn blink_tx_led(&mut self) {
+        self.led_blip(32, 0, 0).await;
+    }
+
+    async fn save_new_config(&mut self, cfg: LoRaConfig) {
+        self.run.config = Some(cfg);
+    }
+
+    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 ───────────────────────────────────────────────
+
+#[task]
+pub async fn display_task(
+    parts: DisplayParts,
+    mut led: LedDriver,
+    radio_events: &'static RadioEventChannel,
+    display_commands: &'static DisplayCommandChannel,
+) {
+    let mut mac_str: heapless::String<18> = heapless::String::new();
+    let m = Board::mac_address();
+    let _ = core::fmt::Write::write_fmt(
+        &mut mac_str,
+        format_args!(
+            "{:02X}:{:02X}:{:02X}:{:02X}:{:02X}:{:02X}",
+            m[0], m[1], m[2], m[3], m[4], m[5]
+        ),
+    );
+
+    let Some(display) = board::create_display(parts.i2c).await else {
+        defmt::error!("display init failed, running LED-only loop");
+        loop {
+            match display_commands.receive().await {
+                DisplayCommand::Reset | DisplayCommand::Off => {
+                    led.set_rgb(0, 0, 0).await;
+                }
+                DisplayCommand::On => {}
+            }
+        }
+    };
+
+    let ctx = DisplayContext {
+        peripherals: Peripherals {
+            display,
+            led,
+            mac_str,
+        },
+        run: RunState::new(),
+    };
+
+    let mut machine = Display::new(ctx, &DISPLAY_EVENTS);
+    let sender = DisplaySender::from_channel(&DISPLAY_EVENTS);
+
+    let run = async {
+        let _ = machine.run().await;
+    };
+
+    let command_forwarder = async {
+        loop {
+            let ev = match display_commands.receive().await {
+                DisplayCommand::On => DisplayEvent::CmdOn,
+                DisplayCommand::Off => DisplayEvent::CmdOff,
+                DisplayCommand::Reset => DisplayEvent::CmdReset,
+            };
+            let _ = sender.send(ev).await;
+        }
+    };
+
+    let radio_event_forwarder = async {
+        loop {
+            let ev = radio_events.receive().await;
+            let _ = sender.send(ev.into()).await;
+        }
+    };
+
+    join3(run, command_forwarder, radio_event_forwarder).await;
+}
+
+// ── Rendering ──────────────────────────────────────────────────────
+
+mod render {
+    use core::fmt::Write;
+
+    use embedded_graphics::mono_font::ascii::{FONT_6X10, FONT_9X15_BOLD};
+    use embedded_graphics::mono_font::MonoTextStyle;
+    use embedded_graphics::pixelcolor::BinaryColor;
+    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::Badge;
+    use crate::protocol::{LoRaBandwidth, LoRaConfig};
+
+    pub const RSSI_HISTORY_LEN: usize = 128;
+
+    const CHAR_W: i32 = 6;
+    const FONT_H: i32 = 10;
+    const MODE_BOX_W: i32 = 2 * CHAR_W + 2;
+
+    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,
+    ) {
+        let bb = target.bounding_box();
+        let w = bb.size.width as i32;
+        let h = bb.size.height as i32;
+        let title_x = MODE_BOX_W + 1;
+        let title_w = w - title_x;
+        let header_h = 2 * FONT_H;
+        let sep1_y = header_h + 3;
+        let info_y = sep1_y + 1;
+        let sep2_y = info_y + 2 * FONT_H + 3;
+        let spark_top = sep2_y + 2;
+        let spark_h = h - spark_top;
+        let visible_bars = ((w / 2) as usize).min(RSSI_HISTORY_LEN);
+
+        let _ = target.clear(BinaryColor::Off);
+        let style = MonoTextStyle::new(&FONT_6X10, BinaryColor::On);
+        let mut buf: String<32> = String::new();
+
+        let fill = PrimitiveStyle::with_fill(BinaryColor::On);
+        let mut inv_style = MonoTextStyle::new(&FONT_6X10, BinaryColor::Off);
+        inv_style.set_background_color(Some(BinaryColor::On));
+
+        match badge {
+            Badge::Rx => {
+                Rectangle::new(
+                    Point::new(0, 0),
+                    Size::new(MODE_BOX_W as u32, FONT_H as u32),
+                )
+                .into_styled(fill)
+                .draw(target)
+                .ok();
+                Text::new("RX", Point::new(1, FONT_H - 1), inv_style)
+                    .draw(target)
+                    .ok();
+            }
+            Badge::Tx => {
+                Rectangle::new(
+                    Point::new(0, FONT_H),
+                    Size::new(MODE_BOX_W as u32, FONT_H as u32),
+                )
+                .into_styled(fill)
+                .draw(target)
+                .ok();
+                Text::new("TX", Point::new(1, 2 * FONT_H - 1), inv_style)
+                    .draw(target)
+                    .ok();
+            }
+        }
+
+        Line::new(Point::new(MODE_BOX_W, 0), Point::new(MODE_BOX_W, sep1_y))
+            .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
+            .draw(target)
+            .ok();
+
+        let title_center_x = title_x + title_w / 2;
+
+        buf.clear();
+        let _ = write!(buf, "DongLoRa v{}", board.version);
+        Text::with_alignment(
+            &buf,
+            Point::new(title_center_x, FONT_H - 1),
+            style,
+            Alignment::Center,
+        )
+        .draw(target)
+        .ok();
+
+        if let Some(cfg) = config {
+            buf.clear();
+            let freq_mhz = cfg.freq_hz / 1_000_000;
+            let freq_khz = (cfg.freq_hz % 1_000_000) / 1_000;
+            let bw_str = match cfg.bw {
+                LoRaBandwidth::Khz7 => "7.8",
+                LoRaBandwidth::Khz10 => "10.4",
+                LoRaBandwidth::Khz15 => "15.6",
+                LoRaBandwidth::Khz20 => "20.8",
+                LoRaBandwidth::Khz31 => "31.2",
+                LoRaBandwidth::Khz41 => "41.7",
+                LoRaBandwidth::Khz62 => "62.5",
+                LoRaBandwidth::Khz125 => "125",
+                LoRaBandwidth::Khz250 => "250",
+                LoRaBandwidth::Khz500 => "500",
+                LoRaBandwidth::Khz200 => "200",
+                LoRaBandwidth::Khz400 => "400",
+                LoRaBandwidth::Khz800 => "800",
+                LoRaBandwidth::Khz1600 => "1600",
+            };
+            // Show only the CR denominator; the "4/" numerator is implied for
+            // every LoRa coding rate and just clutters the line.
+            let cr_str = match cfg.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",
+            };
+            let _ = write!(
+                buf,
+                "{}.{:03}/{}/{}/{}",
+                freq_mhz, freq_khz, bw_str, cfg.sf, cr_str
+            );
+            Text::with_alignment(
+                &buf,
+                Point::new(title_center_x, 2 * FONT_H - 1),
+                style,
+                Alignment::Center,
+            )
+            .draw(target)
+            .ok();
+        }
+
+        Line::new(Point::new(0, sep1_y), Point::new(w - 1, sep1_y))
+            .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
+            .draw(target)
+            .ok();
+
+        let center_x = w / 2;
+
+        buf.clear();
+        let _ = write!(
+            buf,
+            "RX:{} TX:{}",
+            compact_count(rx_count),
+            compact_count(tx_count)
+        );
+        Text::with_alignment(
+            &buf,
+            Point::new(center_x, info_y + FONT_H - 1),
+            style,
+            Alignment::Center,
+        )
+        .draw(target)
+        .ok();
+
+        buf.clear();
+        match (last_rssi, last_snr) {
+            (Some(rssi), Some(snr)) => {
+                let _ = write!(buf, "RSSI:{}dBm SNR:{}dB", rssi, snr);
+            }
+            (Some(rssi), None) => {
+                let _ = write!(buf, "RSSI:{}dBm", rssi);
+            }
+            _ => {
+                let _ = write!(buf, "No signal");
+            }
+        }
+        Text::with_alignment(
+            &buf,
+            Point::new(center_x, info_y + 2 * FONT_H - 1),
+            style,
+            Alignment::Center,
+        )
+        .draw(target)
+        .ok();
+
+        Line::new(Point::new(0, sep2_y), Point::new(w - 1, sep2_y))
+            .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
+            .draw(target)
+            .ok();
+
+        if spark_h > 0 {
+            rssi_sparkline(
+                target,
+                rssi_history,
+                tx_history,
+                rssi_count,
+                current_slot_rssi,
+                current_slot_tx,
+                spark_top,
+                spark_h,
+                visible_bars,
+            );
+        }
+    }
+
+    pub fn info(target: &mut impl DrawTarget<Color = BinaryColor>, board: &BoardInfo) {
+        let bb = target.bounding_box();
+        let w = bb.size.width as i32;
+
+        let _ = target.clear(BinaryColor::Off);
+        let style = MonoTextStyle::new(&FONT_6X10, BinaryColor::On);
+        let title_style = MonoTextStyle::new(&FONT_9X15_BOLD, BinaryColor::On);
+        let mut buf: String<32> = String::new();
+
+        let center_x = w / 2;
+
+        Text::new("DongLoRa", Point::new(4, 15), title_style)
+            .draw(target)
+            .ok();
+        buf.clear();
+        let _ = write!(buf, "v{}", board.version);
+        Text::with_alignment(&buf, Point::new(w - 2, 15), style, Alignment::Right)
+            .draw(target)
+            .ok();
+
+        Text::with_alignment(
+            board.name,
+            Point::new(center_x, 28),
+            style,
+            Alignment::Center,
+        )
+        .draw(target)
+        .ok();
+
+        Text::with_alignment(
+            board.mac,
+            Point::new(center_x, 41),
+            style,
+            Alignment::Center,
+        )
+        .draw(target)
+        .ok();
+
+        Text::with_alignment(
+            "Waiting for host...",
+            Point::new(center_x, 54),
+            style,
+            Alignment::Center,
+        )
+        .draw(target)
+        .ok();
+    }
+
+    /// 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.
+    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};
+
+        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 ───
+        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();
+
+        // ── 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);
+
+        // Layout on a 64 px display:
+        //   blank
+        //   DongLoRa        baseline 22
+        //   blank
+        //   Learn more:     baseline 42
+        //   donglora.com    baseline 52
+        //   blank
+
+        Text::with_alignment(
+            "DongLoRa",
+            Point::new(col_center, 22),
+            title_style,
+            Alignment::Center,
+        )
+        .draw(target)
+        .ok();
+
+        Text::with_alignment(
+            "Learn more:",
+            Point::new(col_center, 42),
+            text_style,
+            Alignment::Center,
+        )
+        .draw(target)
+        .ok();
+
+        Text::with_alignment(
+            "donglora.com",
+            Point::new(col_center, 52),
+            text_style,
+            Alignment::Center,
+        )
+        .draw(target)
+        .ok();
+    }
+
+    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(
+        target: &mut impl DrawTarget<Color = BinaryColor>,
+        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;
+        }
+
+        let fill = PrimitiveStyle::with_fill(BinaryColor::On);
+
+        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, &fill);
+            }
+        }
+
+        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, &fill);
+            }
+        }
+    }
+
+    fn bar_height(rssi: i16, is_tx: bool, spark_h: i32) -> Option<i32> {
+        let h = if rssi <= RSSI_MIN {
+            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(
+        target: &mut impl DrawTarget<Color = BinaryColor>,
+        x: i32,
+        bar_h: i32,
+        is_tx: bool,
+        spark_top: i32,
+        spark_h: i32,
+        fill: &PrimitiveStyle<BinaryColor>,
+    ) {
+        let y = spark_top + spark_h - bar_h;
+        if is_tx {
+            for row in 0..bar_h {
+                if row % 2 == 0 {
+                    Rectangle::new(Point::new(x, y + row), Size::new(2, 1))
+                        .into_styled(*fill)
+                        .draw(target)
+                        .ok();
+                }
+            }
+        } else {
+            Rectangle::new(Point::new(x, y), Size::new(2, bar_h as u32))
+                .into_styled(*fill)
+                .draw(target)
+                .ok();
+        }
+    }
+
+    pub fn blank(target: &mut impl DrawTarget<Color = BinaryColor>) {
+        let _ = target.clear(BinaryColor::Off);
+    }
+}

src/display/mod.rs

@@ -1,5 +0,0 @@
-//! OLED display driver with radio status dashboard.
-
-mod render;
-mod task;
-pub use task::display_task;

src/display/render.rs

@@ -1,398 +0,0 @@
-use core::fmt::Write;
-
-use embedded_graphics::mono_font::ascii::{FONT_6X10, FONT_9X15_BOLD};
-use embedded_graphics::mono_font::MonoTextStyle;
-use embedded_graphics::pixelcolor::BinaryColor;
-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 crate::channel::{RadioState, RadioStatus};
-use crate::protocol::Bandwidth;
-
-/// RSSI ring buffer length — supports displays up to 256px wide (2px per bar).
-pub const RSSI_HISTORY_LEN: usize = 128;
-
-// Font metrics (FONT_6X10)
-const CHAR_W: i32 = 6;
-const FONT_H: i32 = 10;
-
-// Mode box: 2 chars + 1px padding each side
-const MODE_BOX_W: i32 = 2 * CHAR_W + 2; // 14px
-
-// RSSI mapping range (dBm)
-const RSSI_MIN: i16 = -120;
-const RSSI_MAX: i16 = 0;
-
-/// Static board identity info for display rendering.
-pub struct BoardInfo<'a> {
-    pub name: &'a str,
-    pub version: &'a str,
-    pub mac: &'a str,
-}
-
-/// Render the active dashboard (shown when radio is in RX or TX mode).
-pub fn dashboard(
-    target: &mut impl DrawTarget<Color = BinaryColor>,
-    status: &RadioStatus,
-    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,
-) {
-    let bb = target.bounding_box();
-    let w = bb.size.width as i32;
-    let h = bb.size.height as i32;
-    let title_x = MODE_BOX_W + 1;
-    let title_w = w - title_x;
-    let header_h = 2 * FONT_H;
-    let sep1_y = header_h + 3; // 3px gap below header text (clears descenders)
-    let info_y = sep1_y + 1; // 1px line, info text tight below separator
-    let sep2_y = info_y + 2 * FONT_H + 3; // 3px gap below info text (clears descenders)
-    let spark_top = sep2_y + 2; // 1px line + 1px gap above graph
-    let spark_h = h - spark_top;
-    let visible_bars = ((w / 2) as usize).min(RSSI_HISTORY_LEN);
-
-    let _ = target.clear(BinaryColor::Off);
-    let style = MonoTextStyle::new(&FONT_6X10, BinaryColor::On);
-    let mut buf: String<32> = String::new();
-
-    // ── Mode box (left column, 2 rows tall) ─────────────────────────
-    let fill = PrimitiveStyle::with_fill(BinaryColor::On);
-    let mut inv_style = MonoTextStyle::new(&FONT_6X10, BinaryColor::Off);
-    inv_style.set_background_color(Some(BinaryColor::On));
-
-    match status.state {
-        RadioState::Receiving => {
-            // "RX" inverted on row 0
-            Rectangle::new(Point::new(0, 0), Size::new(MODE_BOX_W as u32, FONT_H as u32))
-                .into_styled(fill)
-                .draw(target)
-                .ok();
-            Text::new("RX", Point::new(1, FONT_H - 1), inv_style)
-                .draw(target)
-                .ok();
-        }
-        RadioState::Transmitting => {
-            // "TX" inverted on row 1
-            Rectangle::new(
-                Point::new(0, FONT_H),
-                Size::new(MODE_BOX_W as u32, FONT_H as u32),
-            )
-            .into_styled(fill)
-            .draw(target)
-            .ok();
-            Text::new("TX", Point::new(1, 2 * FONT_H - 1), inv_style)
-                .draw(target)
-                .ok();
-        }
-        RadioState::Idle => {} // Not shown on active screen
-    }
-
-    // Vertical separator between mode box and title box
-    Line::new(Point::new(MODE_BOX_W, 0), Point::new(MODE_BOX_W, sep1_y))
-        .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
-        .draw(target)
-        .ok();
-
-    // ── Title box (right of mode box) ───────────────────────────────
-    let title_center_x = title_x + title_w / 2;
-
-    // Row 0: "DongLoRa v{version}"
-    buf.clear();
-    let _ = write!(buf, "DongLoRa v{}", board.version);
-    Text::with_alignment(
-        &buf,
-        Point::new(title_center_x, FONT_H - 1),
-        style,
-        Alignment::Center,
-    )
-    .draw(target)
-    .ok();
-
-    // Row 1: radio settings "{freq}/{bw}/{sf}/{cr}"
-    if let Some(cfg) = status.config {
-        buf.clear();
-        let freq_mhz = cfg.freq_hz / 1_000_000;
-        let freq_khz = (cfg.freq_hz % 1_000_000) / 1_000;
-        let bw_str = match cfg.bw {
-            Bandwidth::Khz7 => "7.8",
-            Bandwidth::Khz10 => "10.4",
-            Bandwidth::Khz15 => "15.6",
-            Bandwidth::Khz20 => "20.8",
-            Bandwidth::Khz31 => "31.2",
-            Bandwidth::Khz41 => "41.7",
-            Bandwidth::Khz62 => "62.5",
-            Bandwidth::Khz125 => "125",
-            Bandwidth::Khz250 => "250",
-            Bandwidth::Khz500 => "500",
-        };
-        let _ = write!(
-            buf,
-            "{}.{:03}/{}/{}/{}",
-            freq_mhz, freq_khz, bw_str, cfg.sf, cfg.cr
-        );
-        Text::with_alignment(
-            &buf,
-            Point::new(title_center_x, 2 * FONT_H - 1),
-            style,
-            Alignment::Center,
-        )
-        .draw(target)
-        .ok();
-    }
-
-    // ── First separator line ────────────────────────────────────────
-    Line::new(Point::new(0, sep1_y), Point::new(w - 1, sep1_y))
-        .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
-        .draw(target)
-        .ok();
-
-    // ── Info rows (centered) ────────────────────────────────────────
-    let center_x = w / 2;
-
-    // Row 2: packet counters
-    buf.clear();
-    let _ = write!(
-        buf,
-        "RX:{} TX:{}",
-        compact_count(status.rx_count),
-        compact_count(status.tx_count)
-    );
-    Text::with_alignment(
-        &buf,
-        Point::new(center_x, info_y + FONT_H - 1),
-        style,
-        Alignment::Center,
-    )
-    .draw(target)
-    .ok();
-
-    // Row 3: RSSI + SNR
-    buf.clear();
-    match (status.last_rssi, status.last_snr) {
-        (Some(rssi), Some(snr)) => {
-            let _ = write!(buf, "RSSI:{}dBm SNR:{}dB", rssi, snr);
-        }
-        (Some(rssi), None) => {
-            let _ = write!(buf, "RSSI:{}dBm", rssi);
-        }
-        _ => {
-            let _ = write!(buf, "No signal");
-        }
-    }
-    Text::with_alignment(
-        &buf,
-        Point::new(center_x, info_y + 2 * FONT_H - 1),
-        style,
-        Alignment::Center,
-    )
-    .draw(target)
-    .ok();
-
-    // ── Second separator line ───────────────────────────────────────
-    Line::new(Point::new(0, sep2_y), Point::new(w - 1, sep2_y))
-        .into_styled(PrimitiveStyle::with_stroke(BinaryColor::On, 1))
-        .draw(target)
-        .ok();
-
-    // ── Sparkline bar graph ─────────────────────────────────────────
-    if spark_h > 0 {
-        rssi_sparkline(
-            target,
-            rssi_history,
-            tx_history,
-            rssi_count,
-            current_slot_rssi,
-            current_slot_tx,
-            spark_top,
-            spark_h,
-            visible_bars,
-        );
-    }
-}
-
-/// Render the splash/waiting screen (shown when idle or no config).
-pub fn splash(
-    target: &mut impl DrawTarget<Color = BinaryColor>,
-    board: &BoardInfo,
-) {
-    let bb = target.bounding_box();
-    let w = bb.size.width as i32;
-
-    let _ = target.clear(BinaryColor::Off);
-    let style = MonoTextStyle::new(&FONT_6X10, BinaryColor::On);
-    let title_style = MonoTextStyle::new(&FONT_9X15_BOLD, BinaryColor::On);
-    let mut buf: String<32> = String::new();
-
-    let center_x = w / 2;
-
-    // Row 1: "DongLoRa" bold left, version small right
-    Text::new("DongLoRa", Point::new(4, 15), title_style)
-        .draw(target)
-        .ok();
-    buf.clear();
-    let _ = write!(buf, "v{}", board.version);
-    Text::with_alignment(&buf, Point::new(w - 2, 15), style, Alignment::Right)
-        .draw(target)
-        .ok();
-
-    // Row 2: board name
-    Text::with_alignment(
-        board.name,
-        Point::new(center_x, 28),
-        style,
-        Alignment::Center,
-    )
-    .draw(target)
-    .ok();
-
-    // Row 3: MAC address
-    Text::with_alignment(
-        board.mac,
-        Point::new(center_x, 41),
-        style,
-        Alignment::Center,
-    )
-    .draw(target)
-    .ok();
-
-    // Row 4: status
-    Text::with_alignment(
-        "Waiting for host...",
-        Point::new(center_x, 54),
-        style,
-        Alignment::Center,
-    )
-    .draw(target)
-    .ok();
-}
-
-/// Format a u32 count compactly for display.
-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
-}
-
-/// Render the RSSI history as a bar-chart sparkline.
-///
-/// The current (uncommitted) slot is rendered at the rightmost position
-/// so that incoming packets appear on the graph immediately.
-fn rssi_sparkline(
-    target: &mut impl DrawTarget<Color = BinaryColor>,
-    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;
-    }
-
-    let fill = PrimitiveStyle::with_fill(BinaryColor::On);
-
-    // Draw committed history
-    for i in 0..hist_slots {
-        let idx = if count <= RSSI_HISTORY_LEN {
-            // Buffer hasn't wrapped: slots occupy indices 0..committed-1.
-            // Skip oldest entries that don't fit on screen.
-            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, &fill);
-        }
-    }
-
-    // Draw live (current) bar at the rightmost position
-    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, &fill);
-        }
-    }
-}
-
-/// Compute the pixel height for a sparkline bar, or None to skip.
-fn bar_height(rssi: i16, is_tx: bool, spark_h: i32) -> Option<i32> {
-    let h = if rssi <= RSSI_MIN {
-        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) }
-}
-
-/// Draw a single sparkline bar (solid for RX, dotted for TX).
-fn draw_bar(
-    target: &mut impl DrawTarget<Color = BinaryColor>,
-    x: i32,
-    bar_h: i32,
-    is_tx: bool,
-    spark_top: i32,
-    spark_h: i32,
-    fill: &PrimitiveStyle<BinaryColor>,
-) {
-    let y = spark_top + spark_h - bar_h;
-    if is_tx {
-        for row in 0..bar_h {
-            if row % 2 == 0 {
-                Rectangle::new(Point::new(x, y + row), Size::new(2, 1))
-                    .into_styled(*fill)
-                    .draw(target)
-                    .ok();
-            }
-        }
-    } else {
-        Rectangle::new(Point::new(x, y), Size::new(2, bar_h as u32))
-            .into_styled(*fill)
-            .draw(target)
-            .ok();
-    }
-}
-
-/// Clear the display (display-off state).
-pub fn blank(target: &mut impl DrawTarget<Color = BinaryColor>) {
-    let _ = target.clear(BinaryColor::Off);
-}

src/display/task.rs

@@ -1,239 +0,0 @@
-use embassy_executor::task;
-use embassy_futures::select::{select3, Either3};
-use embassy_time::Timer;
-use ssd1306::mode::DisplayConfigAsync;
-use ssd1306::prelude::DisplayRotation;
-use ssd1306::size::DisplaySize128x64;
-use ssd1306::{I2CDisplayInterface, Ssd1306Async};
-
-use crate::board::DisplayParts;
-use crate::channel::{
-    DisplayCommand, DisplayCommandChannel, RadioState, RadioStatus, StatusWatch,
-};
-
-use crate::board::{Board, LoRaBoard};
-
-use super::render::{self, RSSI_HISTORY_LEN};
-
-const BOARD_NAME: &str = Board::NAME;
-
-/// Duration per sparkline slot. 128 slots * 1s = ~2 minutes of history.
-const SPARK_SLOT_MS: u64 = 1000;
-
-/// 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;
-
-struct DisplayState {
-    rssi_history: [i16; RSSI_HISTORY_LEN],
-    tx_history: [bool; RSSI_HISTORY_LEN],
-    rssi_count: usize,
-    current_slot_rssi: i16,
-    current_slot_tx: bool,
-    display_on: bool,
-    disconnected: bool,
-    last_status: RadioStatus,
-}
-
-impl DisplayState {
-    fn new() -> Self {
-        Self {
-            rssi_history: [NO_SIGNAL; RSSI_HISTORY_LEN],
-            tx_history: [false; RSSI_HISTORY_LEN],
-            rssi_count: 0,
-            current_slot_rssi: NO_SIGNAL,
-            current_slot_tx: false,
-            display_on: true,
-            disconnected: true,
-            last_status: RadioStatus::default(),
-        }
-    }
-
-    /// Record an RSSI sample in the current time slot (keep best).
-    fn record_rssi(&mut self, rssi: i16) {
-        if self.current_slot_rssi == NO_SIGNAL || rssi > self.current_slot_rssi {
-            self.current_slot_rssi = rssi;
-        }
-    }
-
-    /// Mark the current time slot as having a transmit.
-    fn record_tx(&mut self) {
-        self.current_slot_tx = true;
-    }
-
-    /// Advance to the next time slot, committing the current slot's data.
-    fn advance_slot(&mut self) {
-        let idx = self.rssi_count % RSSI_HISTORY_LEN;
-        self.rssi_history[idx] = self.current_slot_rssi;
-        self.tx_history[idx] = self.current_slot_tx;
-        self.rssi_count += 1;
-        self.current_slot_rssi = NO_SIGNAL;
-        self.current_slot_tx = false;
-    }
-
-    /// Whether the active dashboard should be shown (RX or TX mode).
-    fn is_active(&self) -> bool {
-        matches!(
-            self.last_status.state,
-            RadioState::Receiving | RadioState::Transmitting
-        )
-    }
-}
-
-#[task]
-pub async fn display_task(
-    parts: DisplayParts,
-    status: &'static StatusWatch,
-    display_commands: &'static DisplayCommandChannel,
-) {
-    // Format MAC address as "XX:XX:XX:XX:XX:XX"
-    let mut mac_str: heapless::String<18> = heapless::String::new();
-    let m = parts.mac;
-    let _ = core::fmt::Write::write_fmt(
-        &mut mac_str,
-        format_args!(
-            "{:02X}:{:02X}:{:02X}:{:02X}:{:02X}:{:02X}",
-            m[0], m[1], m[2], m[3], m[4], m[5]
-        ),
-    );
-
-    let board_info = render::BoardInfo {
-        name: BOARD_NAME,
-        version: env!("CARGO_PKG_VERSION"),
-        mac: &mac_str,
-    };
-
-    let interface = I2CDisplayInterface::new(parts.i2c);
-    let mut display = Ssd1306Async::new(interface, DisplaySize128x64, DisplayRotation::Rotate0)
-        .into_buffered_graphics_mode();
-
-    if display.init().await.is_err() {
-        defmt::error!("SSD1306 init failed");
-        return;
-    }
-    if display
-        .set_brightness(ssd1306::prelude::Brightness::BRIGHTEST)
-        .await
-        .is_err()
-    {
-        defmt::warn!("display brightness set failed");
-    }
-
-    let mut state = DisplayState::new();
-    let Some(mut receiver) = status.receiver() else {
-        defmt::error!("no watch receiver available for display");
-        return;
-    };
-
-    // Show splash/waiting screen
-    render_splash(&mut display, &board_info).await;
-
-    loop {
-        match select3(
-            receiver.changed(),
-            display_commands.receive(),
-            Timer::after_millis(SPARK_SLOT_MS),
-        )
-        .await
-        {
-            Either3::First(radio_status) => {
-                if state.disconnected {
-                    continue;
-                }
-                if let Some(rssi) = radio_status.last_rssi {
-                    if radio_status.rx_count != state.last_status.rx_count {
-                        state.record_rssi(rssi);
-                    }
-                }
-                if radio_status.tx_count != state.last_status.tx_count {
-                    state.record_tx();
-                }
-                state.last_status = radio_status;
-
-                if state.display_on {
-                    render_current(&mut display, &state, &board_info).await;
-                }
-            }
-            Either3::Second(cmd) => match cmd {
-                DisplayCommand::Off => {
-                    state.disconnected = false;
-                    state.display_on = false;
-                    render::blank(&mut display);
-                    let _ = display.flush().await;
-                }
-                DisplayCommand::On => {
-                    state.disconnected = false;
-                    state.display_on = true;
-                    if let Some(s) = receiver.try_get() {
-                        state.last_status = s;
-                    }
-                    render_current(&mut display, &state, &board_info).await;
-                }
-                DisplayCommand::Reset => {
-                    state = DisplayState::new();
-                    render_splash(&mut display, &board_info).await;
-                }
-            },
-            Either3::Third(()) => {
-                // Timer tick: advance sparkline slot
-                state.advance_slot();
-                if state.display_on && state.is_active() {
-                    render_dashboard(&mut display, &state, &board_info).await;
-                }
-            }
-        }
-    }
-}
-
-// The concrete display type is verbose but avoids making this generic
-// over both DrawTarget and the SSD1306-specific flush method.
-type Display<I> = ssd1306::Ssd1306Async<
-    I,
-    DisplaySize128x64,
-    ssd1306::mode::BufferedGraphicsModeAsync<DisplaySize128x64>,
->;
-
-/// Render the appropriate screen (active dashboard or splash) and flush.
-async fn render_current<I>(
-    display: &mut Display<I>,
-    state: &DisplayState,
-    board: &render::BoardInfo<'_>,
-) where
-    I: display_interface::AsyncWriteOnlyDataCommand,
-{
-    if state.is_active() {
-        render_dashboard(display, state, board).await;
-    } else {
-        render_splash(display, board).await;
-    }
-}
-
-/// Render the active dashboard and flush.
-async fn render_dashboard<I>(
-    display: &mut Display<I>,
-    state: &DisplayState,
-    board: &render::BoardInfo<'_>,
-) where
-    I: display_interface::AsyncWriteOnlyDataCommand,
-{
-    render::dashboard(
-        display,
-        &state.last_status,
-        &state.rssi_history,
-        &state.tx_history,
-        state.rssi_count,
-        state.current_slot_rssi,
-        state.current_slot_tx,
-        board,
-    );
-    let _ = display.flush().await;
-}
-
-/// Render the splash/waiting screen and flush.
-async fn render_splash<I>(display: &mut Display<I>, board: &render::BoardInfo<'_>)
-where
-    I: display_interface::AsyncWriteOnlyDataCommand,
-{
-    render::splash(display, board);
-    let _ = display.flush().await;
-}

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

@@ -0,0 +1,82 @@
+#[cfg(any(
+    feature = "wio_tracker_l1",
+    feature = "elecrow_thinknode_m2",
+    feature = "lilygo_tbeam_supreme"
+))]
+pub mod sh1106;
+
+#[cfg(any(feature = "lilygo_tbeam_supreme", feature = "lilygo_tbeam"))]
+pub mod axp;
+
+#[cfg(feature = "lilygo_tbeam")]
+pub mod inverted_pin;
+
+#[cfg(any(
+    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"
+))]
+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

@@ -0,0 +1,131 @@
+//! Minimal async SH1106 I2C OLED driver (128x64, page addressing).
+//!
+//! The SH1106 is very similar to the SSD1306 but only supports page-mode
+//! addressing (no horizontal/vertical auto-advance). This driver sends
+//! framebuffer data page-by-page with explicit page/column commands.
+
+use embedded_graphics::draw_target::DrawTarget;
+use embedded_graphics::geometry::{OriginDimensions, Size};
+use embedded_graphics::pixelcolor::BinaryColor;
+use embedded_graphics::Pixel;
+use embedded_hal_async::i2c::I2c;
+
+const WIDTH: usize = 128;
+const HEIGHT: usize = 64;
+const PAGES: usize = HEIGHT / 8;
+const BUF_SIZE: usize = WIDTH * PAGES; // 1024
+
+/// SH1106 has a 132-column RAM; visible 128 columns are centered with a
+/// 2-column offset on each side.
+const COL_OFFSET: u8 = 2;
+
+pub struct Sh1106<I> {
+    i2c: I,
+    addr: u8,
+    buffer: [u8; BUF_SIZE],
+}
+
+impl<I: I2c> Sh1106<I> {
+    pub fn new(i2c: I, addr: u8) -> Self {
+        Self {
+            i2c,
+            addr,
+            buffer: [0u8; BUF_SIZE],
+        }
+    }
+
+    /// 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 {
+            self.i2c.write(self.addr, &[0x00, c]).await?;
+        }
+        Ok(())
+    }
+
+    /// Initialize the display with sensible defaults.
+    pub async fn init(&mut self) -> Result<(), I::Error> {
+        self.cmd(&[
+            0xAE, // display off
+            0xD5, 0x80, // clock div: default
+            0xA8, 0x3F, // multiplex ratio: 64
+            0xD3, 0x00, // display offset: 0
+            0x40, // start line: 0
+            0x8D, 0x14, // charge pump: enable
+            0xA1, // segment remap: column 127 mapped to SEG0
+            0xC8, // COM scan direction: remapped
+            0xDA, 0x12, // COM pin config: alternative, no L/R remap
+            0x81, 0xCF, // contrast: 207
+            0xD9, 0xF1, // pre-charge: phase1=1, phase2=15
+            0xDB, 0x40, // VCOMH deselect: ~0.77×Vcc
+            0xA4, // entire display ON (follow RAM)
+            0xA6, // normal display (not inverted)
+            0xAF, // display on
+        ])
+        .await
+    }
+
+    /// Flush the entire framebuffer to the display, page by page.
+    pub async fn flush(&mut self) -> Result<(), I::Error> {
+        // Each I2C data write is prefixed with 0x40 (data continuation byte).
+        let mut page_buf = [0u8; 1 + WIDTH]; // 0x40 + 128 data bytes
+        page_buf[0] = 0x40;
+
+        for page in 0..PAGES {
+            // Set page address and column start (with SH1106 2-column offset).
+            self.cmd(&[
+                0xB0 | page as u8,        // page address
+                COL_OFFSET & 0x0F,        // column low nibble
+                0x10 | (COL_OFFSET >> 4), // column high nibble
+            ])
+            .await?;
+
+            let start = page * WIDTH;
+            page_buf[1..].copy_from_slice(&self.buffer[start..start + WIDTH]);
+            self.i2c.write(self.addr, &page_buf).await?;
+        }
+        Ok(())
+    }
+
+    /// Set display brightness (contrast).
+    pub async fn set_brightness(&mut self, value: u8) -> Result<(), I::Error> {
+        self.cmd(&[0x81, value]).await
+    }
+}
+
+impl<I: I2c> DrawTarget for Sh1106<I> {
+    type Color = BinaryColor;
+    type Error = core::convert::Infallible;
+
+    fn draw_iter<T>(&mut self, pixels: T) -> Result<(), Self::Error>
+    where
+        T: IntoIterator<Item = Pixel<Self::Color>>,
+    {
+        for Pixel(pos, color) in pixels {
+            let x = pos.x;
+            let y = pos.y;
+            if x >= 0 && x < WIDTH as i32 && y >= 0 && y < HEIGHT as i32 {
+                let x = x as usize;
+                let y = y as usize;
+                let idx = (y / 8) * WIDTH + x;
+                let bit = (y % 8) as u8;
+                if color.is_on() {
+                    self.buffer[idx] |= 1 << bit;
+                } else {
+                    self.buffer[idx] &= !(1 << bit);
+                }
+            }
+        }
+        Ok(())
+    }
+
+    fn clear(&mut self, color: Self::Color) -> Result<(), Self::Error> {
+        self.buffer.fill(if color.is_on() { 0xFF } else { 0x00 });
+        Ok(())
+    }
+}
+
+impl<I: I2c> OriginDimensions for Sh1106<I> {
+    fn size(&self) -> Size {
+        Size::new(WIDTH as u32, HEIGHT as u32)
+    }
+}

src/driver/simple_led.rs

@@ -0,0 +1,20 @@
+//! Simple single-color LED driver (GPIO on/off).
+//!
+//! Generic over any `OutputPin`. Any non-zero RGB value turns the LED on;
+//! all zeros turns it off.
+
+use embedded_hal::digital::OutputPin;
+
+use crate::board::RgbLed;
+
+pub struct SimpleLed<P>(pub P);
+
+impl<P: OutputPin> RgbLed for SimpleLed<P> {
+    async fn set_rgb(&mut self, r: u8, g: u8, b: u8) {
+        if r > 0 || g > 0 || b > 0 {
+            let _ = self.0.set_high();
+        } else {
+            let _ = self.0.set_low();
+        }
+    }
+}

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/esp32s3.rs

@@ -0,0 +1,97 @@
+//! ESP32-S3 MCU initialization primitives.
+//!
+//! Provides low-level bus init for ESP32-S3 boards.
+//! Board files call these with specific pins and construct higher-level
+//! drivers (Sx126x, SSD1306, USB, UART, etc.) themselves.
+
+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::{Config as I2cConfig, 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 DMA and wrap in a shared bus (StaticCell + Mutex).
+///
+/// Generic over pin type so boards with different SPI pin assignments can
+/// share this helper. Any GPIO that implements the esp-hal interconnect
+/// traits (which is every GPIO on the ESP32-S3) can be passed directly.
+pub fn init_spi(
+    spi2: esp_hal::peripherals::SPI2<'static>,
+    dma_ch0: esp_hal::peripherals::DMA_CH0<'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_ch0);
+
+    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))
+}
+
+// ── I2C bus ─────────────────────────────────────────────────────────
+
+/// Initialize I2C0 for peripherals (display, sensors, etc.).
+///
+/// Generic over pin type. I2C lines are bidirectional (open-drain), so both
+/// `PeripheralInput` and `PeripheralOutput` bounds are required.
+pub fn init_i2c(
+    i2c0: esp_hal::peripherals::I2C0<'static>,
+    sda: impl PeripheralInput<'static> + PeripheralOutput<'static>,
+    scl: impl PeripheralInput<'static> + PeripheralOutput<'static>,
+) -> I2cBus {
+    I2c::new(i2c0, I2cConfig::default())
+        .expect("I2C init")
+        .with_sda(sda)
+        .with_scl(scl)
+        .into_async()
+}
+
+// ── 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

@@ -0,0 +1,22 @@
+//! MCU family initialization primitives.
+//!
+//! Each submodule provides low-level bus and peripheral init for one MCU family.
+//! Board files call these with specific pins and construct higher-level drivers.
+
+#[cfg(any(
+    feature = "heltec_v3",
+    feature = "heltec_v3_uart",
+    feature = "heltec_v4",
+    feature = "elecrow_thinknode_m2",
+    feature = "lilygo_tbeam_supreme"
+))]
+pub mod esp32s3;
+
+#[cfg(feature = "lilygo_tbeam")]
+pub mod esp32;
+
+#[cfg(any(feature = "rak_wisblock_4631", feature = "wio_tracker_l1"))]
+pub mod nrf52840;
+
+#[cfg(feature = "waveshare_rp2040_lora")]
+pub mod rp2040;

src/hal/nrf52840.rs

@@ -0,0 +1,80 @@
+//! nRF52840 MCU initialization primitives.
+//!
+//! Provides shared boilerplate for nRF52840 boards: interrupt bindings,
+//! type aliases, StaticCell bus wrapping, USB init, and MAC address reading.
+
+use embassy_nrf::bind_interrupts;
+use embassy_sync::blocking_mutex::raw::NoopRawMutex;
+use static_cell::StaticCell;
+
+// ── Interrupts (shared by all nRF52840 boards) ─────────────────────
+
+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>;
+});
+
+// ── MCU-level types ─────────────────────────────────────────────────
+
+pub type SpiBus = embassy_nrf::spim::Spim<'static>;
+pub type I2cBus = embassy_nrf::twim::Twim<'static>;
+pub type UsbNrfDriver =
+    embassy_nrf::usb::Driver<'static, &'static embassy_nrf::usb::vbus_detect::SoftwareVbusDetect>;
+
+// ── SPI bus sharing ─────────────────────────────────────────────────
+
+/// Wrap an initialized SPI peripheral in a shared bus (StaticCell + Mutex).
+pub fn share_spi_bus(spi: SpiBus) -> &'static embassy_sync::mutex::Mutex<NoopRawMutex, SpiBus> {
+    static SPI_BUS: StaticCell<embassy_sync::mutex::Mutex<NoopRawMutex, SpiBus>> =
+        StaticCell::new();
+    SPI_BUS.init(embassy_sync::mutex::Mutex::new(spi))
+}
+
+// ── I2C DMA buffer ──────────────────────────────────────────────────
+
+/// Allocate a DMA-safe buffer for Twim I2C.
+///
+/// Every nRF52840 Twim user needs a `&'static mut [u8]` buffer.
+/// This provides one via StaticCell so board files don't repeat the pattern.
+pub fn alloc_i2c_buffer() -> &'static mut [u8; 256] {
+    static TWIM_BUF: StaticCell<[u8; 256]> = StaticCell::new();
+    TWIM_BUF.init([0u8; 256])
+}
+
+// ── USB VBUS detection ──────────────────────────────────────────────
+
+/// Allocate and initialize software VBUS detection.
+pub fn alloc_vbus_detect(
+    vbus_detect: bool,
+    self_powered: bool,
+) -> &'static embassy_nrf::usb::vbus_detect::SoftwareVbusDetect {
+    static VBUS: StaticCell<embassy_nrf::usb::vbus_detect::SoftwareVbusDetect> = StaticCell::new();
+    VBUS.init(embassy_nrf::usb::vbus_detect::SoftwareVbusDetect::new(
+        vbus_detect,
+        self_powered,
+    ))
+}
+
+// ── MAC address ─────────────────────────────────────────────────────
+
+/// Read the factory-programmed device address from FICR registers.
+pub fn mac_address() -> [u8; 6] {
+    // SAFETY: 0x10000000 is the nRF52840 FICR (Factory Information Configuration
+    // Registers) base address. Offsets 0x0A4 and 0x0A8 are the DEVICEADDR[0] and
+    // DEVICEADDR[1] registers containing the factory-programmed device address.
+    // read_volatile is correct for memory-mapped hardware registers.
+    unsafe {
+        let ficr = 0x10000000 as *const u32;
+        let addr0 = core::ptr::read_volatile(ficr.byte_add(0x0A4));
+        let addr1 = core::ptr::read_volatile(ficr.byte_add(0x0A8));
+        [
+            addr0 as u8,
+            (addr0 >> 8) as u8,
+            (addr0 >> 16) as u8,
+            (addr0 >> 24) as u8,
+            addr1 as u8,
+            (addr1 >> 8) as u8,
+        ]
+    }
+}

src/hal/rp2040.rs

@@ -0,0 +1,80 @@
+//! RP2040 MCU initialization primitives.
+//!
+//! Provides shared boilerplate for RP2040 boards: interrupt bindings,
+//! type aliases, StaticCell bus wrapping, USB init, and MAC address reading.
+
+use embassy_rp::bind_interrupts;
+use embassy_sync::blocking_mutex::raw::NoopRawMutex;
+use static_cell::StaticCell;
+
+// ── Interrupts (shared by all RP2040 boards) ──────────────────────
+
+bind_interrupts!(pub struct Irqs {
+    USBCTRL_IRQ => embassy_rp::usb::InterruptHandler<embassy_rp::peripherals::USB>;
+    DMA_IRQ_0 => embassy_rp::dma::InterruptHandler<embassy_rp::peripherals::DMA_CH0>,
+        embassy_rp::dma::InterruptHandler<embassy_rp::peripherals::DMA_CH1>;
+});
+
+// ── MCU-level types ────────────────────────────────────────────────
+
+pub type SpiBus =
+    embassy_rp::spi::Spi<'static, embassy_rp::peripherals::SPI1, embassy_rp::spi::Async>;
+pub type UsbRpDriver = embassy_rp::usb::Driver<'static, embassy_rp::peripherals::USB>;
+
+// ── SPI bus sharing ────────────────────────────────────────────────
+
+/// Wrap an initialized SPI peripheral in a shared bus (StaticCell + Mutex).
+pub fn share_spi_bus(spi: SpiBus) -> &'static embassy_sync::mutex::Mutex<NoopRawMutex, SpiBus> {
+    static SPI_BUS: StaticCell<embassy_sync::mutex::Mutex<NoopRawMutex, SpiBus>> =
+        StaticCell::new();
+    SPI_BUS.init(embassy_sync::mutex::Mutex::new(spi))
+}
+
+// ── MAC address ────────────────────────────────────────────────────
+
+/// Store for the MAC address derived from flash unique ID.
+/// Populated once during `init_mac()`, read by `mac_address()`.
+static MAC: StaticCell<[u8; 6]> = StaticCell::new();
+static mut MAC_REF: Option<&'static [u8; 6]> = None;
+
+/// Read the flash chip's unique ID and derive a 6-byte MAC address.
+///
+/// Must be called once during board init before `mac_address()`.
+pub fn init_mac<const FLASH_SIZE: usize>(
+    flash: &mut embassy_rp::flash::Flash<
+        '_,
+        embassy_rp::peripherals::FLASH,
+        embassy_rp::flash::Blocking,
+        FLASH_SIZE,
+    >,
+) {
+    let mut uid = [0u8; 8];
+    flash.blocking_unique_id(&mut uid).expect("flash unique ID");
+
+    // XOR the first 2 bytes into bytes 2..8 to fold 8 bytes into 6,
+    // then set the locally-administered bit (byte 0, bit 1).
+    let mac = [
+        uid[2] ^ uid[0] | 0x02,
+        uid[3] ^ uid[1],
+        uid[4],
+        uid[5],
+        uid[6],
+        uid[7],
+    ];
+
+    let stored = MAC.init(mac);
+    // SAFETY: Written once during single-threaded init, before the executor
+    // starts. All subsequent reads are from &'static reference.
+    unsafe {
+        MAC_REF = Some(stored);
+    }
+}
+
+/// Return the MAC address derived from the flash unique ID.
+///
+/// Panics if `init_mac()` has not been called.
+pub fn mac_address() -> [u8; 6] {
+    // SAFETY: MAC_REF is set once during init before the executor starts,
+    // and only read (never written) after that.
+    unsafe { *MAC_REF.expect("init_mac() must be called before mac_address()") }
+}

src/host/framing.rs

@@ -0,0 +1,121 @@
+//! Shared framing helpers for USB and UART host transports.
+//!
+//! Ingress path: raw bytes → `FrameDecoder` → `(type_id, tag, payload)`
+//! → `Command::parse` → forwarded to radio task along with the tag. On
+//! parse failure we echo `ERR(ELENGTH/EPARAM/EMODULATION/EUNKNOWN_CMD)`
+//! with the received tag. On CRC/COBS failure we emit async
+//! `ERR(EFRAME)` with tag `0x0000` (`PROTOCOL.md §2.5`).
+//!
+//! Egress path: `OutboundFrame` (tag + DeviceMessage) → `encode_frame`
+//! → bytes ready for transport-level write.
+
+use defmt::warn;
+
+use crate::channel::{CommandChannel, InboundEvent, OutboundChannel, OutboundFrame};
+use crate::protocol::{
+    encode_frame, Command, CommandParseError, DeviceMessage, ErrorCode, FrameEncodeError,
+    MAX_PAYLOAD_FIELD, MAX_WIRE_FRAME,
+};
+
+/// Dispatch a frame-level decode into the appropriate downstream queue.
+///
+/// - `type_id`, `tag`, and `payload` come from `FrameDecoder`.
+/// - Known commands are forwarded to the radio task via `commands`.
+/// - Parse failures produce a synchronous `ERR` with the echoed tag on
+///   `outbound`, so the host sees a concrete answer instead of timing out.
+/// - The caller is responsible for rejecting `tag == 0` before calling
+///   this; the spec says hosts MUST NOT send tag 0, and we classify such
+///   frames as framing errors upstream.
+pub async fn dispatch_frame(
+    type_id: u8,
+    tag: u16,
+    payload: &[u8],
+    commands: &CommandChannel,
+    outbound: &OutboundChannel,
+) {
+    if tag == 0 {
+        // Hosts MUST NOT use tag 0 on outbound commands. Treat as
+        // framing error; do not route to radio. (Spec §2.2)
+        emit_async_err(outbound, ErrorCode::EFrame).await;
+        return;
+    }
+    match Command::parse(type_id, payload) {
+        Ok(cmd) => {
+            let envelope = InboundEvent::Command { tag, cmd };
+            if commands.try_send(envelope).is_err() {
+                emit_sync_err(outbound, tag, ErrorCode::EBusy).await;
+            }
+        }
+        Err(e) => {
+            let code = parse_err_to_wire_code(e);
+            emit_sync_err(outbound, tag, code).await;
+        }
+    }
+}
+
+/// Emit an async framing error (tag = 0x0000) per spec §2.5.
+pub async fn emit_async_err(outbound: &OutboundChannel, code: ErrorCode) {
+    let frame = OutboundFrame {
+        tag: 0,
+        msg: DeviceMessage::Err(code),
+    };
+    if outbound.try_send(frame).is_err() {
+        warn!("async ERR dropped: outbound queue full");
+    }
+}
+
+/// Emit a synchronous error response echoing the originating tag.
+async fn emit_sync_err(outbound: &OutboundChannel, tag: u16, code: ErrorCode) {
+    let frame = OutboundFrame {
+        tag,
+        msg: DeviceMessage::Err(code),
+    };
+    if outbound.try_send(frame).is_err() {
+        warn!("sync ERR dropped: outbound queue full");
+    }
+}
+
+fn parse_err_to_wire_code(e: CommandParseError) -> ErrorCode {
+    match e {
+        CommandParseError::UnknownType => ErrorCode::EUnknownCmd,
+        CommandParseError::WrongLength => ErrorCode::ELength,
+        CommandParseError::InvalidField => ErrorCode::EParam,
+        CommandParseError::ReservedBitSet => ErrorCode::EParam,
+        CommandParseError::UnknownModulation => ErrorCode::EModulation,
+    }
+}
+
+/// Encode an outbound frame into a single wire-ready byte buffer.
+///
+/// Returns the number of bytes written to `out`, or `None` on buffer
+/// overflow / encode failure (caller may log and drop).
+pub fn encode_outbound(frame: &OutboundFrame, out: &mut [u8; MAX_WIRE_FRAME]) -> Option<usize> {
+    let mut payload_buf = [0u8; MAX_PAYLOAD_FIELD];
+    let payload_len = match frame.msg.encode_payload(&mut payload_buf) {
+        Ok(n) => n,
+        Err(e) => {
+            warn!("encode_payload failed: {:?}", defmt::Debug2Format(&e));
+            return None;
+        }
+    };
+    match encode_frame(
+        frame.msg.type_id(),
+        frame.tag,
+        &payload_buf[..payload_len],
+        out.as_mut_slice(),
+    ) {
+        Ok(n) => Some(n),
+        Err(FrameEncodeError::BufferTooSmall) => {
+            warn!("encode_frame: output buffer too small");
+            None
+        }
+        Err(FrameEncodeError::PayloadTooLarge) => {
+            warn!("encode_frame: payload exceeds MAX_PAYLOAD_FIELD");
+            None
+        }
+        Err(FrameEncodeError::CobsEncode) => {
+            warn!("encode_frame: COBS encode refused");
+            None
+        }
+    }
+}

src/host/mod.rs

@@ -0,0 +1,20 @@
+//! Host communication: unified USB/UART transport.
+//!
+//! Exports a single `host_task` regardless of transport.
+//! The cfg dispatch is contained entirely within this module.
+
+pub mod framing;
+
+cfg_if::cfg_if! {
+    if #[cfg(any(
+        feature = "heltec_v3_uart",
+        feature = "elecrow_thinknode_m2",
+        feature = "lilygo_tbeam"
+    ))] {
+        mod uart;
+        pub use uart::host_task;
+    } else {
+        mod usb;
+        pub use usb::host_task;
+    }
+}

src/host/uart.rs

@@ -0,0 +1,141 @@
+//! UART host task for DongLoRa Protocol v2.
+//!
+//! UART has no DTR line, so we assume a host is always present and
+//! rely entirely on the spec §3.4 inactivity watchdog (1 s of silence
+//! → Disconnected → drop radio to Unconfigured).
+
+use defmt::warn;
+use embassy_executor::task;
+use embassy_time::{Duration, Instant};
+use embedded_io_async::Write;
+
+use super::framing::{dispatch_frame, emit_async_err, encode_outbound};
+use crate::channel::{
+    CommandChannel, DisplayCommand, DisplayCommandChannel, InboundEvent, OutboundChannel,
+};
+use crate::protocol::{ErrorCode, FrameDecoder, FrameResult, MAX_PAYLOAD_FIELD, MAX_WIRE_FRAME};
+
+const READ_BUF: usize = 64;
+const INACTIVITY_MS: u64 = 1000;
+
+#[task]
+pub async fn host_task(
+    parts: crate::board::UartParts,
+    commands: &'static CommandChannel,
+    outbound: &'static OutboundChannel,
+    display_commands: &'static DisplayCommandChannel,
+    has_display: bool,
+    _mac: [u8; 6],
+) {
+    let (mut rx, mut tx) = parts.driver.split();
+
+    // UART has no DTR — wake display immediately and assume a host.
+    if has_display {
+        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;
+
+    loop {
+        use embassy_futures::select::{select3, Either3};
+
+        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) => {
+                    last_frame_at = Instant::now();
+                    if !connected {
+                        if has_display {
+                            let _ = display_commands.try_send(DisplayCommand::On);
+                        }
+                        connected = true;
+                    }
+                    dispatch_bytes(&mut decoder, &read_buf[..n], commands, outbound).await;
+                }
+                Err(_) => {
+                    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");
+                    }
+                }
+            }
+            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;
+        }
+    }
+}
+
+async fn dispatch_bytes(
+    decoder: &mut FrameDecoder,
+    bytes: &[u8],
+    commands: &'static CommandChannel,
+    outbound: &'static OutboundChannel,
+) {
+    let mut work: heapless::Vec<FrameWork, 4> = heapless::Vec::new();
+    decoder.feed(bytes, |res| match res {
+        FrameResult::Ok {
+            type_id,
+            tag,
+            payload,
+        } => {
+            let mut p: heapless::Vec<u8, MAX_PAYLOAD_FIELD> = heapless::Vec::new();
+            let _ = p.extend_from_slice(payload);
+            let _ = work.push(FrameWork::Ok {
+                type_id,
+                tag,
+                payload: p,
+            });
+        }
+        FrameResult::Err(_) => {
+            let _ = work.push(FrameWork::Frame);
+        }
+    });
+    for w in work {
+        match w {
+            FrameWork::Ok {
+                type_id,
+                tag,
+                payload,
+            } => {
+                dispatch_frame(type_id, tag, &payload, commands, outbound).await;
+            }
+            FrameWork::Frame => {
+                emit_async_err(outbound, ErrorCode::EFrame).await;
+            }
+        }
+    }
+}
+
+#[allow(clippy::large_enum_variant)]
+enum FrameWork {
+    Ok {
+        type_id: u8,
+        tag: u16,
+        payload: heapless::Vec<u8, MAX_PAYLOAD_FIELD>,
+    },
+    Frame,
+}

src/host/usb.rs

@@ -0,0 +1,307 @@
+//! USB CDC-ACM host task for DongLoRa Protocol v2.
+//!
+//! ```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
+//! ```
+//!
+//! 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.
+//!
+//! 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.
+
+use defmt::warn;
+use embassy_executor::task;
+use embassy_futures::join::join;
+use embassy_time::{Duration, Instant};
+use embassy_usb::class::cdc_acm::{CdcAcmClass, Receiver, Sender, State};
+use embassy_usb::Builder;
+use hsmc::{statechart, Duration as HsmcDuration};
+use static_cell::StaticCell;
+
+use super::framing::{dispatch_frame, emit_async_err, encode_outbound};
+use crate::channel::{
+    CommandChannel, DisplayCommand, DisplayCommandChannel, InboundEvent, OutboundChannel,
+};
+use crate::protocol::{ErrorCode, FrameDecoder, FrameResult, MAX_WIRE_FRAME};
+
+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.
+const INACTIVITY_MS: u64 = 1000;
+
+/// Poll interval for the DTR edge detector / inactivity check.
+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,
+}
+
+pub struct HostContext {
+    commands: &'static CommandChannel,
+    display_commands: &'static DisplayCommandChannel,
+    has_display: bool,
+}
+
+impl HostContext {
+    async fn wake_display_if_present(&self) {
+        if self.has_display {
+            self.display_commands.send(DisplayCommand::On).await;
+        }
+    }
+
+    async fn reset_display_if_present(&self) {
+        if self.has_display {
+            self.display_commands.send(DisplayCommand::Reset).await;
+        }
+    }
+
+    fn send_radio_reset(&self) {
+        if self.commands.try_send(InboundEvent::Reset).is_err() {
+            warn!("radio Reset inject: command queue full");
+        }
+    }
+}
+
+statechart! {
+    Host {
+        context: HostContext;
+        events: HostInput;
+        default(Disconnected);
+
+        state Disconnected {
+            on(DtrRaised) => Connected;
+        }
+
+        state Connected {
+            entry: wake_display;
+            exit: reset_radio, reset_display;
+            on(DtrDropped) => Disconnected;
+            on(InactivityTimeout) => Disconnected;
+        }
+    }
+}
+
+impl HostActions for HostActionContext<'_> {
+    async fn wake_display(&mut self) {
+        self.wake_display_if_present().await;
+    }
+
+    async fn reset_radio(&mut self) {
+        self.send_radio_reset();
+    }
+
+    async fn reset_display(&mut self) {
+        self.reset_display_if_present().await;
+    }
+}
+
+#[task]
+pub async fn host_task(
+    parts: crate::board::UsbParts,
+    commands: &'static CommandChannel,
+    outbound: &'static OutboundChannel,
+    display_commands: &'static DisplayCommandChannel,
+    has_display: bool,
+    mac: [u8; 6],
+) {
+    let mut config = embassy_usb::Config::new(0x1209, 0x5741);
+    config.manufacturer = Some("DongLoRa");
+    config.product = Some("DongLoRa LoRa Radio");
+    config.device_class = 0xEF;
+    config.device_sub_class = 0x02;
+    config.device_protocol = 0x01;
+    config.composite_with_iads = true;
+
+    static SERIAL_BUF: StaticCell<[u8; 12]> = StaticCell::new();
+    let serial_buf = SERIAL_BUF.init([0u8; 12]);
+    const HEX: &[u8; 16] = b"0123456789ABCDEF";
+    for (i, &byte) in mac.iter().enumerate() {
+        serial_buf[i * 2] = HEX[(byte >> 4) as usize];
+        serial_buf[i * 2 + 1] = HEX[(byte & 0x0F) as usize];
+    }
+    config.serial_number = Some(core::str::from_utf8(serial_buf).expect("MAC hex is valid UTF-8"));
+
+    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 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 cdc_state = CDC_STATE.init(State::new());
+
+    let mut builder = Builder::new(parts.driver, config, desc_buf, conf_buf, bos_buf, ctrl_buf);
+
+    let class = CdcAcmClass::new(&mut builder, cdc_state, MAX_USB_PACKET as u16);
+    let mut usb_dev = builder.build();
+    let (sender, receiver) = class.split();
+
+    join(
+        usb_dev.run(),
+        protocol_loop(
+            sender,
+            receiver,
+            commands,
+            outbound,
+            display_commands,
+            has_display,
+        ),
+    )
+    .await;
+}
+
+async fn protocol_loop<'d, D: embassy_usb_driver::Driver<'d>>(
+    mut sender: Sender<'d, D>,
+    mut receiver: Receiver<'d, D>,
+    commands: &'static CommandChannel,
+    outbound: &'static OutboundChannel,
+    display_commands: &'static DisplayCommandChannel,
+    has_display: bool,
+) {
+    use embassy_futures::select::{select3, Either3};
+
+    let mut machine = Host::new_local(HostContext {
+        commands,
+        display_commands,
+        has_display,
+    });
+    machine.step(HsmcDuration::ZERO).await;
+
+    let mut read_buf = [0u8; MAX_USB_PACKET];
+    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),
+            outbound.receive(),
+            embassy_time::Timer::after(Duration::from_millis(POLL_INTERVAL_MS)),
+        )
+        .await
+        {
+            Either3::First(Ok(0)) => {}
+            Either3::First(Ok(n)) => {
+                last_frame_at = Instant::now();
+                dispatch_bytes(&mut decoder, &read_buf[..n], commands, outbound).await;
+            }
+            Either3::First(Err(_)) => {
+                decoder.reset();
+                embassy_time::Timer::after_millis(100).await;
+            }
+            Either3::Second(frame) => {
+                if let Some(n) = encode_outbound(&frame, &mut write_buf) {
+                    for chunk in write_buf[..n].chunks(MAX_USB_PACKET) {
+                        if sender.write_packet(chunk).await.is_err() {
+                            warn!("USB write failed, frame dropped");
+                            break;
+                        }
+                    }
+                }
+            }
+            Either3::Third(()) => {}
+        }
+
+        // DTR edge detection — drives Connected / Disconnected transitions.
+        let connected = receiver.dtr();
+        let was_connected = matches!(machine.current_state(), HostState::Connected);
+        match (was_connected, connected) {
+            (false, true) => {
+                let _ = machine.dispatch(HostInput::DtrRaised).await;
+                last_frame_at = Instant::now();
+            }
+            (true, false) => {
+                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;
+        }
+    }
+}
+
+/// Feed raw bytes into the frame decoder. For each complete frame:
+/// - Ok → route into the command channel (or emit sync ERR on parse fail)
+/// - Err(Crc | Cobs | TooShort) → emit async ERR(EFRAME)
+///
+/// Borrow-scoped per the `FrameDecoder::feed` callback contract: the
+/// payload slice is valid only for the duration of the callback.
+async fn dispatch_bytes(
+    decoder: &mut FrameDecoder,
+    bytes: &[u8],
+    commands: &'static CommandChannel,
+    outbound: &'static OutboundChannel,
+) {
+    // `FrameDecoder::feed` hands payloads by reference; we must synchronously
+    // copy any data we need before the callback returns. To avoid fighting
+    // lifetimes we accumulate per-frame work as an enum.
+    let mut work: heapless::Vec<FrameWork, 4> = heapless::Vec::new();
+    decoder.feed(bytes, |res| match res {
+        FrameResult::Ok {
+            type_id,
+            tag,
+            payload,
+        } => {
+            let mut p: heapless::Vec<u8, { crate::protocol::MAX_PAYLOAD_FIELD }> =
+                heapless::Vec::new();
+            let _ = p.extend_from_slice(payload);
+            let _ = work.push(FrameWork::Ok {
+                type_id,
+                tag,
+                payload: p,
+            });
+        }
+        FrameResult::Err(_e) => {
+            let _ = work.push(FrameWork::Frame);
+        }
+    });
+    for w in work {
+        match w {
+            FrameWork::Ok {
+                type_id,
+                tag,
+                payload,
+            } => {
+                dispatch_frame(type_id, tag, &payload, commands, outbound).await;
+            }
+            FrameWork::Frame => {
+                emit_async_err(outbound, ErrorCode::EFrame).await;
+            }
+        }
+    }
+}
+
+#[allow(clippy::large_enum_variant)]
+enum FrameWork {
+    Ok {
+        type_id: u8,
+        tag: u16,
+        payload: heapless::Vec<u8, { crate::protocol::MAX_PAYLOAD_FIELD }>,
+    },
+    Frame,
+}

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

@@ -3,11 +3,11 @@
 //! Three async tasks communicate via static channels:
 //!
 //! ```text
-//! usb_task ──Command──► radio_task ──► SX1262
-//!          ◄──Response──     │
-//!                       StatusWatch
-//!                            ▼
-//!                      display_task (optional)
+//! host_task ──Command──► radio_task ──► SX1262
+//!           ◄──Response──     │
+//!                        StatusWatch
+//!                             ▼
+//!                       display_task (optional)
 //! ```
 //!
 //! The host drives everything. The radio idles until commanded.
@@ -19,13 +19,20 @@
 mod board;
 #[cfg(not(test))]
 mod channel;
+#[cfg(all(not(test), feature = "debug-checkpoint"))]
+mod debug_blink;
 #[cfg(not(test))]
 mod display;
+#[cfg(not(test))]
+mod driver;
+#[cfg(not(test))]
+mod hal;
+#[cfg(not(test))]
+mod host;
+mod lbt;
 mod protocol;
 #[cfg(not(test))]
 mod radio;
-#[cfg(not(test))]
-mod usb;
 
 #[cfg(not(test))]
 use embassy_executor::Spawner;
@@ -33,13 +40,16 @@ use embassy_executor::Spawner;
 #[cfg(not(test))]
 use crate::board::LoRaBoard;
 #[cfg(not(test))]
-use crate::channel::{CommandChannel, DisplayCommandChannel, ResponseChannel, StatusWatch};
+use crate::channel::{CommandChannel, DisplayCommandChannel, OutboundChannel, RadioEventChannel};
+#[cfg(not(test))]
+use crate::protocol::{cap, Info, MAX_MCU_UID_LEN, MAX_RADIO_UID_LEN};
 
 #[cfg(not(test))]
 cfg_if::cfg_if! {
-    if #[cfg(feature = "rak_wisblock_4631")] {
+    if #[cfg(any(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_v4"))] {
+    } 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 _;
     }
@@ -48,20 +58,22 @@ cfg_if::cfg_if! {
 #[cfg(not(test))]
 static COMMANDS: CommandChannel = CommandChannel::new();
 #[cfg(not(test))]
-static RESPONSES: ResponseChannel = ResponseChannel::new();
+static OUTBOUND: OutboundChannel = OutboundChannel::new();
 #[cfg(not(test))]
-static STATUS: StatusWatch = StatusWatch::new();
+static RADIO_EVENTS: RadioEventChannel = RadioEventChannel::new();
 #[cfg(not(test))]
 static DISPLAY_COMMANDS: DisplayCommandChannel = DisplayCommandChannel::new();
+#[cfg(not(test))]
+static mut INFO: Option<Info> = None;
 
 #[cfg(not(test))]
 cfg_if::cfg_if! {
-    if #[cfg(feature = "rak_wisblock_4631")] {
+    if #[cfg(any(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_v4"))] {
+    } 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;
@@ -72,28 +84,112 @@ cfg_if::cfg_if! {
 #[cfg(not(test))]
 async fn run(spawner: Spawner) {
     let board = <board::Board as LoRaBoard>::init();
-    let mac = board::Board::mac_address();
-    let (radio, usb, display) = board.into_parts();
+    let parts = board.into_parts();
 
-    let has_display = display.is_some();
+    // Build the GET_INFO struct once at boot. This is the authoritative
+    // snapshot of device capabilities reported over the wire.
+    let info = build_info(parts.mac);
+    // SAFETY: touched only here at boot, before any task is spawned.
+    let info_ref: &'static Info = unsafe {
+        INFO = Some(info);
+        #[allow(static_mut_refs)]
+        INFO.as_ref().expect("INFO just initialized")
+    };
 
-    spawner
-        .spawn(radio::radio_task(radio, &COMMANDS, &RESPONSES, &STATUS))
-        .expect("spawn radio_task");
-    spawner
-        .spawn(usb::usb_task(
-            usb,
+    spawner.spawn(
+        radio::radio_task(parts.radio, &COMMANDS, &OUTBOUND, &RADIO_EVENTS, info_ref)
+            .expect("spawn radio_task"),
+    );
+
+    spawner.spawn(
+        host::host_task(
+            parts.host,
             &COMMANDS,
-            &RESPONSES,
+            &OUTBOUND,
             &DISPLAY_COMMANDS,
-            has_display,
-            mac,
-        ))
-        .expect("spawn usb_task");
+            parts.display.is_some(),
+            parts.mac,
+        )
+        .expect("spawn host_task"),
+    );
 
-    if let Some(dp) = display {
-        spawner
-            .spawn(display::display_task(dp, &STATUS, &DISPLAY_COMMANDS))
-            .expect("spawn display_task");
+    // Suppress "assigned but never read" warning on non-USB/UART path.
+    let _ = info_ref;
+
+    if let Some(dp) = parts.display {
+        #[cfg(feature = "debug-checkpoint")]
+        {
+            // LED is taken over by the checkpoint blinker; the display
+            // init struct is dropped unused for this debug build.
+            let _ = dp;
+            spawner
+                .spawn(debug_blink::debug_blink_task(parts.led).expect("spawn debug_blink_task"));
+        }
+        #[cfg(not(feature = "debug-checkpoint"))]
+        {
+            #[allow(clippy::unit_arg)] // LedDriver is () for boards without LEDs
+            spawner.spawn(
+                display::display_task(dp, parts.led, &RADIO_EVENTS, &DISPLAY_COMMANDS)
+                    .expect("spawn display_task"),
+            );
+        }
     }
 }
+
+#[cfg(not(test))]
+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);
+
+    Info {
+        proto_major: 1,
+        proto_minor: 0,
+        fw_major: parse_u8_or(env!("CARGO_PKG_VERSION_MAJOR"), 0),
+        fw_minor: parse_u8_or(env!("CARGO_PKG_VERSION_MINOR"), 0),
+        fw_patch: parse_u8_or(env!("CARGO_PKG_VERSION_PATCH"), 0),
+        radio_chip_id: chip_id,
+        capability_bitmap: cap::LORA | cap::CAD_BEFORE_TX,
+        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,
+        tx_queue_capacity: 1,
+        freq_min_hz: fmin,
+        freq_max_hz: fmax,
+        tx_power_min_dbm: tx_min,
+        tx_power_max_dbm: tx_max,
+        mcu_uid_len: 6,
+        mcu_uid,
+        radio_uid_len: 0,
+        radio_uid: [0u8; MAX_RADIO_UID_LEN],
+    }
+}
+
+#[cfg(not(test))]
+const fn parse_u8_or(s: &str, default: u8) -> u8 {
+    // CARGO_PKG_VERSION_* strings are short decimal ascii. Parse them at
+    // compile time via a tiny constant function instead of pulling in a
+    // dependency.
+    let bytes = s.as_bytes();
+    let mut i = 0;
+    let mut out: u32 = 0;
+    while i < bytes.len() {
+        let b = bytes[i];
+        if b < b'0' || b > b'9' {
+            return default;
+        }
+        out = out * 10 + (b - b'0') as u32;
+        if out > u8::MAX as u32 {
+            return default;
+        }
+        i += 1;
+    }
+    out as u8
+}

src/protocol.rs

@@ -1,661 +1,16 @@
-//! Wire protocol types and fixed-size little-endian serialization.
+//! Wire protocol types for DongLoRa Protocol v2.
 //!
-//! Every integer is fixed-width LE. No varints, no zigzag.
-//! See `docs/PROTOCOL.md` for the complete specification.
-
-use heapless::Vec;
-
-/// Maximum LoRa payload size in bytes.
-pub const MAX_PAYLOAD: usize = 256;
-
-/// RadioConfig wire size (fixed).
-pub const RADIO_CONFIG_SIZE: usize = 13;
-
-/// Sentinel value for `tx_power_dbm`: use the board's maximum TX power.
-pub const TX_POWER_MAX: i8 = i8::MIN; // -128 on the wire
-
-/// Sentinel value for `preamble_len`: use the firmware default (16 symbols).
-pub const PREAMBLE_DEFAULT: u16 = 0;
-
-
-/// LoRa signal bandwidth.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-#[cfg_attr(not(test), derive(defmt::Format))]
-#[repr(u8)]
-pub enum Bandwidth {
-    Khz7 = 0,
-    Khz10 = 1,
-    Khz15 = 2,
-    Khz20 = 3,
-    Khz31 = 4,
-    Khz41 = 5,
-    Khz62 = 6,
-    Khz125 = 7,
-    Khz250 = 8,
-    Khz500 = 9,
-}
-
-impl Bandwidth {
-    fn from_u8(v: u8) -> Option<Self> {
-        match v {
-            0 => Some(Self::Khz7),
-            1 => Some(Self::Khz10),
-            2 => Some(Self::Khz15),
-            3 => Some(Self::Khz20),
-            4 => Some(Self::Khz31),
-            5 => Some(Self::Khz41),
-            6 => Some(Self::Khz62),
-            7 => Some(Self::Khz125),
-            8 => Some(Self::Khz250),
-            9 => Some(Self::Khz500),
-            _ => None,
-        }
-    }
-}
-
-/// Complete LoRa radio configuration.
-///
-/// Wire layout (13 bytes, all little-endian):
-/// ```text
-/// [freq_hz:4] [bw:1] [sf:1] [cr:1] [sync_word:2] [tx_power_dbm:1] [preamble_len:2] [cad:1]
-/// ```
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-#[cfg_attr(not(test), derive(defmt::Format))]
-pub struct RadioConfig {
-    /// Frequency in Hz (150_000_000 - 960_000_000 for SX1262).
-    pub freq_hz: u32,
-    pub bw: Bandwidth,
-    /// Spreading factor (5-12).
-    pub sf: u8,
-    /// Coding rate denominator (5-8). E.g. 5 = CR 4/5, 8 = CR 4/8.
-    pub cr: u8,
-    pub sync_word: u16,
-    /// Transmit power in dBm. Set to [`TX_POWER_MAX`] (-128) for the
-    /// board's maximum.
-    pub tx_power_dbm: i8,
-    /// Preamble length in symbols. Set to [`PREAMBLE_DEFAULT`] (0) for
-    /// the firmware default (16 symbols). Valid range: 6–65535.
-    pub preamble_len: u16,
-    /// Channel Activity Detection (listen-before-talk) before TX.
-    /// 0 = disabled, non-zero = enabled. Default: 1 (enabled).
-    pub cad: u8,
-}
-
-impl RadioConfig {
-    /// Validate fields against hardware limits.
-    pub fn validate(&self, power_range: (i8, i8)) -> Result<(), &'static str> {
-        if !(150_000_000..=960_000_000).contains(&self.freq_hz) {
-            return Err("frequency out of range (150-960 MHz)");
-        }
-        if !(5..=12).contains(&self.sf) {
-            return Err("spreading factor out of range (5-12)");
-        }
-        if !(5..=8).contains(&self.cr) {
-            return Err("coding rate out of range (5-8)");
-        }
-        if self.tx_power_dbm != TX_POWER_MAX
-            && !(power_range.0..=power_range.1).contains(&self.tx_power_dbm)
-        {
-            return Err("TX power out of range for this board");
-        }
-        if self.preamble_len != PREAMBLE_DEFAULT && self.preamble_len < 6 {
-            return Err("preamble length too short (min 6)");
-        }
-        Ok(())
-    }
-
-    /// Resolve sentinel values to concrete defaults.
-    pub fn resolve(mut self, power_range: (i8, i8)) -> Self {
-        if self.tx_power_dbm == TX_POWER_MAX {
-            self.tx_power_dbm = power_range.1;
-        }
-        if self.preamble_len == PREAMBLE_DEFAULT {
-            self.preamble_len = 16;
-        }
-        self
-    }
-
-    /// Whether CAD (listen-before-talk) is enabled.
-    pub fn cad_enabled(&self) -> bool {
-        self.cad != 0
-    }
-
-    /// Serialize to fixed-size LE bytes. Returns number of bytes written (always 13).
-    pub fn write_to(self, buf: &mut [u8]) -> usize {
-        buf[0..4].copy_from_slice(&self.freq_hz.to_le_bytes());
-        buf[4] = self.bw as u8;
-        buf[5] = self.sf;
-        buf[6] = self.cr;
-        buf[7..9].copy_from_slice(&self.sync_word.to_le_bytes());
-        buf[9] = self.tx_power_dbm as u8;
-        buf[10..12].copy_from_slice(&self.preamble_len.to_le_bytes());
-        buf[12] = self.cad;
-        RADIO_CONFIG_SIZE
-    }
-
-    /// Deserialize from fixed-size LE bytes.
-    pub fn from_bytes(buf: &[u8]) -> Option<Self> {
-        if buf.len() < RADIO_CONFIG_SIZE {
-            return None;
-        }
-        Some(Self {
-            freq_hz: u32::from_le_bytes(buf[0..4].try_into().ok()?),
-            bw: Bandwidth::from_u8(buf[4])?,
-            sf: buf[5],
-            cr: buf[6],
-            sync_word: u16::from_le_bytes(buf[7..9].try_into().ok()?),
-            tx_power_dbm: buf[9] as i8,
-            preamble_len: u16::from_le_bytes(buf[10..12].try_into().ok()?),
-            cad: buf[12],
-        })
-    }
-}
-
-/// Host → firmware commands.
-#[allow(clippy::large_enum_variant)]
-#[derive(Debug, PartialEq)]
-pub enum Command {
-    Ping,
-    GetConfig,
-    SetConfig(RadioConfig),
-    StartRx,
-    StopRx,
-    Transmit {
-        config: Option<RadioConfig>,
-        payload: Vec<u8, MAX_PAYLOAD>,
-    },
-    DisplayOn,
-    DisplayOff,
-    GetMac,
-}
-
-impl Command {
-    /// Deserialize from a COBS-decoded frame.
-    pub fn from_bytes(buf: &[u8]) -> Option<Self> {
-        let tag = *buf.first()?;
-        let rest = &buf[1..];
-        match tag {
-            0 => Some(Self::Ping),
-            1 => Some(Self::GetConfig),
-            2 => Some(Self::SetConfig(RadioConfig::from_bytes(rest)?)),
-            3 => Some(Self::StartRx),
-            4 => Some(Self::StopRx),
-            5 => {
-                // Transmit: has_config:u8 + [RadioConfig if 1] + len:u16 LE + payload
-                if rest.is_empty() {
-                    return None;
-                }
-                let (config, pos) = if rest[0] == 0 {
-                    (None, 1)
-                } else if rest[0] == 1 && rest.len() > RADIO_CONFIG_SIZE {
-                    (Some(RadioConfig::from_bytes(&rest[1..])?), 1 + RADIO_CONFIG_SIZE)
-                } else {
-                    return None;
-                };
-                if rest.len() < pos + 2 {
-                    return None;
-                }
-                let len = u16::from_le_bytes(rest[pos..pos + 2].try_into().ok()?) as usize;
-                let data_start = pos + 2;
-                if rest.len() < data_start + len {
-                    return None;
-                }
-                let mut payload = Vec::new();
-                let _ = payload.extend_from_slice(&rest[data_start..data_start + len]);
-                Some(Self::Transmit { config, payload })
-            }
-            6 => Some(Self::DisplayOn),
-            7 => Some(Self::DisplayOff),
-            8 => Some(Self::GetMac),
-            _ => None,
-        }
-    }
-}
-
-/// Firmware → host responses.
-#[allow(clippy::large_enum_variant)]
-#[derive(Debug, PartialEq)]
-pub enum Response {
-    Pong,
-    Config(RadioConfig),
-    RxPacket {
-        rssi: i16,
-        snr: i16,
-        payload: Vec<u8, MAX_PAYLOAD>,
-    },
-    TxDone,
-    Ok,
-    Error(ErrorCode),
-    MacAddress([u8; 6]),
-}
-
-impl Response {
-    /// Serialize to fixed-size LE bytes. Returns number of bytes written.
-    pub fn write_to(self, buf: &mut [u8]) -> usize {
-        match self {
-            Self::Pong => {
-                buf[0] = 0;
-                1
-            }
-            Self::Config(cfg) => {
-                buf[0] = 1;
-                1 + cfg.write_to(&mut buf[1..])
-            }
-            Self::RxPacket { rssi, snr, payload } => {
-                buf[0] = 2;
-                buf[1..3].copy_from_slice(&rssi.to_le_bytes());
-                buf[3..5].copy_from_slice(&snr.to_le_bytes());
-                buf[5..7].copy_from_slice(&(payload.len() as u16).to_le_bytes());
-                buf[7..7 + payload.len()].copy_from_slice(&payload);
-                7 + payload.len()
-            }
-            Self::TxDone => {
-                buf[0] = 3;
-                1
-            }
-            Self::Ok => {
-                buf[0] = 4;
-                1
-            }
-            Self::Error(code) => {
-                buf[0] = 5;
-                buf[1] = code as u8;
-                2
-            }
-            Self::MacAddress(mac) => {
-                buf[0] = 6;
-                buf[1..7].copy_from_slice(&mac);
-                7
-            }
-        }
-    }
-}
-
-/// Error codes reported to the host.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-#[cfg_attr(not(test), derive(defmt::Format))]
-#[repr(u8)]
-#[allow(dead_code)] // CrcError reserved per PROTOCOL.md (error code 3)
-pub enum ErrorCode {
-    InvalidConfig = 0,
-    RadioBusy = 1,
-    TxTimeout = 2,
-    CrcError = 3,
-    NotConfigured = 4,
-    NoDisplay = 5,
-}
-
-// ── Tests ───────────────────────────────────────────────────────────
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn make_config() -> RadioConfig {
-        RadioConfig {
-            freq_hz: 915_000_000,
-            bw: Bandwidth::Khz125,
-            sf: 7,
-            cr: 5,
-            sync_word: 0x3444,
-            tx_power_dbm: 22,
-            preamble_len: 16,
-            cad: 1,
-        }
-    }
-
-    // ── RadioConfig roundtrip ───────────────────────────────────────
-
-    #[test]
-    fn radio_config_roundtrip() {
-        let cfg = make_config();
-        let mut buf = [0u8; RADIO_CONFIG_SIZE];
-        let n = cfg.write_to(&mut buf);
-        assert_eq!(n, RADIO_CONFIG_SIZE);
-        assert_eq!(RadioConfig::from_bytes(&buf), Some(cfg));
-    }
-
-    #[test]
-    fn radio_config_roundtrip_all_bandwidths() {
-        for bw_val in 0u8..=9 {
-            let bw = Bandwidth::from_u8(bw_val).unwrap();
-            let cfg = RadioConfig {
-                freq_hz: 433_000_000,
-                bw,
-                sf: 12,
-                cr: 8,
-                sync_word: 0x1234,
-                tx_power_dbm: -9,
-            };
-            let mut buf = [0u8; RADIO_CONFIG_SIZE];
-            cfg.write_to(&mut buf);
-            assert_eq!(RadioConfig::from_bytes(&buf), Some(cfg));
-        }
-    }
-
-    #[test]
-    fn radio_config_roundtrip_negative_power() {
-        let cfg = RadioConfig {
-            tx_power_dbm: TX_POWER_MAX,
-            ..make_config()
-        };
-        let mut buf = [0u8; RADIO_CONFIG_SIZE];
-        cfg.write_to(&mut buf);
-        assert_eq!(RadioConfig::from_bytes(&buf), Some(cfg));
-    }
-
-    #[test]
-    fn radio_config_from_short_buffer() {
-        let buf = [0u8; RADIO_CONFIG_SIZE - 1];
-        assert!(RadioConfig::from_bytes(&buf).is_none());
-    }
-
-    #[test]
-    fn radio_config_from_empty_buffer() {
-        assert!(RadioConfig::from_bytes(&[]).is_none());
-    }
-
-    #[test]
-    fn radio_config_invalid_bandwidth() {
-        let mut buf = [0u8; RADIO_CONFIG_SIZE];
-        make_config().write_to(&mut buf);
-        buf[4] = 255; // invalid bandwidth
-        assert!(RadioConfig::from_bytes(&buf).is_none());
-    }
-
-    // ── RadioConfig::validate ───────────────────────────────────────
-
-    #[test]
-    fn validate_freq_boundaries() {
-        let power_range = (-9, 22);
-        let base = make_config();
-
-        let mut cfg = RadioConfig { freq_hz: 150_000_000, ..base };
-        assert!(cfg.validate(power_range).is_ok());
-
-        cfg.freq_hz = 960_000_000;
-        assert!(cfg.validate(power_range).is_ok());
-
-        cfg.freq_hz = 149_999_999;
-        assert!(cfg.validate(power_range).is_err());
-
-        cfg.freq_hz = 960_000_001;
-        assert!(cfg.validate(power_range).is_err());
-    }
-
-    #[test]
-    fn validate_sf_boundaries() {
-        let power_range = (-9, 22);
-        let base = make_config();
-
-        for sf in 5..=12 {
-            assert!(RadioConfig { sf, ..base }.validate(power_range).is_ok());
-        }
-        assert!(RadioConfig { sf: 4, ..base }.validate(power_range).is_err());
-        assert!(RadioConfig { sf: 13, ..base }.validate(power_range).is_err());
-    }
-
-    #[test]
-    fn validate_cr_boundaries() {
-        let power_range = (-9, 22);
-        let base = make_config();
-
-        for cr in 5..=8 {
-            assert!(RadioConfig { cr, ..base }.validate(power_range).is_ok());
-        }
-        assert!(RadioConfig { cr: 4, ..base }.validate(power_range).is_err());
-        assert!(RadioConfig { cr: 9, ..base }.validate(power_range).is_err());
-    }
-
-    #[test]
-    fn validate_tx_power_max_sentinel() {
-        let cfg = RadioConfig { tx_power_dbm: TX_POWER_MAX, ..make_config() };
-        assert!(cfg.validate((-9, 22)).is_ok());
-    }
-
-    #[test]
-    fn validate_tx_power_out_of_range() {
-        let cfg = RadioConfig { tx_power_dbm: 23, ..make_config() };
-        assert!(cfg.validate((-9, 22)).is_err());
-
-        let cfg = RadioConfig { tx_power_dbm: -10, ..make_config() };
-        assert!(cfg.validate((-9, 22)).is_err());
-    }
-
-    #[test]
-    fn validate_preamble_default_sentinel() {
-        let cfg = RadioConfig { preamble_len: PREAMBLE_DEFAULT, ..make_config() };
-        assert!(cfg.validate((-9, 22)).is_ok());
-    }
-
-    #[test]
-    fn validate_preamble_boundaries() {
-        let power_range = (-9, 22);
-        let base = make_config();
-
-        assert!(RadioConfig { preamble_len: 6, ..base }.validate(power_range).is_ok());
-        assert!(RadioConfig { preamble_len: 5, ..base }.validate(power_range).is_err());
-    }
-
-    // ── RadioConfig::resolve ──────────────────────────────────────
-
-    #[test]
-    fn resolve_power_max_sentinel() {
-        let cfg = RadioConfig { tx_power_dbm: TX_POWER_MAX, ..make_config() };
-        assert_eq!(cfg.resolve((-9, 22)).tx_power_dbm, 22);
-    }
-
-    #[test]
-    fn resolve_power_explicit_unchanged() {
-        let cfg = RadioConfig { tx_power_dbm: 10, ..make_config() };
-        assert_eq!(cfg.resolve((-9, 22)).tx_power_dbm, 10);
-    }
-
-    #[test]
-    fn resolve_preamble_default() {
-        let cfg = RadioConfig { preamble_len: PREAMBLE_DEFAULT, ..make_config() };
-        assert_eq!(cfg.resolve((-9, 22)).preamble_len, 16);
-    }
-
-    #[test]
-    fn resolve_preamble_explicit_unchanged() {
-        let cfg = RadioConfig { preamble_len: 32, ..make_config() };
-        assert_eq!(cfg.resolve((-9, 22)).preamble_len, 32);
-    }
-
-    // ── Command::from_bytes ─────────────────────────────────────────
-
-    #[test]
-    fn command_ping() {
-        assert_eq!(Command::from_bytes(&[0]), Some(Command::Ping));
-    }
-
-    #[test]
-    fn command_get_config() {
-        assert_eq!(Command::from_bytes(&[1]), Some(Command::GetConfig));
-    }
-
-    #[test]
-    fn command_set_config() {
-        let cfg = make_config();
-        let mut buf = [0u8; 1 + RADIO_CONFIG_SIZE];
-        buf[0] = 2;
-        cfg.write_to(&mut buf[1..]);
-        assert_eq!(Command::from_bytes(&buf), Some(Command::SetConfig(cfg)));
-    }
-
-    #[test]
-    fn command_start_stop_rx() {
-        assert_eq!(Command::from_bytes(&[3]), Some(Command::StartRx));
-        assert_eq!(Command::from_bytes(&[4]), Some(Command::StopRx));
-    }
-
-    #[test]
-    fn command_transmit_no_config() {
-        let payload = b"hello";
-        let mut buf = [0u8; 64];
-        buf[0] = 5; // tag
-        buf[1] = 0; // has_config = false
-        buf[2..4].copy_from_slice(&(payload.len() as u16).to_le_bytes());
-        buf[4..9].copy_from_slice(payload);
-
-        match Command::from_bytes(&buf[..9]).unwrap() {
-            Command::Transmit { config, payload: p } => {
-                assert!(config.is_none());
-                assert_eq!(p.as_slice(), b"hello");
-            }
-            _ => panic!("expected Transmit"),
-        }
-    }
-
-    #[test]
-    fn command_transmit_with_config() {
-        let cfg = make_config();
-        let mut buf = [0u8; 64];
-        buf[0] = 5; // tag
-        buf[1] = 1; // has_config = true
-        cfg.write_to(&mut buf[2..]);
-        let payload = b"test";
-        let pos = 2 + RADIO_CONFIG_SIZE;
-        buf[pos..pos + 2].copy_from_slice(&(payload.len() as u16).to_le_bytes());
-        buf[pos + 2..pos + 6].copy_from_slice(payload);
-
-        match Command::from_bytes(&buf[..pos + 6]).unwrap() {
-            Command::Transmit { config, payload: p } => {
-                assert_eq!(config, Some(cfg));
-                assert_eq!(p.as_slice(), b"test");
-            }
-            _ => panic!("expected Transmit"),
-        }
-    }
-
-    #[test]
-    fn command_transmit_empty_payload() {
-        let mut buf = [0u8; 4];
-        buf[0] = 5; // tag
-        buf[1] = 0; // has_config = false
-        buf[2..4].copy_from_slice(&0u16.to_le_bytes());
-
-        match Command::from_bytes(&buf).unwrap() {
-            Command::Transmit { config, payload } => {
-                assert!(config.is_none());
-                assert!(payload.is_empty());
-            }
-            _ => panic!("expected Transmit"),
-        }
-    }
-
-    #[test]
-    fn command_transmit_truncated() {
-        // Tag only — missing has_config byte
-        assert!(Command::from_bytes(&[5]).is_none());
-
-        // has_config=1 but no config bytes
-        assert!(Command::from_bytes(&[5, 1]).is_none());
-
-        // has_config=0 but no length bytes
-        assert!(Command::from_bytes(&[5, 0]).is_none());
-
-        // has_config=0, length says 5 but only 2 bytes of payload
-        let mut buf = [0u8; 6];
-        buf[0] = 5;
-        buf[1] = 0;
-        buf[2..4].copy_from_slice(&5u16.to_le_bytes());
-        buf[4] = 0xAA;
-        buf[5] = 0xBB;
-        assert!(Command::from_bytes(&buf).is_none());
-    }
-
-    #[test]
-    fn command_display_and_mac() {
-        assert_eq!(Command::from_bytes(&[6]), Some(Command::DisplayOn));
-        assert_eq!(Command::from_bytes(&[7]), Some(Command::DisplayOff));
-        assert_eq!(Command::from_bytes(&[8]), Some(Command::GetMac));
-    }
-
-    #[test]
-    fn command_invalid_tag() {
-        assert!(Command::from_bytes(&[9]).is_none());
-        assert!(Command::from_bytes(&[255]).is_none());
-    }
-
-    #[test]
-    fn command_empty_buffer() {
-        assert!(Command::from_bytes(&[]).is_none());
-    }
-
-    // ── Response::write_to ──────────────────────────────────────────
-
-    #[test]
-    fn response_pong() {
-        let mut buf = [0u8; 1];
-        assert_eq!(Response::Pong.write_to(&mut buf), 1);
-        assert_eq!(buf[0], 0);
-    }
-
-    #[test]
-    fn response_config() {
-        let cfg = make_config();
-        let mut buf = [0u8; 1 + RADIO_CONFIG_SIZE];
-        let n = Response::Config(cfg).write_to(&mut buf);
-        assert_eq!(n, 1 + RADIO_CONFIG_SIZE);
-        assert_eq!(buf[0], 1);
-        assert_eq!(RadioConfig::from_bytes(&buf[1..]), Some(cfg));
-    }
-
-    #[test]
-    fn response_rx_packet() {
-        let mut payload = Vec::new();
-        let _ = payload.extend_from_slice(b"data");
-        let mut buf = [0u8; 64];
-        let n = Response::RxPacket { rssi: -80, snr: 10, payload }.write_to(&mut buf);
-        assert_eq!(n, 7 + 4); // tag(1) + rssi(2) + snr(2) + len(2) + "data"(4)
-        assert_eq!(buf[0], 2);
-        assert_eq!(i16::from_le_bytes([buf[1], buf[2]]), -80);
-        assert_eq!(i16::from_le_bytes([buf[3], buf[4]]), 10);
-        assert_eq!(u16::from_le_bytes([buf[5], buf[6]]), 4);
-        assert_eq!(&buf[7..11], b"data");
-    }
-
-    #[test]
-    fn response_tx_done() {
-        let mut buf = [0u8; 1];
-        assert_eq!(Response::TxDone.write_to(&mut buf), 1);
-        assert_eq!(buf[0], 3);
-    }
-
-    #[test]
-    fn response_ok() {
-        let mut buf = [0u8; 1];
-        assert_eq!(Response::Ok.write_to(&mut buf), 1);
-        assert_eq!(buf[0], 4);
-    }
-
-    #[test]
-    fn response_error_codes() {
-        let mut buf = [0u8; 2];
-        for (code, val) in [
-            (ErrorCode::InvalidConfig, 0),
-            (ErrorCode::RadioBusy, 1),
-            (ErrorCode::TxTimeout, 2),
-            (ErrorCode::CrcError, 3),
-            (ErrorCode::NotConfigured, 4),
-            (ErrorCode::NoDisplay, 5),
-        ] {
-            let n = Response::Error(code).write_to(&mut buf);
-            assert_eq!(n, 2);
-            assert_eq!(buf[0], 5);
-            assert_eq!(buf[1], val);
-        }
-    }
-
-    #[test]
-    fn response_mac_address() {
-        let mac = [0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF];
-        let mut buf = [0u8; 7];
-        let n = Response::MacAddress(mac).write_to(&mut buf);
-        assert_eq!(n, 7);
-        assert_eq!(buf[0], 6);
-        assert_eq!(&buf[1..7], &mac);
-    }
-}
+//! Wire definitions live in the `donglora-protocol` crate so host-side
+//! Rust projects can share them with the firmware without duplicating
+//! wire layouts. This module re-exports them unchanged so firmware
+//! modules can `use crate::protocol::*;`.
+
+#[allow(unused_imports)]
+pub use donglora_protocol::{
+    cap, commands, encode_frame, events, Command, CommandParseError, DeviceMessage,
+    DeviceMessageParseError, ErrorCode, FlrcConfig, FrameDecoder, FrameEncodeError, FrameResult,
+    FskConfig, Info, InfoParseError, LoRaBandwidth, LoRaCodingRate, LoRaConfig, LoRaHeaderMode,
+    LrFhssConfig, Modulation, ModulationId, OkPayload, Owner, RadioChipId, RxOrigin, RxPayload,
+    SetConfigResult, SetConfigResultCode, TxDonePayload, TxFlags, TxResult, MAX_MCU_UID_LEN,
+    MAX_OK_PAYLOAD, MAX_OTA_PAYLOAD, MAX_PAYLOAD_FIELD, MAX_RADIO_UID_LEN, MAX_WIRE_FRAME,
+};

src/radio.rs

@@ -0,0 +1,884 @@
+//! LoRa radio task: SX1262 statechart driven by DongLoRa Protocol v2 host commands.
+//!
+//! ```text
+//! Radio
+//! ├── Unconfigured   (default)   no config cached → RF ops rejected
+//! └── Configured
+//!     ├── Idle          (default)  ready, waiting
+//!     ├── StartingRx              brief: HW init in response to host
+//!     │                           RxStart; responds Ok/Err then →
+//!     │                           Receiving (Ok) or Idle (Err)
+//!     ├── Receiving               continuous RX
+//!     ├── ResumingRx              brief: post-TX HW re-arm; silent →
+//!     │                           Receiving (Ok) or Idle (Err)
+//!     └── Transmitting
+//!         ├── FromIdle (default)  TxDone → Idle
+//!         └── FromRx              TxDone → ResumingRx
+//! ```
+//!
+//! The task body is a single `machine.run().await`. Host commands flow in
+//! via the `CommandChannel` as `InboundCommand { tag, cmd }` envelopes;
+//! outbound D→H messages flow out via `OutboundChannel` as `OutboundFrame
+//! { tag, msg }` envelopes (tag `0` for async RX / async ERR, echoed tag
+//! for tag-correlated OK / ERR / TX_DONE).
+//!
+//! The `RadioInput` event variants intentionally do NOT carry the
+//! command tag. Tags are routing metadata — the `next_command` during
+//! activity stashes `incoming_tag` into context before emitting the
+//! corresponding event, and action handlers read it back from context
+//! when building responses. This keeps the hsmc DSL free of
+//! bindings-with-transition combos, which hsmc's macro forbids.
+
+use defmt::{error, info, warn};
+use embassy_executor::task;
+use embassy_time::{Delay, Instant};
+use heapless::Vec as HVec;
+use hsmc::statechart;
+use lora_phy::mod_params::RadioError;
+use lora_phy::{LoRa, RxMode};
+
+use crate::board::{RadioDriver, RadioParts};
+use crate::channel::{
+    CommandChannel, InboundEvent, OutboundChannel, OutboundFrame, RadioEvent, RadioEventChannel,
+};
+use crate::protocol::{
+    Command, DeviceMessage, ErrorCode, Info, LoRaBandwidth, LoRaCodingRate, LoRaConfig,
+    LoRaHeaderMode, Modulation, OkPayload, Owner, RxOrigin, RxPayload, SetConfigResult,
+    SetConfigResultCode, TxDonePayload, TxResult, MAX_OTA_PAYLOAD,
+};
+
+// LBT retry timing lives in `crate::lbt` — the math is pure and
+// host-testable, so it's split out of this (HW-gated) module.
+use crate::lbt::{
+    cad_retries, jittered_sleep_us, toa_us, CAD_ASSUMED_PEER_PAYLOAD_B, CAD_BUDGET_US,
+};
+
+type LoRaDriver = LoRa<RadioDriver, Delay>;
+
+// ── Pending TX staging ──────────────────────────────────────────────
+
+/// A TX request accepted by the radio task but not yet on the air.
+/// Carries the tag so the eventual `TX_DONE` echoes it.
+#[derive(Debug, Clone)]
+pub struct PendingTx {
+    pub tag: u16,
+    pub skip_cad: bool,
+    pub data: HVec<u8, MAX_OTA_PAYLOAD>,
+    pub config: LoRaConfig,
+}
+
+// ── Events driving the statechart ───────────────────────────────────
+//
+// Per-event tags are NOT carried on these variants (see module doc):
+// `next_command` stashes `ctx.incoming_tag` before emitting.
+
+#[allow(clippy::large_enum_variant)]
+#[derive(Debug, Clone)]
+pub enum RadioInput {
+    CmdPing,
+    CmdGetInfo,
+    CmdSetConfig(Modulation),
+    /// TX request. The stashed tag + flags + data sit on the context's
+    /// `pending_tx` slot (filled by `next_command`); this event merely
+    /// wakes the chart.
+    CmdTx,
+    CmdRxStart,
+    CmdRxStop,
+
+    /// Host-transport disconnect / liveness timeout: park the radio.
+    Reset,
+
+    /// Internal: emitted by `apply_set_config` on a successful LoRa
+    /// configuration apply. Drives the Unconfigured → Configured
+    /// transition. No-op when dispatched in Configured.
+    ConfigApplied,
+    /// Internal: emitted by `apply_set_config` when the SPI write to the
+    /// radio failed mid-configuration (spec §6.3). Drives Configured →
+    /// Unconfigured; no-op in Unconfigured.
+    ConfigFailedRadio,
+
+    PacketReceived(RxPayload),
+    RxFailed,
+    StartRxOk,
+    StartRxFailed,
+    TransmitDone {
+        airtime_us: u32,
+    },
+    ChannelBusy,
+    TransmitFailed,
+
+    /// Internal: emitted by `bump_resume_retries` when another
+    /// `try_start_rx_hw` attempt is allowed. Drives a self-transition on
+    /// `ResumingRx` so the entry action runs again after a short backoff.
+    ResumeRxRetry,
+    /// Internal: emitted by `bump_resume_retries` after
+    /// `MAX_RESUME_RETRIES` attempts have failed — the chip is genuinely
+    /// wedged; fall through to `Idle` so the host can reconfigure.
+    ResumeRxExhausted,
+}
+
+/// How many back-to-back `try_start_rx_hw` failures to tolerate in
+/// `ResumingRx` before giving up and parking in `Idle`. 5 × 25 ms ≈
+/// 125 ms worst-case resume window, enough to ride out SX1262
+/// post-TX timing flukes without pegging the CPU on a dead chip.
+const MAX_RESUME_RETRIES: u8 = 5;
+
+/// Backoff between `ResumingRx` retry attempts.
+const RESUME_RX_RETRY_BACKOFF_MS: u64 = 25;
+
+// ── Context ─────────────────────────────────────────────────────────
+
+pub struct RadioContext {
+    pub commands: &'static CommandChannel,
+    pub outbound: &'static OutboundChannel,
+    pub events: &'static RadioEventChannel,
+    pub info: &'static Info,
+    pub lora: LoRaDriver,
+    pub rx_buf: [u8; MAX_OTA_PAYLOAD],
+    /// Active LoRa config. `None` in `Unconfigured`; `Some(cfg)` in
+    /// `Configured` (LoRa is the only modulation the firmware drives
+    /// today; others are rejected upstream with `EMODULATION`).
+    pub config: Option<LoRaConfig>,
+    pub pending_tx: Option<PendingTx>,
+    /// Packets dropped since the previous successfully-delivered RX event.
+    pub packets_dropped: u16,
+    /// Tag of the command currently being handled. Written by
+    /// `next_command` just before emitting the event; read by action
+    /// handlers to construct tag-echoed responses.
+    pub incoming_tag: u16,
+    /// Tag of the TX currently on the wire. Captured on entry to
+    /// `Transmitting`; consumed by `respond_tx_*` handlers.
+    pub last_tx_tag: Option<u16>,
+    /// Tag of a pending `RX_START`, pulled by `respond_ok_start_rx` /
+    /// `respond_err_start_rx` once the chip reports back.
+    pub pending_rx_start_tag: Option<u16>,
+    /// Number of consecutive `try_start_rx_hw` failures while in
+    /// `ResumingRx`. Reset on any `StartRxOk`. See `MAX_RESUME_RETRIES`
+    /// for the limit before falling through to `Idle`.
+    pub resume_retries: u8,
+    /// Per-CAD-retry sleep in microseconds: time-on-air for a
+    /// `CAD_ASSUMED_PEER_PAYLOAD_B`-byte packet under the current
+    /// config. Recomputed on every successful `SET_CONFIG`; `0` while
+    /// `Unconfigured` (the CAD path is unreachable without a config).
+    pub cad_retry_delay_us: u32,
+}
+
+impl RadioContext {
+    fn announce(&self, ev: RadioEvent) {
+        if self.events.try_send(ev).is_err() {
+            warn!("radio event dropped: downstream queue full");
+        }
+    }
+
+    async fn send(&self, tag: u16, msg: DeviceMessage) {
+        self.outbound.send(OutboundFrame { tag, msg }).await;
+    }
+}
+
+// ── Statechart ─────────────────────────────────────────────────────
+
+statechart! {
+    Radio {
+        context: RadioContext;
+        events: RadioInput;
+        default(Unconfigured);
+
+        // Globals: PING always answers; GET_INFO always answers; Reset
+        // forces Unconfigured.
+        on(CmdPing) => respond_pong;
+        on(CmdGetInfo) => respond_info;
+        on(Reset) => reset_to_unconfigured, Unconfigured;
+
+        state Unconfigured {
+            during: next_command(commands, incoming_tag, pending_tx);
+            on(CmdSetConfig(m: Modulation)) => apply_set_config;
+            on(ConfigApplied) => Configured;
+            on(CmdTx) => reject_tx_not_configured;
+            on(CmdRxStart) => reject_not_configured;
+            on(CmdRxStop) => reject_not_configured;
+        }
+
+        state Configured {
+            on(CmdSetConfig(m: Modulation)) => apply_set_config;
+            on(ConfigFailedRadio) => Unconfigured;
+            // Default post-reconfigure landing is Idle. The RX ring is
+            // always cleared as part of apply_set_config. Receiving
+            // overrides this handler to auto-resume RX with the new
+            // parameters (spec §3.5) so callers do not need to re-issue
+            // RX_START after SET_CONFIG.
+            on(ConfigApplied) => Idle;
+            default(Idle);
+
+            state Idle {
+                entry: announce_idle;
+                during: next_command(commands, incoming_tag, pending_tx);
+                on(CmdRxStart) => stage_rx_start;
+                on(CmdRxStart) => StartingRx;
+                on(CmdTx) => TransmittingFromIdle;
+                on(CmdRxStop) => respond_ok;
+            }
+
+            state StartingRx {
+                entry: try_start_rx_hw;
+                on(StartRxOk) => respond_ok_start_rx, Receiving;
+                on(StartRxFailed) => respond_err_start_rx, Idle;
+            }
+
+            state Receiving {
+                entry: announce_entered_rx;
+                during: next_command(commands, incoming_tag, pending_tx);
+                during: next_packet(lora, rx_buf, config);
+                on(CmdRxStart) => respond_ok;
+                on(PacketReceived(rx: RxPayload)) => record_packet;
+                // Transient driver error during `next_packet` — re-arm
+                // the chip via ResumingRx rather than parking in Idle
+                // (which would bounce the OLED and leave the radio
+                // waiting for a client-initiated RX_START that will
+                // never come because clients already think RX is up).
+                on(RxFailed) => ResumingRx;
+                on(CmdRxStop) => stop_rx_hw, respond_ok;
+                on(CmdRxStop) => Idle;
+                on(CmdTx) => TransmittingFromRx;
+                // Spec §3.5: a SET_CONFIG issued while receiving clears
+                // the RX ring (already handled by apply_set_config) but
+                // auto-rearms RX with the new parameters — the caller
+                // does not need to send a fresh RX_START. Override the
+                // parent's `on(ConfigApplied) => Idle` by landing in
+                // ResumingRx, whose entry kicks the chip back into RX.
+                on(ConfigApplied) => ResumingRx;
+            }
+
+            // Bounded-retry RX re-arm. Entered after every TX while
+            // already receiving, on RX driver errors, and on mid-session
+            // SET_CONFIG. If `try_start_rx_hw` succeeds we land cleanly
+            // in Receiving; if it fails we back off and retry, only
+            // conceding to Idle after MAX_RESUME_RETRIES attempts (chip
+            // is genuinely wedged at that point).
+            state ResumingRx {
+                entry: try_start_rx_hw;
+                on(StartRxOk) => reset_resume_retries, Receiving;
+                on(StartRxFailed) => bump_resume_retries;
+                on(ResumeRxRetry) => ResumingRx;
+                on(ResumeRxExhausted) => Idle;
+            }
+
+            state Transmitting {
+                entry: announce_entered_tx;
+                exit: announce_packet_tx;
+                default(TransmittingFromIdle);
+
+                state TransmittingFromIdle {
+                    during: perform_tx(lora, pending_tx, cad_retry_delay_us);
+                    on(TransmitDone { airtime_us: u32 }) => respond_tx_done;
+                    on(TransmitDone) => Idle;
+                    on(ChannelBusy) => respond_tx_channel_busy, Idle;
+                    on(TransmitFailed) => respond_tx_failed, Idle;
+                }
+
+                state TransmittingFromRx {
+                    during: perform_tx(lora, pending_tx, cad_retry_delay_us);
+                    on(TransmitDone { airtime_us: u32 }) => respond_tx_done;
+                    on(TransmitDone) => ResumingRx;
+                    // Even on failure, we were receiving before the TX —
+                    // return to RX (the client still gets a TX_FAILED
+                    // reply via respond_tx_failed). Dropping to Idle here
+                    // would break the "RX session stays up" invariant.
+                    on(ChannelBusy) => respond_tx_channel_busy, ResumingRx;
+                    on(TransmitFailed) => respond_tx_failed, ResumingRx;
+                }
+            }
+        }
+    }
+}
+
+// ── during: activities ──────────────────────────────────────────────
+
+/// Read the next host command, stash its tag into context, and (for TX)
+/// stage a placeholder pending-TX struct before emitting the corresponding
+/// event. The `apply_set_config` / `try_start_rx_hw` / TX-staging actions
+/// patch in the real config from ctx when they run.
+async fn next_command(
+    commands: &mut &'static CommandChannel,
+    incoming_tag: &mut u16,
+    pending_tx: &mut Option<PendingTx>,
+) -> RadioInput {
+    match commands.receive().await {
+        InboundEvent::Reset => RadioInput::Reset,
+        InboundEvent::Command { tag, cmd } => {
+            *incoming_tag = tag;
+            match cmd {
+                Command::Ping => RadioInput::CmdPing,
+                Command::GetInfo => RadioInput::CmdGetInfo,
+                Command::SetConfig(m) => RadioInput::CmdSetConfig(m),
+                Command::Tx { flags, data } => {
+                    // Placeholder config: the real `ctx.config` is patched
+                    // in by `announce_entered_tx`. `reject_tx_not_configured`
+                    // (Unconfigured state) consumes this slot without
+                    // touching the config field.
+                    *pending_tx = Some(PendingTx {
+                        tag,
+                        skip_cad: flags.skip_cad,
+                        data,
+                        config: dummy_lora_config(),
+                    });
+                    RadioInput::CmdTx
+                }
+                Command::RxStart => RadioInput::CmdRxStart,
+                Command::RxStop => RadioInput::CmdRxStop,
+            }
+        }
+    }
+}
+
+async fn next_packet(
+    lora: &mut LoRaDriver,
+    rx_buf: &mut [u8; MAX_OTA_PAYLOAD],
+    config: &mut Option<LoRaConfig>,
+) -> RadioInput {
+    let Some(cfg) = config.as_ref() else {
+        return RadioInput::RxFailed;
+    };
+    let mdltn = match to_lora_mod_params(lora, cfg) {
+        Ok(m) => m,
+        Err(_) => return RadioInput::RxFailed,
+    };
+    let pkt = match lora.create_rx_packet_params(
+        cfg.preamble_len,
+        matches!(cfg.header_mode, LoRaHeaderMode::Implicit),
+        MAX_OTA_PAYLOAD as u8,
+        cfg.payload_crc,
+        cfg.iq_invert,
+        &mdltn,
+    ) {
+        Ok(p) => p,
+        Err(_) => return RadioInput::RxFailed,
+    };
+    match lora.rx(&pkt, rx_buf).await {
+        Ok((len, status)) => {
+            let ts_us = Instant::now().as_micros();
+            let copy_len = (len as usize).min(MAX_OTA_PAYLOAD);
+            let mut data: HVec<u8, MAX_OTA_PAYLOAD> = HVec::new();
+            let _ = data.extend_from_slice(&rx_buf[..copy_len]);
+            RadioInput::PacketReceived(RxPayload {
+                rssi_tenths_dbm: (status.rssi as i32 * 10) as i16,
+                snr_tenths_db: (status.snr as i32 * 10) as i16,
+                // lora-phy 3.0's RxStatus doesn't expose FreqErr; 0 for now.
+                freq_err_hz: 0,
+                timestamp_us: ts_us,
+                // SX126x silently drops bad-CRC packets at the chip; any
+                // packet arriving here passed CRC.
+                crc_valid: true,
+                packets_dropped: 0, // filled in by record_packet
+                origin: RxOrigin::Ota,
+                data,
+            })
+        }
+        Err(_) => RadioInput::RxFailed,
+    }
+}
+
+async fn perform_tx(
+    lora: &mut LoRaDriver,
+    pending: &mut Option<PendingTx>,
+    cad_retry_delay_us: &mut u32,
+) -> RadioInput {
+    #[cfg(feature = "debug-checkpoint")]
+    crate::debug_blink::set(6);
+    let Some(tx) = pending.take() else {
+        return RadioInput::TransmitFailed;
+    };
+    // Scale CAD retry count to the cached per-retry sleep: fewer retries
+    // when each one-full-packet wait is expensive (slow SFs). When the
+    // one-packet wait exceeds the total budget, the helper returns
+    // `retries = 1` — a single CAD, bail on busy, no sleep.
+    let (retries, sleep_us) = cad_retries(*cad_retry_delay_us);
+    let start = Instant::now();
+    match do_tx(lora, &tx, retries, sleep_us).await {
+        Ok(TxOutcome::Transmitted) => RadioInput::TransmitDone {
+            airtime_us: Instant::now().duration_since(start).as_micros() as u32,
+        },
+        Ok(TxOutcome::ChannelBusy) => RadioInput::ChannelBusy,
+        Err(_) => {
+            #[cfg(feature = "debug-checkpoint")]
+            crate::debug_blink::set(15);
+            RadioInput::TransmitFailed
+        }
+    }
+}
+
+// ── Actions ─────────────────────────────────────────────────────────
+
+impl RadioActions for RadioActionContext<'_> {
+    // ── PING / GET_INFO ───────────────────────────────────────────────
+
+    async fn respond_pong(&mut self) {
+        let tag = self.incoming_tag;
+        self.send(tag, DeviceMessage::Ok(OkPayload::Empty)).await;
+    }
+
+    async fn respond_info(&mut self) {
+        let tag = self.incoming_tag;
+        let info = *self.info;
+        self.send(tag, DeviceMessage::Ok(OkPayload::Info(info)))
+            .await;
+    }
+
+    // ── SET_CONFIG ────────────────────────────────────────────────────
+
+    async fn apply_set_config(&mut self, m: Modulation) {
+        let tag = self.incoming_tag;
+        match m {
+            Modulation::LoRa(cfg) => {
+                if let Err(code) = validate_lora(&cfg, self.info) {
+                    // Validation failure: radio + state unchanged (spec §3.5).
+                    self.send(tag, DeviceMessage::Err(code)).await;
+                    return;
+                }
+                // Cancel any queued-but-not-started TX per spec §3.5.
+                if let Some(cancelled) = self.pending_tx.take() {
+                    let td = TxDonePayload {
+                        result: TxResult::Cancelled,
+                        airtime_us: 0,
+                    };
+                    self.send(cancelled.tag, DeviceMessage::TxDone(td)).await;
+                }
+                if let Err(_e) = reconfigure_radio(&mut self.lora, &cfg).await {
+                    // Hardware failure: drop to Unconfigured (spec §6.3).
+                    self.config = None;
+                    self.cad_retry_delay_us = 0;
+                    self.send(tag, DeviceMessage::Err(ErrorCode::ERadio)).await;
+                    let _ = self.emit(RadioInput::ConfigFailedRadio);
+                    return;
+                }
+                self.config = Some(cfg);
+                self.cad_retry_delay_us = toa_us(&cfg, CAD_ASSUMED_PEER_PAYLOAD_B);
+                if self.cad_retry_delay_us > CAD_BUDGET_US {
+                    defmt::debug!(
+                        "LBT degraded: assumed-packet ToA {=u32} us > budget {=u32} us; single-CAD-and-bail",
+                        self.cad_retry_delay_us,
+                        CAD_BUDGET_US
+                    );
+                }
+                self.packets_dropped = 0;
+                self.announce(RadioEvent::ConfigChanged(cfg));
+                let result = SetConfigResult {
+                    result: SetConfigResultCode::Applied,
+                    owner: Owner::Mine,
+                    current: Modulation::LoRa(cfg),
+                };
+                self.send(tag, DeviceMessage::Ok(OkPayload::SetConfig(result)))
+                    .await;
+                // Drive the Unconfigured → Configured transition (no-op in
+                // Configured — there's no handler for this event there).
+                let _ = self.emit(RadioInput::ConfigApplied);
+            }
+            _ => {
+                self.send(tag, DeviceMessage::Err(ErrorCode::EModulation))
+                    .await;
+            }
+        }
+    }
+
+    // ── TX ────────────────────────────────────────────────────────────
+
+    async fn reject_tx_not_configured(&mut self) {
+        if let Some(pt) = self.pending_tx.take() {
+            self.send(pt.tag, DeviceMessage::Err(ErrorCode::ENotConfigured))
+                .await;
+        }
+    }
+
+    async fn respond_tx_done(&mut self, airtime_us: u32) {
+        if let Some(tag) = self.last_tx_tag.take() {
+            let td = TxDonePayload {
+                result: TxResult::Transmitted,
+                airtime_us,
+            };
+            self.send(tag, DeviceMessage::TxDone(td)).await;
+        }
+    }
+
+    async fn respond_tx_channel_busy(&mut self) {
+        if let Some(tag) = self.last_tx_tag.take() {
+            let td = TxDonePayload {
+                result: TxResult::ChannelBusy,
+                airtime_us: 0,
+            };
+            self.send(tag, DeviceMessage::TxDone(td)).await;
+        }
+    }
+
+    async fn respond_tx_failed(&mut self) {
+        if let Some(tag) = self.last_tx_tag.take() {
+            self.send(tag, DeviceMessage::Err(ErrorCode::ERadio)).await;
+        }
+    }
+
+    // ── RX_START / RX_STOP ────────────────────────────────────────────
+
+    async fn stage_rx_start(&mut self) {
+        self.pending_rx_start_tag = Some(self.incoming_tag);
+    }
+
+    async fn try_start_rx_hw(&mut self) {
+        let Some(cfg) = self.config else {
+            error!("try_start_rx_hw: no config cached — state invariant broken");
+            let _ = self.emit(RadioInput::StartRxFailed);
+            return;
+        };
+        match start_rx(&mut self.lora, &cfg).await {
+            Ok(()) => {
+                let _ = self.emit(RadioInput::StartRxOk);
+            }
+            Err(e) => {
+                warn!("start_rx failed: {}", e);
+                let _ = self.emit(RadioInput::StartRxFailed);
+            }
+        }
+    }
+
+    async fn reset_resume_retries(&mut self) {
+        self.resume_retries = 0;
+    }
+
+    async fn bump_resume_retries(&mut self) {
+        self.resume_retries = self.resume_retries.saturating_add(1);
+        if self.resume_retries >= MAX_RESUME_RETRIES {
+            warn!(
+                "ResumingRx: {} failed attempts, giving up to Idle",
+                self.resume_retries
+            );
+            self.resume_retries = 0;
+            let _ = self.emit(RadioInput::ResumeRxExhausted);
+            return;
+        }
+        // Short backoff before the next `try_start_rx_hw` cycle. The
+        // self-transition on ResumingRx (driven by ResumeRxRetry) will
+        // re-run the entry action.
+        embassy_time::Timer::after_millis(RESUME_RX_RETRY_BACKOFF_MS).await;
+        let _ = self.emit(RadioInput::ResumeRxRetry);
+    }
+
+    async fn respond_ok(&mut self) {
+        let tag = self.incoming_tag;
+        self.send(tag, DeviceMessage::Ok(OkPayload::Empty)).await;
+    }
+
+    async fn respond_ok_start_rx(&mut self) {
+        if let Some(tag) = self.pending_rx_start_tag.take() {
+            self.send(tag, DeviceMessage::Ok(OkPayload::Empty)).await;
+        }
+    }
+
+    async fn respond_err_start_rx(&mut self) {
+        if let Some(tag) = self.pending_rx_start_tag.take() {
+            self.send(tag, DeviceMessage::Err(ErrorCode::ERadio)).await;
+        }
+    }
+
+    async fn reject_not_configured(&mut self) {
+        let tag = self.incoming_tag;
+        self.send(tag, DeviceMessage::Err(ErrorCode::ENotConfigured))
+            .await;
+    }
+
+    async fn stop_rx_hw(&mut self) {
+        let _ = self.lora.enter_standby().await;
+    }
+
+    // ── Reset (disconnect / inactivity timeout) ──────────────────────
+
+    async fn reset_to_unconfigured(&mut self) {
+        self.pending_tx = None;
+        self.last_tx_tag = None;
+        self.pending_rx_start_tag = None;
+        self.config = None;
+        self.packets_dropped = 0;
+        let _ = self.lora.enter_standby().await;
+        self.announce(RadioEvent::Idle);
+    }
+
+    // ── Announcements ─────────────────────────────────────────────────
+
+    async fn announce_idle(&mut self) {
+        self.announce(RadioEvent::Idle);
+    }
+
+    async fn announce_entered_rx(&mut self) {
+        self.announce(RadioEvent::EnteredRx);
+    }
+
+    async fn announce_entered_tx(&mut self) {
+        // Patch the staged TX's config to whatever's active now. The
+        // tag and data stay exactly as the host sent them.
+        if let (Some(cfg), Some(pt)) = (self.config, self.pending_tx.as_mut()) {
+            pt.config = cfg;
+        }
+        if let Some(pt) = self.pending_tx.as_ref() {
+            self.last_tx_tag = Some(pt.tag);
+        }
+        self.announce(RadioEvent::EnteredTx);
+    }
+
+    async fn announce_packet_tx(&mut self) {
+        self.announce(RadioEvent::PacketTx);
+    }
+
+    // ── Packet bookkeeping ────────────────────────────────────────────
+
+    async fn record_packet(&mut self, rx: RxPayload) {
+        let rssi_dbm = rx.rssi_tenths_dbm / 10;
+        let snr_db = Some(rx.snr_tenths_db / 10);
+        self.announce(RadioEvent::PacketRx {
+            rssi: rssi_dbm,
+            snr: snr_db,
+        });
+        let mut rx = rx;
+        rx.packets_dropped = self.packets_dropped;
+        let delivered = self
+            .outbound
+            .try_send(OutboundFrame {
+                tag: 0,
+                msg: DeviceMessage::Rx(rx),
+            })
+            .is_ok();
+        if delivered {
+            self.packets_dropped = 0;
+        } else {
+            warn!("RX dropped: outbound queue full");
+            self.packets_dropped = self.packets_dropped.saturating_add(1);
+        }
+    }
+}
+
+// ── LoRa helpers ────────────────────────────────────────────────────
+
+enum TxOutcome {
+    Transmitted,
+    ChannelBusy,
+}
+
+fn to_bw(bw: LoRaBandwidth) -> Option<lora_phy::mod_params::Bandwidth> {
+    use lora_phy::mod_params::Bandwidth::*;
+    Some(match bw {
+        LoRaBandwidth::Khz7 => _7KHz,
+        LoRaBandwidth::Khz10 => _10KHz,
+        LoRaBandwidth::Khz15 => _15KHz,
+        LoRaBandwidth::Khz20 => _20KHz,
+        LoRaBandwidth::Khz31 => _31KHz,
+        LoRaBandwidth::Khz41 => _41KHz,
+        LoRaBandwidth::Khz62 => _62KHz,
+        LoRaBandwidth::Khz125 => _125KHz,
+        LoRaBandwidth::Khz250 => _250KHz,
+        LoRaBandwidth::Khz500 => _500KHz,
+        LoRaBandwidth::Khz200
+        | LoRaBandwidth::Khz400
+        | LoRaBandwidth::Khz800
+        | LoRaBandwidth::Khz1600 => return None,
+    })
+}
+
+fn to_sf(sf: u8) -> Option<lora_phy::mod_params::SpreadingFactor> {
+    use lora_phy::mod_params::SpreadingFactor::*;
+    Some(match sf {
+        5 => _5,
+        6 => _6,
+        7 => _7,
+        8 => _8,
+        9 => _9,
+        10 => _10,
+        11 => _11,
+        12 => _12,
+        _ => return None,
+    })
+}
+
+fn to_cr(cr: LoRaCodingRate) -> lora_phy::mod_params::CodingRate {
+    use lora_phy::mod_params::CodingRate::*;
+    match cr {
+        LoRaCodingRate::Cr4_5 => _4_5,
+        LoRaCodingRate::Cr4_6 => _4_6,
+        LoRaCodingRate::Cr4_7 => _4_7,
+        LoRaCodingRate::Cr4_8 => _4_8,
+    }
+}
+
+fn to_lora_mod_params(
+    lora: &mut LoRaDriver,
+    cfg: &LoRaConfig,
+) -> Result<lora_phy::mod_params::ModulationParams, RadioError> {
+    let sf = to_sf(cfg.sf).ok_or(RadioError::UnavailableSpreadingFactor)?;
+    let bw = to_bw(cfg.bw).ok_or(RadioError::UnavailableBandwidth)?;
+    let cr = to_cr(cfg.cr);
+    lora.create_modulation_params(sf, bw, cr, cfg.freq_hz)
+}
+
+async fn start_rx(lora: &mut LoRaDriver, cfg: &LoRaConfig) -> Result<(), RadioError> {
+    let mdltn = to_lora_mod_params(lora, cfg)?;
+    let pkt = lora.create_rx_packet_params(
+        cfg.preamble_len,
+        matches!(cfg.header_mode, LoRaHeaderMode::Implicit),
+        MAX_OTA_PAYLOAD as u8,
+        cfg.payload_crc,
+        cfg.iq_invert,
+        &mdltn,
+    )?;
+    lora.prepare_for_rx(RxMode::Continuous, &mdltn, &pkt).await
+}
+
+async fn reconfigure_radio(lora: &mut LoRaDriver, cfg: &LoRaConfig) -> Result<(), RadioError> {
+    lora.enter_standby().await?;
+    // Calibrate image etc. via a throwaway create_modulation_params call
+    // — inside the SET_CONFIG OK window so first TX/RX is fast.
+    let _ = to_lora_mod_params(lora, cfg)?;
+    Ok(())
+}
+
+async fn do_tx(
+    lora: &mut LoRaDriver,
+    tx: &PendingTx,
+    retries: u8,
+    sleep_us: u32,
+) -> Result<TxOutcome, RadioError> {
+    let mdltn = to_lora_mod_params(lora, &tx.config)?;
+
+    if !tx.skip_cad {
+        #[cfg(feature = "debug-checkpoint")]
+        crate::debug_blink::set(7);
+        lora.prepare_for_cad(&mdltn).await?;
+        // Reaches here → prepare_for_cad (SPI setup) completed.
+        // Hang past here means lora.cad() is waiting on DIO1.
+        #[cfg(feature = "debug-checkpoint")]
+        crate::debug_blink::set(19);
+        let mut saw_activity = false;
+        for i in 0..retries {
+            if !lora.cad(&mdltn).await? {
+                saw_activity = false;
+                break;
+            }
+            saw_activity = true;
+            // Skip the trailing sleep: if the last CAD was busy, we're
+            // about to return ChannelBusy, so sleeping + re-preparing
+            // is wasted work.
+            if i + 1 == retries {
+                break;
+            }
+            let entropy = embassy_time::Instant::now().as_ticks() as u32;
+            let jittered_us = jittered_sleep_us(sleep_us, entropy);
+            embassy_time::Timer::after(embassy_time::Duration::from_micros(jittered_us as u64))
+                .await;
+            lora.prepare_for_cad(&mdltn).await?;
+        }
+        if saw_activity {
+            return Ok(TxOutcome::ChannelBusy);
+        }
+    }
+
+    let mut tx_pkt = lora.create_tx_packet_params(
+        tx.config.preamble_len,
+        matches!(tx.config.header_mode, LoRaHeaderMode::Implicit),
+        tx.config.payload_crc,
+        tx.config.iq_invert,
+        &mdltn,
+    )?;
+    #[cfg(feature = "debug-checkpoint")]
+    crate::debug_blink::set(8);
+    lora.prepare_for_tx(&mdltn, &mut tx_pkt, tx.config.tx_power_dbm as i32, &tx.data)
+        .await?;
+    #[cfg(feature = "debug-checkpoint")]
+    crate::debug_blink::set(9);
+    lora.tx().await?;
+    #[cfg(feature = "debug-checkpoint")]
+    crate::debug_blink::set(10);
+    Ok(TxOutcome::Transmitted)
+}
+
+fn validate_lora(cfg: &LoRaConfig, info: &Info) -> Result<(), ErrorCode> {
+    if cfg.freq_hz < info.freq_min_hz || cfg.freq_hz > info.freq_max_hz {
+        return Err(ErrorCode::EParam);
+    }
+    if !(5..=12).contains(&cfg.sf) {
+        return Err(ErrorCode::EParam);
+    }
+    if info.supported_sf_bitmap & (1u16 << cfg.sf) == 0 {
+        return Err(ErrorCode::EParam);
+    }
+    if info.supported_bw_bitmap & (1u16 << cfg.bw.as_u8()) == 0 {
+        return Err(ErrorCode::EParam);
+    }
+    if cfg.tx_power_dbm < info.tx_power_min_dbm || cfg.tx_power_dbm > info.tx_power_max_dbm {
+        return Err(ErrorCode::EParam);
+    }
+    if cfg.preamble_len < 6 {
+        return Err(ErrorCode::EParam);
+    }
+    Ok(())
+}
+
+fn dummy_lora_config() -> LoRaConfig {
+    LoRaConfig {
+        freq_hz: 915_000_000,
+        sf: 7,
+        bw: LoRaBandwidth::Khz125,
+        cr: LoRaCodingRate::Cr4_5,
+        preamble_len: 8,
+        sync_word: 0x1424,
+        tx_power_dbm: 0,
+        header_mode: LoRaHeaderMode::Explicit,
+        payload_crc: true,
+        iq_invert: false,
+    }
+}
+
+// ── Task entry ──────────────────────────────────────────────────────
+
+#[task]
+pub async fn radio_task(
+    parts: RadioParts,
+    commands: &'static CommandChannel,
+    outbound: &'static OutboundChannel,
+    events: &'static RadioEventChannel,
+    info: &'static Info,
+) {
+    #[cfg(feature = "debug-checkpoint")]
+    crate::debug_blink::set(1);
+    let lora = match LoRa::new(parts.driver, false, parts.delay).await {
+        Ok(l) => {
+            info!("radio initialized");
+            #[cfg(feature = "debug-checkpoint")]
+            crate::debug_blink::set(2);
+            l
+        }
+        Err(e) => {
+            error!("radio init failed: {}", e);
+            #[cfg(feature = "debug-checkpoint")]
+            crate::debug_blink::set(16);
+            return;
+        }
+    };
+
+    let ctx = RadioContext {
+        commands,
+        outbound,
+        events,
+        info,
+        lora,
+        rx_buf: [0u8; MAX_OTA_PAYLOAD],
+        config: None,
+        pending_tx: None,
+        packets_dropped: 0,
+        incoming_tag: 0,
+        last_tx_tag: None,
+        pending_rx_start_tag: None,
+        resume_retries: 0,
+        cad_retry_delay_us: 0,
+    };
+
+    static RADIO_INTERNAL_CH: embassy_sync::channel::Channel<
+        embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex,
+        RadioInput,
+        8,
+    > = embassy_sync::channel::Channel::new();
+    let mut machine = Radio::new(ctx, &RADIO_INTERNAL_CH);
+    let _ = machine.run().await;
+}

src/radio/mod.rs

@@ -1,4 +0,0 @@
-//! LoRa radio control via SX1262.
-
-mod task;
-pub use task::radio_task;

src/radio/task.rs

@@ -1,376 +0,0 @@
-//! LoRa radio task: SX1262 state machine driven by host commands.
-//!
-//! Owns the radio peripheral exclusively. Receives [`Command`]s from the USB
-//! task, drives the SX1262 via [`lora_phy`], and sends [`Response`]s back.
-//! Publishes [`RadioStatus`] to the display task via a watch channel.
-//!
-//! # State machine
-//!
-//! ```text
-//! Idle ──StartRx──► Receiving ──StopRx──► Idle
-//!   │                    │
-//!   └──Transmit──► Transmitting ──TxDone──► (previous state)
-//! ```
-//!
-//! # Invariants
-//!
-//! - This task never panics. All errors are reported to the host or logged.
-//! - Config is validated before use (see [`RadioConfig::validate`]).
-
-use defmt::{error, info, warn};
-use embassy_executor::task;
-use embassy_futures::select::{select, Either};
-use embassy_time::Delay;
-use lora_phy::mod_params::RadioError;
-use lora_phy::{LoRa, RxMode};
-
-use crate::board::{Board, LoRaBoard, RadioDriver, RadioParts};
-use crate::channel::{CommandChannel, RadioState, RadioStatus, ResponseChannel, StatusWatch};
-use crate::protocol::{self, Command, ErrorCode, RadioConfig, Response};
-
-const MAX_PAYLOAD: usize = protocol::MAX_PAYLOAD;
-// TX power range comes from the board trait: Board::TX_POWER_RANGE
-
-type Radio = LoRa<RadioDriver, Delay>;
-
-// ── Fixed LoRa radio parameters ─────────────────────────────────────
-//
-// These are intentionally not host-configurable. They are sensible
-// defaults for a general-purpose LoRa pipe. Making them configurable
-// would add protocol complexity for marginal benefit.
-
-/// Explicit header mode (variable-length packets).
-const IMPLICIT_HEADER: bool = false;
-
-/// Enable CRC on received/transmitted packets.
-const CRC_ON: bool = true;
-
-/// Standard IQ polarity (not inverted).
-const IQ_INVERTED: bool = false;
-
-// ── Task entry point ────────────────────────────────────────────────
-
-#[task]
-pub async fn radio_task(
-    parts: RadioParts,
-    commands: &'static CommandChannel,
-    responses: &'static ResponseChannel,
-    status: &'static StatusWatch,
-) {
-    let mut state = RadioStatus::default();
-    status.sender().send(state.clone());
-
-    let mut lora = match LoRa::new(parts.driver, false, parts.delay).await {
-        Ok(l) => l,
-        Err(e) => {
-            error!("radio init failed: {}", e);
-            responses
-                .send(Response::Error(ErrorCode::InvalidConfig))
-                .await;
-            // Radio is non-functional — respond to commands but can't do RF.
-            loop {
-                let cmd = commands.receive().await;
-                if let Command::Ping = cmd {
-                    responses.send(Response::Pong).await;
-                } else {
-                    responses
-                        .send(Response::Error(ErrorCode::InvalidConfig))
-                        .await;
-                }
-            }
-        }
-    };
-
-    info!("radio initialized");
-    let mut rx_buf = [0u8; MAX_PAYLOAD];
-
-    loop {
-        if state.state == RadioState::Receiving {
-            // Defensive: config must be Some when Receiving. If not, recover.
-            let cfg = match state.config {
-                Some(c) => c,
-                None => {
-                    warn!("BUG: receiving without config, returning to idle");
-                    state.state = RadioState::Idle;
-                    status.sender().send(state.clone());
-                    continue;
-                }
-            };
-
-            match select(rx_once(&mut lora, &cfg, &mut rx_buf), commands.receive()).await {
-                Either::First(rx_result) => match rx_result {
-                    Ok((len, pkt_status)) => {
-                        state.rx_count = state.rx_count.wrapping_add(1);
-                        state.last_rssi = Some(pkt_status.rssi);
-                        state.last_snr = Some(pkt_status.snr);
-                        status.sender().send(state.clone());
-
-                        let copy_len = (len as usize).min(MAX_PAYLOAD);
-                        if (len as usize) > copy_len {
-                            warn!("RX payload truncated: {} > {}", len, MAX_PAYLOAD);
-                        }
-                        let mut payload = heapless::Vec::new();
-                        // copy_len <= MAX_PAYLOAD == Vec capacity, so this cannot fail.
-                        let _ = payload.extend_from_slice(&rx_buf[..copy_len]);
-
-                        responses
-                            .send(Response::RxPacket {
-                                rssi: pkt_status.rssi,
-                                snr: pkt_status.snr,
-                                payload,
-                            })
-                            .await;
-
-                        if let Err(e) = start_rx(&mut lora, &cfg).await {
-                            warn!("restart RX failed: {}", e);
-                            state.state = RadioState::Idle;
-                            status.sender().send(state.clone());
-                            responses
-                                .send(Response::Error(ErrorCode::RadioBusy))
-                                .await;
-                        }
-                    }
-                    Err(e) => {
-                        warn!("RX error: {}", e);
-                        if start_rx(&mut lora, &cfg).await.is_err() {
-                            state.state = RadioState::Idle;
-                            status.sender().send(state.clone());
-                            responses
-                                .send(Response::Error(ErrorCode::RadioBusy))
-                                .await;
-                        }
-                    }
-                },
-                Either::Second(cmd) => {
-                    handle_cmd(cmd, &mut lora, &mut state, responses, status).await;
-                }
-            }
-        } else {
-            let cmd = commands.receive().await;
-            handle_cmd(cmd, &mut lora, &mut state, responses, status).await;
-        }
-    }
-}
-
-// ── Command handler ─────────────────────────────────────────────────
-
-async fn handle_cmd(
-    cmd: Command,
-    lora: &mut Radio,
-    state: &mut RadioStatus,
-    responses: &ResponseChannel,
-    status: &StatusWatch,
-) {
-    match cmd {
-        Command::Ping => {
-            responses.send(Response::Pong).await;
-        }
-        Command::GetConfig => {
-            if let Some(cfg) = state.config {
-                responses.send(Response::Config(cfg)).await;
-            } else {
-                responses
-                    .send(Response::Error(ErrorCode::NotConfigured))
-                    .await;
-            }
-        }
-        Command::SetConfig(cfg) => {
-            if let Err(reason) = cfg.validate(Board::TX_POWER_RANGE) {
-                warn!("SetConfig rejected: {}", reason);
-                responses
-                    .send(Response::Error(ErrorCode::InvalidConfig))
-                    .await;
-            } else {
-                // Resolve TX_POWER_MAX sentinel to board's actual max
-                state.config = Some(cfg.resolve(Board::TX_POWER_RANGE));
-                status.sender().send(state.clone());
-                responses.send(Response::Ok).await;
-            }
-        }
-        Command::StartRx => {
-            if let Some(cfg) = state.config {
-                match start_rx(lora, &cfg).await {
-                    Ok(()) => {
-                        state.state = RadioState::Receiving;
-                        status.sender().send(state.clone());
-                        responses.send(Response::Ok).await;
-                    }
-                    Err(e) => {
-                        warn!("StartRx failed: {}", e);
-                        responses
-                            .send(Response::Error(ErrorCode::InvalidConfig))
-                            .await;
-                    }
-                }
-            } else {
-                responses
-                    .send(Response::Error(ErrorCode::NotConfigured))
-                    .await;
-            }
-        }
-        Command::StopRx => {
-            // Best-effort: if standby fails, radio is in unknown state
-            // but there's nothing useful we can do except continue.
-            let _ = lora.enter_standby().await;
-            state.state = RadioState::Idle;
-            status.sender().send(state.clone());
-            responses.send(Response::Ok).await;
-        }
-        Command::DisplayOn | Command::DisplayOff | Command::GetMac => {}
-        Command::Transmit { config, payload } => {
-            let tx_config = config.map(|c| c.resolve(Board::TX_POWER_RANGE)).or(state.config);
-            if let Some(cfg) = tx_config {
-                if let Err(reason) = cfg.validate(Board::TX_POWER_RANGE) {
-                    warn!("TX config rejected: {}", reason);
-                    responses
-                        .send(Response::Error(ErrorCode::InvalidConfig))
-                        .await;
-                    return;
-                }
-
-                let was_receiving = state.state == RadioState::Receiving;
-                state.state = RadioState::Transmitting;
-                status.sender().send(state.clone());
-
-                match do_tx(lora, &cfg, &payload).await {
-                    Ok(()) => {
-                        state.tx_count = state.tx_count.wrapping_add(1);
-                        responses.send(Response::TxDone).await;
-                    }
-                    Err(e) => {
-                        warn!("TX failed: {}", e);
-                        responses
-                            .send(Response::Error(ErrorCode::TxTimeout))
-                            .await;
-                    }
-                }
-
-                // Restore previous state. If we were receiving, restart RX
-                // using the stored config — NOT the per-packet TX override.
-                state.state = if was_receiving {
-                    // state.config is always Some when was_receiving (invariant).
-                    let rx_cfg = state.config.unwrap_or(cfg);
-                    match start_rx(lora, &rx_cfg).await {
-                        Ok(()) => RadioState::Receiving,
-                        Err(e) => {
-                            warn!("post-TX RX restart failed: {}", e);
-                            RadioState::Idle
-                        }
-                    }
-                } else {
-                    RadioState::Idle
-                };
-                status.sender().send(state.clone());
-            } else {
-                responses
-                    .send(Response::Error(ErrorCode::NotConfigured))
-                    .await;
-            }
-        }
-    }
-}
-
-// ── LoRa helpers ────────────────────────────────────────────────────
-
-fn to_bw(bw: protocol::Bandwidth) -> lora_phy::mod_params::Bandwidth {
-    use lora_phy::mod_params::Bandwidth::*;
-    match bw {
-        protocol::Bandwidth::Khz7 => _7KHz,
-        protocol::Bandwidth::Khz10 => _10KHz,
-        protocol::Bandwidth::Khz15 => _15KHz,
-        protocol::Bandwidth::Khz20 => _20KHz,
-        protocol::Bandwidth::Khz31 => _31KHz,
-        protocol::Bandwidth::Khz41 => _41KHz,
-        protocol::Bandwidth::Khz62 => _62KHz,
-        protocol::Bandwidth::Khz125 => _125KHz,
-        protocol::Bandwidth::Khz250 => _250KHz,
-        protocol::Bandwidth::Khz500 => _500KHz,
-    }
-}
-
-fn to_sf(sf: u8) -> lora_phy::mod_params::SpreadingFactor {
-    use lora_phy::mod_params::SpreadingFactor::*;
-    match sf {
-        5 => _5,
-        6 => _6,
-        7 => _7,
-        8 => _8,
-        9 => _9,
-        10 => _10,
-        11 => _11,
-        12 => _12,
-        _ => {
-            warn!("BUG: invalid SF {} passed validation", sf);
-            _7
-        }
-    }
-}
-
-fn to_cr(cr: u8) -> lora_phy::mod_params::CodingRate {
-    use lora_phy::mod_params::CodingRate::*;
-    match cr {
-        5 => _4_5,
-        6 => _4_6,
-        7 => _4_7,
-        8 => _4_8,
-        _ => {
-            warn!("BUG: invalid CR {} passed validation", cr);
-            _4_5
-        }
-    }
-}
-
-/// Create modulation parameters from a validated config.
-fn modulation_params(
-    lora: &mut Radio,
-    cfg: &RadioConfig,
-) -> Result<lora_phy::mod_params::ModulationParams, RadioError> {
-    lora.create_modulation_params(to_sf(cfg.sf), to_bw(cfg.bw), to_cr(cfg.cr), cfg.freq_hz)
-}
-
-async fn start_rx(lora: &mut Radio, cfg: &RadioConfig) -> Result<(), RadioError> {
-    let mdltn = modulation_params(lora, cfg)?;
-    let pkt = lora.create_rx_packet_params(
-        cfg.preamble_len, IMPLICIT_HEADER, MAX_PAYLOAD as u8, CRC_ON, IQ_INVERTED, &mdltn,
-    )?;
-    lora.prepare_for_rx(RxMode::Continuous, &mdltn, &pkt).await
-}
-
-async fn rx_once(
-    lora: &mut Radio,
-    cfg: &RadioConfig,
-    buf: &mut [u8],
-) -> Result<(u8, lora_phy::mod_params::PacketStatus), RadioError> {
-    let mdltn = modulation_params(lora, cfg)?;
-    let pkt = lora.create_rx_packet_params(
-        cfg.preamble_len, IMPLICIT_HEADER, MAX_PAYLOAD as u8, CRC_ON, IQ_INVERTED, &mdltn,
-    )?;
-    lora.rx(&pkt, buf).await
-}
-
-/// Maximum CAD attempts before transmitting anyway.
-const CAD_MAX_RETRIES: u8 = 10;
-
-async fn do_tx(lora: &mut Radio, cfg: &RadioConfig, payload: &[u8]) -> Result<(), RadioError> {
-    let mdltn = modulation_params(lora, cfg)?;
-
-    // Listen-before-talk: check channel is clear before transmitting.
-    if cfg.cad_enabled() {
-        lora.prepare_for_cad(&mdltn).await?;
-        for _ in 0..CAD_MAX_RETRIES {
-            if !lora.cad(&mdltn).await? {
-                break; // Channel is clear
-            }
-            // Channel busy — wait briefly and retry
-            embassy_time::Timer::after_millis(10).await;
-            lora.prepare_for_cad(&mdltn).await?;
-        }
-    }
-
-    let mut tx_pkt = lora.create_tx_packet_params(
-        cfg.preamble_len, IMPLICIT_HEADER, CRC_ON, IQ_INVERTED, &mdltn,
-    )?;
-    lora.prepare_for_tx(&mdltn, &mut tx_pkt, cfg.tx_power_dbm as i32, payload)
-        .await?;
-    lora.tx().await
-}

src/usb/mod.rs

@@ -1,4 +0,0 @@
-//! USB CDC-ACM interface with COBS-framed command/response protocol.
-
-mod task;
-pub use task::usb_task;

src/usb/task.rs

@@ -1,234 +0,0 @@
-//! USB CDC-ACM task: COBS-framed fixed-size LE command/response protocol.
-//!
-//! Reads COBS frames from USB, decodes them, parses commands, routes them
-//! to the radio or display task, and sends COBS-framed responses back.
-
-use defmt::warn;
-use embassy_executor::task;
-use embassy_futures::join::join;
-use embassy_usb::class::cdc_acm::{CdcAcmClass, Receiver, Sender, State};
-use embassy_usb::Builder;
-use static_cell::StaticCell;
-
-use crate::channel::{
-    CommandChannel, DisplayCommand, DisplayCommandChannel, ResponseChannel,
-};
-use crate::protocol::{Command, ErrorCode, Response};
-
-const MAX_FRAME: usize = 512;
-const MAX_PACKET: usize = 64;
-
-// Worst case: tag(1) + rssi(2) + snr(2) + len(2) + payload(256) = 263 bytes.
-// COBS adds ceil(263/254)+1 = 3 bytes. 266 < 512. Plenty of room.
-const _: () = assert!(
-    MAX_FRAME >= crate::protocol::MAX_PAYLOAD + 64,
-    "MAX_FRAME too small for max payload + COBS overhead"
-);
-
-#[task]
-pub async fn usb_task(
-    parts: crate::board::UsbParts,
-    commands: &'static CommandChannel,
-    responses: &'static ResponseChannel,
-    display_commands: &'static DisplayCommandChannel,
-    has_display: bool,
-    mac: [u8; 6],
-) {
-    // ── USB device configuration ────────────────────────────────────
-    // VID 0x1209: pid.codes open-source USB vendor ID
-    // PID 0x5741: DongLoRa product ID
-    // Class 0xEF/0x02/0x01: Miscellaneous / Interface Association Descriptor
-    let mut config = embassy_usb::Config::new(0x1209, 0x5741);
-    config.manufacturer = Some("DongLoRa");
-    config.product = Some("DongLoRa LoRa Radio");
-    config.device_class = 0xEF;
-    config.device_sub_class = 0x02;
-    config.device_protocol = 0x01;
-    config.composite_with_iads = true;
-
-    // Use MAC address as USB serial number for unique device identification.
-    static SERIAL_BUF: StaticCell<[u8; 12]> = StaticCell::new();
-    let serial_buf = SERIAL_BUF.init([0u8; 12]);
-    const HEX: &[u8; 16] = b"0123456789ABCDEF";
-    for (i, &byte) in mac.iter().enumerate() {
-        serial_buf[i * 2] = HEX[(byte >> 4) as usize];
-        serial_buf[i * 2 + 1] = HEX[(byte & 0x0F) as usize];
-    }
-    config.serial_number = Some(core::str::from_utf8(serial_buf).expect("MAC hex is valid UTF-8"));
-
-    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 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 cdc_state = CDC_STATE.init(State::new());
-
-    let mut builder = Builder::new(
-        parts.driver,
-        config,
-        desc_buf,
-        conf_buf,
-        bos_buf,
-        ctrl_buf,
-    );
-
-    let class = CdcAcmClass::new(&mut builder, cdc_state, MAX_PACKET as u16);
-    let mut usb_dev = builder.build();
-    let (sender, receiver) = class.split();
-
-    // ── Run USB device + protocol loop concurrently ────────────────
-    join(
-        usb_dev.run(),
-        protocol_loop(sender, receiver, commands, responses, display_commands, has_display, mac),
-    )
-    .await;
-}
-
-async fn protocol_loop<'d, D: embassy_usb_driver::Driver<'d>>(
-    mut sender: Sender<'d, D>,
-    mut receiver: Receiver<'d, D>,
-    commands: &'static CommandChannel,
-    responses: &'static ResponseChannel,
-    display_commands: &'static DisplayCommandChannel,
-    has_display: bool,
-    mac: [u8; 6],
-) {
-    use embassy_futures::select::select3;
-    use embassy_futures::select::Either3;
-
-    let mut read_buf = [0u8; MAX_PACKET];
-    let mut write_buf = [0u8; MAX_FRAME];
-    let mut cobs_encode_buf = [0u8; MAX_FRAME];
-
-    // COBS accumulator: collect bytes until 0x00 sentinel
-    let mut frame_buf = [0u8; MAX_FRAME];
-    let mut frame_len: usize = 0;
-
-    let mut was_connected = false;
-
-    loop {
-        match select3(
-            receiver.read_packet(&mut read_buf),
-            responses.receive(),
-            embassy_time::Timer::after_millis(250), // DTR poll interval for disconnect detection
-        )
-        .await
-        {
-            Either3::First(result) => {
-                let n = match result {
-                    Ok(0) => continue,
-                    Ok(n) => n,
-                    Err(_) => {
-                        frame_len = 0; // reset accumulator
-                        embassy_time::Timer::after_millis(100).await;
-                        continue;
-                    }
-                };
-
-                // Feed bytes into the COBS accumulator
-                for &byte in &read_buf[..n] {
-                    if byte == 0x00 {
-                        // End of COBS frame — decode and parse
-                        if frame_len > 0 {
-                            let mut decode_buf = [0u8; MAX_FRAME];
-                            if let Some(decoded_len) =
-                                ucobs::decode(&frame_buf[..frame_len], &mut decode_buf)
-                            {
-                                if let Some(cmd) = Command::from_bytes(&decode_buf[..decoded_len]) {
-                                    route_command(
-                                        cmd, commands, responses, display_commands, has_display, mac,
-                                    )
-                                    .await;
-                                }
-                            }
-                        }
-                        frame_len = 0;
-                    } else if frame_len < MAX_FRAME {
-                        frame_buf[frame_len] = byte;
-                        frame_len += 1;
-                    } else {
-                        // Frame too large — discard
-                        frame_len = 0;
-                    }
-                }
-            }
-            Either3::Second(response) => {
-                // Serialize response to fixed-size LE bytes, then COBS encode
-                let raw_len = response.write_to(&mut write_buf);
-                let encoded_len = ucobs::encode(&write_buf[..raw_len], &mut cobs_encode_buf)
-                    .unwrap_or(0);
-                // Append 0x00 sentinel
-                if encoded_len < cobs_encode_buf.len() {
-                    cobs_encode_buf[encoded_len] = 0x00;
-                    let frame = &cobs_encode_buf[..encoded_len + 1];
-                    for chunk in frame.chunks(MAX_PACKET) {
-                        if sender.write_packet(chunk).await.is_err() {
-                            warn!("USB write failed, response dropped");
-                            break;
-                        }
-                    }
-                } else {
-                    warn!("COBS encode buffer overflow");
-                }
-            }
-            Either3::Third(()) => {
-                // Poll DTR every 250ms to detect host disconnect
-            }
-        }
-
-        // Check DTR after every select wake
-        let connected = receiver.dtr();
-        if was_connected && !connected && has_display {
-            display_commands.send(DisplayCommand::Reset).await;
-        }
-        if !was_connected && connected && has_display {
-            display_commands.send(DisplayCommand::On).await;
-        }
-        was_connected = connected;
-    }
-}
-
-/// Route a parsed command to the appropriate handler.
-///
-/// Display and MAC commands are handled locally (response sent immediately).
-/// All other commands are forwarded to the radio task (response sent later).
-/// Both paths feed the same `ResponseChannel`, so the one-outstanding-command
-/// rule in PROTOCOL.md is required to keep solicited responses ordered.
-async fn route_command(
-    cmd: Command,
-    commands: &CommandChannel,
-    responses: &ResponseChannel,
-    display_commands: &DisplayCommandChannel,
-    has_display: bool,
-    mac: [u8; 6],
-) {
-    match cmd {
-        Command::DisplayOn => {
-            if has_display {
-                display_commands.send(DisplayCommand::On).await;
-                responses.send(Response::Ok).await;
-            } else {
-                responses.send(Response::Error(ErrorCode::NoDisplay)).await;
-            }
-        }
-        Command::DisplayOff => {
-            if has_display {
-                display_commands.send(DisplayCommand::Off).await;
-                responses.send(Response::Ok).await;
-            } else {
-                responses.send(Response::Error(ErrorCode::NoDisplay)).await;
-            }
-        }
-        Command::GetMac => {
-            responses.send(Response::MacAddress(mac)).await;
-        }
-        other => {
-            commands.send(other).await;
-        }
-    }
-}