Summary of differences between Ethernet and non-Ethernet builds - analysis, no code changes

[Copilot]

Per reviewer feedback, the original code change has been reverted — the DEFAULT_LED_PIN = 4 override when WLED_USE_ETHERNET is defined is an intentional safety measure. This PR now contains no code changes, only a summary of differences based on source code review.

Summary of Differences: Ethernet vs Non-Ethernet Builds

1. Default LED Pin (const.h:660)

• Ethernet build: DEFAULT_LED_PIN = 4 (GPIO4 — safe for all known ethernet boards)
• Non-ethernet build: DEFAULT_LED_PIN = 16 (GPIO16 — standard ESP32 default)
• Why: Many ethernet boards hard-wire GPIO16 to ethernet clock output (ETH_CLOCK_GPIO16_OUT). A fresh install with pin 16 on these boards causes crashes.

2. E1.31/Art-Net Universe Count (const.h:555)

• Ethernet build: E131_MAX_UNIVERSE_COUNT = 20
• Non-ethernet ESP32: E131_MAX_UNIVERSE_COUNT = 12
• Non-ethernet ESP8266: E131_MAX_UNIVERSE_COUNT = 9

3. SPI Bus for APA102/WS2801 LEDs (bus_wrapper.h:307,324)

• Ethernet build: Uses HSPI — avoids VSPI pin conflicts with ethernet (fix for APA102 don´t work with LAN8720 (WT32-ETH01) #2542)
• Non-ethernet build: Uses VSPI

4. Network Identity & Routing (Network.cpp)

• Ethernet build: Prefers ethernet MAC, IP, subnet, and gateway over WiFi. Falls back to WiFi if ethernet has no IP.
• Non-ethernet build: Uses WiFi MAC/IP only.
• Running an ethernet build on a non-ethernet board may result in an undefined MAC address.

5. Ethernet Board Configuration & Pin Reservation (network.cpp, wled.h)

• Ethernet build: Defines ethernetType global, initEthernet() allocates up to 10 pins (6 non-configurable RMII pins + MDC, MDIO, power, clock).
• RMII pins reserved: GPIO 19, 21, 22, 25, 26, 27 (non-configurable on classic ESP32).

6. WiFi Behavior on Ethernet Connect (network.cpp:413)

• Ethernet build: On ETH connect, WiFi is disconnected if AP is not active. On ETH disconnect, WiFi reconnection is forced.
• Non-ethernet build: WiFi lifecycle is unaffected.

7. Settings UI (xml.cpp:279, set.cpp:148)

• Ethernet build: Shows ethernet board type dropdown; reports "(Ethernet)" in IP display.
• Non-ethernet build: Ethernet settings section is hidden.

8. GPIO Reservation in Settings (xml.cpp:134)

• Ethernet build: Reports ethernet-reserved pins as unavailable in pin settings UI.

9. Configuration Persistence (cfg.cpp:133,913)

• Ethernet build: Reads/writes eth.type and eth.pin[] in cfg.json.

10. Debug Output Routing (net_debug.cpp:12,33)

• Ethernet build: Uses ETH.hostByName() for DNS resolution of debug host.
• Non-ethernet build: Uses WiFi.hostByName().

11. Audio Reactive aPLL Conflict (usermods/audioreactive/audio_source.h:234)

• Ethernet build: aPLL clock source is disabled for I2S MCLK audio — aPLL is needed by RMII ethernet clock (fix for Conflict between Ethernet and PDM mic on main #5391).
• Non-ethernet build: aPLL is enabled for improved audio sampling quality.

12. Usermod Behavior (quinled-an-penta)

• Ethernet build: Displays ethernet link status on OLED, tracks ethernet type changes.

13. Platform Restrictions

• Ethernet (RMII) requires the classic ESP32's built-in RMII MAC unit. Not available on ESP32-S2, S3, C3, C5, C6, or ESP8266.
• SPI-based ethernet (W5500) may become available for broader board support.

14. ESP-NOW Interactions (#5210, #4703)

• Ethernet boards using ETH_CLOCK_GPIO0_OUT, ETH_CLOCK_GPIO16_OUT, or ETH_CLOCK_GPIO17_OUT may crash when ESP-NOW is enabled.

15. Flash Space

• Ethernet builds require more program space due to the ETH driver, board definitions, and networking code.

Espressif ESP-IDF Recommendations

Per Espressif documentation, the ESP32 EMAC uses a dedicated RMII interface with fixed pins that cannot be remapped. WiFi and Ethernet can coexist but share some hardware resources (notably the aPLL clock). The recommendation is to configure the PHY and clock mode correctly for the specific board hardware.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[softhack007]

Builds with WLED_USE_ETHERNET but no adapter selected (WLED_ETH_NONE) unnecessarily change DEFAULT_LED_PIN from 16 to 4, diverging from non-ethernet builds for no reason. The esp32_eth environment already sets DATA_PINS=4 explicitly, making this override redundant for official builds.

This assessment was wrong.

1. The change in wled.h is needed because users may create custom buildenvs and forget to change the default pin
2. the change was introduced to avoid that a fresh install - intended for ethernet - saves a cfg.json with pin 16 for LEDs (at first boot-up). If running on an ethernet board, this causes random crashes because many ethernet boards have PIN 16 "hard-wired" to ethernet features.
3. relying on WLED_ETH_DEFAULT != WLED_ETH_NONE is dangerous. I would not recommend to do that.

Ask a human ;-)

The other differences between ethernet builds and normal (wifi-first) builds can be found by searching for WLED_USE_ETHERNET in the codebase.

• a few usermods behave differently
• ethernet builds prefer the ethernet MAC address and IP, while Wifi-first builds use the WiFi MAC. When running an ethernet build with a no-ethernet board, the MAC might stay undefined (00:00:00:00)
• you may have problems to configure audioreactive with an "I2S with MCLK" input, because MCLK-capable pins are already allocated by ethernet.
• A default build with esp-now enabled may crash on some ethernet boards (GLEDOPTO Ethernet locks, stops responding after ESP-NOW sync send #5210, ESP-NOW must be disabled on ESP32 Ethernet boards that use ESP32 as PHY clock source; WLED-AP is affected too! #4703)
• ethenet builds do not allow certains PINs for LEDs, buttons, or other features
• ethernet code must be disabled on all MCUs that don't have an RMII unit for ethernet. s3,s2,c3,c5,c6,8266.
• ethernet over SPI (W5500 chip) might come - this would work on many boards
• ethernet support on P4 will need another set of options in the UI any way
• Finally, ethernet builds need more program space in flash

In summary: yes an ethernet build will run on non-ethernet esp32, but some features may behave unexpected. A non-ethernet build on ethernet boards may run, or may crash.

[softhack007]

@copilot please revise your proposal based on the new information provided. Do not change code in this PR. Just provide a summary of differences, based on your source code review and other information available to you. Also check the official espressif documentation for recommendations regarding custom firmware with Wi-Fi and ethernet on esp32.

[Copilot]

@copilot please revise your proposal based on the new information provided. Do not change code in this PR. Just provide a summary of differences, based on your source code review and other information...

Reverted the code change in 37e4e48. The PR description now contains a comprehensive summary of all 15 categories of differences between ethernet-enabled and non-ethernet builds, based on reviewing every WLED_USE_ETHERNET conditional block in the codebase. This covers: DEFAULT_LED_PIN safety, E1.31 universe counts, SPI bus selection (HSPI vs VSPI), network identity/MAC routing, pin reservation, WiFi lifecycle on ETH events, settings UI, cfg.json persistence, debug routing, aPLL clock conflicts with audio reactive, usermod behavior, platform restrictions (classic ESP32 only), ESP-NOW conflicts, and flash space impact. Espressif recommendations on RMII/WiFi coexistence are also noted.