Discussion: move away from Arduino and into pure IDF?

[DedeHai]

Discussion started in #4838

While using Arduino has some advantages - ease of use of external libraries mostly - it comes with a bag of disadvantages like increased code size, restrictions of hardware support and some bad implementation choices.

The goal here is to discuss and explore the implications to libraries, usermods and forks.

[softhack007]

A few thoughts

• We should see this together with our future idea of a hardware abstraction layer.
  • At least a port to Linux might be interesting at some point, both for better testing tools and for opening the doors for a very high-performance hardware platform.
  • If we "fully embrace" esp-idf, we are also fully vendor-locked.
  • "fully embracing" esp-idf implies a lot of re-writing - network code (no Wifi or ETH objects), webserver, pin handling, serial output, file handling (no File object), and most "extended features" like IR, MQTT, DMX, Alexa, etc all need to be re-written
• Many usermods are written "arduino style", and I guess that dropping arduino-esp32 will break most of them.
• Many external libs - especially the ones needed for usermods - require Arduino
• We could continue with a "hybrid approach", and prefer esp-idf APIs over arduino-esp32 APIs. With this, we can't have any benefit in firmware size (Arduino will still be pulled-in by the linker), but the WLED core could benefit from lots of features that are not exposed in arduino-style APIs.
• "Arduino as an idf component" might work for us - we could configure the esp-idf kernel as we need it, but still having arduino support.
• Moving everything to esp-idf also means that 8266 support will die, unless we duplicate a lot of code to optionally use 8266 SDK APIs. Or we write our own "arduino-like" abstraction layer.

[DedeHai]

@coderabbitai please compile a summary list of used arduino functionalities in the codebase including usermods and libraries. What are the advantages and disadvantages / implications when moving from arduino to pure IDF?

[coderabbitai]

🧩 Analysis chain

Let me scan the codebase to compile a comprehensive picture of Arduino API usage before writing the final analysis.

---

🏁 Script executed:

#!/bin/bash
echo "=== Arduino.h includes ==="
rg -rn '#include.*Arduino\.h' --type=cpp --type=c -l | head -40

echo ""
echo "=== Wire (I2C) usage ==="
rg -rn '\bWire\b' --type=cpp --type=c -l | head -30

echo ""
echo "=== SPI usage ==="
rg -rn '\bSPI\b' --type=cpp --type=c -l | head -30

echo ""
echo "=== Serial usage ==="
rg -rn '\bSerial\b' --type=cpp --type=c -l | head -30

echo ""
echo "=== WiFi (arduino) usage ==="
rg -rn '\bWiFi\b' --type=cpp --type=c -l | head -30

echo ""
echo "=== ETH usage ==="
rg -rn '\bETH\b' --type=cpp --type=c -l | head -20

echo ""
echo "=== SPIFFS / LittleFS usage ==="
rg -rn '\bSPIFFS\b|\bLittleFS\b' --type=cpp --type=c -l | head -20

echo ""
echo "=== File / FS objects ==="
rg -rn '\bFile\b' --type=cpp --type=c -l | head -20

echo ""
echo "=== Ticker usage ==="
rg -rn '\bTicker\b' --type=cpp --type=c -l | head -10

echo ""
echo "=== HardwareSerial usage ==="
rg -rn '\bHardwareSerial\b' --type=cpp --type=c -l | head -10

echo ""
echo "=== delay / millis / micros ==="
rg -rn '\bdelay\b|\bmillis\b|\bmicros\b' --type=cpp --type=c -l | head -20

echo ""
echo "=== pinMode / digitalWrite / analogWrite ==="
rg -rn '\bpinMode\b|\bdigitalWrite\b|\banalogWrite\b|\bdigitalRead\b|\banalogRead\b' --type=cpp --type=c -l | head -20

echo ""
echo "=== String (Arduino String class) ==="
rg -rn '\bString\b' --type=cpp --type=c -l | head -20

echo ""
echo "=== LEDC / ledcSetup / ledcAttachPin ==="
rg -rn '\bledc\w*\b' --type=cpp --type=c -l | head -20

echo ""
echo "=== AsyncWebServer / ESPAsyncWebServer ==="
rg -rn 'AsyncWebServer\|ESPAsyncWebServer' --type=cpp --type=c -l | head -20

echo ""
echo "=== WebServer includes ==="
rg -rn '#include.*WebServer\|#include.*AsyncWebServer' --type=cpp --type=c -l | head -20

echo ""
echo "=== MQTT (PubSubClient or AsyncMQTT) ==="
rg -rn '\bMQTT\b|PubSubClient|AsyncMqttClient' --type=cpp --type=c -l | head -10

echo ""
echo "=== IRremoteESP8266 / IRrecv / IRsend ==="
rg -rn '\bIRrecv\b|\bIRsend\b|\bIRremote\b' --type=cpp --type=c -l | head -10

echo ""
echo "=== Preferences / EEPROM ==="
rg -rn '\bPreferences\b|\bEEPROM\b' --type=cpp --type=c -l | head -10

echo ""
echo "=== NeoPixelBus / FastLED ==="
rg -rn '\bNeoPixelBus\b|\bFastLED\b' --type=cpp --type=c -l | head -10

echo ""
echo "=== pgm_read / PROGMEM ==="
rg -rn '\bPROGMEM\b|\bpgm_read\b' --type=cpp --type=c -l | head -10

echo ""
echo "=== esp_idf direct calls already present ==="
rg -rn '#include.*esp_\w+\.h' --type=cpp --type=c -l | head -20

echo ""
echo "=== Arduino includes in usermods ==="
rg -rn '#include.*Arduino\.h' usermods/ -l 2>/dev/null | head -30

echo ""
echo "=== All Arduino-style library includes in usermods ==="
rg -rn '#include.*<Wire\.h>|#include.*<SPI\.h>|#include.*<SPIFFS\.h>|#include.*<LittleFS\.h>|#include.*<Ticker\.h>|#include.*<HardwareSerial\.h>' usermods/ -l 2>/dev/null | head -30

Length of output: 9988

---

🏁 Script executed:

#!/bin/bash
echo "=== AsyncWebServer / ESPAsyncTCP headers ==="
rg -rn 'ESPAsyncWebServer|AsyncWebServer|AsyncTCP|ESPAsyncTCP' --type=cpp -l | head -30

echo ""
echo "=== OTA / ArduinoOTA ==="
rg -rn 'ArduinoOTA|Update\.h|ElegantOTA' --type=cpp -l | head -20

echo ""
echo "=== DNS / mDNS ==="
rg -rn 'mDNS|DNSServer|mdns' --type=cpp -l | head -20

echo ""
echo "=== OneWire / DallasTemperature ==="
rg -rn 'OneWire|DallasTemperature' --type=cpp -l | head -10

echo ""
echo "=== attachInterrupt / detachInterrupt ==="
rg -rn 'attachInterrupt|detachInterrupt' --type=cpp -l | head -10

