🚀 [Success] Huidu HD-WF2 (ESP32-S3) HUB75 Setup Guide for WLED-MM

[hirofairlane]

Hi everyone,

After many hours of trial and error, I’ve finally managed to get a stable WLED-MM setup on the Huidu HD-WF2 board (ESP32-S3).

I initially tried using the standard pre-compiled binaries, but they all resulted in immediate boot loops and filesystem corruption (Superblock 0x0 errors). For this specific board, all generic images I tried lead to a boot loop.

How I solved it
The breakthrough came from using the esp32S3_8MB_M environment as a base and applying some critical optimizations. That lead the board to a stable working status, with some warnings that haven't affected the performance.

Switching to flash_mode = dio: The standard QIO mode was too unstable when the HUB75 driver was active, leading to flash write failures.

Resource Optimization: Since this board lacks PSRAM, the system was running out of heap memory. By stripping down unused modules (Alexa, Loxone, etc.) and forcing WLED_MAX_SEGMENTS=1, the ESP32-S3 finally had enough "breathing room" to handle the 2D matrix effects.

My setup:
platformio_override.ini

[platformio]
default_envs = huidu_hd_wf2

[env:huidu_hd_wf2]
extends = esp32S3_8MB_M  ; Using this as our stable base
board_build.flash_mode = dio      ; Critical for stability on Huidu boards
board_build.f_flash = 80000000L

build_flags = 
  ${env:esp32S3_8MB_M.build_flags}
  -D WLED_RELEASE_NAME=HUIDU_HD_WF2
  -D WLED_ENABLE_2D
  -D WLED_MAX_SEGMENTS=1          ; Essential for boards without PSRAM
  -D WLED_DISABLE_ALEXA           ; Stripping down to free up RAM
  -D WLED_DISABLE_LOXONE
  ; --- HUIDU HD-WF2 ONBOARD PINS ---
  -D LEDPIN=4
  -D RLYPIN=21
  -D BTNPIN=48
  -D IRPIN=15
  -D HW_PIN_SDA=42
  -D HW_PIN_SCL=41

Flashing tip:
To flash this board, use a USB-A to USB-C cable connected to the USB-A female port on the Huidu board.
The board must be powered with 5V via the screw terminals while flashing.

[hirofairlane]

A couple of tweaks for better performace and stability.

[env:huidu_hd_wf2]
extends = esp32S3_8MB_M  ; Using this as our stable base
board_build.flash_mode = dio      ; Critical for stability on Huidu boards
board_build.f_flash = 80000000L
platform = espressif32@6.5.0
platform_packages = ${esp32.platformV4_packages}
board = esp32-s3-devkitc-1
build_unflags = 
  -D USERMOD_DALLASTEMPERATURE ;; disabled because it hangs during usermod setup on -S3 (autodetect broken?)
  -D USE_ALT_DISPLAY ;; four line display seems to have problems with I2C - it hangs during usermod setup
  -D USERMOD_FOUR_LINE_DISPLAY ;; see above
  -D USERMOD_ROTARY_ENCODER_UI ;; see above
  -D WLED_ENABLE_DMX 
build_flags = 
  ${env:esp32S3_8MB_M.build_flags}
  -D WLED_RELEASE_NAME=HUIDU_HD_WF2
  -D WLED_ENABLE_2D
  -D WLED_MAX_SEGMENTS=1          ; Saving as much PSRAM as possible, increase value in case needed
  -D WLED_DISABLE_ALEXA           ; Stripping down to free up RAM
  -D WLED_DISABLE_LOXONE
  ; --- HUIDU HD-WF2 ONBOARD PINS ---
  -D LEDPIN=4
  -D RLYPIN=21
  -D BTNPIN=48
  -D IRPIN=15
  -D HW_PIN_SDA=42
  -D HW_PIN_SCL=41
  -D WLED_DISABLE_AUDIO        ; Disabling audio as board does not implement mic
  -D WLED_DISABLE_SOUNDS       ; Disabling audio as board does not implement mic
  -D WLED_DISABLE_INFRARED     ; Disabling audio as board does not implement IR
  -D WLED_DISABLE_ADALIGHT     ; Stripping down to free up RAM

[softhack007]

