# Phase 1 — Reconnaissance

## Project

`donglora` v1.5.2 — Embedded Rust firmware. Single binary per board, compiled with mutually-exclusive cargo features. Exposes the LoRa radio over a host transport (USB CDC-ACM or UART) using a COBS-framed binary protocol (DongLoRa Protocol v2).

## Languages / runtime

- **Rust 1.94 stable** for ARM (thumbv6m, thumbv7em); **Rust esp** fork for Xtensa (esp32, esp32-s3). `no_std`, `no_main`, `panic = abort`, LTO fat, opt-level 3.
- **No allocator.** All collections are fixed-capacity `heapless::Vec<_, N>`.
- **Async runtime: embassy-executor 0.10** (Cortex-M) / **esp-rtos 0.3** (Xtensa). Three long-lived tasks per board.
- **Statecharts: hsmc 0.6** drive the host, radio, and display tasks.

## Supported boards (one feature → one binary)

| Board                       | MCU        | Radio  | Host transport         |
|-----------------------------|------------|--------|------------------------|
| heltec_mesh_node_t114       | nRF52840   | SX1262 | USB CDC-ACM (native)   |
| heltec_v3                   | ESP32-S3   | SX1262 | USB CDC-ACM (native)   |
| heltec_v3_uart              | ESP32-S3   | SX1262 | UART0 via CP2102       |
| heltec_v4                   | ESP32-S3   | SX1262 | USB CDC-ACM (native)   |
| elecrow_thinknode_m2        | ESP32-S3   | SX1262 | UART0 via CP2102       |
| lilygo_tbeam                | ESP32      | SX1276 | UART0 via CP2102       |
| lilygo_tbeam_supreme        | ESP32-S3   | SX1262 | USB CDC-ACM (native)   |
| rak_wisblock_4631           | nRF52840   | SX1262 | USB CDC-ACM (native)   |
| waveshare_rp2040_lora       | RP2040     | SX1262 | USB CDC-ACM (native)   |
| wio_tracker_l1              | nRF52840   | SX1262 | USB CDC-ACM (native)   |

## Entry points (untrusted-byte ingress)

There is **exactly one network-facing entry point per board image**: the host transport (USB CDC-ACM **or** UART, never both in the same build).

| Module                       | Inbound bytes from                  |
|------------------------------|-------------------------------------|
| `src/host/usb.rs`            | USB CDC-ACM (host OS, kernel-side)  |
| `src/host/uart.rs`           | UART0 (CP2102 → host OS)            |
| `src/radio.rs` (RX path)     | LoRa over-the-air (any peer in RF range, on configured freq+sync) |

There is **no networking** (TCP/UDP/HTTP/etc.), **no filesystem**, **no shell**, **no storage**. The radio is the only RF surface; OTA RX packets become a `DeviceMessage::Rx(...)` forwarded to the host with `tag = 0` — the firmware itself does not interpret payload bytes.

USB descriptors / VID:PID `1209:5741` (composite IAD device). The CDC-ACM serial-number string is the device's MAC address as 12-char uppercase hex (`src/host/usb.rs:184-189`).

## Wire format (one path from byte → command)

```
raw bytes
  → FrameDecoder (donglora-protocol 1.2.0 frame.rs)
      COBS-delimited, CRC16/CCITT-FALSE-protected, payload ≤ MAX_PAYLOAD_FIELD (275 B)
  → dispatch_frame (host/framing.rs)
      rejects tag=0 with async ERR(EFRAME)
      calls Command::parse(type_id, payload)
  → InboundEvent::Command { tag, cmd } via CommandChannel (depth 8)
  → radio task statechart (radio.rs)
```

Egress (`DeviceMessage::Ok|Err|Rx|TxDone`) is symmetric: built by the radio task, sent through `OutboundChannel` (depth 64), encoded by `encode_outbound`, written packet-by-packet.

Commands accepted from host: `PING`, `GET_INFO`, `SET_CONFIG`, `TX`, `RX_START`, `RX_STOP` (only these `type_id` bytes; anything else → `ERR(EUNKNOWN_CMD)`).

## Trust boundaries

| Boundary                              | Direction       | Treated as       |
|---------------------------------------|-----------------|------------------|
| USB / UART host → firmware            | inbound bytes   | **trusted** (it's the user's PC) |
| LoRa RF peer → firmware (RX payload)  | inbound bytes   | **untrusted**, but only memcpy'd to host — firmware never interprets |
| firmware → SX1262/SX1276 via SPI      | outbound        | trusted (own peripheral) |