echo ""
echo "=== esp_idf already used - full list of esp_ includes ==="
rg -rn '#include.*<esp_' --type=cpp | head -40

echo ""
echo "=== FreeRTOS usage ==="
rg -rn 'xTaskCreate|vTaskDelay|xQueueCreate|TaskHandle_t|SemaphoreHandle|xSemaphore|portTICK|freertos' --type=cpp -l | head -20

echo ""
echo "=== Improv / BLE usage ==="
rg -rn 'BLE|Bluetooth|NimBLE' --type=cpp -l | head -10

echo ""
echo "=== Watchdog / esp_task_wdt ==="
rg -rn 'wdt|watchdog|esp_task_wdt' --type=cpp -l | head -10

echo ""
echo "=== usermod Wire.begin calls ==="
rg -n 'Wire\.begin\|Wire\.setClock\|Wire\.requestFrom\|Wire\.write\|Wire\.read\|Wire\.endTransmission' usermods/ | head -30

echo ""
echo "=== Core WLED Wire usage ==="
rg -n 'Wire\.' wled00/ | head -20

echo ""
echo "=== NeoPixelBus bus types used ==="
rg -n 'NeoPixelBus\|NeoBus\|NeoEsp32\|NeoEsp8266' wled00/bus_wrapper.h | head -40

echo ""
echo "=== esp-idf native calls used in wled core ==="
rg -n 'esp_wifi\|esp_netif\|esp_event\|esp_system\|esp_ota\|esp_https_ota\|nvs_flash\|nvs_open' wled00/ | head -30

echo ""
echo "=== WLED lib directory ==="
ls lib/ 2>/dev/null

echo ""
echo "=== External libs with their own Arduino dependencies ==="
find lib/ -name "*.h" -o -name "*.cpp" 2>/dev/null | xargs grep -l 'Arduino\.h' 2>/dev/null | head -20

echo ""
echo "=== platformio.ini lib_deps ==="
cat platformio.ini 2>/dev/null | grep -A 200 'lib_deps' | head -60

Length of output: 6931

---

@DedeHai Here is a comprehensive breakdown based on a full codebase scan.

---

Arduino Functionality Usage in WLED

1. Core Language / Runtime APIs

Arduino API	Used In	Scope
Arduino.h (base include)	wled.h, bus_manager.cpp, all bundled deps, 12+ usermods	Pervasive
delay() / millis() / micros()	Nearly every core .cpp, many usermods	Pervasive
String class	util.cpp, udp.cpp, wled_metadata.cpp, 10+ usermods	High
PROGMEM / pgm_read_*	Font headers, wled_metadata.cpp, presets.cpp, wled_server.cpp	Medium
Serial / HardwareSerial	wled_serial.cpp, SparkFunDMX.cpp, 10+ usermods	High

2. Hardware Peripheral APIs

Arduino API	Used In	Scope
Wire (I2C)	wled.h, cfg.cpp, set.cpp, DS1307RTC, 10+ usermods	High
SPI	pin_manager, bus_wrapper.h, FX_2Dfcn.cpp, presets.cpp, cfg.cpp, set.cpp, 6+ usermods	High
pinMode() / digitalWrite() / analogWrite() / digitalRead() / analogRead()	wled.cpp, set.cpp, SparkFunDMX, ESPDMX, 10+ usermods	High
LEDC Arduino wrappers (ledcSetup, ledcAttachPin, etc.)	pin_manager.h/.cpp, bus_manager.cpp, PWM_fan, pwm_outputs, quinled-an-penta	Medium
attachInterrupt() / detachInterrupt()	usermod_v2_rotary_encoder_ui_ALT, mpu6050_imu, PWM_fan	Low

3. Networking APIs

Arduino API	Used In	Scope
WiFi object (arduino-esp32)	network.cpp, wled.cpp, xml.cpp, udp.cpp, json.cpp, improv.cpp, button.cpp, fcn_declare.h, Network.h/.cpp abstraction, 5+ usermods	High
ETH object (arduino-esp32)	network.cpp, xml.cpp, set.cpp, net_debug.cpp, Network.h/.cpp, quinled-an-penta	Medium
mDNS / DNSServer	wled_server.cpp, network.cpp, wled.cpp, set.cpp, mqtt.cpp, improv.cpp	High
AsyncMqttClient (Arduino lib)	mqtt.cpp	Medium
ArduinoOTA	ota_update.h/.cpp, wled.cpp, xml.cpp	Medium

4. Storage APIs

Arduino API	Used In	Scope
LittleFS / SPIFFS	wled.h, file.cpp, sd_card usermod	Medium
File / FS objects	file.cpp, presets.cpp, cfg.cpp, wled_server.cpp, 4 usermods	High
Preferences / EEPROM	TTGO-T-Display, Temperature, photoresistor, Timezone.cpp	Low

5. Web Server

Arduino API	Used In	Scope
ESPAsyncWebServer (Aircoookie fork)	wled_server.cpp, set.cpp, file.cpp, json.cpp, ota_update.h/.cpp, Espalexa, 2 usermods	Critical
AsyncJson-v6.h	Bundled dep, used throughout JSON API	High
ESPAsyncTCP (ESP8266)	Platform-level dep	ESP8266 only

6. External Libraries (all Arduino-dependent)

Library	Version / Source	Used For
FastLED	3.6.0	Color palettes, HSV math, bus_manager.cpp, FX.h, colors.cpp
NeoPixelBus (Makuna fork)	git pin	LED bus drivers (bus_wrapper.h, bus_manager.cpp)
IRremoteESP8266	2.8.2	IR remote (ir.cpp, wled.h)
ESPAsyncWebServer	Aircoookie fork v2.4.2	Web API / UI
AsyncMqttClient	0.9.0	MQTT
QuickESPNow	Blazoncek fork	ESP-NOW
OneWire / DallasTemperature	optional	Temperature usermod
U8g2	optional	OLED display usermods
TFT_eSPI	optional	TFT display usermods
Adafruit BMP280 / CCS811 / Si7021 / BusIO / MAX1704X	optional	Sensor usermods
MPU6050	optional	IMU usermod

7. Bundled Dependencies (wled00/src/dependencies/)

All of these include Arduino.h directly:

Dependency	Arduino Dependency
espalexa/ (Alexa)	Arduino.h, ESPAsyncWebServer, WiFi
e131/ESPAsyncE131	Arduino.h, ESPAsyncWebServer, WiFi
dmx/ESPDMX + SparkFunDMX	Arduino.h, HardwareSerial, pinMode/digitalWrite
json/ArduinoJson-v6.h	Arduino.h (for PROGMEM, Stream)
network/Network.h/.cpp	WiFi, ETH objects
time/ (Time, Toki, DS1307RTC, Timezone)	Arduino.h, Wire

8. What is Already ESP-IDF Native (Hybrid already exists)

The codebase already uses ESP-IDF directly in several places:

