donglora/firmware
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: native USB CDC-ACM support for Heltec V3

Browse Source 
The default heltec_v3 feature now uses native USB OTG (same as V4),
appearing as /dev/ttyACM0 with the DongLoRa VID:PID (1209:5741).
This requires a hardware mod: solder R29/R3 and disconnect the CP2102
from the USB data lines.

Stock (unmodified) V3 boards should use the new heltec_v3_uart feature
which preserves the original UART-over-CP2102 behavior (/dev/ttyUSB0).

- heltec_v3: switched from UART to USB OTG
- heltec_v3_uart: new feature, UART fallback for stock boards
- Removed #[cfg] gates on UsbParts/UartParts (both always defined)
- Updated README with hardware mod instructions and board table
- Updated justfile with heltec_v3_uart board definition
This commit is contained in:
swaits committed 2026-04-07 10:44:25 -06:00
1 parent 07651dce44
commit 6db287c241
9 files changed
+142 -20
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+33 -5
View File
@@ -18,11 +18,39 @@ 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 |
| RAK WisBlock 4631 | `rak_wisblock_4631` | nRF52840 | SX1262 | Native CDC-ACM | thumbv7em-none-eabihf |
| 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