From efd54fd8f3afc8c5cd9d99a4ee6c32be51dc9211 Mon Sep 17 00:00:00 2001 From: zackees Date: Fri, 19 Jun 2026 21:46:20 -0700 Subject: [PATCH] =?UTF-8?q?docs(esp32p4):=20correct=20USB=20CDC=20warning?= =?UTF-8?q?=20=E2=80=94=20only=20CDC=5FON=5FBOOT=20is=20toxic?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- platforms/platformio.esp32p4.ini | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/platforms/platformio.esp32p4.ini b/platforms/platformio.esp32p4.ini index 2381d0e..0ca70b3 100644 --- a/platforms/platformio.esp32p4.ini +++ b/platforms/platformio.esp32p4.ini @@ -19,9 +19,15 @@ board_build.partitions = huge_app.csv ; stalls during execution, silently corrupting LED protocol timing. ; See FastLED src/platforms/esp/32/drivers/parlio/ for the canonical chipset list. ; -; Do NOT add -DARDUINO_USB_CDC_ON_BOOT=1 or -DARDUINO_USB_MODE=1 here. They -; wire Serial to the USB-CDC interface, which only enumerates when a USB host -; is connected — boards powered from a wall adapter then hang in setup(). +; Do NOT add -DARDUINO_USB_CDC_ON_BOOT=1 here. It wires Serial to the USB-CDC +; interface, which only enumerates when a USB host is connected — sketches +; that touch Serial in setup() (especially `while (!Serial) {}`) then hang +; when the board is powered from a wall adapter instead of a PC. +; +; ARDUINO_USB_MODE selects HWCDC vs TinyUSB *when CDC-on-boot is enabled*; +; it has no effect on Serial routing while CDC_ON_BOOT=0, so we leave it +; unset here. P4's upstream default is 0 (TinyUSB); C3/C5/C6/H2 force it to +; 1 (HWCDC) via platform.txt. build_flags = -DCONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM=1 -DCONFIG_PARLIO_TX_ISR_CACHE_SAFE=1