Single configured usermod crashes on ESP32-C3

[aalaei]

What happened?

The default i2ssdPin is hardcoded to 32, but ESP32-C3 only has GPIOs 0–21. This causes pin allocation to fail silently, leaves GPIO 15 stuck as allocated, and ends up with disableSoundProcessing = false
despite having no working audio source (line 1475 overrides the earlier check at 1472). Result: watchdog crash loop, no WiFi AP.

Fix is straightforward — define valid default pins for C3, either in the board env or in the code:

-D I2S_SDPIN=2
-D I2S_WSPIN=3
-D I2S_CKPIN=4

Tested on ESP32-C3-DevKitM-1, WLED 0.17.0-dev. Without the fix it bootloops, with it everything works fine.

To Reproduce Bug

flash audio reactive version to esp32-c3

Expected Behavior

The board boots properly, there’s no boot loop, and the WLED SSID is visible.

Install Method

Self-Compiled

What version of WLED?

0.16.x

Which microcontroller/board are you seeing the problem on?

ESP32-C3

Relevant log/trace output

Anything else?

A propsed PR to solve the issue #5496

Code of Conduct

• I agree to follow this project's Code of Conduct

[acvigue]

seconding this, can verify that #42844e4f causes a bootloop.

[aalaei]

Apparently I was wrong bootloop is not related to I2S there's another issue on 0.16-beta release.

[acvigue]

Hmm. I ran a git bisect and that was the problematic commit. As a quick fix, i removed custom_usermods = audioreactive from the usermods list under esp32c3dev in platformio.ini and was able to get my C3 (reflashed Govee H60B2 board) working again

[DedeHai]

This is a very interesting bug. I never came accross it my testing - and also my test env does not show the bootloop but the default env does. Unfortunately any debug output is useless. I strongly suspect a RAM memory alignment issue.

[DedeHai]

@coderabbitai in commit 42844e4 the use of IDF DSP FFT dsps_fft2r.h was added. Please check if the library requires special RAM alignment for buffers, i.e. valFFT, vImag, windowFFT, windowFloat

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Find the audio_source.h and audio_reactive.cpp files and check buffer allocations
rg -n "valFFT|vImag|windowFFT|windowFloat|malloc|aligned_alloc|heap_caps" usermods/audioreactive/ -A2 -B2

Length of output: 16289

---

🌐 Web query:

ESP-IDF dsps_fft2r alignment requirement buffer float

💡 Result:

For dsps_fft2r_fc32 / dsps_fft2r_fc32_* the complex float buffer is float data[2*N] (Re0, Im0, …). For the optimized implementations (notably ESP32‑S3 SIMD) you should ensure the data buffer is 16‑byte aligned; Espressif’s dl_fft (which reuses esp-dsp’s float FFT) explicitly requires x to be allocated with heap_caps_aligned_alloc(..., 16, ...) and “aligned to 16 bytes.” [1]

Ways to do it:

• Dynamic: heap_caps_aligned_alloc(16, 2*N*sizeof(float), caps) (ESP-IDF provides this API) [2]
• Static/stack: __attribute__((aligned(16))) float data[2*N]; (16-byte alignment is a documented/used pattern in Espressif docs) [3]

Rule of thumb: always align FFT input/output buffers to 16 bytes; it’s safe even if you end up using the ANSI C fallback. [1]

Sources:
[1] Espressif Component Registry espressif/dl_fft README (alignment note + example) (components.espressif.com)
[2] ESP-IDF Programming Guide: heap_caps_aligned_alloc() (docs.espressif.com)
[3] ESP32‑S3 Technical Reference Manual (mentions aligned(16) / aligned alloc usage) (akizukidenshi.com)

Citations:

• 1: https://components.espressif.com/components/espressif/dl_fft/versions/0.3.1/readme
• 2: https://docs.espressif.com/projects/esp-idf/en/v4.4/api-reference/system/mem_alloc.html?utm_source=openai
• 3: https://akizukidenshi.com/goodsaffix/esp32-s3_technical_reference_manual_en.pdf?utm_source=openai

---

@DedeHai, here's what I found after examining the buffer allocations and the IDF DSP FFT alignment requirements:

---

IDF DSP FFT Alignment Requirements