IDF Header	Used In
esp_ota_ops.h, esp_flash.h, esp_app_format.h	ota_update.cpp
esp_dmx.h	dmx_input.h/.cpp
esp_timer.h	audioreactive/audio_reactive.cpp
esp_now.h	wled.h
FreeRTOS (xTaskCreate, SemaphoreHandle_t, portTICK_PERIOD_MS)	dmx_input, util.cpp, audioreactive, NeoESP32RmtHI

lib/NeoESP32RmtHI/ is already an IDF-native RMT driver (not Arduino).

---

Implications of Moving to Pure ESP-IDF

✅ Advantages

1. Performance & control: Direct FreeRTOS task/priority/stack control, no Arduino event loop overhead, finer-grained interrupt management.
2. ESP-IDF V5 feature access: Improved LEDC (note: the PWM/LEDC subsystem needs a full rewrite for IDF V5 anyway, per existing codebase learning), improved RMT, I2S, USB, LP core on ESP32-S/C series.
3. Better networking tuning: Direct LwIP configuration, esp_netif and esp_wifi APIs expose features (e.g. custom TX power curves, roaming hooks, 802.11r/k/v) not available through Arduino WiFi.
4. Smaller firmware (potentially): Arduino framework itself pulls in overhead; eliminating it could free flash/RAM, though this depends heavily on which libraries remain.
5. Long-term Espressif support trajectory: ESP-IDF is Espressif's primary SDK — newer chips (ESP32-P4, ESP32-C5/C61) are IDF-first.
6. Linux/native port: IDF's linux target enables host-based unit testing and opens the door to high-performance Linux LED platforms (as @softhack007 noted).
7. Debuggability: OpenOCD + GDB integration is better supported via IDF than Arduino.

❌ Disadvantages / Risks

1. Enormous rewrite scope — based on the scan, essentially every subsystem needs rewriting:

   • WiFi/ETH → esp_wifi + esp_netif
   • Web server → no IDF-native async HTTP server; need a new lib or port
   • Serial → uart_driver_install / uart_write_bytes
   • File system → esp_vfs, esp_littlefs
   • I2C → i2c_master (IDF V5 new driver) or i2c_driver_install
   • SPI → spi_bus_initialize, spi_device_queue_trans
   • GPIO → gpio_set_direction, gpio_set_level
   • LEDC/PWM → already needs rewriting for IDF V5 anyway
   • mDNS → IDF has mdns component but API differs
   • OTA → esp_https_ota (partially already used)
   • MQTT → esp_mqtt_client (IDF component, replaces AsyncMqttClient)
   • IR → no IDF equivalent for IRremoteESP8266; full replacement needed
   • Alexa (Espalexa) → heavily Arduino+AsyncWebServer coupled
   • E1.31 (ESPAsyncE131) → Arduino+AsyncWebServer coupled

2. ESP8266 support ends: ESP-IDF does not support ESP8266. All #ifdef ESP8266 code paths (including lib/ESP8266PWM/, ESP8266-specific build flags, ESPAsyncTCP) would be abandoned.

3. Virtually all usermods break: 12+ usermods include Arduino.h directly; nearly all use Wire, SPI, Serial, String, pinMode, digitalWrite — they would need full rewrites or a compatibility shim layer.

4. External library ecosystem lost: FastLED, NeoPixelBus, IRremoteESP8266, U8g2, TFT_eSPI, all Adafruit sensor libs, and most optional usermod libraries require Arduino. Some (e.g. NeoPixelBus) partially support IDF but this isn't their primary target.

5. Arduino String class pervasive: Used in 20+ files; requires replacement with std::string or manual char[] buffers.

6. Community contribution barrier rises sharply: The vast majority of usermod authors are Arduino developers. Pure IDF significantly raises the skill floor.

7. delay()/millis()/micros() everywhere: These are trivially replaceable (vTaskDelay, esp_timer_get_time, pdMS_TO_TICKS), but the sheer volume of call sites is high.

---

Recommended Path: Layered Hybrid Strategy

Given the above, a pragmatic layered approach seems most viable — consistent with what @softhack007 outlined:

┌─────────────────────────────────────────────────────┐
│              Usermods / External Libs               │  ← Keep Arduino-compatible shim
├─────────────────────────────────────────────────────┤
│              WLED Core (C++ / HAL)                  │  ← Progressively IDF-ify
├──────────────┬──────────────────────────────────────┤
│  Arduino-    │   ESP-IDF native (FreeRTOS, LEDC,    │
│  esp32 shim  │   RMT, I2S, esp_wifi, LittleFS, OTA) │
└──────────────┴──────────────────────────────────────┘
│              ESP-IDF kernel / LwIP / FreeRTOS        │
└─────────────────────────────────────────────────────┘

Concrete priorities where IDF APIs are clearly superior and already needed:

• LEDC/PWM: Must be rewritten for IDF V5 regardless (per prior learning)
• RMT: NeoESP32RmtHI is already IDF-native; complete the migration here
• OTA: Already partially uses esp_ota_ops.h; complete to esp_https_ota
• DMX input: Already uses esp_dmx.h natively
• FreeRTOS task management: Already used in audioreactive and DMX; standardize

Where Arduino-esp32 should be retained for now:

• WiFi / ETH objects (massive rewrite, low immediate gain)
• ESPAsyncWebServer (no IDF equivalent; this is a hard dependency)
• Wire / SPI (workable, but breaks all usermods if changed)
• All external libraries (FastLED, NeoPixelBus, etc.)

The "Arduino as IDF component" framing allows configuring the IDF kernel (task priorities, heap regions, partition tables, lwIP tuning) while keeping Arduino for the API surface that usermods and external libs depend on — this is likely the best near-to-medium term position.

---

🧠 Learnings used

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/bus_manager.cpp:549-556
Timestamp: 2026-02-11T16:20:02.872Z
Learning: ESP-IDF V5 requires a complete rewrite of the LEDC (PWM/analog LED) subsystem in WLED. The framework now manages LEDC channels internally (unlike V4 where WLED managed them directly), and dithering functionality may not work as it did before. Direct LEDC struct access (e.g., `LEDC.channel_group[gr].channel[ch].duty.duty`) used in the current implementation will need to be replaced with proper HAL API calls. This affects `wled00/bus_manager.cpp` BusPwm class and related pin manager LEDC allocation code.

---

Learnt from: netmindz
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2026-03-20T15:29:26.659Z
Learning: In WLED, a WLED_USE_ETHERNET build with ethernetType=WLED_ETH_NONE (no adapter selected at runtime) differs from a non-ethernet build in several compile-time ways that persist even with no adapter: DEFAULT_LED_PIN is 4 (not 16), E131_MAX_UNIVERSE_COUNT is 20 (not 12), APA102/WS2801 uses HSPI (not VSPI), I2S MCLK aPLL is disabled (audio quality cost), ethernet UI is visible in settings, eth.type=0 is written to cfg.json, and net_debug.cpp uses ETH.hostByName() (which will fail since ETH is never initialized). The runtime-gated behaviors (pin reservation, ETH.begin(), WiFi disconnect, MAC/IP preference) are correctly skipped when ethernetType==WLED_ETH_NONE.

