Add WiFi band preference for dual-band ESP32 chips

[jonny190]

Summary

• Adds a "WiFi band" dropdown to WiFi settings: 2.4 GHz only, 5 GHz only, or Auto (both)
• Defaults to Auto on dual-band chips
• Uses WiFi.setBandMode() from the Arduino ESP32 core (IDF 5.4.2+)
• Replaces the hardcoded WIFI_BAND_MODE_AUTO in V5-C6 with a user-selectable setting
• Guarded by #ifdef SOC_WIFI_SUPPORT_5G - zero impact on single-band builds
• Input validation ensures only valid band mode values (1-3) are accepted

Changes (6 files, 32 lines added, 4 removed)

File	Change
wled00/wled.h	New wifiBandMode global (default: WIFI_BAND_MODE_AUTO)
wled00/cfg.cpp	Serialize/deserialize with range validation
wled00/set.cpp	Handle BM form param with validation, trigger reconnect
wled00/xml.cpp	Populate dropdown value; hide on non-5G chips
wled00/wled.cpp	Pass wifiBandMode to WiFi.setBandMode() in initConnection()
wled00/data/settings_wifi.htm	"WiFi band" dropdown in Experimental section

Test plan

Tested on ESP32-C5 hardware:

• Auto mode - connects to strongest available AP
• 5 GHz only mode - connects to 5 GHz AP (channel 44)
• 2.4 GHz only mode - connects to 2.4 GHz AP (channel 6)
• Settings persist across reboots (verified in /cfg.json)
• Dropdown hidden on non-5G chips
• Band mode change triggers WiFi reconnection
• Invalid values rejected (validation in set.cpp and cfg.cpp)

Summary by CodeRabbit

• New Features

  • Added WiFi band selector (Experimental): 2.4 GHz / 5 GHz / Auto.
  • Info panel now displays the configured WiFi band and channel when available.

• Improvements

  • Changing band preference triggers a WiFi reconnect.
  • Expanded TX power choices with inline warning about potential connectivity impacts.

[coderabbitai]

Caution

Review failed

Failed to post review comments

Walkthrough

Adds WiFi 5GHz band support and broad platform-target updates: introduces wifiBandMode handling (UI, JSON, request parsing), renames Network → WLEDNetwork, adds board capability header and target-specific capability flags, expands ESP32-C* / P4 target guards across drivers and build scripts, and migrates many ESP-IDF v5 build configuration items.

Changes

