From e9e80ba49dc3d28edc70c8ca94b53d6ee218572d Mon Sep 17 00:00:00 2001 From: zackees Date: Fri, 19 Jun 2026 21:38:21 -0700 Subject: [PATCH] fix(platforms): drop toxic ARDUINO_USB_CDC_ON_BOOT / USB_MODE flags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit With ARDUINO_USB_CDC_ON_BOOT=1 the Arduino-ESP32 core routes 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() the moment user code touches Serial. This is exactly the failure mode a starter repo must not ship with — users copy these envs as their starting point, and the fixture works on the bench but stops working in deployment. Drop the flag (and the related ARDUINO_USB_MODE=1) from every env that was carrying it: - esp32c6: remove both flags from build_flags - esp32p4: remove ARDUINO_USB_MODE=1 (originally added per issue #9 spec) - esp32c3: remove the explicit =0 stanza; default is already safe and the surrounding comment had the two states reversed Each affected ini gets a short "Do NOT add" comment so the flag doesn't silently come back. Co-Authored-By: Claude Opus 4.7 (1M context) --- platforms/platformio.esp32c3.ini | 9 ++++----- platforms/platformio.esp32c6.ini | 9 +++++---- platforms/platformio.esp32p4.ini | 5 ++++- 3 files changed, 13 insertions(+), 10 deletions(-) diff --git a/platforms/platformio.esp32c3.ini b/platforms/platformio.esp32c3.ini index cb44e1f..393b17f 100644 --- a/platforms/platformio.esp32c3.ini +++ b/platforms/platformio.esp32c3.ini @@ -13,11 +13,10 @@ platform = https://github.com/pioarduino/platform-espressif32/releases/download/ board = esp32-c3-devkitm-1 framework = arduino -; USB CDC Configuration -; Set to 0 to disable USB CDC on boot (halts printing until serial monitor is launched) -; Set to 1 to enable USB CDC on boot (prints immediately without waiting for serial monitor) -build_flags = - -DARDUINO_USB_CDC_ON_BOOT=0 +; Do NOT add -DARDUINO_USB_CDC_ON_BOOT=1. With CDC-on-boot enabled, Serial is +; routed to the USB-CDC interface, which only enumerates when a USB host is +; connected — boards powered from a wall adapter then hang in setup() the +; moment user code touches Serial. Leave Serial on the UART (default). lib_deps = FastLED \ No newline at end of file diff --git a/platforms/platformio.esp32c6.ini b/platforms/platformio.esp32c6.ini index c593d3c..78d7177 100644 --- a/platforms/platformio.esp32c6.ini +++ b/platforms/platformio.esp32c6.ini @@ -30,14 +30,15 @@ monitor_filters = ; Without these the FastLED PARLIO TX ISR sits in flash and takes cache-miss ; 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 here. It wires Serial to the USB-CDC +; interface, which only enumerates when a USB host is connected — sketches +; that touch Serial in setup() then hang when the board is powered from a +; wall adapter instead of a PC. build_flags = -DCONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM=1 -DCONFIG_PARLIO_TX_ISR_CACHE_SAFE=1 - ; ---- CRITICAL: enable USB CDC serial ---- - -D ARDUINO_USB_CDC_ON_BOOT=1 - -D ARDUINO_USB_MODE=1 -; Optional: fix early prints board_build.flash_mode = dio board_upload.flash_size = 4MB diff --git a/platforms/platformio.esp32p4.ini b/platforms/platformio.esp32p4.ini index 7b81f03..2381d0e 100644 --- a/platforms/platformio.esp32p4.ini +++ b/platforms/platformio.esp32p4.ini @@ -18,10 +18,13 @@ board_build.partitions = huge_app.csv ; Without these the FastLED PARLIO TX ISR sits in flash and takes cache-miss ; 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(). build_flags = -DCONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM=1 -DCONFIG_PARLIO_TX_ISR_CACHE_SAFE=1 - -DARDUINO_USB_MODE=1 lib_deps = FastLED