---

Learnt from: mval-sg
Repo: wled/WLED PR: 4876
File: wled00/xml.cpp:0-0
Timestamp: 2025-08-28T08:09:20.630Z
Learning: The WLED codebase has opportunities for refactoring hardcoded array bounds (like the "15" used for DMX channels) to use sizeof(array)/sizeof(array[0]) for more maintainable code, but such changes should be done consistently across the entire codebase in a dedicated refactoring effort.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2026-03-15T13:21:32.008Z
Learning: In WLED code reviews (and generally), when a PR discussion involves "is this worth doing?" uncertainty about a proposed reliability, safety, or data-integrity mechanism (e.g. CRC checks, backups, power-loss protection), suggest performing a software FMEA (Failure Mode and Effects Analysis). The FMEA should: enumerate failure modes for the feared event, assess each mitigation's effectiveness per failure mode, note common-cause/common-mode failures, and rate credibility for the typical WLED use case. This was successfully used in PR `#5421` to evaluate CRC-based config file protection and was well-received by the WLED maintainers (softhack007 explicitly requested this be remembered for future reviews).

---

Learnt from: ksedgwic
Repo: wled/WLED PR: 4883
File: usermods/usermod_v2_skystrip/rest_json_client.h:6-14
Timestamp: 2025-08-29T00:26:15.808Z
Learning: WLED uses a vendored ArduinoJson library (version 6) located at "src/dependencies/json/ArduinoJson-v6.h" which is included through wled.h. Usermods should not directly include ArduinoJson headers but instead rely on wled.h for ArduinoJson symbols. The standard pattern is to include wled.h and use JsonObject, JsonArray, DynamicJsonDocument, etc. without additional includes.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/wled.cpp:385-387
Timestamp: 2026-02-08T19:33:02.648Z
Learning: In WLED ESP32 code, when checking whether USB CDC serial initialization delay is needed, rely on the ARDUINO_USB_CDC_ON_BOOT flag rather than explicit CONFIG_IDF_TARGET checks, because not all development boards for chips with native USB capability (ESP32-C3/C5/C6/S2/S3/H2/P4) actually use the native USB—many have external UART bridge chips instead. The ARDUINO_USB_CDC_ON_BOOT flag correctly indicates the board's actual USB configuration.

[coderabbitai]

🧩 Analysis chain

Let me search the codebase for Arduino API usage patterns across the core, usermods, and libraries.

---

🏁 Script executed:

#!/bin/bash
echo "=== Arduino.h includes ==="
rg -rn '#include.*[Aa]rduino' --type cpp --type h -l | head -60

echo ""
echo "=== WiFi object usage (arduino WiFi.h) ==="
rg -rn '#include.*WiFi\.h|WiFi\.begin|WiFi\.softAP|WiFi\.SSID|WiFi\.localIP|WiFi\.status|WiFi\.disconnect|WiFiClient|WiFiServer|WiFiUDP' -l | head -30

echo ""
echo "=== ETH object (arduino ethernet) ==="
rg -rn '#include.*ETH\.h|ETH\.begin|ETH\.localIP' -l | head -20

echo ""
echo "=== Serial usage ==="
rg -rn '\bSerial\b\.' -l | head -30

echo ""
echo "=== File / SPIFFS / LittleFS (arduino FS) ==="
rg -rn '#include.*FS\.h|#include.*SPIFFS|#include.*LittleFS|LittleFS\.|SPIFFS\.' -l | head -30

echo ""
echo "=== Wire / I2C (arduino) ==="
rg -rn '#include.*Wire\.h|\bWire\b\.' -l | head -20

echo ""
echo "=== SPI (arduino) ==="
rg -rn '#include.*SPI\.h|\bSPI\b\.' -l | head -20

echo ""
echo "=== Ticker (arduino) ==="
rg -rn '#include.*Ticker|Ticker ' -l | head -10

echo ""
echo "=== LEDC arduino ==="
rg -rn 'ledcAttach|ledcWrite|ledcSetup|ledcAttachPin' -l | head -20

echo ""
echo "=== digitalWrite / pinMode / analogRead ==="
rg -rn '\bdigitalWrite\b|\bpinMode\b|\banalogRead\b|\banalogWrite\b|\bdigitalRead\b' -l | head -30

echo ""
echo "=== millis / delay / micros ==="
rg -rn '\bmillis\(\)|\bdelay\(|\bmicros\(\)|\bdelayMicroseconds\(' -l | head -30

echo ""
echo "=== ESP.getXxx / ESP object ==="
rg -rn '\bESP\.' -l | head -20

echo ""
echo "=== ArduinoOTA ==="
rg -rn 'ArduinoOTA|#include.*ArduinoOTA' -l | head -10

echo ""
echo "=== IRremoteESP8266 ==="
rg -rn '#include.*IRremote|IRrecv|IRsend' -l | head -10

echo ""
echo "=== PubSubClient / MQTT ==="
rg -rn '#include.*PubSubClient|PubSubClient' -l | head -10

echo ""
echo "=== Espalexa / Alexa ==="
rg -rn '#include.*Espalexa|Espalexa' -l | head -10

echo ""
echo "=== AsyncTCP / ESPAsyncWebServer ==="
rg -rn '#include.*AsyncTCP|#include.*ESPAsyncWebServer|AsyncWebServer' -l | head -10

echo ""
echo "=== E131 / DMX ==="
rg -rn '#include.*ESPAsyncE131|#include.*ESPDMX|e131|dmx' -li | head -10

echo ""
echo "=== preferences / EEPROM ==="
rg -rn '#include.*Preferences|#include.*EEPROM|\bEEPROM\b|\bPreferences\b' -l | head -10

echo ""
echo "=== HTTPClient ==="
rg -rn '#include.*HTTPClient|HTTPClient' -l | head -10

echo ""
echo "=== NeoPixelBus ==="
rg -rn '#include.*NeoPixelBus' -l | head -10

echo ""
echo "=== Usermods count ==="
fd . usermods -t d --max-depth 1 | wc -l

echo ""
echo "=== Usermods using Arduino-style includes ==="
rg -rn '#include.*Arduino\.h' usermods/ -l | head -30

echo ""
echo "=== String (Arduino String class) usage in core ==="
rg -rn '\bString\b' wled00/ -l | head -20

Length of output: 11143

---

@DedeHai, here's a comprehensive breakdown based on a live scan of the codebase. There are 73 usermods and a large core with widespread Arduino API usage across every functional layer.

---

Arduino API Usage in WLED

1. Core Runtime & Utility APIs