Hint: some flags proposed by @hirofairlane do nothing, and can be skipped

  -D WLED_MAX_SEGMENTS=1 ;; does not exist in source code
  ;;; you might want: -D MAX_NUM_SEGMENTS=8
  -D WLED_ENABLE_2D ;; does not exist in source code
  -D WLED_DISABLE_AUDIO ;; does nothing 
  -D WLED_DISABLE_SOUNDS ;; does nothing

also the flags to select the platform version are inconsistent, better use

    platform = ${esp32.platformV4} ;; standard arduino-esp32 2.0.9
    platform_packages = ${esp32.platformV4_packages}

If you want to disable audioreactive microphone input, use this

    -D SR_DMTYPE=254 ;; set AR default mode to 'Network Receive Only' to prevent driver conflicts.

A word of caution: the board is actually 4MB

test with older HD-WF2 boards showed that only 4MB of flash are usable, so an "8MB" build will get into trouble once you start saving presets. It might be better to try the "4MB" buildenv [env:esp32S3_4MB_S]

To reduce RAM usage, you could try to reduce JSON buffer, for example

  -D JSON_BUFFER_SIZE=18432 -D MIN_HEAP_SIZE=6144
  ;; -D MAX_SEGMENT_DATA=40960  ;; default 32767
  -D WLEDMM_SAVE_FLASH

WLED-MM/platformio.ini

Lines 2196 to 2228 in 7019f29

	[env:esp32S3_4MB_S] ;; Use for HD-WF2
	extends = esp32_4MB_V4_M_base
	;; use standard espressif platform - tasmota platform seems to have problems when there is no PSRAM (sdkconfig.h file not found)
	platform = ${esp32.platformV4}
	platform_packages = ${esp32.platformV4_packages}
	board = esp32-s3-devkitc-1
	build_unflags =
	-D USERMOD_DALLASTEMPERATURE ;; disabled because it hangs during usermod setup on -S3 (autodetect broken?)
	-D USE_ALT_DISPLAY ;; four line display seems to have problems with I2C - it hangs during usermod setup
	-D USERMOD_FOUR_LINE_DISPLAY ;; see above
	-D USERMOD_ROTARY_ENCODER_UI ;; see above
	-D WLED_ENABLE_DMX ;; disabled because it does not work with ESP-IDF 4.4.x (buggy driver in SparkFunDMX)
	build_flags = ${common.build_flags} ${esp32s3.build_flags} -Wno-misleading-indentation -Wno-format-truncation
	${common_mm.build_flags_S}
	${common_mm.HUB75_build_flags}
	${common_mm.animartrix_build_flags}
	-D WLED_RELEASE_NAME=esp32S3_4MB_S
	-DARDUINO_USB_MODE=1 -DARDUINO_USB_CDC_ON_BOOT=0 -DARDUINO_USB_MSC_ON_BOOT=0 -DARDUINO_USB_DFU_ON_BOOT=0 ;; for Serial-to-USB chip
	;;-DARDUINO_USB_MODE=1 -DARDUINO_USB_CDC_ON_BOOT=1 -DARDUINO_USB_MSC_ON_BOOT=0 -DARDUINO_USB_DFU_ON_BOOT=1 ;; for Hardware-CDC USB mode
	-D WLED_DISABLE_ADALIGHT ;; disables serial protocols - recommended for Hardware-CDC USB (Serial RX will receive junk commands when RX pin is unconnected, unless its pulled down by resistor)
	-D WLED_WATCHDOG_TIMEOUT=0 -D CONFIG_ASYNC_TCP_USE_WDT=0
	${common_mm.build_disable_sync_interfaces}
	-D WLEDMM_FASTPATH ; WLEDMM experimental option. Reduces audio lag (latency), and allows for faster LED framerates. May break compatibility with previous versions.
	-D WLEDMM_SAVE_FLASH
	; -D WLED_DEBUG
	; -D SR_DEBUG
	lib_deps = ${esp32s3.lib_deps} ${common_mm.lib_deps_S}
	${common_mm.HUB75_lib_deps}
	${common_mm.animartrix_lib_deps}
	board_build.f_flash = 80000000L
	board_build.flash_mode = dio
	board_build.partitions = ${esp32.extended_partitions} ;; 1.65MB firmware, 700KB filesystem