The dsps_fft2r_fc32 SIMD-optimized variants (_ae32 for ESP32, _aes3 for S3) require the data buffer to be 16-byte aligned. Espressif's dl_fft (which reuses esp-dsp's float FFT) explicitly requires buffers to be allocated with heap_caps_aligned_alloc(..., 16, ...) aligned to 16 bytes.

---

How Each Path Allocates Buffers

Path	Chip	Buffer	Allocation	Aligned?
IDF DSP float FFT	ESP32 / S3 / others	valFFT	heap_caps_malloc + manual ((uintptr_t)+15) & ~15	✅ 16-byte
IDF DSP float FFT	ESP32 / S3 / others	windowFFT	heap_caps_malloc + manual ((uintptr_t)+15) & ~15	✅ 16-byte
IDF DSP integer FFT	C3, S2	valFFT	calloc (line 320)	⚠️ unspecified
IDF DSP integer FFT	C3, S2	windowFFT	calloc (line 323)	⚠️ unspecified
IDF DSP integer FFT	C3, S2	windowFloat	calloc (line 327, temp)	⚠️ unspecified
Arduino FFT	any	valFFT, vImag	calloc (lines 287-288)	⚠️ unspecified

---

Assessment for ESP32-C3

The comment on line 361 confirms: "valFFT is used as a int16_t buffer on C3 and S2" — so C3 takes the integer FFT path and calls dsps_fft2r_sc16_ansi and dsps_bit_rev_sc16_ansi.

The good news: The ANSI C implementations don't use SIMD intrinsics, so strict 16-byte alignment isn't architecturally required. calloc on ESP32 typically returns at least 8-byte aligned memory, which exceeds the 2-byte minimum for int16_t.

However, there are two potential concerns for the C3 bootloop worth investigating beyond alignment:

1. dsps_fft2r_init_sc16(NULL, samplesFFT) at line 325 — passing NULL uses internal static tables. It's worth verifying this is safe and thread-safe when called from the FFT task on C3, since this was newly added in commit 42844e4.

2. Stack pressure in the FFT task — the IDF DSP library may have deeper call chains than the previous approach, potentially triggering a stack overflow on C3 which has tighter memory constraints. This could manifest as a bootloop with no useful debug output (watchdog reset before UART flushes).

My conclusion: the alignment is likely fine for the C3 integer path, but the dsps_fft2r_init_sc16(NULL, ...) call and/or stack depth in the FFT task are more probable culprits for the observed bootloop. Would it help to check the FFT task stack size configuration?

---

🧠 Learnings used

