swaits
d7a1ee86d0
The TX state machine's `prep_for_cad_act` (TxCadPrep entry) and `prep_for_tx_act` (TxPrep entry) both read `ctx.mdltn` and emit `TransmitFailed` → `ERR(ERadio)` if it's None. But `ctx.mdltn` was only ever assigned on the RX path — `try_start_rx_hw` (RxArming entry) and `cache_rx_pkt` (RxSession entry). `reconfigure_radio` already called `to_lora_mod_params(lora, cfg)` during SET_CONFIG but discarded the result via `let _ = …?;` (comment claimed image calibration; the function is pure compute on SX126x). Result: a freshly-booted dongle that issues TX before ever calling RX_START gets `ERR(ERadio)` on the first CmdTx because the chart's TX-entry actions find `ctx.mdltn = None`. The bug was hidden in practice by any prior RX_START (ai-bot, ping_pong --role rx, etc.) leaving `ctx.mdltn` populated across sessions until the next reflash. Fix: thread the `ModulationParams` out of `reconfigure_radio` as its return value, and have `apply_set_config` cache it in `self.mdltn` alongside `self.config`. The failure path clears `self.mdltn` along with `self.config` so a SET_CONFIG that fails leaves a clean Unconfigured state. Surfaced while testing the matching sync-word fix on freshly-flashed dongles via `examples/sync_word_test.py` — the first TX failed with `ERR(ERadio)` until this path was wired up.
DongLoRa Firmware
Embedded Rust firmware for DongLoRa boards. Exposes the LoRa radio over USB CDC-ACM using a COBS-framed binary protocol.
Building
just setup # one-time toolchain install
just build heltec_v4 # build for a specific board
just flash heltec_v4 # build + flash
just check-all # compile-check all boards
just clippy heltec_v4 # lint
just test # host-side protocol unit tests
All commands are run from the firmware/ directory.
Supported Boards
| Board | Feature | MCU | Radio | USB | Target |
|---|---|---|---|---|---|
| Heltec Mesh Node T114 | heltec_mesh_node_t114 |
nRF52840 | SX1262 | Native CDC-ACM | thumbv7em-none-eabihf |
| Heltec V3 | heltec_v3 |
ESP32-S3 | SX1262 | Native CDC-ACM | xtensa-esp32s3-none-elf |
| Heltec V3 (UART) | heltec_v3_uart |
ESP32-S3 | SX1262 | CP2102 bridge | xtensa-esp32s3-none-elf |
| Heltec V4 | heltec_v4 |
ESP32-S3 | SX1262 | Native CDC-ACM | xtensa-esp32s3-none-elf |
| ELECROW ThinkNode-M2 | elecrow_thinknode_m2 |
ESP32-S3 | SX1262 | CP2102 bridge | xtensa-esp32s3-none-elf |
| LilyGo T-Beam | lilygo_tbeam |
ESP32 | SX1276 | CP2102 bridge | xtensa-esp32-none-elf |
| LilyGo T-Beam S3 Supreme | lilygo_tbeam_supreme |
ESP32-S3 | SX1262 | Native CDC-ACM | xtensa-esp32s3-none-elf |
| RAK WisBlock 4631 | rak_wisblock_4631 |
nRF52840 | SX1262 | Native CDC-ACM | thumbv7em-none-eabihf |
| Waveshare RP2040-LoRa | waveshare_rp2040_lora |
RP2040 | SX1262 | Native CDC-ACM | thumbv6m-none-eabi |
| Wio Tracker L1 | wio_tracker_l1 |
nRF52840 | SX1262 | Native CDC-ACM | thumbv7em-none-eabihf |
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:
- Solder 0-ohm (or 22-ohm) resistors at pads R29 (D+) and R3 (D-)
- 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:
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
See src/board/PORTING.md.
Protocol
See PROTOCOL.md
in the donglora-protocol repo
(crates.io: donglora-protocol)
for the complete wire format specification — that is the canonical home;
this firmware just consumes it.