Arduino API	Files Affected	Notes
millis(), delay(), micros(), delayMicroseconds()	Core + virtually all 73 usermods	Most pervasive; maps to esp_timer / vTaskDelay in IDF
digitalWrite(), pinMode(), digitalRead(), analogRead(), analogWrite()	button.cpp, bus_manager.cpp, set.cpp, cfg.cpp, network.cpp + ~15 usermods	Maps to gpio_set_level(), gpio_config(), adc1_get_raw() in IDF
Arduino String class	Throughout entire core (wled.h, util.cpp, mqtt.cpp, ir.cpp, json.cpp, set.cpp, etc.)	Would need replacement with std::string or char* + custom helpers
ESP.getFreeHeap(), ESP.getChipRevision(), ESP.restart(), etc.	xml.cpp, util.cpp, json.cpp, ota_update.cpp, bus_manager.cpp, FX_fcn.cpp, pin_manager.cpp	Maps to esp_get_free_heap_size(), esp_chip_info(), esp_restart() in IDF
Serial (UART)	wled_serial.cpp, wled.cpp, wled_math.cpp + ~15 usermods	Maps to uart_write_bytes() / ESP_LOG* in IDF

2. Networking Stack

Arduino API	Files Affected	Notes
Arduino WiFi object (WiFi.begin, WiFi.softAP, WiFi.SSID, WiFi.localIP, etc.)	wled.h, wled.cpp, network.cpp, udp.cpp, xml.cpp, json.cpp, improv.cpp + ~12 usermods	Full rewrite using esp_wifi_* IDF APIs
Arduino ETH object (ETH.begin, ETH.localIP)	wled.h, network.cpp, Network.h/cpp	Full rewrite using esp_eth_* IDF APIs
WiFiUDP	udp.cpp, ESPAsyncE131.h	IDF has lwIP UDP sockets directly
AsyncTCP / ESPAsyncWebServer	wled_server.cpp, wled.h, ota_update.cpp, set.cpp, json.cpp + 2 usermods	Arduino-only libraries; no direct IDF equivalent; would need full HTTP server rewrite (e.g. esp_http_server)

3. Hardware Peripherals

Arduino API	Files Affected	Notes
Wire (I2C)	wled.h, set.cpp, cfg.cpp + ~10 usermods (MPU6050, BME280, BME68X, VL53L0X, OLED displays, temp sensors)	Maps to i2c_master_* IDF APIs; many sensor libs are Arduino-only
SPI	wled.h, set.cpp, cfg.cpp, pin_manager.h, const.h + ~5 usermods (SD card, TFT displays)	Maps to spi_master_* IDF APIs
ledcAttach*, ledcWrite, ledcSetup (LEDC/PWM)	bus_manager.cpp, pwm_outputs/pwm_outputs.cpp, PWM_fan/PWM_fan.cpp	IDF V5 manages LEDC internally — already a known pain point (see existing learning)

4. File System

Arduino API	Files Affected	Notes
LittleFS / SPIFFS (File, Dir, FS)	wled.h, EleksTube_IPS/TFTs.h (and transitively file.cpp, presets.cpp, cfg.cpp)	Maps to esp_littlefs IDF component; File/Dir objects need full replacement

5. Protocol / Feature Libraries (Arduino-only)