Learnt from: DedeHai
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2026-02-21T15:07:26.737Z
Learning: On ESP32 with ESP-IDF V4, there is an APLL (Audio PLL) resource conflict between Ethernet (when using internal RMII clock on GPIO 0/16/17) and I2S PDM microphones. In commit 98138a02e (Nov 2022, PR `#2907`), the audio reactive usermod was changed to set `use_apll = true` for PDM microphones in `usermods/audioreactive/audio_source.h` line 228. This causes Ethernet initialization to fail because both EMAC and I2S PDM cannot share the APLL simultaneously. This was not an issue in v0.15.3 because APLL was not enabled for PDM mode at that time. The fix is to disable APLL for PDM mode when Ethernet is enabled, either through runtime detection or a compile-time flag.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5496
File: platformio.ini:551-553
Timestamp: 2026-04-11T22:43:01.436Z
Learning: In WLED (usermods/audioreactive/audio_reactive.cpp, lines ~772-787): The default I2S pin values for AudioReactive are defined using `#ifndef` guards: i2ssdPin=32 (I2S_SDPIN), i2swsPin=15 (I2S_WSPIN), i2sckPin=14 (I2S_CKPIN). These are classic ESP32 GPIO numbers and are out-of-range/invalid on ESP32-C3 (GPIO 0-21 only). The correct fix for C3 is to add `#ifdef` CONFIG_IDF_TARGET_ESP32C3 branches inside each `#ifndef` block in audio_reactive.cpp, NOT to add -D I2S_SDPIN/WSPIN/CKPIN overrides to platformio.ini. Safe C3 defaults are GPIO 4 (SDPIN), 5 (WSPIN), 6 (CKPIN) — avoiding strapping pins GPIO 2/8/9, flash pins GPIO 12-17, and USB-JTAG pins GPIO 18-19.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/cfg.cpp:673-673
Timestamp: 2026-03-28T00:51:30.926Z
Learning: In WLED PR `#5048`, the NTP-related crash on ESP32-C5 (pioarduino IDF 5.5.x with CONFIG_LWIP_CHECK_THREAD_SAFETY=y) is definitively NOT caused by ntpUdp.begin(). The crash dump shows the real call chain: WLED::loop() → handleTime() → handleNetworkTime() (ntp.cpp:212) → AsyncDNS::query() (asyncDNS.h:45) → dns_gethostbyname_addrtype() → dns_alloc_pcb() → dns_alloc_random_port() → udp_new_ip_type() ← ASSERT. The fix must be in AsyncDNS::query() (asyncDNS.h:45): the call to dns_gethostbyname_addrtype() must be dispatched to the TCPIP thread via tcpip_callback_with_block() on IDF V5+. The ntpUdp.begin() call sites (wled.cpp:926 and set.cpp:562) are NOT the crash location for this particular bug.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/cfg.cpp:673-673
Timestamp: 2026-03-27T21:17:51.985Z
Learning: In WLED PR `#5048`, the NTP/UDP crash on ESP32-C5 (pioarduino IDF 5.5.x): CONFIG_LWIP_TCPIP_CORE_LOCKING defaults to n (disabled) in arduino-esp32/pioarduino, while CONFIG_LWIP_CHECK_THREAD_SAFETY=y is what actually causes the "Required to lock TCPIP core functionality!" assertion. LOCK_TCPIP_CORE() / UNLOCK_TCPIP_CORE() macros are only functional when CONFIG_LWIP_TCPIP_CORE_LOCKING=y; using them without enabling that config has no effect. The correct fix without sdkconfig changes is to use tcpip_callback() to schedule ntpUdp.begin() (and other raw lwIP API calls) on the TCPIP thread, which works regardless of the locking mode setting. The tasmota core (IDF 5.3.x, used for C6) likely has CONFIG_LWIP_CHECK_THREAD_SAFETY=n, which is why the same violation does not crash on C6.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/set.cpp:551-555
Timestamp: 2026-03-27T21:00:25.902Z
Learning: In WLED PR `#5048` (wled00/set.cpp lines 551-555), the CONFIG_IDF_TARGET_ESP32C5 block that unconditionally forces ntpEnabled = false is an intentional **temporary hotfix** by softhack007 for a known ESP32-C5 crash: `assert failed: udp_new_ip_type udp.c:1278 (Required to lock TCPIP core functionality!)`. Do not flag this as a permanent design issue; the TODO comment in the code already notes it should be resolved properly once the underlying IDF/TCPIP bug on C5 is fixed. A future permanent solution should use a target capability flag rather than overwriting the user's setting.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/cfg.cpp:673-673
Timestamp: 2026-03-27T21:17:51.985Z
Learning: In WLED PR `#5048` (wled00/cfg.cpp), the NTP crash on ESP32-C5 (pioarduino + IDF 5.5.x) is caused by both CONFIG_LWIP_TCPIP_CORE_LOCKING=y AND CONFIG_LWIP_CHECK_THREAD_SAFETY=y being enabled by default in the pioarduino/arduino-esp32 IDF 5.x sdkconfig. The tasmota core (IDF 5.3.x, used for C6) likely has CONFIG_LWIP_CHECK_THREAD_SAFETY=n, which is why the same violation does not crash on C6. Since pioarduino already has TCPIP_CORE_LOCKING enabled, wrapping ntpUdp.begin() (and any other raw lwIP API call) with LOCK_TCPIP_CORE()/UNLOCK_TCPIP_CORE() from lwip/tcpip.h is directly applicable without sdkconfig changes in platformio.ini.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5496
File: platformio.ini:551-553
Timestamp: 2026-04-11T22:54:01.648Z
Learning: In WLED (usermods/audioreactive/audio_reactive.cpp, ESP32-C3 I2S default pins): On ESP32-C3 DevKit boards, GPIO 7 and GPIO 8 are frequently wired to an onboard WS2812b RGB LED, and GPIO 9 is typically the BOOT button. These practical hardware constraints — combined with GPIO 2/8/9 being strapping pins, GPIO 12-17 being SPI flash reserved, and GPIO 18-19 being USB-JTAG pins — make GPIO 4 (SDPIN), 5 (WSPIN), 6 (CKPIN) the safest default I2S pin choices for AudioReactive on C3. Confirmed by softhack007 and aligned with WLED-MM defaults for C3.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5457
File: usermods/zigbee_rgb_light/usermod_zigbee_rgb_light.h:0-0
Timestamp: 2026-03-31T17:31:01.023Z
Learning: In WLED PR `#5457` (zigbee_rgb_light usermod): The WLED_MAX_DIGITAL_CHANNELS=0 build flag used in the esp32c6_zigbee environment is a temporary workaround for rmt_tx_wait_all_done() timeout spam when the Zigbee/802.15.4 stack is active. The root cause is under investigation and is likely related to Zigbee light-sleep (CONFIG_PM_ENABLE) disrupting RMT's internal time base, or ISR latency due to cache-disable during flash ops — NOT the 802.15.4 radio "sharing" the RMT peripheral (they are separate hardware). Because a proper fix (rmt_enable()/rmt_disable() PM-lock wrapping, allow_pd=0, CONFIG_RMT_TX_ISR_CACHE_SAFE) may eliminate the need to disable digital channels entirely, do NOT add a compile-time `#error` guard requiring WLED_MAX_DIGITAL_CHANNELS=0; doing so would prematurely bake in a constraint that may be lifted once the investigation concludes.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: platformio.ini:32-33
Timestamp: 2026-03-30T13:30:13.917Z
Learning: In WLED PR `#5048` (platformio.ini, [env:esp32p4_16MB]): The `board_build.arduino.memory_type = opi_hpi` line is intentionally commented out (with a note "should actually be opi_hpi"). The build succeeds without it — the pioarduino platform package (55.03.37) and esp32-p4-evboard.json provide sufficient defaults for the P4 flash/PSRAM interface. Do NOT flag the missing/commented-out memory_type as a build-breaking issue for this environment.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5457
File: platformio_override.ini:23-23
Timestamp: 2026-03-31T17:05:49.401Z
Learning: In WLED PR `#5457` (platformio_override.ini, esp32c6_zigbee): The comment "Zigbee 802.15.4 radio on C6 shares the RMT peripheral" is factually incorrect per official Espressif documentation. The ESP32-C6 802.15.4 radio does NOT use or share the RMT peripheral. What IS shared (documented in ESP32-C6 datasheet and ESP-IDF RF coexistence guide) is the single 2.4 GHz RF path (antenna/transceiver), shared among WiFi, BLE, and 802.15.4 via time-division multiplexing — this applies equally to WiFi, not just Zigbee. The rmt_tx_wait_all_done() timeout spam is most likely caused by Zigbee light-sleep enabling aggressive power management (CONFIG_PM_ENABLE) that disrupts RMT's internal time base, or ISR latency due to cache-disable during flash ops. Mitigations: wrap TX with rmt_enable()/rmt_disable() for PM lock, set allow_pd=0, or enable CONFIG_RMT_TX_ISR_CACHE_SAFE. For reliable WiFi+Zigbee gateway operation, Espressif officially recommends a dual-SoC solution (e.g., ESP32-S3 + ESP32-H2). ESP32-C5 has the same single-RF coexistence limitation as C6.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 4750
File: usermods/audioreactive/audio_reactive.cpp:311-321
Timestamp: 2025-06-27T06:04:44.652Z
Learning: In WLED's AudioReactive usermod, FFT buffer memory (valFFT, windowFFT) is allocated once during initialization and never deallocated, following typical embedded system design where core functionality buffers persist for the application lifetime. Raw buffer pointers for aligned allocations don't need to be tracked in the current implementation since deallocation is never performed.

[DedeHai]

I tried to hunt this down, here is what I have found:

• The bug is not at all related to the AR usermod (although it has some deficiencies regarding memory managemennt)
• C3 boot loops with ANY usermod BUT only if using just a single one - add two usermods and and it runs
• Commit 3bfbbab or the one before it b97b46a (dynarray) introduce the issue.
  @willmmiles I had claude.ai trace through memory alignment issues in .section but it came up empty handed claiming all is well. Can you please have a look?