swaits
aca4c3cffd
Adds nRF52840 + SX1262 + 1.14" 240×135 ST7789 color TFT support. First color display board in the project; introduces a BoardDisplay trait so each board renders to its native pixel format and resolution without aliasing or color-quantization round-trips. Architecture: - New BoardDisplay trait (src/display.rs) bundles render_*, present(), set_bright/set_dim. Replaces the old DrawTarget<Color=BinaryColor> + DisplayBrightness combo as the LoRaBoard::DisplayDriver bound. - Mono OLED drivers (Sh1106, Ssd1306Async) get adapter impls that delegate to the existing display::render module — no behavior change for any existing board. - T114 ST7789 driver (src/driver/st7789.rs) wraps lcd-async (async fork of mipidsi) with a 64,800-byte raw byte framebuffer in .bss. Renders via lcd_async::raw_framebuf::RawFrameBuf<Rgb565, _>, presents via a single async DMA blit (panel.show_raw_data(...).await) — the await yields the executor for the ~65 ms SPI transfer so the radio task isn't starved during repaints. - PWM backlight on PWM0 / P0.15 (active-LOW, inverted polarity) for smooth dim/bright transitions instead of GPIO toggle. - Native 240×135 Rgb565 renderer (src/display/render_color.rs) with splash + dashboard + sparkline. - Shared QR-code blit (src/display/qr.rs), generic over PixelColor, re-centers the 64×64 bitmap which has cells in cols 0..50 and ~14 px of right-side padding — both mono and color splash now show the QR with 7 px quiet zones on all four sides (was visibly left-shifted). - Shared content types (BoardInfo, DashboardCtx) decouple what to draw from how each board renders it. - create_display() now takes the board's full DisplayParts bundle (was just the I2C bus) so non-I2C displays can carry SPI + control pins through. Hardware: - VEXT_ENABLE on P0.21 driven HIGH at boot — powers the SX1262 + TFT rail. Without this, lora-phy init succeeds at the SPI level but TX_DONE never fires. - VTFT_CTRL on P0.03, active LOW; backlight on P0.15, active LOW. - TFT SPI2 (SCK P1.08 / MOSI P1.09) at 8 MHz over EasyDMA. Async ExclusiveDevice from embedded-hal-bus (with the 'async' feature). - lcd-async builder at display_size(135, 240), display_offset(52, 40), Deg90 rotation, ColorInversion::Inverted — standard 1.14" ST7789 die mapping. - Linker: shared ld/nrf52840-memory.x (S140 SoftDevice preserved at 0x01000-0x26000 per project policy).
71 lines
2.9 KiB
Markdown
71 lines
2.9 KiB
Markdown
# DongLoRa Firmware
|
|
|
|
Embedded Rust firmware for DongLoRa boards. Exposes the LoRa radio over
|
|
USB CDC-ACM using a COBS-framed binary protocol.
|
|
|
|
## Building
|
|
|
|
```sh
|
|
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:**
|
|
|
|
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
|
|
|
|
See [src/board/PORTING.md](src/board/PORTING.md).
|
|
|
|
## Protocol
|
|
|
|
See [PROTOCOL.md](https://github.com/donglora/protocol-rs/blob/main/PROTOCOL.md)
|
|
in the [donglora-protocol](https://github.com/donglora/protocol-rs) repo
|
|
(crates.io: [`donglora-protocol`](https://crates.io/crates/donglora-protocol))
|
|
for the complete wire format specification — that is the canonical home;
|
|
this firmware just consumes it.
|