Cohort / File(s)	Summary
WiFi band config & UI wled00/cfg.cpp, wled00/set.cpp, wled00/wled.h, wled00/wled.cpp, wled00/xml.cpp, wled00/data/settings_wifi.htm, wled00/data/index.js	Add wifiBandMode global (guarded by SOC_WIFI_SUPPORT_5G), JSON serialize/deserialize of "band", UI selector and request parameter (BM) parsing, and log/connection usage of band/channel.
Network abstraction rename wled00/src/dependencies/network/Network.h, wled00/src/dependencies/network/Network.cpp, many callers (wled00/*.cpp, usermods/*, lib/*, wled00/src/dependencies/*, etc.)	Rename NetworkClass/Network → WLEDNetworkClass/WLEDNetwork and replace Network.* usages with WLEDNetwork.* across codebase for IP, MAC, channel, and connectivity checks.
Board capability & target guards wled00/wled_boards.h, wled00/wled.h, wled00/const.h, wled00/wled.h, wled00/pin_manager.cpp	Introduce centralized board capability header with WLED_BOARD and capability macros (WLED_HAS_PARALLEL_I2S, WLED_HAVE_FAST_int_DIVIDE, etc.) and extend many preprocessor guards to cover ESP32C5/C6/C61/P4 variants.
I/O, bus & FX adjustments wled00/FX.h, wled00/FX_fcn.cpp, wled00/FXparticleSystem.cpp, wled00/bus_manager.cpp, wled00/bus_wrapper.h, lib/NeoESP32RmtHI/*	Introduce feature-test macros (WLED_HAS_PARALLEL_I2S, WLED_HAVE_FAST_int_DIVIDE), adjust I2S/parallel I2S/RMT/LEDC handling, add compilation guards for shared RMT, and change arithmetic/select paths based on capabilities.
Platform/ESP-IDF v5 & build config platformio.ini, pio-scripts/set_metadata.py, requirements.txt	Large migration/expansion of PlatformIO environments toward ESP-IDF v5, many new envs/boards, altered build flags and lib deps, and metadata script change to mutate CPPDEFINES in-place.
ESP-IDF version/API compatibility wled00/mbedtls_sha1_shim.cpp, wled00/ntp.cpp, usermods/PWM_fan/PWM_fan.cpp, wled00/network.cpp, wled00/util.cpp, wled00/ota_update.cpp	Add V5-targeted shims and conditional API usage (SHA1 shim, UDP clear vs flush, ledc API differences, ETH.begin signature, bootloader/chip checks).
DMX / E1.31 changes wled00/dmx_input.cpp, wled00/dmx_input.h, wled00/dmx_output.cpp, wled00/src/dependencies/dmx/*, wled00/src/dependencies/e131/ESPAsyncE131.cpp	Update RDM callback signatures to include request/response headers, add personalities handling, broaden platform guards, and switch to WLEDNetwork.localIP() for multicast interface selection.
Various smaller updates wled00/json.cpp, wled00/xml.cpp, wled00/ws.cpp, wled00/udp.cpp, wled00/button.cpp, wled00/FX_fcn.cpp, wled00/NodeStruct.h, wled00/*	Emit WiFi band in serializeInfo, tighten type-safety, adjust subnet checks to use WLEDNetwork, update touch/button guards for new targets, newline fix, and many conditional-guard expansions across usermods and dependencies.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Add support for WPA-Enterprise #5194 — modifies WiFi settings UI and cfg/set serialization (overlaps wifiBandMode UI/JSON changes).
• [esp32-C6 and esp-idf V5 branch] Fix ESP32-C6 GPIO pin validation and runtime compatibility #5114 — adjusts ESP32 target conditional logic and pin/bus handling (overlaps extended target guards and pin_manager/bus changes).
• Revert disable OTA logic & optional Arduino OTA #4748 — changes Network abstraction and connectivity usage (overlaps renaming Network → WLEDNetwork and related callers).

Suggested reviewers

• netmindz
• softhack007
• willmmiles

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.10% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main feature being added: WiFi band preference selection for dual-band ESP32 chips. It is specific, clear, and directly relevant to the primary change.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@wled00/cfg.cpp`:
- Around line 160-162: After deserializing cfg.json, validate the wifiBandMode
value (symbol wifiBandMode) to ensure it's within the allowed 1–3 range before
passing it to esp_wifi_set_band_mode(); follow the same pattern used for txPower
validation — check if wifiBandMode is out of range or missing, clamp or replace
with a safe default (e.g., 1) and log or correct the value in the config
structure so only valid values reach esp_wifi_set_band_mode().

In `@wled00/set.cpp`:
- Around line 126-131: The BM query param is parsed and stored directly into
wifiBandMode (used later with esp_wifi_set_band_mode()), but its value isn't
validated; validate the incoming int from request->arg(F("BM")).toInt() to
ensure it is one of the allowed values (1, 2, or 3) before assigning to
wifiBandMode and toggling forceReconnect; if the value is invalid, do not change
wifiBandMode (and optionally log or ignore the parameter). Update the branch
that checks request->hasArg(F("BM")) to parse, validate against {1,2,3}, set
forceReconnect only when the validated value differs from the current
wifiBandMode, and only then assign the new value so esp_wifi_set_band_mode()
always receives a valid wifi_band_mode_t.

🧹 Nitpick comments (2)

wled00/wled.h (1)

378-380: Replace the magic default with the enum constant.
Using literal 2 ties behavior to enum ordering; prefer WIFI_BAND_MODE_5G_ONLY to stay aligned with ESP-IDF.

♻️ Proposed change

`#ifdef` SOC_WIFI_SUPPORT_5G
-WLED_GLOBAL byte wifiBandMode _INIT(2);  // WIFI_BAND_MODE_5G_ONLY default for dual-band chips
+WLED_GLOBAL byte wifiBandMode _INIT((byte)WIFI_BAND_MODE_5G_ONLY);  // default for dual-band chips
`#endif`

Based on learnings: "In WLED code reviews, when code is modified or added, look for "magic numbers" (hardcoded numeric literals) and suggest replacing them with defined constants when meaningful constants exist in the codebase."

wled00/wled.cpp (1)

772-774: Check esp_wifi_set_band_mode result and confirm call order.
Please verify (per ESP-IDF docs) that this call is valid after WiFi.begin() and log failures to aid diagnostics.

🔍 Suggested error handling

`#ifdef` SOC_WIFI_SUPPORT_5G
-    esp_wifi_set_band_mode((wifi_band_mode_t)wifiBandMode);
+    esp_err_t err = esp_wifi_set_band_mode((wifi_band_mode_t)wifiBandMode);
+    if (err != ESP_OK) {
+      DEBUG_PRINTF_P(PSTR("esp_wifi_set_band_mode failed: %d\n"), err);
+    }
`#endif`

[softhack007]

@jonny190 as already stated - please align to latest "V5-C6" code, and use WiFi.setBandMode() instead of esp_wifi_set_band_mode().

[softhack007]

I would prefer to have WIFI_BAND_MODE_AUTO as the default. This is most compatible to all possible setups.

[netmindz]

I think the default should be auto rather than 5Ghz only

[jonny190]

Updated based on review feedback:

• Rebased onto V5-C6 branch as requested
• Replaced esp_wifi_set_band_mode() with WiFi.setBandMode() from the Arduino ESP32 core (requires IDF 5.4.2+)
• Changed default from 5 GHz only to Auto (both bands)
• Replaced magic number 2 with WIFI_BAND_MODE_AUTO enum constant
• Added input validation in both cfg.cpp (range check on deserialize) and set.cpp (reject values outside 1-3 range)
• Now builds on V5-C6's existing WiFi.setBandMode(WIFI_BAND_MODE_AUTO) call in initConnection(), making it user-configurable instead of hardcoded

[netmindz]

I'm not sure why the usermods ci is triggering when the pr has changes to the usermods, we can ignore those failures in this pr

[softhack007]

looks good to me, thank you 👍

ready to merge