Library	Files Affected	Replaceability
ArduinoOTA	wled.h, wled.cpp, ota_update.h/cpp, xml.cpp	Replace with esp_https_ota / custom IDF OTA
IRremoteESP8266	wled.h, ir.cpp	Arduino-only; no IDF equivalent; full IR subsystem rewrite needed
Espalexa (Alexa/Hue emulation)	wled.h, alexa.cpp, src/dependencies/espalexa/*	Arduino-only; would require from-scratch UDP/HTTP Hue emulation
ESPAsyncE131 (sACN/E1.31)	wled.h, udp.cpp, src/dependencies/e131/*	Arduino/AsyncUDP-based; rewrite using raw lwIP sockets
ESPDMX / SparkFunDMX	wled.h, src/dependencies/dmx/*	Arduino Serial-dependent
NeoPixelBus	bus_wrapper.h, lib/NeoESP32RmtHI/*	Partially IDF-compatible (RMT backend), but Arduino wrapper layer is used
ArduinoJson v6	Vendored at src/dependencies/json/	Standalone C++ lib — already IDF-compatible, no changes needed

6. Usermods

• 12 of 73 usermods explicitly #include <Arduino.h>
• Almost all usermods use Arduino-style APIs: Wire, SPI, Serial, WiFi, millis(), digitalWrite(), String
• Many usermods depend on Arduino-ecosystem sensor/display libraries (e.g. Adafruit, U8g2, TFT_eSPI) which are Arduino-only

---

Advantages of Moving to Pure ESP-IDF

Advantage	Details
Smaller firmware	Arduino layer adds significant overhead; pure IDF binaries can be noticeably smaller
Lower latency	Direct access to FreeRTOS task/queue primitives, no Arduino loop() bottleneck
Better LEDC/RMT/I2S control	Direct HAL access to hardware — critical for LED drivers and audio (AudioReactive)
Full FreeRTOS power	Task priorities, core pinning, mutexes without Arduino abstraction workarounds
IDF component ecosystem	Access to Espressif's managed components (MQTT, HTTP, OTA, provisioning) without Arduino wrappers
IDF V5+ features	Thread-local storage, improved power management, better BT/BLE
Linux/host build target	IDF supports a Linux POSIX target useful for unit testing and simulation

Disadvantages / Implications

Disadvantage	Details
Massive rewrite scope	Networking, webserver, OTA, file I/O, serial, IR, Alexa, E1.31, DMX all need full rewrites
73 usermods broken	Virtually all usermods would need porting; community contribution velocity would drop sharply
External library loss	IRremoteESP8266, ESPAsyncWebServer, Espalexa, NeoPixelBus Arduino mode, many sensor libs — all Arduino-only
ESP8266 support dies	IDF is ESP32-only; 8266 support would require a parallel SDK or full abstraction layer
"Arduino as IDF component"	The hybrid approach softhack007 mentioned: keeps Arduino for compatibility but allows direct IDF calls for performance-critical subsystems — no firmware size savings though
Vendor lock-in	As softhack007 noted, full IDF adoption creates complete dependency on Espressif's toolchain and HAL
Community barrier	The vast majority of usermod contributors know Arduino; IDF has a steeper learning curve

---

Summary Recommendation

A pure IDF migration is extremely high-cost given the breadth of Arduino API usage across the core, all 73 usermods, and numerous Arduino-only libraries. The most pragmatic path forward — aligned with softhack007's suggestion — would be:

1. Hybrid approach: continue using Arduino-ESP32 as the base but prefer direct IDF APIs for performance-critical subsystems (LEDC, RMT/I2S, SPI DMA, task management)
2. HAL-first design: any new subsystem (e.g. the new bus abstraction) should use an internal hardware abstraction layer that could theoretically be backed by either Arduino or IDF — keeping the Linux port door open
3. Selective library replacement: replace the most painful Arduino-only dependencies (ESPAsyncWebServer, IRremote) incrementally rather than as a "big bang" rewrite

---

🧠 Learnings used

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/bus_manager.cpp:549-556
Timestamp: 2026-02-11T16:20:02.872Z
Learning: ESP-IDF V5 requires a complete rewrite of the LEDC (PWM/analog LED) subsystem in WLED. The framework now manages LEDC channels internally (unlike V4 where WLED managed them directly), and dithering functionality may not work as it did before. Direct LEDC struct access (e.g., `LEDC.channel_group[gr].channel[ch].duty.duty`) used in the current implementation will need to be replaced with proper HAL API calls. This affects `wled00/bus_manager.cpp` BusPwm class and related pin manager LEDC allocation code.

---

Learnt from: netmindz
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2026-03-20T15:29:26.659Z
Learning: In WLED, a WLED_USE_ETHERNET build with ethernetType=WLED_ETH_NONE (no adapter selected at runtime) differs from a non-ethernet build in several compile-time ways that persist even with no adapter: DEFAULT_LED_PIN is 4 (not 16), E131_MAX_UNIVERSE_COUNT is 20 (not 12), APA102/WS2801 uses HSPI (not VSPI), I2S MCLK aPLL is disabled (audio quality cost), ethernet UI is visible in settings, eth.type=0 is written to cfg.json, and net_debug.cpp uses ETH.hostByName() (which will fail since ETH is never initialized). The runtime-gated behaviors (pin reservation, ETH.begin(), WiFi disconnect, MAC/IP preference) are correctly skipped when ethernetType==WLED_ETH_NONE.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2026-03-15T13:21:32.008Z
Learning: In WLED code reviews (and generally), when a PR discussion involves "is this worth doing?" uncertainty about a proposed reliability, safety, or data-integrity mechanism (e.g. CRC checks, backups, power-loss protection), suggest performing a software FMEA (Failure Mode and Effects Analysis). The FMEA should: enumerate failure modes for the feared event, assess each mitigation's effectiveness per failure mode, note common-cause/common-mode failures, and rate credibility for the typical WLED use case. This was successfully used in PR `#5421` to evaluate CRC-based config file protection and was well-received by the WLED maintainers (softhack007 explicitly requested this be remembered for future reviews).

---

Learnt from: ksedgwic
Repo: wled/WLED PR: 4883
File: usermods/usermod_v2_skystrip/rest_json_client.h:6-14
Timestamp: 2025-08-29T00:26:15.808Z
Learning: WLED uses a vendored ArduinoJson library (version 6) located at "src/dependencies/json/ArduinoJson-v6.h" which is included through wled.h. Usermods should not directly include ArduinoJson headers but instead rely on wled.h for ArduinoJson symbols. The standard pattern is to include wled.h and use JsonObject, JsonArray, DynamicJsonDocument, etc. without additional includes.

---

Learnt from: mval-sg
Repo: wled/WLED PR: 4876
File: wled00/xml.cpp:0-0
Timestamp: 2025-08-28T08:09:20.630Z
Learning: The WLED codebase has opportunities for refactoring hardcoded array bounds (like the "15" used for DMX channels) to use sizeof(array)/sizeof(array[0]) for more maintainable code, but such changes should be done consistently across the entire codebase in a dedicated refactoring effort.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
echo "=== Arduino Serial usage ==="
rg -rn --type cpp "Serial\." --include="*.h" --include="*.cpp" -l | head -30

echo ""
echo "=== Wire (I2C) usage ==="
rg -rn "Wire\." -l | head -30

echo ""
echo "=== SPI usage ==="
rg -rn "SPI\." -l | head -20

echo ""
echo "=== digitalWrite / pinMode / digitalRead / analogWrite / analogRead ==="
rg -rn "\b(digitalWrite|pinMode|digitalRead|analogWrite|analogRead|analogReadMilliVolts)\s*\(" -l | head -30

echo ""
echo "=== millis / micros / delay / delayMicroseconds ==="
rg -rn "\b(millis|micros|delay|delayMicroseconds)\s*\(" -l | head -20

echo ""
echo "=== Arduino String class ==="
rg -rn "\bString\b" -l | head -20

echo ""
echo "=== WiFi Arduino API ==="
rg -rn "\bWiFi\." -l | head -20

echo ""
echo "=== File / LittleFS / SPIFFS ==="
rg -rn "\b(SPIFFS|LittleFS|File)\b" -l | head -20

echo ""
echo "=== ESP Arduino-specific: ESP.get, ESP.free, ESP.restart ==="
rg -rn "ESP\.(getFreeHeap|getMaxAllocHeap|restart|getCpuFreqMHz|getChipModel|getFreeSketchSpace|reset)\s*\(" -l | head -20

echo ""
echo "=== WebServer / ESPAsyncWebServer ==="
rg -rn "\b(WebServer|AsyncWebServer|ESPAsyncWebServer)\b" -l | head -20

echo ""
echo "=== Ticker / HardwareTimer ==="
rg -rn "\b(Ticker|HardwareTimer)\b" -l | head -20

echo ""
echo "=== ArduinoJson ==="
rg -rn "ArduinoJson|JsonDocument|DynamicJsonDocument|StaticJsonDocument" -l | head -20

echo ""
echo "=== Arduino `#include` patterns ==="
rg -rn '#include\s*[<"](Arduino|Wire|SPI|WiFi|SPIFFS|LittleFS|FS|Ticker|Update|Preferences|HTTPClient|WebServer|ESPAsyncWebServer|AsyncTCP|ESPmDNS|PubSubClient|IRremote|FastLED|Adafruit)' -l | head -40

echo ""
echo "=== attachInterrupt / detachInterrupt ==="
rg -rn "\b(attachInterrupt|detachInterrupt)\s*\(" -l | head -20

echo ""
echo "=== EEPROM / Preferences ==="
rg -rn "\b(EEPROM|Preferences)\b" -l | head -20

echo ""
echo "=== xTaskCreate / TaskHandle (FreeRTOS direct) ==="
rg -rn "\b(xTaskCreate|xTaskCreatePinnedToCore|vTaskDelay|TaskHandle_t)\b" -l | head -20

echo ""
echo "=== Ethernet (Arduino ETH) ==="
rg -rn "\bETH\." -l | head -20

echo ""
echo "=== NeoPixelBus / FastLED ==="
rg -rn "\b(NeoPixelBus|FastLED|CRGB)\b" -l | head -20

echo ""
echo "=== ledcSetup / ledcAttach / ledc (Arduino LEDC) ==="
rg -rn "\b(ledcSetup|ledcAttachPin|ledcWrite|ledcAttach)\s*\(" -l | head -20

echo ""
echo "=== i2s (Arduino-style or raw IDF) ==="
rg -rn "\bi2s_" -l | head -20

echo ""
echo "=== HTTPClient / HTTPUpdate ==="
rg -rn "\b(HTTPClient|HTTPUpdate)\b" -l | head -20

echo ""
echo "=== mDNS (MDNS object) ==="
rg -rn "\bMDNS\." -l | head -20

echo ""
echo "=== update / OTA (ArduinoOTA / Update) ==="
rg -rn "\b(ArduinoOTA|Update\.(begin|write|end|setMD5))\b" -l | head -20

Length of output: 10190

---

@DedeHai, here is a comprehensive analysis based on a full codebase scan.

---

Arduino API Usage in WLED

1. Core (wled00/) — Arduino Surface Area

Category	API / Object	Files Affected
GPIO	digitalWrite, pinMode, digitalRead, analogWrite, analogRead	wled.cpp, set.cpp, button.cpp, json.cpp, cfg.cpp, bus_manager.cpp, network.cpp, DMX deps
Timing	millis(), micros(), delay(), delayMicroseconds()	Nearly every core file
String	Arduino String class	wled.h, util.cpp, udp.cpp, set.cpp, wled_server.cpp, and more
I2C	Wire object	wled.h, set.cpp, cfg.cpp, DS1307RTC dep
SPI	SPI object	wled.h, set.cpp, pin_manager.h, const.h, cfg.cpp
WiFi	Arduino WiFi object	wled.h, wled.cpp, network.cpp, udp.cpp, util.cpp, xml.cpp, net_debug.cpp
Ethernet	Arduino ETH object	network.cpp, net_debug.cpp, wled.h, Network.h/cpp
Filesystem	File, LittleFS, SPIFFS	file.cpp, cfg.cpp, presets.cpp, wled_server.cpp, FX_fcn.cpp, image_loader.cpp
ESP object	ESP.getFreeHeap(), ESP.restart(), ESP.getMaxAllocHeap(), ESP.getCpuFreqMHz()	xml.cpp, wled.cpp, util.cpp, json.cpp, bus_manager.cpp, ota_update.cpp
Web server	ESPAsyncWebServer	wled.h, wled_server.cpp, json.cpp, fcn_declare.h
OTA / Update	ArduinoOTA, Update	wled.h, wled.cpp, ota_update.cpp/h
mDNS	MDNS object	wled.cpp, mqtt.cpp
LED color	FastLED (CRGB, palettes)	colors.h/cpp, palettes.cpp, led.cpp, FX.h, json.cpp
LEDC (PWM)	ledcSetup, ledcAttachPin, ledcWrite	bus_manager.cpp
I2S	i2s_* (raw IDF calls)	bus_manager.cpp
FreeRTOS	xTaskCreate, xTaskCreatePinnedToCore, TaskHandle_t, vTaskDelay	dmx_input.h/cpp

2. Vendored Dependencies — Arduino-Dependent

Library	Arduino APIs Used
ArduinoJson v6	Arduino String, Stream
ESPAsyncE131	Arduino WiFi, UDP
Espalexa	Arduino WiFi, String, UDP, WebServer
DS1307RTC	Arduino Wire
Timezone	Arduino EEPROM
Toki	Arduino.h
SparkFunDMX / ESPDMX	digitalWrite, Serial
NeoPixelBus (lib/NeoESP32RmtHI)	xTaskCreate (FreeRTOS)
AsyncJson-v6	ESPAsyncWebServer, ArduinoJson

3. Usermods — Arduino API Usage

Category	Affected Usermods
Wire (I2C)	VL53L0X, MPU6050, BME280, rotary_encoder_ui_ALT, four_line_display_ALT, TTGO-T-Display, Temperature, quinled-an-penta, Wemos_D1_mini, Si7021, sht
SPI	sd_card, pixels_dice_tray, TTGO-T-Display, ST7789_display, EleksTube_IPS
GPIO (digitalWrite/pinMode)	multi_relay, PIR_sensor_switch, buzzer, rotary_encoder, photoresistor, deep_sleep, RelayBlinds, audioreactive, and ~15 more
attachInterrupt	rotary_encoder_ui_ALT, mpu6050_imu, PIR_sensor_switch, PWM_fan
Arduino String	Widespread — nearly all usermods
WiFi object	deep_sleep, smartnest, HttpPullLightControl, quinled-an-penta, audioreactive, Wemos, TTGO
LEDC	PWM_fan, pwm_outputs
I2S	audioreactive (audio_source.h, audio_reactive.cpp)
FreeRTOS direct	audioreactive, four_line_display_ALT
FastLED / NeoPixelBus	animartrix, pov_display, audioreactive, TetrisAI, user_fx
EEPROM / Preferences	photoresistor_mqtt, Temperature, TTGO (older usermods)
PubSubClient (MQTT)	sensors_to_mqtt, Si7021_MQTT_HA
Adafruit libs	BME280_v2, Si7021
IRremote	usermod_v2_RF433

---

Moving to Pure ESP-IDF: Advantages & Disadvantages

✅ Advantages

Area	Benefit
Performance & Memory	No Arduino overhead layer; smaller binary; direct control of task/heap allocation; faster boot
LED output	Full control over RMT, I2S, and DMA parameters — already partially done in bus_manager.cpp
PWM / LEDC	IDF V5 manages LEDC channels with proper HAL APIs (the Arduino LEDC layer is a known pain point — see existing learning about ESP-IDF V5 LEDC rewrite requirement)
WiFi/Networking	Access to advanced features: WPA3, PMF, roaming, fine-grained power management, raw socket access — not exposed through WiFi Arduino object
Partitioning & OTA	Direct control of esp_ota_* APIs, bootloader, and partition table without Arduino's abstraction constraints
Multi-core / Tasks	Already using FreeRTOS directly in dmx_input and NeoPixelBus; IDF exposes full task, queue, and event-group primitives cleanly
Debug / Tooling	idf.py, JTAG debugging, coredump analysis, and OpenOCD work far better without Arduino in the way
Linux portability	A pure-IDF or HAL-based core opens the door to POSIX/Linux porting (as noted by @softhack007)
Config granularity	sdkconfig / menuconfig gives per-project kernel tuning (stack sizes, task priorities, log levels, Bluetooth, etc.)

❌ Disadvantages / Implications

Area	Risk / Cost
Networking stack rewrite	WiFi, ETH, mDNS, ESPAsyncWebServer, ESPAsyncE131, Espalexa, ArduinoOTA all need replacing. This is the largest single effort.
Filesystem	File/LittleFS/SPIFFS objects need replacing with esp_vfs, esp_littlefs — API is different but IDF equivalents exist
String class	std::string or custom replacement required everywhere; impacts nearly every .cpp file in core and usermods
GPIO/timing primitives	digitalWrite → gpio_set_level, pinMode → gpio_config, millis → esp_timer_get_time / xTaskGetTickCount — mechanical but very widespread
I2C / SPI	Wire → i2c_master_*, SPI → spi_device_* — API is more verbose and requires handle management
Serial / Logging	Serial.print → ESP_LOG* macros; logging subsystem is different
ESP8266 support dies	No IDF on 8266; without an abstraction layer, 8266 support cannot be maintained
All usermods break	Virtually every usermod uses Wire, SPI, GPIO, String, and WiFi — all would need rewriting or a compatibility shim
External library ecosystem	PubSubClient, Adafruit sensor libs, IRremote, etc. all depend on Arduino; replacements or wrappers needed
NeoPixelBus / FastLED	These are Arduino-targeted; FastLED color/palette types (CRGB, CRGBPalette16) are used throughout the FX engine
Community contributions	WLED's contributor base is "Arduino-style" (as @softhack007 noted); pure IDF raises the barrier to entry significantly
ArduinoJson	While it can build without Arduino, it is vendored as v6 and already abstracted — lower migration risk

---

Summary Assessment

The codebase has deep, pervasive coupling to the Arduino-ESP32 layer across all subsystems. The areas closest to IDF-native today are:

• LED output (I2S/RMT in bus_manager.cpp)
• Task management (FreeRTOS direct calls in dmx_input, audioreactive)
• LEDC (partially — direct struct access, which is the known ESP-IDF V5 issue)

The areas requiring the most effort to migrate are:

1. The entire networking stack (WiFi + WebServer + dependencies)
2. The Arduino String class (used in nearly every file)
3. The Filesystem layer
4. All usermods and their external library dependencies

The "Arduino as an IDF component" hybrid approach (as @softhack007 suggested) seems like the most pragmatic path: it allows targeted migration of high-value subsystems (LED output, LEDC, WiFi config) while preserving usermod compatibility and keeping ESP8266 on a separate code path or legacy branch.

---

🧠 Learnings used

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/bus_manager.cpp:549-556
Timestamp: 2026-02-11T16:20:02.872Z
Learning: ESP-IDF V5 requires a complete rewrite of the LEDC (PWM/analog LED) subsystem in WLED. The framework now manages LEDC channels internally (unlike V4 where WLED managed them directly), and dithering functionality may not work as it did before. Direct LEDC struct access (e.g., `LEDC.channel_group[gr].channel[ch].duty.duty`) used in the current implementation will need to be replaced with proper HAL API calls. This affects `wled00/bus_manager.cpp` BusPwm class and related pin manager LEDC allocation code.

---

Learnt from: netmindz
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2026-03-20T15:29:26.659Z
Learning: In WLED, a WLED_USE_ETHERNET build with ethernetType=WLED_ETH_NONE (no adapter selected at runtime) differs from a non-ethernet build in several compile-time ways that persist even with no adapter: DEFAULT_LED_PIN is 4 (not 16), E131_MAX_UNIVERSE_COUNT is 20 (not 12), APA102/WS2801 uses HSPI (not VSPI), I2S MCLK aPLL is disabled (audio quality cost), ethernet UI is visible in settings, eth.type=0 is written to cfg.json, and net_debug.cpp uses ETH.hostByName() (which will fail since ETH is never initialized). The runtime-gated behaviors (pin reservation, ETH.begin(), WiFi disconnect, MAC/IP preference) are correctly skipped when ethernetType==WLED_ETH_NONE.

---

Learnt from: mval-sg
Repo: wled/WLED PR: 4876
File: wled00/xml.cpp:0-0
Timestamp: 2025-08-28T08:09:20.630Z
Learning: The WLED codebase has opportunities for refactoring hardcoded array bounds (like the "15" used for DMX channels) to use sizeof(array)/sizeof(array[0]) for more maintainable code, but such changes should be done consistently across the entire codebase in a dedicated refactoring effort.

---

Learnt from: ksedgwic
Repo: wled/WLED PR: 4883
File: usermods/usermod_v2_skystrip/rest_json_client.h:6-14
Timestamp: 2025-08-29T00:26:15.808Z
Learning: WLED uses a vendored ArduinoJson library (version 6) located at "src/dependencies/json/ArduinoJson-v6.h" which is included through wled.h. Usermods should not directly include ArduinoJson headers but instead rely on wled.h for ArduinoJson symbols. The standard pattern is to include wled.h and use JsonObject, JsonArray, DynamicJsonDocument, etc. without additional includes.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2026-03-15T13:21:32.008Z
Learning: In WLED code reviews (and generally), when a PR discussion involves "is this worth doing?" uncertainty about a proposed reliability, safety, or data-integrity mechanism (e.g. CRC checks, backups, power-loss protection), suggest performing a software FMEA (Failure Mode and Effects Analysis). The FMEA should: enumerate failure modes for the feared event, assess each mitigation's effectiveness per failure mode, note common-cause/common-mode failures, and rate credibility for the typical WLED use case. This was successfully used in PR `#5421` to evaluate CRC-based config file protection and was well-received by the WLED maintainers (softhack007 explicitly requested this be remembered for future reviews).

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/wled.cpp:385-387
Timestamp: 2026-02-08T19:33:02.648Z
Learning: In WLED ESP32 code, when checking whether USB CDC serial initialization delay is needed, rely on the ARDUINO_USB_CDC_ON_BOOT flag rather than explicit CONFIG_IDF_TARGET checks, because not all development boards for chips with native USB capability (ESP32-C3/C5/C6/S2/S3/H2/P4) actually use the native USB—many have external UART bridge chips instead. The ARDUINO_USB_CDC_ON_BOOT flag correctly indicates the board's actual USB configuration.

[softhack007]

pioarduino has an "Arduino Hybrid Mode" that allows esp-idf configuration (add/remove driver, change timing, etc) while everything else still looks like Arduino.

https://deepwiki.com/pioarduino/platform-espressif32/2.9-sdk-configuration-and-build-flags#custom_sdkconfig-option-arduino-hybrid-mode

[env:esp32s3-custom]
framework = arduino
board = esp32s3-devkitc-1
custom_sdkconfig = 
    CONFIG_SPIRAM_SPEED=120
    CONFIG_SPIRAM_SPEED_120M=y
    CONFIG_LCD_RGB_ISR_IRAM_SAFE=y

[willmmiles]

I've had some success doing low-level debugging with framework = arduino, esp-idf, essentially getting a "best of both worlds": a custom IDF compile, with the Arduino framework on top. It's a little different than the hybrid mode in that you get the full menuconfig interface of IDF proper, access to the component manager, all the bells and whistles, but it still brings in the Arduino framework on top.

To speak directly to the topic: my preference would be to steer the project towards supporting more platforms, not fewer. So no, I think that replacing Arduino with ESP-IDF would be a mistake. I think that tying ourselves to a specific vendor toolchain would make this project less useful.

Instead I think we would be best served by isolating the platform touch points in a HAL. I'd be happy to aim for packing Arduino-isms behind that HAL -- letting platforms choose to use common Arduino code for wifi management, or rolling their own wifi implementation of the HAL using native tools is the ideal approach.

In that sense, I do agree that we should be moving our source code away from Arduino-isms. Ideally none of our non-HAL source files would need to include any Arduino headers directly. (For all its warts, IMO std::string<> is a better design than String!)

Or to put it another way: given a choice between Arduino and ESP-IDF, I think the best answer is: both!