Skip to content

Commit 14c1c8b

Browse files
zackeesclaude
andauthored
docs(esp32p4): correct USB CDC warning — only CDC_ON_BOOT is toxic (#12)
The previous comment lumped ARDUINO_USB_MODE=1 in with ARDUINO_USB_CDC_ON_BOOT=1 as a flag to avoid. That was wrong. Per the Arduino-ESP32 core source (cores/esp32/{HWCDC,USBCDC,main}.cpp, platform.txt): - ARDUINO_USB_MODE only selects HWCDC vs TinyUSB when CDC_ON_BOOT=1. With CDC_ON_BOOT=0 (our default) Serial falls back to UART0 regardless of USB_MODE — the flag has no observable effect. - =1 selects HWCDC (passive ROM-backed USB-Serial/JTAG). Bounded ~2s write timeouts; does not wait for host enumeration. - =0 selects TinyUSB, which IS the stack that blocks waiting for the host. P4's upstream default is 0; C3/C5/C6/H2/C61 force =1 via platform.txt. Update the comment to point users at the actual toxic flag (CDC_ON_BOOT=1) and explain that USB_MODE is left unset because it doesn't matter while CDC-on-boot is disabled. No build-flag changes; comment-only. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 021fde7 commit 14c1c8b

1 file changed

Lines changed: 9 additions & 3 deletions

File tree

platforms/platformio.esp32p4.ini

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,15 @@ board_build.partitions = huge_app.csv
1919
; stalls during execution, silently corrupting LED protocol timing.
2020
; See FastLED src/platforms/esp/32/drivers/parlio/ for the canonical chipset list.
2121
;
22-
; Do NOT add -DARDUINO_USB_CDC_ON_BOOT=1 or -DARDUINO_USB_MODE=1 here. They
23-
; wire Serial to the USB-CDC interface, which only enumerates when a USB host
24-
; is connected — boards powered from a wall adapter then hang in setup().
22+
; Do NOT add -DARDUINO_USB_CDC_ON_BOOT=1 here. It wires Serial to the USB-CDC
23+
; interface, which only enumerates when a USB host is connected — sketches
24+
; that touch Serial in setup() (especially `while (!Serial) {}`) then hang
25+
; when the board is powered from a wall adapter instead of a PC.
26+
;
27+
; ARDUINO_USB_MODE selects HWCDC vs TinyUSB *when CDC-on-boot is enabled*;
28+
; it has no effect on Serial routing while CDC_ON_BOOT=0, so we leave it
29+
; unset here. P4's upstream default is 0 (TinyUSB); C3/C5/C6/H2 force it to
30+
; 1 (HWCDC) via platform.txt.
2531
build_flags =
2632
-DCONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM=1
2733
-DCONFIG_PARLIO_TX_ISR_CACHE_SAFE=1

0 commit comments

Comments
 (0)