The firmware is intentionally a **transparent radio bridge**: there is no auth, no crypto, no session state, no key material on device. The radio's freq, power, sync_word, etc. are whatever the host sets (within hardware limits enforced by `validate_lora`).

## Auth / session layer

**None.** Anything that can write CDC-ACM bytes to the device can drive the radio. Per design — the device is a "dongle," ownership is physical-attachment.

The protocol's inactivity watchdog (`PROTOCOL.md §3.4`, 1 s) drops the radio to `Unconfigured` if the host stops sending bytes — this is liveness/cleanup, **not** auth. USB-side this is gated on DTR (USB CDC line state); UART has no DTR so it relies purely on the watchdog.

## Data at rest

**None of security interest.**
- Static `Info` blob built once at boot — MAC, fw version, capability bitmaps. Visible to anyone who issues `GET_INFO`.
- No credentials, tokens, keys, PII.
- Persistent storage: only board-specific bootloader settings region; **firmware never writes to flash at runtime** (see `ld/*.x` — app region is read-only post-flash).
- nRF52840 boards' `s140 SoftDevice` region (0x01000–0x26000) preserved at flash time; firmware never touches it.

## Dependencies (Cargo.lock, security-relevant subset)

- `donglora-protocol 1.2.0` — own crate, the wire codec (frame, command, modulation, info, events). Fuzz/mutation-tested in sibling repo (`/home/swaits/Code/donglora-org/protocol/`).
- `ucobs 0.3` — COBS encode/decode, no_std, very small.
- `lora-phy` — git fork from `swaits/lora-rs branch=fixed` (carries CAD IRQ-clear fixes pending upstream PRs #428/#431/#432). All SX126x/SX127x SPI primitives.
- `hsmc 0.6` — own crate (statecharts).
- `embassy-* 0.5/0.6/0.10/0.8` — well-known embedded async runtime.
- `defmt 0.3`, `panic-probe 1.0` (Cortex-M boards) / `esp-backtrace 0.19` + `esp-println 0.17` (Xtensa boards).
- `heapless 0.9` — fixed-capacity collections.

No HTTP, JSON, TLS, SQL, template, regex, deserialization-of-user-data dependencies.

## Deployment context

Firmware is flashed via UF2 (Cortex-M) or `espflash` (Xtensa). No OTA update path on the device itself — re-flashing requires physical USB. Production builds run with `DEFMT_LOG` unset → defmt strips info/debug/warn at compile time; only `error!` survives.

## Existing security controls / hardening already in place

- **`#![cfg_attr(not(test), no_std)]` / `panic = abort`** — no panic unwinding to abuse.
- **`#![deny(clippy::undocumented_unsafe_blocks)]`** in Cargo.toml — every `unsafe` block must justify itself.
- **`unsafe` audit** (4 sites total):
  - `main.rs:105` — one-time `static mut INFO` init at boot, before any task spawns.
  - `hal/nrf52840.rs:102, 140, 151` — `read_volatile` / `write_volatile` on MMIO registers (POWER.RESETREAS, FICR.DEVICEADDR). Standard.
  - `hal/rp2040.rs:68, 79` — one-time `static mut MAC_REF` init at boot.
- **Memory layout (`ld/nrf52840-memory.x`)** preserves the factory SoftDevice region; UF2-only flashing prevents accidental overwrite.
- **CRC-16/CCITT-FALSE** on every frame, COBS framing — corrupt bytes are caught by either layer before reaching `Command::parse`.
- **Strict typed parsing**: every enum field rejects out-of-range bytes (`from_u8` returns `Option` and `InvalidField` is propagated); reserved bits in `TxFlags` rejected; reserved byte in `LrFhssConfig` rejected.
- **`validate_lora` (`radio.rs:2125-2145`)**: freq within board's chip-supported range, SF ∈ {5..=12} **and** in board bitmap, BW in board bitmap, TX power within board range, preamble ≥ 6.
- **Hardware-limit clamping**: `MAX_OTA_PAYLOAD = 255` matches the chip's `payload_len` register width; the receive buffer is sized exactly to it.
- **`RADIO_THROTTLED` backpressure flag** prevents queue floods if the host is unresponsive.
- **State-machine cancel-safety**: cancel-unsafe lora-phy futures (`lora.tx`, `lora.cad`, `LoRa::new`, `lora.init`) are hosted in chart states whose only event handlers are emitted by the future itself on natural completion — chart cannot drop them.
- **Reset-and-recovery state machine** with bounded attempts (`MAX_RECOVERY_ATTEMPTS = 4`) and a terminal `Dead` state that still answers `PING`/`GET_INFO`.